@tonybfox/threejs-tools 1.0.0

package/dist/terrain/index.d.mts

@@ -0,0 +1,219 @@
+import * as THREE from 'three';
+
+/**
+ * Geographic coordinates
+ */
+interface GeoCoordinates {
+    /** Latitude in degrees */
+    latitude: number;
+    /** Longitude in degrees */
+    longitude: number;
+}
+/**
+ * Terrain dimensions
+ */
+interface TerrainDimensions {
+    /** Width in meters */
+    width: number;
+    /** Depth in meters */
+    depth: number;
+}
+/**
+ * Configuration for fetching satellite imagery from Mapbox
+ */
+interface MapboxTextureOptions {
+    /** Required Mapbox access token */
+    accessToken: string;
+    /** Style identifier (default: mapbox/satellite-v9) */
+    styleId?: string;
+    /** Requested image width in pixels (clamped to Mapbox limits, default: 1024) */
+    imageWidth?: number;
+    /** Requested image height in pixels (clamped to Mapbox limits, default: 1024) */
+    imageHeight?: number;
+    /** Whether to request @2x high-DPI imagery (default: false) */
+    highResolution?: boolean;
+    /** Optional padding factor (0-1) to expand the requested bounds (default: 0.1) */
+    paddingRatio?: number;
+    /** Override imagery format (default: png). jpg is smaller but lossy. */
+    imageFormat?: 'png' | 'jpg';
+}
+/**
+ * Configuration options for the terrain tool
+ */
+interface TerrainToolOptions {
+    /** Number of width segments for the terrain mesh (default: 50) */
+    widthSegments?: number;
+    /** Number of depth segments for the terrain mesh (default: 50) */
+    depthSegments?: number;
+    /** Vertical exaggeration factor for elevation (default: 1.0) */
+    elevationScale?: number;
+    /** Base material color (default: 0x8B7355) */
+    baseColor?: number;
+    /** Whether to enable wireframe mode (default: false) */
+    wireframe?: boolean;
+    /** Texture URL for imagery overlay (optional) */
+    textureUrl?: string;
+    /** Automatically fetch Mapbox satellite imagery for the current bounds */
+    mapbox?: MapboxTextureOptions;
+    /** Whether to receive shadows (default: true) */
+    receiveShadow?: boolean;
+    /** Whether to cast shadows (default: true) */
+    castShadow?: boolean;
+    /** Use demo/synthetic data instead of API (default: false) */
+    useDemoData?: boolean;
+}
+/**
+ * Elevation data point from API
+ */
+interface ElevationPoint {
+    /** Latitude */
+    latitude: number;
+    /** Longitude */
+    longitude: number;
+    /** Elevation in meters */
+    elevation: number;
+}
+/**
+ * Terrain data returned by the API
+ */
+interface TerrainData {
+    /** Center coordinates */
+    center: GeoCoordinates;
+    /** Dimensions */
+    dimensions: TerrainDimensions;
+    /** Grid of elevation points */
+    elevations: number[][];
+    /** Minimum elevation in the dataset */
+    minElevation: number;
+    /** Maximum elevation in the dataset */
+    maxElevation: number;
+}
+/**
+ * Event types dispatched by the terrain tool
+ */
+interface TerrainToolEvents {
+    /** Dispatched when terrain data has been fetched */
+    dataLoaded: {
+        data: TerrainData;
+    };
+    /** Dispatched when the terrain mesh has been created and added to the scene */
+    meshLoaded: {
+        mesh: THREE.Mesh;
+    };
+    /** Dispatched when terrain update starts */
+    updateStarted: {
+        center: GeoCoordinates;
+        dimensions: TerrainDimensions;
+    };
+    /** Dispatched when an error occurs */
+    error: {
+        message: string;
+        error: Error;
+    };
+}
+
+/**
+ * Terrain mesh creator for Three.js scenes
+ * Fetches elevation data from Open-Elevation API and creates 3D terrain meshes
+ *
+ * @example
+ * ```javascript
+ * const terrainTool = new TerrainTool(scene, {
+ *   widthSegments: 100,
+ *   depthSegments: 100,
+ *   elevationScale: 2.0,
+ *   useDemoData: false // Set to true for demo/testing without API
+ * })
+ *
+ * // Listen for events
+ * terrainTool.addEventListener('dataLoaded', (e) => {
+ *   console.log('Terrain data loaded:', e.data)
+ * })
+ *
+ * terrainTool.addEventListener('meshLoaded', (e) => {
+ *   console.log('Terrain mesh created:', e.mesh)
+ * })
+ *
+ * // Load terrain for a location
+ * terrainTool.loadTerrain(
+ *   { latitude: 36.1699, longitude: -115.1398 }, // Las Vegas
+ *   { width: 5000, depth: 5000 } // 5km x 5km
+ * )
+ * ```
+ */
+declare class TerrainTool extends THREE.EventDispatcher<TerrainToolEvents> {
+    private scene;
+    private mesh;
+    private currentData;
+    private isLoading;
+    private mapboxOptions?;
+    private generatedTextureUrls;
+    widthSegments: number;
+    depthSegments: number;
+    elevationScale: number;
+    baseColor: number;
+    wireframe: boolean;
+    textureUrl: string | undefined;
+    receiveShadow: boolean;
+    castShadow: boolean;
+    useDemoData: boolean;
+    /**
+     * Creates a new TerrainTool instance
+     * @param scene - The Three.js scene to add terrain to
+     * @param options - Configuration options
+     */
+    constructor(scene: THREE.Scene, options?: TerrainToolOptions);
+    /**
+     * Update Mapbox imagery configuration at runtime
+     */
+    setMapboxOptions(options?: MapboxTextureOptions): void;
+    /**
+     * Loads terrain data and creates a mesh
+     * @param center - Center coordinates (latitude, longitude)
+     * @param dimensions - Terrain dimensions in meters
+     */
+    loadTerrain(center: GeoCoordinates, dimensions: TerrainDimensions): Promise<void>;
+    /**
+     * Updates the terrain with new coordinates and/or dimensions
+     * @param center - New center coordinates (optional, keeps current if not provided)
+     * @param dimensions - New dimensions (optional, keeps current if not provided)
+     */
+    updateTerrain(center?: GeoCoordinates, dimensions?: TerrainDimensions): Promise<void>;
+    /**
+     * Fetches elevation data from Open-Elevation API or generates demo data
+     * @private
+     */
+    private fetchElevationData;
+    /**
+     * Generates demo terrain data using perlin-like noise
+     * @private
+     */
+    private generateDemoData;
+    /**
+     * Creates a terrain mesh from elevation data
+     * @private
+     */
+    private createMesh;
+    private resolveTexture;
+    private computeBoundingBox;
+    private fetchMapboxTexture;
+    private releaseGeneratedTexture;
+    /**
+     * Gets the current terrain mesh
+     */
+    getMesh(): THREE.Mesh | null;
+    /**
+     * Gets the current terrain data
+     */
+    getData(): TerrainData | null;
+    /**
+     * Checks if terrain is currently loading
+     */
+    isTerrainLoading(): boolean;
+    /**
+     * Disposes of all resources
+     */
+    dispose(): void;
+}
+
+export { type ElevationPoint, type GeoCoordinates, type TerrainData, type TerrainDimensions, TerrainTool, type TerrainToolEvents, type TerrainToolOptions };

