sector-tagger v1.0.0
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.
(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 appappId
: Unique identifier for the app instancefetchImgUrl
: 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 canvasdeleteSector(id: string)
: Delete a sector by its IDfocusOnSector(sector: Sector)
: Focus the view on a specific sectortoggleGrid()
: Toggle the grid overlayhandleImageUpload(event: Event)
: Handle image uploadhandleJSONUpload(event: Event)
: Handle JSON data uploadexportData()
: 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 canvascontainsPoint(x: number, y: number): boolean
: Check if a point is inside the sectormove(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!
14 days ago