Coordinate Systems

/**
 * Coordinate system enumeration
 * Defines how layer data positions and dimensions are interpreted
 */
const COORDINATE_SYSTEM: {
  /** Auto-detect based on viewport type (LNGLAT for geospatial, CARTESIAN otherwise) */
  readonly DEFAULT: -1;
  
  /** Cartesian coordinates - positions and dimensions in common space units */
  readonly CARTESIAN: 0;
  
  /** Longitude/latitude coordinates - [longitude, latitude, elevation] in degrees/meters */
  readonly LNGLAT: 1;
  
  /** Meter offsets - [x, y, z] in meter offsets from coordinate origin */
  readonly METER_OFFSETS: 2;
  
  /** Longitude/latitude offsets - [deltaLng, deltaLat, elevation] in degrees/meters from origin */
  readonly LNGLAT_OFFSETS: 3;
};

type CoordinateSystem = -1 | 0 | 1 | 2 | 3;

import { ScatterplotLayer, COORDINATE_SYSTEM } from "@deck.gl/core";

// Geographic data using longitude/latitude
const geoLayer = new ScatterplotLayer({
  id: 'cities',
  data: cityData,
  getPosition: d => [d.longitude, d.latitude, 0],
  getRadius: 50000, // 50km in meters
  coordinateSystem: COORDINATE_SYSTEM.LNGLAT
});

// Local coordinate system for CAD/engineering data  
const cadLayer = new ScatterplotLayer({
  id: 'cad-points',
  data: cadData,
  getPosition: d => [d.x, d.y, d.z],
  getRadius: 10, // 10 units in common space
  coordinateSystem: COORDINATE_SYSTEM.CARTESIAN
});

// Offset-based positioning from a reference point
const offsetLayer = new ScatterplotLayer({
  id: 'sensor-data',
  data: sensorData,
  getPosition: d => [d.deltaX, d.deltaY, d.elevation],
  coordinateSystem: COORDINATE_SYSTEM.METER_OFFSETS,
  coordinateOrigin: [-122.4, 37.8, 0] // Reference point
});

/**
 * Unit enumeration for measurements
 * Defines the units for various measurements and calculations
 */
const UNIT: {
  /** Common space units (viewport-dependent) */
  readonly common: 0;
  
  /** Meter units */
  readonly meters: 1;
  
  /** Pixel units */
  readonly pixels: 2;
};

type Unit = 0 | 1 | 2;

import { LineLayer, UNIT } from "@deck.gl/core";

// Line widths in different units
const roadLayer = new LineLayer({
  id: 'roads',
  data: roadData,
  getSourcePosition: d => d.startCoord,
  getTargetPosition: d => d.endCoord,
  getWidth: d => d.widthInMeters,
  widthUnits: UNIT.meters, // Width specified in meters
  widthScale: 1
});

const pixelLineLayer = new LineLayer({
  id: 'ui-lines',
  data: uiData,
  getSourcePosition: d => d.start,
  getTargetPosition: d => d.end, 
  getWidth: 2,
  widthUnits: UNIT.pixels, // Always 2 pixels wide
  widthScale: 1
});

/**
 * Operation enumeration for layer rendering
 * Defines different rendering operation types
 */
const OPERATION: {
  /** Standard drawing operation */
  readonly DRAW: "draw";
  
  /** Masking operation (for clipping/stencil) */
  readonly MASK: "mask";
  
  /** Terrain rendering operation */
  readonly TERRAIN: "terrain";
};

type Operation = "draw" | "mask" | "terrain";

import { PolygonLayer, OPERATION } from "@deck.gl/core";

// Regular drawing
const buildingsLayer = new PolygonLayer({
  id: 'buildings',
  data: buildingData,
  operation: OPERATION.DRAW
});

// Masking layer to clip other layers
const boundaryLayer = new PolygonLayer({
  id: 'city-boundary',
  data: boundaryData,
  operation: OPERATION.MASK,
  visible: false // Invisible mask
});

// Terrain-specific rendering
const terrainLayer = new PolygonLayer({
  id: 'terrain',
  data: terrainData,
  operation: OPERATION.TERRAIN
});

