@cloneable/pole-canvas

A powerful React component library for rendering and interacting with utility pole inspection canvas diagrams.

Features

• 🖼️ Interactive Canvas - Pan and zoom capabilities with smooth animations
• 📏 Reference Line Calibration - Define measurement references for accurate scaling
• 📍 Attachment Management - Add, position, and edit equipment attachments on poles
• 🔗 Guy Wire Visualization - Display guy wires and anchors with visual connections
• 📊 Flexible Measurements - Display heights in metric, feet, or feet & inches
• 🎯 Smart Label Positioning - Automatic label deconfliction prevents overlaps
• 📸 High-Quality Export - Generate annotated images with all measurements
• 🎨 Zero CSS Dependencies - Pure inline styles, works in any React environment
• 📱 Mobile Support - Touch gestures for pan and zoom on mobile devices
• ⚡ Performance Optimized - Efficient rendering with React memoization

Installation

npm install @cloneable/pole-canvas

Or with pnpm:

pnpm add @cloneable/pole-canvas

Or with yarn:

yarn add @cloneable/pole-canvas

Requirements

• React 18.0.0 or higher
• React DOM 18.0.0 or higher

Quick Start

import { PoleCanvas } from '@cloneable/pole-canvas';

function MyPoleInspector() {
  const poleImage = new PoleImage({
    id: '1',
    image: 'image-url',
    type: 'front',
    referenceLine: {
      top: {
        id: 'top',
        pixelCoordinates: { x: 100, y: 50 },
        worldCoordinates: { x: 0, y: 0, z: 45 }
      },
      bottom: {
        id: 'bottom',
        pixelCoordinates: { x: 100, y: 400 },
        worldCoordinates: { x: 0, y: 0, z: 0 }
      }
    }
  });

  const attachments = [
    new PoleAttachment({
      id: '1',
      type: 'transformer',
      height: 35,
      classification: 'Power',
      owner: 'Electric Company',
      related_task_id: 'task-1',
      inventoryClass: {
        name: 'Transformer',
        subcategories: []
      },
      images: [{
        imageId: '1',
        point: { x: 100, y: 120 }
      }]
    })
  ];

  return (
    <PoleCanvas
      poleImage={poleImage}
      attachments={attachments}
      measurementFormat="both"
      onPositionChange={(attachmentId, imageId, yPixel) => {
        console.log('Position changed:', { attachmentId, imageId, yPixel });
      }}
      onAttachmentClick={(attachmentId) => {
        console.log('Attachment clicked:', attachmentId);
      }}
      onBackgroundClick={() => {
        console.log('Background clicked');
      }}
      isAddMode={false}
      onAddAttachment={(x, y) => {
        console.log('Add attachment at:', { x, y });
      }}
      toggleAddMode={() => {
        console.log('Toggle add mode');
      }}
    />
  );
}

Using the Hook

The usePoleCanvas hook provides a complete state management solution:

import { usePoleCanvas } from '@cloneable/pole-canvas';

function MyPoleInspector() {
  const [state, actions] = usePoleCanvas({
    initialImage: myPoleImage,
    initialAttachments: myAttachments,
    initialFormat: 'both',
    onChange: (newState) => {
      console.log('State changed:', newState);
    }
  });

  return (
    <PoleCanvas
      poleImage={state.poleImage}
      attachments={state.attachments}
      measurementFormat={state.measurementFormat}
      selectedAttachmentId={state.selectedAttachmentId}
      isAddMode={state.isAddMode}
      isReferenceLineUpdateMode={state.isReferenceLineUpdateMode}
      tempReferencePoints={state.tempReferencePoints}
      onPositionChange={actions.updateAttachmentPosition}
      onAttachmentClick={actions.selectAttachment}
      onBackgroundClick={() => actions.selectAttachment(null)}
      onAddAttachment={(x, y) => {
        // Create and add new attachment
        const newAttachment = createAttachment(x, y);
        actions.addAttachment(newAttachment);
      }}
      toggleAddMode={actions.toggleAddMode}
      onReferencePointUpdate={actions.updateReferencePoint}
    />
  );
}

Custom Components

You can provide custom components for full control over the UI:

import { PoleCanvas } from '@cloneable/pole-canvas';
import type { AttachmentComponentProps, ControlsProps } from '@cloneable/pole-canvas';

const CustomAttachment: React.FC<AttachmentComponentProps> = ({
  attachment,
  position,
  isSelected,
  onClick
}) => {
  return (
    <div
      className={`custom-attachment ${isSelected ? 'selected' : ''}`}
      style={{ left: position.x, top: position.y }}
      onClick={onClick}
    >
      {attachment.classification}
    </div>
  );
};

const CustomControls: React.FC<ControlsProps> = ({
  zoomIn,
  zoomOut,
  resetTransform
}) => {
  return (
    <div className="custom-controls">
      <button onClick={zoomIn}>Zoom In</button>
      <button onClick={zoomOut}>Zoom Out</button>
      <button onClick={resetTransform}>Reset</button>
    </div>
  );
};

function MyPoleInspector() {
  return (
    <PoleCanvas
      poleImage={poleImage}
      attachments={attachments}
      attachmentComponent={CustomAttachment}
      controlsComponent={CustomControls}
      // ... other props
    />
  );
}

Utility Functions

The package includes utility functions for calculations:

import {
  calculateMeasurements,
  calculate3DDistance,
  formatPoleMeasurementString,
  PixelArrayData
} from '@cloneable/pole-canvas';

// Calculate attachment measurements
const measurements = calculateMeasurements(
  pixelY,
  topPoint,
  bottomPoint,
  poleHeight,
  'both'
);

// Work with pixel arrays
const pixelArray = new PixelArrayData(pixelPoints);
const [pixelCoord, worldCoord] = pixelArray.findClosestCoord({ x: 100, y: 200 });

API Reference

PoleCanvas Props

| Prop | Type | Description | |------|------|-------------| | poleImage | PoleImageType | Pole image configuration with reference lines | | attachments | PoleAttachmentType[] | Array of pole attachments | | measurementFormat | PoleFormatOption | Display format: 'percent', 'distance', 'both', 'none' | | onPositionChange | Function | Callback when attachment position changes | | onAttachmentClick | Function | Callback when attachment is clicked | | selectedAttachmentId | string? | Currently selected attachment ID | | onBackgroundClick | Function | Callback when background is clicked | | isAddMode | boolean | Whether add attachment mode is active | | onAddAttachment | Function | Callback to add new attachment | | toggleAddMode | Function | Toggle add mode | | imageLoader | Function? | Custom image loader function | | controlsComponent | Component? | Custom controls component | | attachmentComponent | Component? | Custom attachment component |

Types

• PoleImageType - Pole image configuration
• PoleAttachmentType - Attachment configuration
• Coordinate2D - 2D coordinate
• Coordinate3D - 3D coordinate with z-axis
• ReferencePoint - Links pixel and world coordinates
• PoleFormatOption - Measurement display format

License

MIT