@takram/three-geospatial 0.0.1-alpha.1

package/src/Geodetic.ts

@@ -0,0 +1,160 @@
+import { Vector3 } from 'three'
+
+import { Ellipsoid } from './Ellipsoid'
+import {
+  projectOnEllipsoidSurface,
+  type ProjectOnEllipsoidSurfaceOptions
+} from './helpers/projectOnEllipsoidSurface'
+
+export type GeodeticTuple = [number, number, number]
+
+export interface GeodeticLike {
+  readonly longitude: number
+  readonly latitude: number
+  readonly height: number
+}
+
+const vectorScratch1 = /*#__PURE__*/ new Vector3()
+const vectorScratch2 = /*#__PURE__*/ new Vector3()
+
+export class Geodetic {
+  static readonly MIN_LONGITUDE = -Math.PI
+  static readonly MAX_LONGITUDE = Math.PI
+  static readonly MIN_LATITUDE = -Math.PI / 2
+  static readonly MAX_LATITUDE = Math.PI / 2
+
+  constructor(
+    public longitude = 0,
+    public latitude = 0,
+    public height = 0
+  ) {}
+
+  set(longitude: number, latitude: number, height?: number): this {
+    this.longitude = longitude
+    this.latitude = latitude
+    if (height != null) {
+      this.height = height
+    }
+    return this
+  }
+
+  clone(): Geodetic {
+    return new Geodetic(this.longitude, this.latitude, this.height)
+  }
+
+  copy(other: GeodeticLike): this {
+    this.longitude = other.longitude
+    this.latitude = other.latitude
+    this.height = other.height
+    return this
+  }
+
+  equals(other: GeodeticLike): boolean {
+    return (
+      other.longitude === this.longitude &&
+      other.latitude === this.latitude &&
+      other.height === this.height
+    )
+  }
+
+  setLongitude(value: number): this {
+    this.longitude = value
+    return this
+  }
+
+  setLatitude(value: number): this {
+    this.latitude = value
+    return this
+  }
+
+  setHeight(value: number): this {
+    this.height = value
+    return this
+  }
+
+  normalize(): this {
+    if (this.longitude < Geodetic.MIN_LONGITUDE) {
+      this.longitude += Math.PI * 2
+    }
+    return this
+  }
+
+  // See: https://en.wikipedia.org/wiki/Geographic_coordinate_conversion
+  // Reference: https://github.com/CesiumGS/cesium/blob/1.122/packages/engine/Source/Core/Geodetic.js#L119
+  setFromECEF(
+    position: Vector3,
+    options?: ProjectOnEllipsoidSurfaceOptions & {
+      ellipsoid?: Ellipsoid
+    }
+  ): this {
+    const ellipsoid = options?.ellipsoid ?? Ellipsoid.WGS84
+    const reciprocalRadiiSquared =
+      ellipsoid.reciprocalRadiiSquared(vectorScratch1)
+    const projection = projectOnEllipsoidSurface(
+      position,
+      reciprocalRadiiSquared,
+      vectorScratch2,
+      options
+    )
+    if (projection == null) {
+      throw new Error(
+        `Could not project position to ellipsoid surface: ${position.toArray()}`
+      )
+    }
+    const normal = vectorScratch1
+      .multiplyVectors(projection, reciprocalRadiiSquared)
+      .normalize()
+    this.longitude = Math.atan2(normal.y, normal.x)
+    this.latitude = Math.asin(normal.z)
+    const height = vectorScratch1.subVectors(position, projection)
+    this.height = Math.sign(height.dot(position)) * height.length()
+    return this
+  }
+
+  // See: https://en.wikipedia.org/wiki/Geographic_coordinate_conversion
+  // Reference: https://github.com/CesiumGS/cesium/blob/1.122/packages/engine/Source/Core/Cartesian3.js#L916
+  toECEF(
+    result = new Vector3(),
+    options?: {
+      ellipsoid?: Ellipsoid
+    }
+  ): Vector3 {
+    const ellipsoid = options?.ellipsoid ?? Ellipsoid.WGS84
+    const radiiSquared = vectorScratch1.multiplyVectors(
+      ellipsoid.radii,
+      ellipsoid.radii
+    )
+    const cosLatitude = Math.cos(this.latitude)
+    const normal = vectorScratch2
+      .set(
+        cosLatitude * Math.cos(this.longitude),
+        cosLatitude * Math.sin(this.longitude),
+        Math.sin(this.latitude)
+      )
+      .normalize()
+    result.multiplyVectors(radiiSquared, normal)
+    return result
+      .divideScalar(Math.sqrt(normal.dot(result)))
+      .add(normal.multiplyScalar(this.height))
+  }
+
+  fromArray(array: readonly number[], offset = 0): this {
+    this.longitude = array[offset]
+    this.latitude = array[offset + 1]
+    this.height = array[offset + 2]
+    return this
+  }
+
+  toArray(array: number[] = [], offset = 0): number[] {
+    array[offset] = this.longitude
+    array[offset + 1] = this.latitude
+    array[offset + 2] = this.height
+    return array
+  }
+
+  *[Symbol.iterator](): Generator<number> {
+    yield this.longitude
+    yield this.latitude
+    yield this.height
+  }
+}