/**
 * Project world coordinates to screen space
 * Handles different coordinate systems and projections
 * @param xyz - World coordinates [x, y, z]
 * @param opts - Projection options
 * @returns Screen coordinates [x, y, z]
 */
declare function projectPosition(
  xyz: [number, number, number],
  opts?: {
    viewport?: Viewport;
    coordinateSystem?: CoordinateSystem;
    coordinateOrigin?: [number, number, number];
    fromCoordinateSystem?: CoordinateSystem;
    fromCoordinateOrigin?: [number, number, number];
  }
): [number, number, number];

/**
 * Get world position from common coordinates
 * @param position - Position in common coordinate system
 * @param opts - Transformation options
 * @returns World coordinates
 */
declare function getWorldPosition(
  position: [number, number, number],
  opts?: {
    viewport?: Viewport;
    coordinateSystem?: CoordinateSystem;
    coordinateOrigin?: [number, number, number];
    fromCoordinateSystem?: CoordinateSystem;
    fromCoordinateOrigin?: [number, number, number];
  }
): [number, number, number];

import { projectPosition, getWorldPosition } from "@deck.gl/core";

// Transform coordinates between systems
const transformCoordinates = (layer, viewport) => {
  const data = layer.props.data;
  
  const transformedData = data.map(d => {
    // Project to common space
    const commonPos = projectPosition(
      [d.longitude, d.latitude, d.elevation],
      {
        viewport,
        coordinateSystem: COORDINATE_SYSTEM.LNGLAT,
        coordinateOrigin: [0, 0, 0]
      }
    );
    
    // Convert to meter offsets
    const offsetPos = getWorldPosition(commonPos, {
      viewport,
      coordinateSystem: COORDINATE_SYSTEM.METER_OFFSETS,
      coordinateOrigin: [-122.4, 37.8, 0]
    });
    
    return {
      ...d,
      offsetPosition: offsetPos
    };
  });
  
  return transformedData;
};

interface CoordinateSystemUtils {
  /** Convert between coordinate systems */
  convertCoordinates(
    coordinates: number[],
    fromSystem: CoordinateSystem,
    toSystem: CoordinateSystem,
    opts?: {
      viewport?: Viewport;
      origin?: [number, number, number];
    }
  ): number[];
  
  /** Get appropriate coordinate system for viewport */
  getDefaultCoordinateSystem(viewport: Viewport): CoordinateSystem;
  
  /** Validate coordinate system compatibility */
  isCompatible(
    coordinateSystem: CoordinateSystem,
    viewport: Viewport
  ): boolean;
  
  /** Get coordinate bounds for system */
  getCoordinateBounds(coordinateSystem: CoordinateSystem): {
    min: [number, number, number];
    max: [number, number, number];
  };
}

interface GeographicCoordinateSystem {
  /** WGS84 (World Geodetic System 1984) - Standard GPS coordinates */
  WGS84: {
    datum: "WGS84";
    ellipsoid: "WGS84";
    primeMeridian: 0;
    units: "degrees";
  };
  
  /** Web Mercator (EPSG:3857) - Web mapping standard */
  WEB_MERCATOR: {
    datum: "WGS84";
    projection: "Mercator";
    centralMeridian: 0;
    units: "meters";
  };
  
  /** UTM (Universal Transverse Mercator) zones */
  UTM: {
    getZone(longitude: number, latitude: number): number;
    project(longitude: number, latitude: number, zone: number): [number, number];
    unproject(x: number, y: number, zone: number): [number, number];
  };
}

// Working with different geographic coordinate systems
const gpsData = [
  {id: 1, lat: 37.7749, lng: -122.4194}, // San Francisco
  {id: 2, lat: 40.7128, lng: -74.0060},  // New York
  {id: 3, lat: 51.5074, lng: -0.1278}    // London
];

// Convert GPS coordinates to Web Mercator
const webMercatorData = gpsData.map(point => {
  const [x, y] = geographic.WEB_MERCATOR.project(point.lng, point.lat);
  return {
    ...point,
    webMercatorX: x,
    webMercatorY: y
  };
});

