VTPL Drawing Board (vtpl-drawing-board)

A highly performant, customizable, and responsive React component for image annotations, masking, perimeter grid modeling, and directional vector drawing.

Perfect for computer vision workflows, area labeling, crosswalk zone detection, security zoning, and custom SVG annotations.

🌟 Live Demo

Check out the interactive Annotation Studio Demo:
👉 https://vtpl-drawing-board.vercel.app (Replace with your actual deployed URL!)

Load custom images, draw bounds, scale zones, adjust line vector directions, and download/import your coordinate mapping instantly.

✨ Features

• 📐 Multiple Shapes Support: Draw Rectangles, Polygons, and Directional Lines.
• ⚡ Self-Contained & Scoped CSS: 100% Vanilla CSS module scoping. No Tailwind CSS dependency or style leaks!
• 🗺️ High-Resolution Projection: Shapes and calculations automatically project onto the image's natural resolution, regardless of the display screen size.
• 📏 Dynamic Resizing Handles: Drag edges to resize rectangles, reposition points for polygons and lines.
• ↔️ Directional Vectors: Configure lines with "IN", "OUT", or "IN/OUT" arrows and easily reverse directions with a clean dark-mode context menu.
• 🎨 Extensive Theme Customization: Completely customize SVG strokes, fills, hover effects, handle points, and text colors.

📦 Installation

Install via npm:

npm install vtpl-drawing-board

Or via yarn:

yarn add vtpl-drawing-board

🚀 Quick Start

Ensure you import the package and its custom stylesheet in your application:

import React, { useState } from "react";
import DrawingBoard from "vtpl-drawing-board";
import "vtpl-drawing-board/dist/style.css"; // Ensure styles are imported!

function App() {
  const [shapes, setShapes] = useState([]);
  const [tool, setTool] = useState("rectangle"); // "select" | "line" | "rectangle" | "polygon"
  const [editMode, setEditMode] = useState(true);

  return (
    <div style={{ width: "100%", height: "600px", background: "#0f172a" }}>
      <DrawingBoard
        imageSrc="https://images.unsplash.com/photo-1542282088-fe8426682b8f"
        imageNaturalSize={{ width: 1920, height: 1080 }}
        shapes={shapes}
        onShapesChange={(newShapes) => setShapes(newShapes)}
        tool={tool}
        onToolChange={(newTool) => setTool(newTool)}
        editMode={editMode}
      />
    </div>
  );
}

export default App;

📖 Component API

DrawingBoardProps

| Prop | Type | Required | Description | | :--- | :--- | :---: | :--- | | imageSrc | string | Yes | The base image source URL (relative path, import, or base64 data URL). | | imageNaturalSize | { width: number; height: number } | Yes | The absolute width/height dimensions of the asset. Coordinates scale dynamically to this. | | shapes | Shape[] | Yes | Array of active shape models drawn on the image canvas. | | onShapesChange | (shapes: Shape[]) => void | Yes | Triggered on drawing complete, shapes deleted, dragged, or resized. | | tool | "select" \| "line" \| "rectangle" \| "polygon" | Yes | Current active cursor interaction tool. | | onToolChange | (tool: Tool) => void | No | Callback when a tool finishes creation and resets back to "select". | | editMode | boolean | Yes | When false, locks the canvas (read-only view mode). When true, enables active drawing. | | colors | ShapeColorTheme | No | Overrides theme colors for fills, handles, text, and active drawing draft outlines. |

Shape Schema Types

export type Point = {
  x: number;
  y: number;
};

export type RectangleShape = {
  id: string;
  type: "rectangle";
  x: number;
  y: number;
  width: number;
  height: number;
};

export type LineShape = {
  id: string;
  type: "line";
  points: [Point, Point];
  in: boolean;
  out: boolean;
  reverseDirection: boolean;
};

export type PolygonShape = {
  id: string;
  type: "polygon";
  points: Point[];
};

export type Shape = RectangleShape | LineShape | PolygonShape;

🎨 Theme Customization (ShapeColorTheme)

Pass a custom object to the colors property to style the elements. All values default to an elegant, high-contrast dark palette:

export interface ShapeColorTheme {
  // Rectangle styles
  rectangleFill?: string;             // Fill color (e.g. "rgba(59,130,246,0.15)")
  rectangleStroke?: string;           // Border stroke color (e.g. "#2563eb")
  rectangleHoverFill?: string;        // Hover fill color (e.g. "rgba(59,130,246,0.25)")
  rectangleResizeHandleFill?: string; // Sizing edge handles color

  // Line / Vector arrow styles
  lineVisualStroke?: string;          // Main visible line stroke
  lineDragHitBoxStroke?: string;      // Hitbox line stroke (normally "transparent")
  lineArrowStroke?: string;           // Arrow outlines stroke
  lineArrowFillInActive?: string;     // Disabled direction arrow fill
  lineArrowFillActive?: string;       // Active direction arrow fill
  lineTextIn?: string;                // "IN" label text color
  lineTextOut?: string;               // "OUT" label text color
  linePointFill?: string;             // Grab handles fill color
  linePointStroke?: string;           // Grab handles border color

  // Polygon styles
  polygonFill?: string;
  polygonStroke?: string;
  polygonHoverFill?: string;
  polygonPointFill?: string;
  polygonPointStroke?: string;

  // Active Drawing Draft outlines
  draftLinePointFill?: string;
  draftLinePointStroke?: string;
  draftPolylineStroke?: string;
  draftPolygonPointFill?: string;
  draftPolygonPointStroke?: string;
}

📄 License

MIT © SantuVTPL