Coordinate System

WebCAD supports multiple coordinate systems for coordinate calculation and conversion in different scenarios. Understanding the coordinate system is essential for correctly handling user input and entity positioning.

Coordinate System Types

Coordinate System	Full Name	Description	Use Case
WCS	World Coordinate System	World coordinates	Entity storage, geometric calculation
UCS	User Coordinate System	User coordinates	User input, relative positioning
DCS	Display Coordinate System	Display coordinates	View display, zoom and pan
Canvas	Canvas Coordinate	Canvas coordinates	Mouse events, screen pixels

Coordinate System Details

WCS (World Coordinate System)

The world coordinate system is the absolute reference coordinate system. All entity geometric data is stored in WCS.

Characteristics:

• Origin fixed at (0, 0)
• X-axis points right, Y-axis points up
• Units are typically millimeters or inches
• Not affected by view transformations

import { LineEnt, Point2D } from 'vjcad';

// Entity coordinates always use WCS
const line = new LineEnt(
  new Point2D(0, 0),      // WCS coordinates
  new Point2D(100, 100)   // WCS coordinates
);

// Get entity's WCS bounding box
const bounds = line.boundingBox();  // Returns WCS bounding box by default

UCS (User Coordinate System)

The user coordinate system is a customizable working coordinate system that facilitates drawing in specific directions or positions.

Characteristics:

• Origin can be moved
• Can be rotated
• Used to simplify drawing at specific angles
• User input relative coordinates are based on UCS

import { Engine, Point2D } from 'vjcad';

// Convert UCS coordinates to WCS
const ucsPoint = new Point2D(50, 50);  // UCS coordinates
const wcsPoint = Engine.trans.UcsToWcs(ucsPoint);

// Convert WCS coordinates to UCS
const wcsPoint2 = new Point2D(100, 100);
const ucsPoint2 = Engine.trans.WcsToUcs(wcsPoint2);

DCS (Display Coordinate System)

The display coordinate system is the coordinate system after view transformation (zoom, pan).

Characteristics:

• Affected by view zoom
• Affected by view pan
• Origin at bottom-left corner of view
• Units in pixels

import { Engine, Point2D } from 'vjcad';

// WCS to DCS
const wcsPoint = new Point2D(100, 100);
const dcsPoint = Engine.trans.WcsToDcs(wcsPoint);

// DCS to WCS
const dcsPoint2 = new Point2D(500, 300);
const wcsPoint2 = Engine.trans.DcsToWcs(dcsPoint2);

Canvas (Canvas Coordinates)

Canvas coordinates are the pixel coordinates of the browser Canvas element, with origin at the top-left corner.

Characteristics:

• Origin at top-left corner of Canvas
• Y-axis points down (opposite to WCS/DCS)
• Units in pixels
• Used for handling mouse events

import { Engine, Point2D } from 'vjcad';

// Handle mouse events
canvas.addEventListener('click', (event) => {
  // Get Canvas coordinates
  const canvasPoint = new Point2D(event.offsetX, event.offsetY);
  
  // Convert to WCS coordinates
  const wcsPoint = Engine.trans.CanvasToWcs(canvasPoint);
  console.log(`World coordinates: (${wcsPoint.x}, ${wcsPoint.y})`);
});

Coordinate Conversion

CoordinateTransform Class

The CoordinateTransform class provides all coordinate conversion methods.

import { Engine, CoordinateTransform, Point2D } from 'vjcad';

// Get coordinate transformer
const trans: CoordinateTransform = Engine.trans;

Conversion Method List

Method	Description	Input	Output
WcsToUcs(point)	World to user coordinates	WCS	UCS
UcsToWcs(point)	User to world coordinates	UCS	WCS
WcsToDcs(point)	World to display coordinates	WCS	DCS
DcsToWcs(point)	Display to world coordinates	DCS	WCS
WcsToCanvas(point)	World to canvas coordinates	WCS	Canvas
CanvasToWcs(point)	Canvas to world coordinates	Canvas	WCS
UcsToDcs(point)	User to display coordinates	UCS	DCS
DcsToUcs(point)	Display to user coordinates	DCS	UCS

Complete Conversion Example

import { Engine, Point2D } from 'vjcad';

const trans = Engine.trans;

// Starting point (WCS)
const wcsPoint = new Point2D(100, 100);
console.log('WCS:', wcsPoint.x, wcsPoint.y);

// WCS -> UCS
const ucsPoint = trans.WcsToUcs(wcsPoint);
console.log('UCS:', ucsPoint.x, ucsPoint.y);