package/dist/terrain/index.d.ts

@@ -0,0 +1,219 @@
+import * as THREE from 'three';
+
+/**
+ * Geographic coordinates
+ */
+interface GeoCoordinates {
+    /** Latitude in degrees */
+    latitude: number;
+    /** Longitude in degrees */
+    longitude: number;
+}
+/**
+ * Terrain dimensions
+ */
+interface TerrainDimensions {
+    /** Width in meters */
+    width: number;
+    /** Depth in meters */
+    depth: number;
+}
+/**
+ * Configuration for fetching satellite imagery from Mapbox
+ */
+interface MapboxTextureOptions {
+    /** Required Mapbox access token */
+    accessToken: string;
+    /** Style identifier (default: mapbox/satellite-v9) */
+    styleId?: string;
+    /** Requested image width in pixels (clamped to Mapbox limits, default: 1024) */
+    imageWidth?: number;
+    /** Requested image height in pixels (clamped to Mapbox limits, default: 1024) */
+    imageHeight?: number;
+    /** Whether to request @2x high-DPI imagery (default: false) */
+    highResolution?: boolean;
+    /** Optional padding factor (0-1) to expand the requested bounds (default: 0.1) */
+    paddingRatio?: number;
+    /** Override imagery format (default: png). jpg is smaller but lossy. */
+    imageFormat?: 'png' | 'jpg';
+}
+/**
+ * Configuration options for the terrain tool
+ */
+interface TerrainToolOptions {
+    /** Number of width segments for the terrain mesh (default: 50) */
+    widthSegments?: number;
+    /** Number of depth segments for the terrain mesh (default: 50) */
+    depthSegments?: number;
+    /** Vertical exaggeration factor for elevation (default: 1.0) */
+    elevationScale?: number;
+    /** Base material color (default: 0x8B7355) */
+    baseColor?: number;
+    /** Whether to enable wireframe mode (default: false) */
+    wireframe?: boolean;
+    /** Texture URL for imagery overlay (optional) */
+    textureUrl?: string;
+    /** Automatically fetch Mapbox satellite imagery for the current bounds */
+    mapbox?: MapboxTextureOptions;
+    /** Whether to receive shadows (default: true) */
+    receiveShadow?: boolean;
+    /** Whether to cast shadows (default: true) */
+    castShadow?: boolean;
+    /** Use demo/synthetic data instead of API (default: false) */
+    useDemoData?: boolean;
+}
+/**
+ * Elevation data point from API
+ */
+interface ElevationPoint {
+    /** Latitude */
+    latitude: number;
+    /** Longitude */
+    longitude: number;
+    /** Elevation in meters */
+    elevation: number;
+}
+/**
+ * Terrain data returned by the API
+ */
+interface TerrainData {
+    /** Center coordinates */
+    center: GeoCoordinates;
+    /** Dimensions */
+    dimensions: TerrainDimensions;
+    /** Grid of elevation points */
+    elevations: number[][];
+    /** Minimum elevation in the dataset */
+    minElevation: number;
+    /** Maximum elevation in the dataset */
+    maxElevation: number;
+}
+/**
+ * Event types dispatched by the terrain tool
+ */
+interface TerrainToolEvents {
+    /** Dispatched when terrain data has been fetched */
+    dataLoaded: {
+        data: TerrainData;
+    };
+    /** Dispatched when the terrain mesh has been created and added to the scene */
+    meshLoaded: {
+        mesh: THREE.Mesh;
+    };
+    /** Dispatched when terrain update starts */
+    updateStarted: {
+        center: GeoCoordinates;
+        dimensions: TerrainDimensions;
+    };
+    /** Dispatched when an error occurs */
+    error: {
+        message: string;
+        error: Error;
+    };
+}
+
+/**
+ * Terrain mesh creator for Three.js scenes
+ * Fetches elevation data from Open-Elevation API and creates 3D terrain meshes
+ *
+ * @example
+ * ```javascript
+ * const terrainTool = new TerrainTool(scene, {
+ *   widthSegments: 100,
+ *   depthSegments: 100,
+ *   elevationScale: 2.0,
+ *   useDemoData: false // Set to true for demo/testing without API
+ * })
+ *
+ * // Listen for events
+ * terrainTool.addEventListener('dataLoaded', (e) => {
+ *   console.log('Terrain data loaded:', e.data)
+ * })
+ *
+ * terrainTool.addEventListener('meshLoaded', (e) => {
+ *   console.log('Terrain mesh created:', e.mesh)
+ * })
+ *
+ * // Load terrain for a location
+ * terrainTool.loadTerrain(
+ *   { latitude: 36.1699, longitude: -115.1398 }, // Las Vegas
+ *   { width: 5000, depth: 5000 } // 5km x 5km
+ * )
+ * ```
+ */
+declare class TerrainTool extends THREE.EventDispatcher<TerrainToolEvents> {
+    private scene;
+    private mesh;
+    private currentData;
+    private isLoading;
+    private mapboxOptions?;
+    private generatedTextureUrls;
+    widthSegments: number;
+    depthSegments: number;
+    elevationScale: number;
+    baseColor: number;
+    wireframe: boolean;
+    textureUrl: string | undefined;
+    receiveShadow: boolean;
+    castShadow: boolean;
+    useDemoData: boolean;
+    /**
+     * Creates a new TerrainTool instance
+     * @param scene - The Three.js scene to add terrain to
+     * @param options - Configuration options
+     */
+    constructor(scene: THREE.Scene, options?: TerrainToolOptions);
+    /**
+     * Update Mapbox imagery configuration at runtime
+     */
+    setMapboxOptions(options?: MapboxTextureOptions): void;
+    /**
+     * Loads terrain data and creates a mesh
+     * @param center - Center coordinates (latitude, longitude)
+     * @param dimensions - Terrain dimensions in meters
+     */
+    loadTerrain(center: GeoCoordinates, dimensions: TerrainDimensions): Promise<void>;
+    /**
+     * Updates the terrain with new coordinates and/or dimensions
+     * @param center - New center coordinates (optional, keeps current if not provided)
+     * @param dimensions - New dimensions (optional, keeps current if not provided)
+     */
+    updateTerrain(center?: GeoCoordinates, dimensions?: TerrainDimensions): Promise<void>;
+    /**
+     * Fetches elevation data from Open-Elevation API or generates demo data
+     * @private
+     */
+    private fetchElevationData;
+    /**
+     * Generates demo terrain data using perlin-like noise
+     * @private
+     */
+    private generateDemoData;
+    /**
+     * Creates a terrain mesh from elevation data
+     * @private
+     */
+    private createMesh;
+    private resolveTexture;
+    private computeBoundingBox;
+    private fetchMapboxTexture;
+    private releaseGeneratedTexture;
+    /**
+     * Gets the current terrain mesh
+     */
+    getMesh(): THREE.Mesh | null;
+    /**
+     * Gets the current terrain data
+     */
+    getData(): TerrainData | null;
+    /**
+     * Checks if terrain is currently loading
+     */
+    isTerrainLoading(): boolean;
+    /**
+     * Disposes of all resources
+     */
+    dispose(): void;
+}
+
+export { type ElevationPoint, type GeoCoordinates, type TerrainData, type TerrainDimensions, TerrainTool, type TerrainToolEvents, type TerrainToolOptions };

package/dist/terrain/index.mjs

@@ -0,0 +1,7 @@
+import {
+  TerrainTool
+} from "../chunk-EIROAPF7.mjs";
+export {
+  TerrainTool
+};
+//# sourceMappingURL=index.mjs.map

package/dist/terrain/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}