@giro3d/giro3d
Version:
A JS/WebGL framework for 3D geospatial data visualization
344 lines • 13.8 kB
TypeScript
import { Vector2, type Vector2Like, Vector3, type Vector3Like } from 'three';
import CoordinateSystem from './CoordinateSystem';
/**
* A geographic coordinate expressed in degrees, minutes, seconds.
*/
export interface DMS {
degrees: number;
minutes?: number;
seconds?: number;
}
export declare function parseDMS(dms: DMS): number;
/**
* Represents coordinates associated with a {@link CoordinateSystem | coordinate reference system (CRS)}.
* The exact semantics of the values in the coordinates depend on the kind of CRS used:
* - for projected systems, X is the easting, Y is the northing and Z is the elevation above/below
* the map plane.
* - for geocentric systems (such as ECEF), XYZ are cartesian coordinates in the 3D frame.
* - for geographic systems (such as EPSG:4326), X is the longitude, Y is the latitude and Z is the
* elevation above/below the reference ellipsoid.
*/
export declare class Coordinates {
readonly isCoordinates: true;
private readonly _values;
crs: CoordinateSystem;
/**
* Create coordinates from a pair of XY coordinates.
* @param crs - The coordinate system to use.
* @param x - The X coordinate.
* @param y - The Y coordinate.
* @example
* const x = 124225;
* const y = 10244.2;
* const mercator = new Coordinates(CoordinateSystem.epsg3857, x, y);
*
* // If using geographic coordinates, X is the longitude and Y is the latitude.
* const lon = 4.2123;
* const lat = 43.256;
* const geo = new Coordinates(CoordinateSystem.epsg4326, lon, lat);
*/
constructor(crs: CoordinateSystem, x: number, y: number);
/**
* Create coordinates from a XYZ triplet.
* @param crs - The coordinate system to use.
* @param x - The X coordinate.
* @param y - The Y coordinate.
* @param z - The Z coordinate.
* @example
* const x = 124225;
* const y = 10244.2;
* const z = 1000;
* const mercator = new Coordinates(CoordinateSystem.epsg3857, x, y, z);
*
* // If using geographic coordinates, X is the longitude and Y is the latitude.
* // Z is still the elevation in meters.
* const lon = 4.2123;
* const lat = 43.256;
* const geo = new Coordinates(CoordinateSystem.epsg4326, lon, lat, z);
*/
constructor(crs: CoordinateSystem, x: number, y: number, z: number);
/**
* Create coordinates from a {@link Vector2Like}
* @param crs - The coordinate system to use.
* @param xy - The vector to initialize coordinates.
* @example
* const coord = new Coordinates(CoordinateSystem.epsg3857, new THREE.Vector2(1020, 20924));
* // Alternatively, you don't have to use an actual Vector2 instance.
* // Any object that matches the Vector2Like interface will do.
* const coord = new Coordinates(CoordinateSystem.epsg3857, \{ x: 1020, y: 20924 \});
*/
constructor(crs: CoordinateSystem, xy: Vector2Like);
/**
* Create coordinates from a {@link Vector3Like}
* @param crs - The coordinate system to use.
* @param xyz - The vector to initialize coordinates.
* @example
* const coord = new Coordinates(CoordinateSystem.epsg3857, new THREE.Vector3(1020, 20924, 1000));
* // Alternatively, you don't have to use an actual Vector3 instance.
* // Any object that matches the Vector3Like interface will do.
* const coord = new Coordinates(CoordinateSystem.epsg3857, \{ x: 1020, y: 20924, z: 1000 \});
*/
constructor(crs: CoordinateSystem, xyz: Vector3Like);
get values(): Float64Array;
/**
* Sets the values in this coordinate from a XY pair.
* @param crs - The coordinate system to use.
* @param x - The X coordinate.
* @param y - The Y coordinate.
*/
set(crs: CoordinateSystem, x: number, y: number): this;
/**
* Sets the values in this coordinate from a XYZ triplet.
* @param crs - The coordinate system to use.
* @param x - The X coordinate.
* @param y - The Y coordinate.
* @param z - The Z coordinate.
*/
set(crs: CoordinateSystem, x: number, y: number, z: number): this;
/**
* Sets the values in this coordinate from a {@link Vector2Like}
* @param crs - The coordinate system to use.
* @param vector - The vector to initialize coordinates.
*/
set(crs: CoordinateSystem, xy: Vector2Like): this;
/**
* Sets the values in this coordinate from a {@link Vector3Like}
* @param crs - The coordinate system to use.
* @param vector - The vector to initialize coordinates.
*/
set(crs: CoordinateSystem, xyz: Vector3Like): this;
clone(target?: Coordinates): Coordinates;
copy(src: Coordinates): this;
/**
* Returns the longitude in geographic coordinates.
* Coordinates must be in geographic system (can be
* converted by using {@link as} ).
*
* ```js
* const position = { longitude: 2.33, latitude: 48.24, altitude: 24999549 };
* const coordinates = new Coordinates(
* 'EPSG:4326', position.longitude, position.latitude, position.altitude); // Geographic
* coordinates.longitude; // Longitude in geographic system
* // returns 2.33
*
* // or
*
* const position = { x: 20885167, y: 849862, z: 23385912 };
* // Geocentric system
* const coords = new Coordinates(CoordinateSystem.epsg4978, position.x, position.y, position.z);
* const coordinates = coords.as(CoordinateSystem.epsg4326); // Geographic system
* coordinates.longitude; // Longitude in geographic system
* // returns 2.330201911389028
* ```
* @returns The longitude of the position.
*/
get longitude(): number;
/**
* Returns the latitude in geographic coordinates.
* Coordinates must be in geographic system (can be converted by using {@link as}).
*
* ```js
* const position = { longitude: 2.33, latitude: 48.24, altitude: 24999549 };
* const coordinates = new Coordinates(
* 'EPSG:4326', position.longitude, position.latitude, position.altitude); // Geographic
* coordinates.latitude; // Latitude in geographic system
* // returns : 48.24
*
* // or
*
* const position = { x: 20885167, y: 849862, z: 23385912 };
* // Geocentric system
* const coords = new Coordinates(CoordinateSystem.epsg4978, position.x, position.y, position.z);
* const coordinates = coords.as(CoordinateSystem.epsg4326); // Geographic system
* coordinates.latitude; // Latitude in geographic system
* // returns : 48.24830764643365
* ```
* @returns The latitude of the position.
*/
get latitude(): number;
/**
* Returns the altitude in geographic coordinates.
* Coordinates must be in geographic system (can be converted by using {@link as}).
*
* ```js
* const position = { longitude: 2.33, latitude: 48.24, altitude: 24999549 };
* // Geographic system
* const coordinates =
* new Coordinates(CoordinateSystem.epsg4326, position.longitude, position.latitude, position.altitude);
* coordinates.altitude; // Altitude in geographic system
* // returns : 24999549
*
* // or
*
* const position = { x: 20885167, y: 849862, z: 23385912 };
* // Geocentric system
* const coords = new Coordinates(CoordinateSystem.epsg4978, position.x, position.y, position.z);
* const coordinates = coords.as(CoordinateSystem.epsg4326); // Geographic system
* coordinates.altitude; // Altitude in geographic system
* // returns : 24999548.046711832
* ```
* @returns The altitude of the position.
*/
get altitude(): number;
/**
* Set the altitude.
*
* @param altitude - the new altitude.
* ```js
* coordinates.setAltitude(10000)
* ```
*/
setAltitude(altitude: number): void;
withLongitude(longitude: number | DMS): this;
withLatitude(latitude: number | DMS): this;
withCRS(crs: CoordinateSystem): this;
withAltitude(altitude: number): this;
/**
* Returns the `x` component of this coordinate in geocentric coordinates.
* Coordinates must be in geocentric system (can be
* converted by using {@link as}).
*
* ```js
* const position = { x: 20885167, y: 849862, z: 23385912 };
* const coordinates = new Coordinates(CoordinateSystem.epsg4978, position.x, position.y, position.z);
* coordinates.x; // Geocentric system
* // returns : 20885167
*
* // or
*
* const position = { longitude: 2.33, latitude: 48.24, altitude: 24999549 };
* // Geographic system
* const coords =
* new Coordinates(CoordinateSystem.epsg4326, position.longitude, position.latitude, position.altitude);
* const coordinates = coords.as(CoordinateSystem.epsg4978); // Geocentric system
* coordinates.x; // Geocentric system
* // returns : 20888561.0301258
* ```
* @returns The `x` component of the position.
*/
get x(): number;
/**
* Returns the `y` component of this coordinate in geocentric coordinates.
* Coordinates must be in geocentric system (can be
* converted by using {@link as}).
*
* ```js
* const position = { x: 20885167, y: 849862, z: 23385912 };
* const coordinates = new Coordinates(CoordinateSystem.epsg4978, position.x, position.y, position.z);
* coordinates.y; // Geocentric system
* // returns : 849862
* ```
* @returns The `y` component of the position.
*/
get y(): number;
/**
* Returns the `z` component of this coordinate in geocentric coordinates.
* Coordinates must be in geocentric system (can be
* converted by using {@link as}).
*
* ```js
* const position = { x: 20885167, y: 849862, z: 23385912 };
* const coordinates = new Coordinates(CoordinateSystem.epsg4978, position.x, position.y, position.z);
* coordinates.z; // Geocentric system
* // returns : 23385912
* ```
* @returns The `z` component of the position.
*/
get z(): number;
/**
* Returns the equivalent `Vector3` of this coordinate.
*
* ```js
* const position = { x: 20885167, y: 849862, z: 23385912 };
* // Geocentric system
* const coordinates = new Coordinates(CoordinateSystem.epsg4978, position.x, position.y, position.z);
* coordinates.toVector3();
* // returns : Vector3
* // x: 20885167
* // y: 849862
* // z: 23385912
*
* // or
*
* const position = { longitude: 2.33, latitude: 48.24, altitude: 24999549 };
* // Geographic system
* const coordinates =
* new Coordinates(CoordinateSystem.epsg4326, position.longitude, position.latitude, position.altitude);
* coordinates.toVector3();
* // returns : Vector3
* // x: 2.33
* // y: 48.24
* // z: 24999549
* ```
* @param target - the geocentric coordinate
* @returns target position
*/
toVector3(target?: Vector3): Vector3;
/**
* Returns the equivalent `Vector2` of this coordinate. Note that the Z component (elevation) is
* lost.
*
* ```js *
* const position = { x: 20885167, y: 849862, z: 23385912 };
* // Metric system
* const coordinates = new Coordinates(CoordinateSystem.epsg3857, position.x, position.y, position.z);
* coordinates.toVector2();
* // returns : Vector2
* // x: 20885167
* // y: 849862
*
* // or
*
* const position = { longitude: 2.33, latitude: 48.24, altitude: 24999549 };
* // Geographic system
* const coordinates =
* new Coordinates(CoordinateSystem.epsg4326, position.longitude, position.latitude, position.altitude);
* coordinates.toVector2();
* // returns : Vector2
* // x: 2.33
* // y: 48.24
* ```
* @param target - the geocentric coordinate
* @returns target position
*/
toVector2(target?: Vector2): Vector2;
/**
* Converts coordinates in another [CRS](http://inspire.ec.europa.eu/theme/rs).
*
* If target is not specified, creates a new instance.
* The original instance is never modified (except if you passed it as `target`).
*
* ```js
* const position = { longitude: 2.33, latitude: 48.24, altitude: 24999549 };
* // Geographic system
* const coords =
* new Coordinates(CoordinateSystem.epsg4326, position.longitude, position.latitude, position.altitude);
* const coordinates = coords.as(CoordinateSystem.epsg4978); // Geocentric system
* ```
* @param crs - the [CRS](http://inspire.ec.europa.eu/theme/rs) EPSG string
* @param target - the object that is returned
* @returns the converted coordinate
*/
as(crs: CoordinateSystem, target?: Coordinates): Coordinates;
private convert;
/**
* Returns the boolean result of the check if this coordinate is geographic (true)
* or geocentric (false).
*
* ```js
* const position = { x: 20885167, y: 849862, z: 23385912 };
* const coordinates = new Coordinates(CoordinateSystem.epsg4978, position.x, position.y, position.z);
* coordinates.isGeographic(); // Geocentric system
* // returns : false
* ```
* @returns `true` if the coordinate is geographic.
*/
isGeographic(): boolean;
/**
* Creates a geographic coordinate in EPSG:4326
*/
static WGS84(latitude: number | DMS, longitude: number | DMS, altitude?: number): Coordinates;
}
export declare function isCoordinates(obj: unknown): obj is Coordinates;
export default Coordinates;
//# sourceMappingURL=Coordinates.d.ts.map