React-based polygon editor for image regions with workplace linking
npm install xpoligonbash
npm install xpoligon
`
$3
The library uses Tailwind CSS for styling. You need to import the compiled CSS file:
`tsx
// Import the library styles
import 'xpoligon/dist/index.css';
// Then use the component
import { PolygonEditorPage } from 'xpoligon';
`
Important: The library includes its own compiled CSS with all necessary Tailwind styles. You don't need to have Tailwind CSS installed in your project unless you want to customize the styles.
Usage
$3
`tsx
// Import styles and component
import 'xpoligon/dist/index.css';
import { PolygonEditorPage } from 'xpoligon';
import type { PolygonEditorData } from 'xpoligon';
const MyApp = () => {
const data: PolygonEditorData = {
camera: {
id: 'cam1',
name: 'Main camera',
screenshot: '/path/to/image.jpg',
isActive: true,
},
workplaces: [
{ id: 'wp1', name: 'Table #1' },
{ id: 'wp2', name: 'Table #2' },
],
polygons: [], // Existing polygons
};
const handleSave = (saveData) => {
console.log('Save data:', saveData);
// Send to server
};
const handleChange = (polygons) => {
console.log('Polygons changed:', polygons);
};
return (
data={data}
onSave={handleSave}
onChange={handleChange}
autoSaveDelay={1500}
/>
);
};
`
$3
`tsx
// Import styles first
import 'xpoligon/dist/index.css';
import { useState, useEffect } from 'react';
import { PolygonEditorPage } from 'xpoligon';
import type { PolygonEditorData } from 'xpoligon';
const CameraEditor = ({ cameraId }) => {
const [data, setData] = useState(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
const loadData = async () => {
setLoading(true);
try {
// Load data from your server
const response = await fetch( /api/cameras/${cameraId}/editor-data);
const editorData = await response.json();
setData(editorData);
} catch (error) {
console.error('Failed to load data:', error);
} finally {
setLoading(false);
}
};
loadData();
}, [cameraId]);
if (!data) return Loading...;
return (
data={data}
loading={loading}
onSave={async (saveData) => {
// Send data to your server
await fetch(/api/cameras/${saveData.cameraId}/polygons, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(saveData),
});
}}
onError={(error) => console.error(error)}
/>
);
};
`
API
$3
`typescript
interface PolygonEditorProps {
data: PolygonEditorData; // Camera, workplaces, and polygons data
loading?: boolean; // Loading state
onSave?: (data: SaveData) => void; // Save callback
onChange?: (polygons: Polygon[]) => void; // Change callback
onError?: (error: string) => void; // Error callback
autoSaveDelay?: number; // Autosave delay (ms)
}
`
$3
`typescript
interface PolygonEditorData {
camera: Camera; // Camera data with image
workplaces: Workplace[]; // List of workplaces
polygons: Polygon[]; // Existing polygons
}
`
$3
`typescript
interface Camera {
id: string;
name: string;
screenshot: string; // Image URL
isActive: boolean;
}
interface Workplace {
id: string;
name: string;
}
interface Polygon {
id: string;
points: Point[]; // Relative coordinates (0-1)
linkedWorkplace?: string; // Linked workplace ID
closed: boolean;
}
interface Point {
x: number; // 0-1
y: number; // 0-1
}
`
$3
When saving, data is passed in the following format:
`typescript
interface SaveData {
cameraId: string;
imageSize: {
width: number;
height: number;
};
regions: Array<{
id: string;
linkedWorkplace?: string;
relativeCoordinates: Point[]; // 0-1
pixelCoordinates: Point[]; // pixels
closed: boolean;
}>;
timestamp: string;
}
`
Hotkeys
- Delete / Backspace - Delete selected polygon
- Escape - Cancel drawing
- Click - Add point
- Double Click - Finish polygon
Features
$3
The library uses two coordinate systems:
1. Relative coordinates (0-1) - for internal work and scaling
2. Pixel coordinates - for sending to the server
$3
Changes are automatically saved after the specified delay. Default is 1000ms.
$3
Polygons can be linked to workplaces from the list. The link is shown by color and label.
Architecture
The library is built using Feature-Sliced Design principles:
`
src/
āāā app/ # App configuration
āāā pages/ # Pages (main component)
āāā widgets/ # Composite UI blocks
āāā features/ # Business logic
āāā entities/ # Data models
āāā shared/ # Reusable code
`
Customization
$3
The library comes with compiled Tailwind CSS styles. To customize the appearance:
1. Override CSS classes: The library uses CSS classes like .polygon-editor-button, .polygon-editor-canvas, etc. You can override them in your own CSS:
`css
/ Override button styles /
.polygon-editor-button-primary {
background-color: #your-color !important;
}
/ Override canvas border /
.polygon-editor-canvas {
border-color: #your-border-color !important;
}
`
2. Custom CSS file: Import your custom styles after the library styles:
`tsx
import 'xpoligon/dist/index.css';
import './my-custom-styles.css'; // Your overrides
`
$3
All internal components are exported and can be used separately:
`tsx
import { PolygonCanvas, ItemsPanel } from 'xpoligon';
`
$3
Hooks and utilities are exported:
`tsx
import {
useImageProcessing,
useCanvasDimensions,
usePolygonChanges,
generateId
} from 'xpoligon';
``