package/src/PointOfView.ts

@@ -0,0 +1,169 @@
+import { Matrix4, Quaternion, Ray, Vector3, type Camera } from 'three'
+
+import { Ellipsoid } from './Ellipsoid'
+import { clamp } from './math'
+
+const EPSILON = 0.000001
+
+const eastScratch = /*#__PURE__*/ new Vector3()
+const northScratch = /*#__PURE__*/ new Vector3()
+const upScratch = /*#__PURE__*/ new Vector3()
+const vectorScratch1 = /*#__PURE__*/ new Vector3()
+const vectorScratch2 = /*#__PURE__*/ new Vector3()
+const vectorScratch3 = /*#__PURE__*/ new Vector3()
+const matrixScratch = /*#__PURE__*/ new Matrix4()
+const quaternionScratch = /*#__PURE__*/ new Quaternion()
+const rayScratch = /*#__PURE__*/ new Ray()
+
+export class PointOfView {
+  // Distance from the target.
+  private _distance!: number
+
+  // Radians from the local east direction relative from true north, measured
+  // clockwise (90 degrees is true north, and -90 is true south).
+  heading: number
+
+  // Radians from the local horizon plane, measured with positive values looking
+  // up (90 degrees is straight up, -90 is straight down).
+  private _pitch!: number
+
+  roll: number
+
+  constructor(distance = 0, heading = 0, pitch = 0, roll = 0) {
+    this.distance = distance
+    this.heading = heading
+    this.pitch = pitch
+    this.roll = roll
+  }
+
+  get distance(): number {
+    return this._distance
+  }
+
+  set distance(value: number) {
+    this._distance = Math.max(value, EPSILON)
+  }
+
+  get pitch(): number {
+    return this._pitch
+  }
+
+  set pitch(value: number) {
+    this._pitch = clamp(value, -Math.PI / 2 + EPSILON, Math.PI / 2 - EPSILON)
+  }
+
+  set(distance: number, heading: number, pitch: number, roll?: number): this {
+    this.distance = distance
+    this.heading = heading
+    this.pitch = pitch
+    if (roll != null) {
+      this.roll = roll
+    }
+    return this
+  }
+
+  clone(): PointOfView {
+    return new PointOfView(this.distance, this.heading, this.pitch, this.roll)
+  }
+
+  copy(other: PointOfView): this {
+    this.distance = other.distance
+    this.heading = other.heading
+    this.pitch = other.pitch
+    this.roll = other.roll
+    return this
+  }
+
+  equals(other: PointOfView): boolean {
+    return (
+      other.distance === this.distance &&
+      other.heading === this.heading &&
+      other.pitch === this.pitch &&
+      other.roll === this.roll
+    )
+  }
+
+  decompose(
+    target: Vector3,
+    eye: Vector3,
+    quaternion: Quaternion,
+    up?: Vector3,
+    ellipsoid = Ellipsoid.WGS84
+  ): void {
+    ellipsoid.getEastNorthUpVectors(
+      target,
+      eastScratch,
+      northScratch,
+      upScratch
+    )
+    up?.copy(upScratch)
+
+    // h = east * cos(heading) + north * sin(heading)
+    // v = h * cos(pitch) + up * sin(pitch)
+    const offset = vectorScratch1
+      .copy(eastScratch)
+      .multiplyScalar(Math.cos(this.heading))
+      .add(
+        vectorScratch2.copy(northScratch).multiplyScalar(Math.sin(this.heading))
+      )
+      .multiplyScalar(Math.cos(this.pitch))
+      .add(vectorScratch2.copy(upScratch).multiplyScalar(Math.sin(this.pitch)))
+      .normalize()
+      .multiplyScalar(this.distance)
+    eye.copy(target).sub(offset)
+
+    if (this.roll !== 0) {
+      const rollAxis = vectorScratch1.copy(target).sub(eye).normalize()
+      upScratch.applyQuaternion(
+        quaternionScratch.setFromAxisAngle(rollAxis, this.roll)
+      )
+    }
+    quaternion.setFromRotationMatrix(
+      matrixScratch.lookAt(eye, target, upScratch)
+    )
+  }
+
+  setFromCamera(camera: Camera, ellipsoid = Ellipsoid.WGS84): this | undefined {
+    const eye = vectorScratch1.setFromMatrixPosition(camera.matrixWorld)
+    const direction = vectorScratch2
+      .set(0, 0, 0.5)
+      .unproject(camera)
+      .sub(eye)
+      .normalize()
+    const target = ellipsoid.getIntersection(rayScratch.set(eye, direction))
+    if (target == null) {
+      return
+    }
+
+    this.distance = eye.distanceTo(target)
+    ellipsoid.getEastNorthUpVectors(
+      target,
+      eastScratch,
+      northScratch,
+      upScratch
+    )
+    this.heading = Math.atan2(
+      northScratch.dot(direction),
+      eastScratch.dot(direction)
+    )
+    this.pitch = Math.asin(upScratch.dot(direction))
+
+    // Need to rotate camera's up to evaluate it in world space.
+    const up = vectorScratch1.copy(camera.up).applyQuaternion(camera.quaternion)
+    const s = vectorScratch3
+      .copy(direction)
+      .multiplyScalar(-up.dot(direction))
+      .add(up)
+      .normalize()
+    const t = vectorScratch1
+      .copy(direction)
+      .multiplyScalar(-upScratch.dot(direction))
+      .add(upScratch)
+      .normalize()
+    const x = t.dot(s)
+    const y = direction.dot(t.cross(s))
+    this.roll = Math.atan2(y, x)
+
+    return this
+  }
+}

