1.0.0 • Published 2 months ago

sector-tagger v1.0.0

Weekly downloads
-
License
MIT
Repository
-
Last release
2 months ago

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:

  1. Rectangle Sector
  2. Circle Sector
  3. 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.

Testing and contribution is welcome!

sectortagtaggingarearegionselectioncanvasdrawinglibraryshaperectanglescirclespolygons
1.0.0

2 months ago