# gl-enu

**Repository Path**: nodets/gl-enu

## Basic Information

- **Project Name**: gl-enu
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-19
- **Last Updated**: 2025-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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
```bash
# 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:
```typescript
// 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):
```javascript
// 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:
```html
<!-- 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