package/src/Rectangle.ts

@@ -0,0 +1,97 @@
+import { Geodetic } from './Geodetic'
+
+export type RectangleTuple = [number, number, number, number]
+
+export interface RectangleLike {
+  readonly west: number
+  readonly south: number
+  readonly east: number
+  readonly north: number
+}
+
+export class Rectangle {
+  static readonly MAX = /*#__PURE__*/ new Rectangle(
+    Geodetic.MIN_LONGITUDE,
+    Geodetic.MIN_LATITUDE,
+    Geodetic.MAX_LONGITUDE,
+    Geodetic.MAX_LATITUDE
+  )
+
+  constructor(
+    public west = 0,
+    public south = 0,
+    public east = 0,
+    public north = 0
+  ) {}
+
+  get width(): number {
+    let east = this.east
+    if (east < this.west) {
+      east += Math.PI * 2
+    }
+    return east - this.west
+  }
+
+  get height(): number {
+    return this.north - this.south
+  }
+
+  set(west: number, south: number, east: number, north: number): this {
+    this.west = west
+    this.south = south
+    this.east = east
+    this.north = north
+    return this
+  }
+
+  clone(): Rectangle {
+    return new Rectangle(this.west, this.south, this.east, this.north)
+  }
+
+  copy(other: RectangleLike): this {
+    this.west = other.west
+    this.south = other.south
+    this.east = other.east
+    this.north = other.north
+    return this
+  }
+
+  equals(other: RectangleLike): boolean {
+    return (
+      other.west === this.west &&
+      other.south === this.south &&
+      other.east === this.east &&
+      other.north === this.north
+    )
+  }
+
+  at(x: number, y: number, result = new Geodetic()): Geodetic {
+    return result.set(
+      this.west + (this.east - this.west) * x,
+      this.north + (this.south - this.north) * y
+    )
+  }
+
+  fromArray(array: readonly number[], offset = 0): this {
+    this.west = array[offset]
+    this.south = array[offset + 1]
+    this.east = array[offset + 2]
+    this.north = array[offset + 3]
+    return this
+  }
+
+  toArray(array: number[] = [], offset = 0): number[] {
+    array[offset] = this.west
+    array[offset + 1] = this.south
+    array[offset + 2] = this.east
+    array[offset + 3] = this.north
+    return array
+  }
+
+  *[Symbol.iterator](): Generator<number> {
+    yield this.west
+    yield this.south
+    yield this.east
+    yield this.north
+  }
+}