// WCS -> DCS
const dcsPoint = trans.WcsToDcs(wcsPoint);
console.log('DCS:', dcsPoint.x, dcsPoint.y);

// WCS -> Canvas
const canvasPoint = trans.WcsToCanvas(wcsPoint);
console.log('Canvas:', canvasPoint.x, canvasPoint.y);

// Reverse conversion
const wcsFromCanvas = trans.CanvasToWcs(canvasPoint);
console.log('WCS (from Canvas):', wcsFromCanvas.x, wcsFromCanvas.y);

Engine Shortcut Methods

The Engine class provides commonly used coordinate conversion shortcut methods:

import { Engine, Point2D } from 'vjcad';

// Canvas to WCS (most common)
const wcsPoint = Engine.canvasToWcs(new Point2D(500, 300));

// WCS to UCS
const ucsPoint = Engine.wcsToUcs(wcsPoint);

// UCS to WCS
const wcsPoint2 = Engine.ucsToWcs(ucsPoint);

// WCS to DCS
const dcsPoint = Engine.wcsToDcs(wcsPoint);

Use Cases

Scenario 1: Handling Mouse Events

import { Engine, Point2D, LineEnt } from 'vjcad';

// Draw line on mouse click
let startPoint: Point2D | null = null;

canvas.addEventListener('click', (event) => {
  // Convert mouse position to WCS
  const canvasPoint = new Point2D(event.offsetX, event.offsetY);
  const wcsPoint = Engine.canvasToWcs(canvasPoint);
  
  if (!startPoint) {
    startPoint = wcsPoint;
  } else {
    // Create line (using WCS coordinates)
    const line = new LineEnt(startPoint, wcsPoint);
    line.setDefaults();
    Engine.addEntities(line);
    startPoint = null;
  }
});

Scenario 2: Getting Entity Bounding Box

import { Engine, EntityBase, BoundingBox, CoordinateSystemType } from 'vjcad';

const entity: EntityBase = /* ... */;

// Get WCS bounding box (for geometric calculation)
const wcsBounds = entity.boundingBox(CoordinateSystemType.WCS);

// Get DCS bounding box (for screen display)
const dcsBounds = entity.boundingBox(CoordinateSystemType.DCS);

// Check if entity is within visible screen range
const screenBounds = /* get screen bounds */;
const isVisible = /* check if dcsBounds intersects screenBounds */;

Scenario 3: Displaying UI Elements at Specific Position

import { Engine, Point2D } from 'vjcad';

// Entity center point (WCS)
const entityCenter = new Point2D(100, 100);

// Convert to Canvas coordinates
const canvasPoint = Engine.trans.WcsToCanvas(entityCenter);

// Display tooltip at this position
showTooltip(canvasPoint.x, canvasPoint.y, 'Entity info');

Scenario 4: Calculating Screen Distance

import { Engine, Point2D } from 'vjcad';

// Two WCS points
const wcsPoint1 = new Point2D(0, 0);
const wcsPoint2 = new Point2D(100, 0);

// Convert to DCS to calculate screen distance
const dcsPoint1 = Engine.wcsToDcs(wcsPoint1);
const dcsPoint2 = Engine.wcsToDcs(wcsPoint2);

const screenDistance = Math.sqrt(
  Math.pow(dcsPoint2.x - dcsPoint1.x, 2) +
  Math.pow(dcsPoint2.y - dcsPoint1.y, 2)
);
console.log('Screen distance (pixels):', screenDistance);

Coordinate System Transformation Diagram

Notes

1. Entity coordinates always use WCS: When creating and storing entities, coordinates must be in WCS.

2. Mouse events use Canvas coordinates: Convert to WCS before processing mouse events.

3. View transform affects DCS: Zoom and pan change the conversion relationship from WCS to DCS.

4. UCS simplifies input: Set UCS when drawing at specific angles.

5. Performance consideration: Frequent coordinate conversion may affect performance; cache conversion results when possible.

// Good practice: cache conversion results
const points = entities.map(e => e.position);
const dcsPoints = points.map(p => Engine.wcsToDcs(p));  // Batch conversion

// Avoid: repeated conversion in loop
for (const entity of entities) {
  // Converting every iteration is inefficient
  const dcs = Engine.wcsToDcs(entity.position);
}

Next Steps

• Undo/Redo - Learn about the undo mechanism
• Point2D - Point operations
• BoundingBox - Bounding box calculation