gl-enu

A high-performance library for generating ENU (East-North-Up) orthonormal bases, optimized for WebGL and real-time graphics projects. It supports ESM, CJS, and IIFE module formats to fit all development environments, producing unit orthogonal vectors (East, North, Up) from geographic coordinates (latitude/longitude).

Features

• Multi-Module Support: Works with ESM (for bundlers like Vite/Webpack), CJS (for Node.js), and IIFE (for vanilla browser use, global name: glenu).
• Extreme Performance: Inline calculations, hardcoded radian conversion factors, and no redundant calls—ideal for high-frequency rendering.
• WebGL-Optimized: Native Float32Array support matches GPU single-precision requirements, avoiding type conversion overhead.
• Type Safety: Full TypeScript declarations for autocompletion and compile-time validation.
• Lightweight: <2KB minified, no dependencies.

Installation

# Install via npm
npm install gl-enu --save

# Install via yarn
yarn add gl-enu

Quick Start

Choose the usage example that matches your environment:

1. ESM (Webpack/Vite/Modern Browsers)

Use with bundlers (Vite, Webpack) or modern browsers that support ES modules:

// Import specific functions or all exports
import { getENU32 } from 'gl-enu';
// Or import from the ESM entry directly: import { getENU32 } from 'gl-enu/dist/esm/index.js'

// Generate WebGL-compatible ENU basis (Beijing: 116.4074°E, 39.9042°N)
const enuBasis = getENU32(116.4074, 39.9042);
const [east, north, up] = enuBasis;

// Project ECEF vector to ENU (for WebGL rendering)
const ecefVec = new Float32Array([1000, 2000, 3000]);
const enuVec = new Float32Array(3);

enuVec[0] = ecefVec[0] * east[0] + ecefVec[1] * east[1] + ecefVec[2] * east[2]; // East component
enuVec[1] = ecefVec[0] * north[0] + ecefVec[1] * north[1] + ecefVec[2] * north[2]; // North component
enuVec[2] = ecefVec[0] * up[0] + ecefVec[1] * up[1] + ecefVec[2] * up[2]; // Up component

console.log('ENU Vector (ESM):', enuVec);

2. CJS (Node.js)

Use in Node.js environments (e.g., server-side geospatial processing):

// Require the CJS module
const { getENU64 } = require('gl-enu');
// Or require from the CJS entry directly: const { getENU64 } = require('gl-enu/dist/cjs/index.js')

// Generate high-precision ENU basis (New York: -74.0060°W, 40.7128°N)
const enuBasis = getENU64(-74.0060, 40.7128);
const [east, north, up] = enuBasis;

console.log('East Vector (CJS):', east); // Float64Array([x, y, z])

3. IIFE (Vanilla Browser)

Use in vanilla HTML/JS without bundlers—access via the global glenu object:

<!-- Load the IIFE file (host locally or use a CDN) -->
<script src="node_modules/gl-enu/dist/index.global.js"></script>
<!-- Or use a CDN (replace with your preferred CDN link) -->
<!-- <script src="https://unpkg.com/gl-enu@latest/dist/index.global.js"></script> -->

<script>
  // Use the global `glenu` object
  const enuBasis = glenu.getENU(116.4074, 39.9042); // Array-based ENU basis
  const [east, north, up] = enuBasis;

  console.log('North Vector (IIFE):', north); // [x, y, z] array
</script>

API Reference

All functions work across ESM/CJS/IIFE formats (adjust import/access syntax as needed):

1. getENU(longitude: number, latitude: number): [number[], number[], number[]]

Generates an ENU basis using standard Array (general-purpose use).

• Parameters:
  • longitude: Longitude in degrees (valid range: -180 to 180).
  • latitude: Latitude in degrees (valid range: -90 to 90).
• Returns:
  Tuple [east, north, up] → each element is a [x, y, z] array (unit orthogonal vectors).

2. getENU32(longitude: number, latitude: number): [Float32Array, Float32Array, Float32Array]

Generates an ENU basis using Float32Array (WebGL/GPU optimization).

• Parameters: Same as getENU.
• Returns:
  Tuple [east, north, up] → each element is a Float32Array(3) (ideal for WebGL uniforms/buffers).

3. getENU64(longitude: number, latitude: number): [Float64Array, Float64Array, Float64Array]

Generates an ENU basis using Float64Array (high-precision calculations).

• Parameters: Same as getENU.
• Returns:
  Tuple [east, north, up] → each element is a Float64Array(3) (minimizes numerical error for geospatial/physics tasks).

Performance Benchmarks

| Function | Throughput (Single Thread) | Use Case | |------------|-----------------------------|---------------------------| | getENU | ~12 million calls/sec | General computing | | getENU32 | ~9.5 million calls/sec | WebGL/real-time rendering | | getENU64 | ~9.2 million calls/sec | High-precision geospatial |

Benchmark environment: Node.js 20.10.0, Intel Core i7-12700H (14 cores)

Usage Notes

1. Coordinate Validity: Ensure longitude (-180→180) and latitude (-90→90) are valid. Out-of-range values produce mathematically orthogonal vectors but invalid geographic meaning.
2. WebGL Integration: Pair getENU32 with libraries like gl-transform to convert between ECEF (world) and ENU (local) space for rendering.
3. Browser Support:
   • ESM: Chrome 61+, Firefox 60+, Safari 11.1+.
   • IIFE: All modern browsers (IE11+ with polyfills for Float32Array/Float64Array).

License

MIT License