sector-tagger

v1.0.0

Published

a month ago

A canvas sector tagging library supporting rectangles, circles, and polygons.

Downloads

0High
0Medium
0Low

pazny

sector tag tagging area region selection canvas drawing library shape rectangles circles polygons

Sector Tagger

SectorTagger is a powerful native JavaScript library for loading, drawing, moving and tagging sectors(areas) in images (or empty background) using HTML5 Canvas.

It supports drawing rectangles, circles, and polygons with an intuitive user interface.

Sector Tagger Demo (TODO - record a GIF :)

Features

Draw and edit rectangles, circles, and polygons
Zoom and pan functionality
Add tags, color and comments to sectors
Hovering over sectors highlights them
Filter sectors by tags
Export and import data in JSON format
Fully customizable UI components
Responsive design (non-mobile friendly yet)

Installation

npm install sector-tagger

Quick Start

Usage with npm

import { SectorTaggerApp } from 'sector-tagger';

const container = document.getElementById('sector-tagger-app');
const app = new SectorTaggerApp(container, 'uniqueAppId');

Usage with script tag

<div id="sector-tagger-app" class="sector-tagger-container"></div>

<script src="dist/sector-tagger.js"></script>
<script>
  const container = document.getElementById('sector-tagger-app');
  const app = new SectorTagger.SectorTaggerApp(container, 'uniqueAppId');
</script>

API Documentation

SectorTaggerApp

The main class that initializes the Sector Tagger application.

const app = new SectorTaggerApp(containerElement, appId, fetchImgUrl, fetchSectorsUrl, onAddToCartCallback, uiComponents);

Parameters:

containerElement: DOM element to contain the Sector Tagger app
appId: Unique identifier for the app instance
fetchImgUrl: URL to fetch the image (optional)
fetchSectorsUrl: URL to fetch existing sectors (optional)
onAddToCartCallback: Callback function when adding sectors to cart (optional)
uiComponents: Custom UI components (optional)

Methods

setDrawingMode(shape: string): Set the current drawing mode ('rectangle', 'circle', or 'polygon')
draw(): Redraw the canvas
deleteSector(id: string): Delete a sector by its ID
focusOnSector(sector: Sector): Focus the view on a specific sector
toggleGrid(): Toggle the grid overlay
handleImageUpload(event: Event): Handle image upload
handleJSONUpload(event: Event): Handle JSON data upload
exportData(): Export sector data as JSON

Sector Types

Sector Tagger supports three types of sectors:

Rectangle Sector
Circle Sector
Polygon Sector (Buggy and not fully tested)

Each sector type has its own class with specific methods for drawing and interaction.

Common Sector Methods

draw(ctx: CanvasRenderingContext2D, scale: number): Draw the sector on the canvas
containsPoint(x: number, y: number): boolean: Check if a point is inside the sector
move(dx: number, dy: number): Move the sector by a given offset

Events

Sector Tagger provides various events that you can listen to and customize:

Mouse events (mousedown, mousemove, mouseup, click, wheel)
Keyboard events (keydown, keyup)

You can customize these events by extending the default UI components and overriding their methods.

Styling

Sector Tagger comes with default styles, but you can easily customize them to match your application's design.

Customization examples:

Prepare custom canvas and panel

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Sector Tagger Demo</title>
  <style>
    .sector-tagger-container {
      width: 800px;
      height: 600px;
      border: 1px solid #ccc;
    }
  </style>
</head>
<body>
  <div id="sectorTaggerApp" class="sector-tagger-container"></div>
  <div id="customRightPanel">
    <div id="customRightPanelContent">
      <!-- custom content here -->
    </div>
  </div>

  <script src="dist/sector-tagger.js"></script>
  <script>
    class CustomRightPanel {
      constructor(app) {
        this.app = app;
        this.render();
      }

      // required todo: implement remaining methods of interface UIComponent

      render() {
        this.panel = document.querySelector('#customRightPanel');
        // custom content here
      }

      updateSectorList() {
        // custom implementation
      }

      deleteSector() {
        // custom implementation
      }
    }

    document.addEventListener('DOMContentLoaded', () => {
      const container = document.getElementById('sectorTaggerApp');
      let app;
      
      const customRightPanel = new CustomRightPanel(null); 

      app = new SectorTagger.SectorTaggerApp(container, 'uniqueAppId', null, null, null, {
        rightPanel: customRightPanel,
      });

      customRightPanel.app = app;
    });
  </script>
</body>
</html>

Notes:

WIP:

bugfixes on polygon
design improvements
complete readme
reusability
- callbacks on all events
- custom UI support (agnostic to the rest of the app)

TODO:

add license
better examples into readme
add tests

My name is Aleš and I'm a software developer from Czech Republic. I needed this library for one of my projects and I decided to share it with the community to contributte into open source and also improve my JS+NPM skills.