package/src/TileCoordinate.test.ts

@@ -0,0 +1,38 @@
+import { TileCoordinate } from './TileCoordinate'
+
+describe('TileCoordinate', () => {
+  test('getParent', () => {
+    const tile = new TileCoordinate()
+    tile.set(0, 0, 1)
+    expect(tile.getParent()).toMatchObject({ x: 0, y: 0, z: 0 })
+    tile.set(1, 0, 1)
+    expect(tile.getParent()).toMatchObject({ x: 0, y: 0, z: 0 })
+    tile.set(0, 1, 1)
+    expect(tile.getParent()).toMatchObject({ x: 0, y: 0, z: 0 })
+    tile.set(1, 1, 1)
+    expect(tile.getParent()).toMatchObject({ x: 0, y: 0, z: 0 })
+    tile.set(2, 0, 1)
+    expect(tile.getParent()).toMatchObject({ x: 1, y: 0, z: 0 })
+    tile.set(3, 0, 1)
+    expect(tile.getParent()).toMatchObject({ x: 1, y: 0, z: 0 })
+    tile.set(2, 1, 1)
+    expect(tile.getParent()).toMatchObject({ x: 1, y: 0, z: 0 })
+    tile.set(3, 1, 1)
+    expect(tile.getParent()).toMatchObject({ x: 1, y: 0, z: 0 })
+  })
+
+  test('traverseChildren', () => {
+    const tile = new TileCoordinate()
+    const child = new TileCoordinate()
+    const iterator = tile.traverseChildren(1, child)
+    expect(iterator.next().done).toBe(false)
+    expect(child).toMatchObject({ x: 0, y: 0, z: 1 })
+    expect(iterator.next().done).toBe(false)
+    expect(child).toMatchObject({ x: 1, y: 0, z: 1 })
+    expect(iterator.next().done).toBe(false)
+    expect(child).toMatchObject({ x: 0, y: 1, z: 1 })
+    expect(iterator.next().done).toBe(false)
+    expect(child).toMatchObject({ x: 1, y: 1, z: 1 })
+    expect(iterator.next().done).toBe(true)
+  })
+})

package/src/TileCoordinate.ts

@@ -0,0 +1,112 @@
+export type TileCoordinateTuple = [number, number, number]
+
+export interface TileCoordinateLike {
+  readonly x: number
+  readonly y: number
+  readonly z: number
+}
+
+function* traverseChildren(
+  x: number,
+  y: number,
+  z: number,
+  maxZ: number,
+  result?: TileCoordinate
+): Generator<TileCoordinate> {
+  if (z >= maxZ) {
+    return
+  }
+  const divisor = 2 ** z
+  const nextZ = z + 1
+  const scale = 2 ** nextZ
+  const nextX = Math.floor((x / divisor) * scale)
+  const nextY = Math.floor((y / divisor) * scale)
+  const children = [
+    [nextX, nextY, nextZ],
+    [nextX + 1, nextY, nextZ],
+    [nextX, nextY + 1, nextZ],
+    [nextX + 1, nextY + 1, nextZ]
+  ] as const
+  if (nextZ < maxZ) {
+    for (const child of children) {
+      for (const coord of traverseChildren(...child, maxZ, result)) {
+        yield coord
+      }
+    }
+  } else {
+    for (const child of children) {
+      yield (result ?? new TileCoordinate()).set(...child)
+    }
+  }
+}
+
+export class TileCoordinate {
+  constructor(
+    public x = 0,
+    public y = 0,
+    public z = 0
+  ) {}
+
+  set(x: number, y: number, z?: number): this {
+    this.x = x
+    this.y = y
+    if (z != null) {
+      this.z = z
+    }
+    return this
+  }
+
+  clone(): TileCoordinate {
+    return new TileCoordinate(this.x, this.y, this.z)
+  }
+
+  copy(other: TileCoordinateLike): this {
+    this.x = other.x
+    this.y = other.y
+    this.z = other.z
+    return this
+  }
+
+  equals(other: TileCoordinateLike): boolean {
+    return other.x === this.x && other.y === this.y && other.z === this.z
+  }
+
+  getParent(result = new TileCoordinate()): TileCoordinate {
+    const divisor = 2 ** this.z
+    const x = this.x / divisor
+    const y = this.y / divisor
+    const z = this.z - 1
+    const scale = 2 ** z
+    return result.set(Math.floor(x * scale), Math.floor(y * scale), z)
+  }
+
+  *traverseChildren(
+    depth: number,
+    result?: TileCoordinate
+  ): Generator<TileCoordinate> {
+    const { x, y, z } = this
+    for (const coord of traverseChildren(x, y, z, z + depth, result)) {
+      yield coord
+    }
+  }
+
+  fromArray(array: readonly number[], offset = 0): this {
+    this.x = array[offset]
+    this.y = array[offset + 1]
+    this.z = array[offset + 2]
+    return this
+  }
+
+  toArray(array: number[] = [], offset = 0): number[] {
+    array[offset] = this.x
+    array[offset + 1] = this.y
+    array[offset + 2] = this.z
+    return array
+  }
+
+  *[Symbol.iterator](): Generator<number> {
+    yield this.x
+    yield this.y
+    yield this.z
+  }
+}

