DTED Toolkit

A JavaScript library for working with DTED (Digital Terrain Elevation Data). Provides elevation lookup and line-of-sight calculations with terrain profile analysis.

Features

• Elevation Lookup: Get elevation data for any geographic coordinate
• Line of Sight Analysis: Determine if there's line of sight between two points accounting for terrain and Earth's curvature
• Performance Optimized: Built-in LRU caching for DTED files
• Async/Await: Modern asynchronous API
• No External Services: Works entirely offline with local DTED files

Installation

npm install dted-toolkit

Quick Start

const { getElevation, calculateLineOfSight } = require('dted-toolkit');
const path = require('path');

// Path to your DTED data directory
const dtedPath = path.join(__dirname, 'DTED');

// Get elevation at a point
async function example() {
  try {
    // Get elevation for San Francisco
    const elevation = await getElevation(dtedPath, 37.7749, -122.4194);
    console.log(`Elevation: ${elevation.elevation}m`);

    // Check line of sight between two points
    const los = await calculateLineOfSight(
      dtedPath,
      37.7749, -122.4194,  // Point 1: San Francisco
      37.8044, -122.2712,  // Point 2: Oakland
      2, 2                 // Heights above ground (meters)
    );

    console.log(`Has line of sight: ${los.hasLineOfSight}`);
    console.log(`Distance: ${los.distance}m`);

    if (los.obstruction) {
      console.log(`Blocked by terrain at ${los.obstruction.distanceFromStart}m`);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}

example();

API Reference

getElevation(dtedBasePath, latitude, longitude)

Get elevation at a specific coordinate.

Parameters:

• dtedBasePath (string): Path to your DTED data directory
• latitude (number): Latitude in decimal degrees (-90 to 90)
• longitude (number): Longitude in decimal degrees (-180 to 180)

Returns: Promise

{
  latitude: 37.7749,
  longitude: -122.4194,
  elevation: 16.5,        // meters above sea level
  unit: 'meters',
  source: 'DTED Level 2'
}

Example:

const result = await getElevation('/path/to/DTED', 37.7749, -122.4194);
console.log(`Elevation: ${result.elevation}m`);

calculateLineOfSight(dtedBasePath, lat1, lon1, lat2, lon2, height1, height2)

Calculate line of sight between two points using terrain profile analysis.

Parameters:

• dtedBasePath (string): Path to your DTED data directory
• lat1 (number): First point latitude
• lon1 (number): First point longitude
• lat2 (number): Second point latitude
• lon2 (number): Second point longitude
• height1 (number, optional): Height above ground at point 1 in meters (default: 2)
• height2 (number, optional): Height above ground at point 2 in meters (default: 2)

Returns: Promise

{
  hasLineOfSight: true,
  distance: 12500.5,      // meters
  point1: {
    latitude: 37.7749,
    longitude: -122.4194,
    elevation: 10.0,      // ground elevation
    heightAboveGround: 2
  },
  point2: {
    latitude: 37.8044,
    longitude: -122.2712,
    elevation: 15.0,
    heightAboveGround: 2
  },
  samplesAnalyzed: 100,
  obstruction: {          // Only present if blocked
    location: {
      latitude: 37.79,
      longitude: -122.35
    },
    elevation: 50.0,
    obstructionHeight: 5.5,
    distanceFromStart: 6250.0
  }
}

Example:

const result = await calculateLineOfSight(
  '/path/to/DTED',
  37.7749, -122.4194,
  37.8044, -122.2712,
  10, 10  // 10m antenna heights
);

if (result.hasLineOfSight) {
  console.log('Clear line of sight!');
} else if (result.obstruction) {
  console.log(`Blocked at ${result.obstruction.distanceFromStart}m`);
}

calculateHorizonDistance(height)

Calculate the distance to the horizon from a given height, accounting for atmospheric refraction.

Parameters:

• height (number): Height above ground in meters

Returns: number - Distance to horizon in meters

Example:

const { calculateHorizonDistance } = require('dted-toolkit');
const distance = calculateHorizonDistance(100);
console.log(`Horizon at ${distance}m`);

DTED Data

What is DTED?

DTED (Digital Terrain Elevation Data) is a standard format for storing elevation data. This library supports DTED Level 2 files.

Directory Structure

Your DTED files should be organized in this structure:

DTED/
└── DTED/
    ├── E000/
    │   ├── N00.DT2
    │   ├── N01.DT2
    │   └── ...
    ├── E001/
    │   └── ...
    └── ...

Where:

• Exxx directories represent longitude (E for East, W for West)
• Nxx.DT2 files represent latitude (N for North, S for South)
• Each file covers a 1°x1° area

Obtaining DTED Data

DTED data can be obtained from various sources:

• USGS Earth Explorer
• NGA (National Geospatial-Intelligence Agency)
• OpenTopography

Note: Some DTED datasets may have usage restrictions. Check licensing before use.

Performance

Caching

The toolkit uses an LRU (Least Recently Used) cache to keep up to 20 DTED files in memory, significantly improving performance for repeated queries in the same geographic area.

Cache configuration:

• Max files: 20 (configurable)
• TTL: 30 minutes
• Auto-eviction when capacity reached

Line of Sight Optimization

Line of sight calculations use:

• Parallel elevation sampling: Fetches multiple elevations concurrently
• Early termination: Stops when obstruction is found
• Batch processing: Processes samples in batches of 20

Error Handling

The toolkit throws descriptive errors for common issues:

try {
  const result = await getElevation('/path/to/DTED', 37.7749, -122.4194);
} catch (error) {
  if (error.message.includes('DTED file not found')) {
    console.error('No DTED data for this location');
  } else if (error.message.includes('outside this DTED file')) {
    console.error('Coordinates out of bounds');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Advanced Usage

Direct Module Access

For advanced use cases, you can access the full modules:

const { dtedParser, lineOfSightCalculator } = require('dted-toolkit');

// Access cache statistics
const stats = dtedParser.getCacheStats();
console.log(`Cached files: ${stats.itemCount}/${stats.max}`);

// Clear the cache
dtedParser.clearCache();

// Parse UHL header directly
const metadata = dtedParser.parseUHL(buffer);

Custom Sample Count

Adjust the number of terrain samples for line of sight calculations:

// Default: 100 samples
const result = await calculateLineOfSight(
  dtedPath, lat1, lon1, lat2, lon2,
  2, 2, 200  // 200 samples for higher accuracy
);

Requirements

• Node.js >= 14.0.0
• DTED Level 2 data files

Dependencies

• @turf/along - Geographic distance calculations
• @turf/distance - Point distance calculations
• @turf/helpers - Geographic helpers
• lru-cache - File caching

Contributing

Contributions are welcome! Please ensure:

• All tests pass: npm test
• Code follows existing style
• New features include tests and documentation

License

MIT License - see LICENSE file for details

Related Projects

• eleven-api - REST API service using dted-toolkit

Support

For bugs and feature requests, please open an issue.