// Create layer with proper coordinate system
const globalPointsLayer = new ScatterplotLayer({
  id: 'global-points',
  data: gpsData,
  getPosition: d => [d.lng, d.lat, 0],
  coordinateSystem: COORDINATE_SYSTEM.LNGLAT,
  getRadius: 100000, // 100km radius
  radiusUnits: UNIT.meters
});

interface CoordinateOriginSystem {
  /** Set global coordinate origin */
  setOrigin(origin: [number, number, number]): void;
  
  /** Get current coordinate origin */
  getOrigin(): [number, number, number];
  
  /** Transform coordinates relative to origin */
  toOriginSpace(coordinates: [number, number, number]): [number, number, number];
  
  /** Transform coordinates from origin space */
  fromOriginSpace(coordinates: [number, number, number]): [number, number, number];
  
  /** Calculate offset between two origins */
  getOffset(
    fromOrigin: [number, number, number],
    toOrigin: [number, number, number]
  ): [number, number, number];
}

// High-precision positioning with coordinate origins
const precisionLayer = new ScatterplotLayer({
  id: 'precision-sensors',
  data: sensorData,
  
  // Use meter offsets for high precision
  coordinateSystem: COORDINATE_SYSTEM.METER_OFFSETS,
  
  // Set origin at sensor array center
  coordinateOrigin: [-122.419416, 37.774929, 0],
  
  // Positions are offsets in meters from origin
  getPosition: d => [d.offsetX, d.offsetY, d.offsetZ],
  
  // Radius in meters
  getRadius: 1.0,
  radiusUnits: UNIT.meters
});

// Multiple coordinate systems in one visualization
const multiSystemLayers = [
  // Global reference layer (GPS coordinates)
  new ScatterplotLayer({
    id: 'cities',
    data: cityData,
    coordinateSystem: COORDINATE_SYSTEM.LNGLAT,
    getPosition: d => [d.longitude, d.latitude, 0],
    getRadius: 50000
  }),
  
  // Local detail layer (meter offsets)
  new ScatterplotLayer({
    id: 'local-details',
    data: localData,
    coordinateSystem: COORDINATE_SYSTEM.METER_OFFSETS,
    coordinateOrigin: [-122.4, 37.8, 0],
    getPosition: d => [d.deltaX, d.deltaY, d.deltaZ],
    getRadius: 10
  }),
  
  // UI overlay layer (cartesian)
  new ScatterplotLayer({
    id: 'ui-elements',
    data: uiData,
    coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
    getPosition: d => [d.screenX, d.screenY, 0],
    getRadius: 5,
    radiusUnits: UNIT.pixels
  })
];

interface CoordinatePerformanceOptions {
  /** Cache coordinate transformations */
  cacheTransforms?: boolean;
  
  /** Batch coordinate calculations */
  batchSize?: number;
  
  /** Use pre-computed coordinate arrays */
  precomputed?: boolean;
  
  /** Precision level for calculations */
  precision?: 'single' | 'double';
  
  /** Coordinate bounds for culling */
  bounds?: [[number, number], [number, number]];
}

// Optimized coordinate handling for large datasets
const optimizedLayer = new ScatterplotLayer({
  id: 'million-points',
  data: millionPointsData,
  
  coordinateSystem: COORDINATE_SYSTEM.LNGLAT,
  getPosition: d => d.coordinates, // Pre-computed coordinates
  
  // Performance optimizations
  updateTriggers: {
    getPosition: [] // Static positions, no updates
  },
  
  // Coordinate bounds for culling
  bounds: [[-180, -90], [180, 90]],
  
  // GPU-optimized rendering
  parameters: {
    coordinatePerformance: {
      cacheTransforms: true,
      batchSize: 10000,
      precomputed: true,
      precision: 'single'
    }
  }
});

// Efficient coordinate system switching
const switchCoordinateSystem = (layer, newSystem) => {
  // Pre-transform coordinates if switching frequently
  if (newSystem !== layer.props.coordinateSystem) {
    const transformedData = layer.props.data.map(d => ({
      ...d,
      transformedPosition: convertCoordinates(
        d.originalPosition,
        layer.props.coordinateSystem,
        newSystem
      )
    }));
    
    layer.setProps({
      data: transformedData,
      coordinateSystem: newSystem,
      getPosition: d => d.transformedPosition
    });
  }
};