package/src/TilingScheme.test.ts

@@ -0,0 +1,63 @@
+import { Rectangle } from './Rectangle'
+import { TileCoordinate } from './TileCoordinate'
+import { TilingScheme } from './TilingScheme'
+
+describe('TilingScheme', () => {
+  test('getTile', () => {
+    {
+      const bounds = Rectangle.MAX
+      const tilingScheme = new TilingScheme(2, 1, bounds)
+      const tile = new TileCoordinate()
+
+      tilingScheme.getTile(bounds.at(0, 0), 0, tile)
+      expect(tile).toMatchObject({ x: 0, y: 0, z: 0 })
+      tilingScheme.getTile(bounds.at(0.5 - Number.EPSILON, 0), 0, tile)
+      expect(tile).toMatchObject({ x: 0, y: 0, z: 0 })
+      tilingScheme.getTile(bounds.at(0, 1), 0, tile)
+      expect(tile).toMatchObject({ x: 0, y: 0, z: 0 })
+      tilingScheme.getTile(bounds.at(0.5 - Number.EPSILON, 1), 0, tile)
+      expect(tile).toMatchObject({ x: 0, y: 0, z: 0 })
+
+      tilingScheme.getTile(bounds.at(0.5 + Number.EPSILON, 0), 0, tile)
+      expect(tile).toMatchObject({ x: 1, y: 0, z: 0 })
+      tilingScheme.getTile(bounds.at(1, 0), 0, tile)
+      expect(tile).toMatchObject({ x: 1, y: 0, z: 0 })
+      tilingScheme.getTile(bounds.at(0.5 + Number.EPSILON, 1), 0, tile)
+      expect(tile).toMatchObject({ x: 1, y: 0, z: 0 })
+      tilingScheme.getTile(bounds.at(1, 1), 0, tile)
+      expect(tile).toMatchObject({ x: 1, y: 0, z: 0 })
+    }
+    {
+      const rect = Rectangle.MAX
+      const tilingScheme = new TilingScheme(1, 1, rect)
+      const tile = new TileCoordinate()
+
+      tilingScheme.getTile(rect.at(0, 0), 0, tile)
+      expect(tile).toMatchObject({ x: 0, y: 0, z: 0 })
+      tilingScheme.getTile(rect.at(0, 1), 0, tile)
+      expect(tile).toMatchObject({ x: 0, y: 0, z: 0 })
+      tilingScheme.getTile(rect.at(1, 0), 0, tile)
+      expect(tile).toMatchObject({ x: 0, y: 0, z: 0 })
+      tilingScheme.getTile(rect.at(1, 1), 0, tile)
+      expect(tile).toMatchObject({ x: 0, y: 0, z: 0 })
+    }
+  })
+
+  test('getRectangle', () => {
+    const bounds = Rectangle.MAX
+    const tilingScheme = new TilingScheme(2, 1, bounds)
+    const rect = new Rectangle()
+
+    tilingScheme.getRectangle({ x: 0, y: 0, z: 0 }, rect)
+    expect(rect.west).toBeCloseTo(-Math.PI)
+    expect(rect.south).toBeCloseTo(-Math.PI / 2)
+    expect(rect.east).toBeCloseTo(0)
+    expect(rect.north).toBeCloseTo(Math.PI / 2)
+
+    tilingScheme.getRectangle({ x: 1, y: 0, z: 0 }, rect)
+    expect(rect.west).toBeCloseTo(0)
+    expect(rect.south).toBeCloseTo(-Math.PI / 2)
+    expect(rect.east).toBeCloseTo(Math.PI)
+    expect(rect.north).toBeCloseTo(Math.PI / 2)
+  })
+})