@paresh-barik-neophyte/store-layout-mapper/README.md

A React-based image annotation tool for mapping store layouts

# Store Layout Mapper

A powerful React-based annotation tool for mapping store layouts. This tool allows you to annotate store layout images with customized zones, gondolas, cameras and define pipelines for AI processing.

## Installation

```bash
npm install @paresh-barik-neophyte/store-layout-mapper
```

or using yarn:

```bash
yarn add @paresh-barik-neophyte/store-layout-mapper
```

## Features

- Store Layout Image annotation with custom Tools
- Support for multiple pipelines
- Interactive zoom, pan, and pinch controls
- Save and load annotation data
- Customizable UI elements
- Responsive design

## Usage

```tsx
import { AnnotationTool } from "@paresh-barik-neophyte/store-layout-mapper";
import "@paresh-barik-neophyte/store-layout-mapper/dist/index.css";

function App() {

  // Example Annotation Data
  const annotationData = {
  "zones": [
    {
      "id": "fe575294-9e68-43b0-be2b-709f29be112f",
      "name": "Playstation",
      "type": "default",
      "color": "hsla(356, 75%, 60%, 0.7)",
      // Three points minimum is required to create a zone
      "points": [
        {
          "x": 45.77316864990952,
          "y": 62.81035413942268
        },
        {
          "x": 64.73106703826052,
          "y": 62.89697099012196
        },
        {
          "x": 67.58442419365008,
          "y": 62.98358784082123
        },
      ],
      "gondolas": [
        {
          "id": "d6de83df-03e0-4836-ab0d-4fd1e422d069",
          "zoneId": "fe575294-9e68-43b0-be2b-709f29be112f",
          "serialNumber": 1,
          "name": "Gondola 1",
          "type": "default",
          "coordinates": {
            "x": 50.077385375836144,
            "y": 65.77698127587298
          },
          "brand": "PS4"
        },
      ]
    },
  ],
  "cameras": [
    {
      "id": "8e77dc5b-dc48-4f85-9737-0ec976072d00",
      "name": "Hik vision",
      "serialNumber": 1,
      "rtspAddress": "rtsp://username:password@192.168.1.100:554/stream1",
      "coordinates": {
        "x": 42.87144950883539,
        "y": 59.02086692132923
      },
      "rotation": -122.57846342756096,
      "color": "hsla(0, 85%, 60%, 0.7)",
      "watchingZones": [
        "fe575294-9e68-43b0-be2b-709f29be112f"
      ],
      "skipFrames": 5,
      "isActive": true,
      "pipelines": [
        "/home/user/projects/pipelines/tracking_pipeline_v2.py",
        "/home/user/projects/pipelines/analysis_pipeline_basic.py"
      ]
    },
  ],
  "timestamp": "2024-11-28T17:31:45.555Z"
}


  // Example Pipeline Options
  const pipelineOptions = [
    {
      value: '/home/user/projects/pipelines/detection_pipeline_v1.py',
      label: 'Detection Pipeline V1'
    },
    {
      value: '/home/user/projects/pipelines/tracking_pipeline_v2.py',
      label: 'Tracking Pipeline V2'
    },
    {
      value: '/home/user/projects/pipelines/analysis_pipeline_basic.py',
      label: 'Basic Analysis Pipeline'
    },
    {
      value: '/home/user/projects/pipelines/advanced_detection_v3.py',
      label: 'Advanced Detection V3'
    }
  ];

  const handleSave = (data) => {
    console.log('Annotation data:', data);
    // Handle the saved data
  };

  return (
    <AnnotationTool
      enableEdit={true} //Make it false to disable all editing tools
      image="/path/to/your/image.jpg" 
      annotationData={annotationData}
      pipelines={pipelineOptions}
      onSave={handleSave}
    />
  );
}
```

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `enableEdit` | boolean | Yes | Enable/disable editing capabilities |
| `image` | string | No | URL or path to the image to be annotated |
| `annotationData` | AnnotationData | No | Initial annotation data |
| `pipelines` | PipelineOption[] | Yes | Array of available pipeline options |
| `onSave` | (data: AnnotationData) => void | Yes | Callback function when annotations are saved |

## Data Types

### AnnotationData
```typescript
interface Point {
  x: number;
  y: number;
}

interface Gondola {
  id: string;
  zoneId: string;
  serialNumber: number;
  name: string;
  type: string;
  coordinates: Point;
  brand: string;
}
interface Zone {
  id: string;
  name: string;
  type: string;
  color: string;
  points: Point[];
  gondolas: Gondola[];
}

interface Camera {
  id: string;
  name: string;
  serialNumber: number;
  rtspAddress: string;
  coordinates: Point;
  rotation: number;
  color: string;
  watchingZones: string[];
  skipFrames: number;
  isActive: boolean;
  pipelines: string[];
}

interface AnnotationData {
  zones: Zone[];
  cameras: Camera[];
  timestamp: string;
}
```

### PipelineOption
```typescript
interface PipelineOption {
  value: string;
  label: string;
}
```

## Features in Detail

1. **Store Layout Annotation**
   - Add, edit, and delete Zones, Gondolas, and Cameras on the layout image of stores
   - Input Brands associated with individual gondolas
   - Precise positioning with zoom capabilities
   - Rotate the cameras with 'pressing and holding shift + dragging the mouse right click'
   - Predefined pipeline options

2. **Advanced Features**
   - Enable or disable the editing options
   - Fetch the image from cloud or add from your system
   - Import existing annotation data or export to download as a json file
   - Customizable onSave function to handle the annotation data
   - Image added from system is converted to base64 format easy uploading to cloud
   - Undo button to discard the last change

3. **Interactive Controls**
   - Zoom in/out
   - Pan across the image
   - Pinch to zoom (touch devices)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT [Paresh Kumar Barik]