@takram/three-geospatial 0.0.1-alpha.1

package/src/TilingScheme.ts

@@ -0,0 +1,76 @@
+import { Vector2 } from 'three'
+
+import { type GeodeticLike } from './Geodetic'
+import { Rectangle, type RectangleLike } from './Rectangle'
+import { TileCoordinate, type TileCoordinateLike } from './TileCoordinate'
+
+const vectorScratch = /*#__PURE__*/ new Vector2()
+
+export interface TilingSchemeLike {
+  readonly width: number
+  readonly height: number
+  readonly rectangle: RectangleLike
+}
+
+// TODO: Support slippyMap and EPSG:3857
+export class TilingScheme {
+  constructor(
+    public width = 2,
+    public height = 1,
+    public rectangle = Rectangle.MAX
+  ) {}
+
+  clone(): TilingScheme {
+    return new TilingScheme(this.width, this.height, this.rectangle.clone())
+  }
+
+  copy(other: TilingSchemeLike): this {
+    this.width = other.width
+    this.height = other.height
+    this.rectangle.copy(other.rectangle)
+    return this
+  }
+
+  getSize(z: number, result = new Vector2()): Vector2 {
+    return result.set(this.width << z, this.height << z)
+  }
+
+  // Reference: https://github.com/CesiumGS/cesium/blob/1.122/packages/engine/Source/Core/GeographicTilingScheme.js#L210
+  getTile(
+    geodetic: GeodeticLike,
+    z: number,
+    result = new TileCoordinate()
+  ): TileCoordinate {
+    const size = this.getSize(z, vectorScratch)
+    const width = this.rectangle.width / size.x
+    const height = this.rectangle.height / size.y
+    let longitude = geodetic.longitude
+    if (this.rectangle.east < this.rectangle.west) {
+      longitude += Math.PI * 2
+    }
+    let x = Math.floor((longitude - this.rectangle.west) / width)
+    if (x >= size.x) {
+      x = size.x - 1
+    }
+    let y = Math.floor((geodetic.latitude - this.rectangle.south) / height)
+    if (y >= size.y) {
+      y = size.y - 1
+    }
+    result.x = x
+    result.y = y
+    result.z = z
+    return result
+  }
+
+  // Reference: https://github.com/CesiumGS/cesium/blob/1.122/packages/engine/Source/Core/GeographicTilingScheme.js#L169
+  getRectangle(tile: TileCoordinateLike, result = new Rectangle()): Rectangle {
+    const size = this.getSize(tile.z, vectorScratch)
+    const width = this.rectangle.width / size.x
+    const height = this.rectangle.height / size.y
+    result.west = tile.x * width + this.rectangle.west
+    result.east = (tile.x + 1) * width + this.rectangle.west
+    result.north = this.rectangle.north - (size.y - tile.y - 1) * height
+    result.south = this.rectangle.north - (size.y - tile.y) * height
+    return result
+  }
+}

package/src/TypedArrayLoader.ts

@@ -0,0 +1,53 @@
+import { Loader, type TypedArray } from 'three'
+
+import { ArrayBufferLoader } from './ArrayBufferLoader'
+import {
+  parseFloat32Array,
+  parseInt16Array,
+  parseUint16Array
+} from './typedArray'
+
+export abstract class TypedArrayLoader<T extends TypedArray> extends Loader<T> {
+  abstract parseTypedArray(buffer: ArrayBuffer): T
+
+  override load(
+    url: string,
+    onLoad: (data: T) => void,
+    onProgress?: (event: ProgressEvent) => void,
+    onError?: (error: unknown) => void
+  ): void {
+    const loader = new ArrayBufferLoader(this.manager)
+    loader.setRequestHeader(this.requestHeader)
+    loader.setPath(this.path)
+    loader.setWithCredentials(this.withCredentials)
+    loader.load(
+      url,
+      arrayBuffer => {
+        try {
+          onLoad(this.parseTypedArray(arrayBuffer))
+        } catch (error) {
+          if (onError != null) {
+            onError(error)
+          } else {
+            console.error(error)
+          }
+          this.manager.itemError(url)
+        }
+      },
+      onProgress,
+      onError
+    )
+  }
+}
+
+export class Int16ArrayLoader extends TypedArrayLoader<Int16Array> {
+  readonly parseTypedArray = parseInt16Array
+}
+
+export class Uint16ArrayLoader extends TypedArrayLoader<Uint16Array> {
+  readonly parseTypedArray = parseUint16Array
+}
+
+export class Float32ArrayLoader extends TypedArrayLoader<Float32Array> {
+  readonly parseTypedArray = parseFloat32Array
+}

package/src/assertions.ts

@@ -0,0 +1,13 @@
+export function assertType<T>(value: unknown): asserts value is T {}
+
+export function isNotNullish<T>(value: T | null | undefined): value is T {
+  return value != null
+}
+
+export function isNotUndefined<T>(value: T | undefined): value is T {
+  return value !== undefined
+}
+
+export function isNotFalse<T>(value: T | false): value is T {
+  return value !== false
+}

package/src/bufferGeometry.ts

@@ -0,0 +1,62 @@
+import { pick } from 'lodash-es'
+import { Box3, BufferAttribute, BufferGeometry, Sphere, Vector3 } from 'three'
+
+import { isNotNullish } from './assertions'
+
+export type BufferGeometryLike = Pick<
+  BufferGeometry,
+  'attributes' | 'index' | 'boundingBox' | 'boundingSphere'
+>
+
+export function toBufferGeometryLike(
+  geometry: BufferGeometry
+): [BufferGeometryLike, ArrayBuffer[]] {
+  return [
+    pick(geometry, ['attributes', 'index', 'boundingBox', 'boundingSphere']),
+    [
+      ...Object.values(geometry.attributes).map(
+        attribute => attribute.array.buffer
+      ),
+      geometry.index?.array.buffer
+    ].filter(isNotNullish)
+  ]
+}
+
+export function fromBufferGeometryLike(
+  input: BufferGeometryLike,
+  result = new BufferGeometry()
+): BufferGeometry {
+  for (const [name, attribute] of Object.entries(input.attributes)) {
+    result.setAttribute(
+      name,
+      new BufferAttribute(
+        attribute.array,
+        attribute.itemSize,
+        attribute.normalized
+      )
+    )
+  }
+  result.index =
+    input.index != null
+      ? new BufferAttribute(
+          input.index.array,
+          input.index.itemSize,
+          input.index.normalized
+        )
+      : null
+  if (input.boundingBox != null) {
+    const { min, max } = input.boundingBox
+    result.boundingBox = new Box3(
+      new Vector3(min.x, min.y, min.z),
+      new Vector3(max.x, max.y, max.z)
+    )
+  }
+  if (input.boundingSphere != null) {
+    const { center, radius } = input.boundingSphere
+    result.boundingSphere = new Sphere(
+      new Vector3(center.x, center.y, center.z),
+      radius
+    )
+  }
+  return result
+}

package/src/helpers/projectOnEllipsoidSurface.ts

@@ -0,0 +1,72 @@
+import { Vector3 } from 'three'
+
+const vectorScratch = /*#__PURE__*/ new Vector3()
+
+// See: https://en.wikipedia.org/wiki/Geographic_coordinate_conversion
+// Reference: https://github.com/CesiumGS/cesium/blob/1.122/packages/engine/Source/Core/scaleToGeodeticSurface.js
+
+export interface ProjectOnEllipsoidSurfaceOptions {
+  centerTolerance?: number
+}
+
+export function projectOnEllipsoidSurface(
+  position: Vector3,
+  reciprocalRadiiSquared: Vector3,
+  result = new Vector3(),
+  options?: ProjectOnEllipsoidSurfaceOptions
+): Vector3 | undefined {
+  const { x, y, z } = position
+  const rx = reciprocalRadiiSquared.x
+  const ry = reciprocalRadiiSquared.y
+  const rz = reciprocalRadiiSquared.z
+  const x2 = x * x * rx
+  const y2 = y * y * ry
+  const z2 = z * z * rz
+
+  // Compute the squared ellipsoid norm.
+  const normSquared = x2 + y2 + z2
+  const ratio = Math.sqrt(1 / normSquared)
+
+  // When very close to center or at center.
+  if (!Number.isFinite(ratio)) {
+    return undefined
+  }
+
+  // As an initial approximation, assume that the radial intersection is the
+  // projection point.
+  const intersection = vectorScratch.copy(position).multiplyScalar(ratio)
+  if (normSquared < (options?.centerTolerance ?? 0.1)) {
+    return result.copy(intersection)
+  }
+
+  // Use the gradient at the intersection point in place of the true unit
+  // normal. The difference in magnitude will be absorbed in the multiplier.
+  const gradient = intersection
+    .multiply(reciprocalRadiiSquared)
+    .multiplyScalar(2)
+
+  // Compute the initial guess at the normal vector multiplier.
+  let lambda = ((1 - ratio) * position.length()) / (gradient.length() / 2)
+
+  let correction = 0
+  let sx: number
+  let sy: number
+  let sz: number
+  let error: number
+  do {
+    lambda -= correction
+    sx = 1 / (1 + lambda * rx)
+    sy = 1 / (1 + lambda * ry)
+    sz = 1 / (1 + lambda * rz)
+    const sx2 = sx * sx
+    const sy2 = sy * sy
+    const sz2 = sz * sz
+    const sx3 = sx2 * sx
+    const sy3 = sy2 * sy
+    const sz3 = sz2 * sz
+    error = x2 * sx2 + y2 * sy2 + z2 * sz2 - 1
+    correction = error / ((x2 * sx3 * rx + y2 * sy3 * ry + z2 * sz3 * rz) * -2)
+  } while (Math.abs(error) > 1e-12)
+
+  return result.set(x * sx, y * sy, z * sz)
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+/// <reference types="vite-plugin-glsl/ext" />
+
+import depth from './shaders/depth.glsl'
+import packing from './shaders/packing.glsl'
+import transform from './shaders/transform.glsl'
+
+export const depthShader: string = depth
+export const packingShader: string = packing
+export const transformShader: string = transform
+
+export * from './ArrayBufferLoader'
+export * from './assertions'
+export * from './bufferGeometry'
+export * from './DataLoader'
+export * from './Ellipsoid'
+export * from './EllipsoidGeometry'
+export * from './Geodetic'
+export * from './math'
+export * from './PointOfView'
+export * from './Rectangle'
+export * from './TileCoordinate'
+export * from './TilingScheme'
+export * from './typedArray'
+export * from './TypedArrayLoader'
+export * from './types'

package/src/math.ts

@@ -0,0 +1,41 @@
+import { MathUtils } from 'three'
+
+export const clamp = MathUtils.clamp
+export const euclideanModulo = MathUtils.euclideanModulo
+export const inverseLerp = MathUtils.inverseLerp
+export const lerp = MathUtils.lerp
+export const radians = MathUtils.degToRad
+export const degrees = MathUtils.radToDeg
+export const isPowerOfTwo = MathUtils.isPowerOfTwo
+export const ceilPowerOfTwo = MathUtils.ceilPowerOfTwo
+export const floorPowerOfTwo = MathUtils.floorPowerOfTwo
+export const normalize = MathUtils.normalize
+
+// Prefer glsl's argument order which differs from that of MathUtils.
+export function smoothstep(min: number, max: number, x: number): number {
+  if (x <= min) {
+    return 0
+  }
+  if (x >= max) {
+    return 1
+  }
+  x = (x - min) / (max - min)
+  return x * x * (3 - 2 * x)
+}
+
+export function saturate(x: number): number {
+  return Math.min(Math.max(x, 0), 1)
+}
+
+export function closeTo(
+  a: number,
+  b: number,
+  relativeEpsilon: number,
+  absoluteEpsilon = relativeEpsilon
+): boolean {
+  const diff = Math.abs(a - b)
+  return (
+    diff <= absoluteEpsilon ||
+    diff <= relativeEpsilon * Math.max(Math.abs(a), Math.abs(b))
+  )
+}

package/src/r3f/EastNorthUpFrame.tsx

@@ -0,0 +1,52 @@
+import { forwardRef, useEffect, useMemo, type ReactNode } from 'react'
+import { Group, Matrix4, Vector3 } from 'three'
+import { type SetOptional } from 'type-fest'
+
+import { Ellipsoid } from '../Ellipsoid'
+import { Geodetic, type GeodeticLike } from '../Geodetic'
+
+const matrixScratch = /*#__PURE__*/ new Matrix4()
+const geodeticScratch = /*#__PURE__*/ new Geodetic()
+const vectorScratch = /*#__PURE__*/ new Vector3()
+
+class EastNorthUpFrameGroup extends Group {
+  set(
+    longitude: number,
+    latitude: number,
+    height: number,
+    ellipsoid = Ellipsoid.WGS84
+  ): void {
+    // TODO: Support nesting
+    const position = geodeticScratch
+      .set(longitude, latitude, height)
+      .toECEF(vectorScratch)
+    const matrix = ellipsoid.getEastNorthUpFrame(position, matrixScratch)
+    matrix.decompose(this.position, this.quaternion, this.scale)
+  }
+}
+
+export interface EastNorthUpFrameProps
+  extends SetOptional<GeodeticLike, 'height'> {
+  ellipsoid?: Ellipsoid
+  children?: ReactNode
+}
+
+export const EastNorthUpFrame = /*#__PURE__*/ forwardRef<
+  EastNorthUpFrameGroup,
+  EastNorthUpFrameProps
+>(function EastNorthUpFrame(
+  { longitude, latitude, height = 0, ellipsoid = Ellipsoid.WGS84, children },
+  forwardedRef
+) {
+  const group = useMemo(() => new EastNorthUpFrameGroup(), [])
+
+  useEffect(() => {
+    group.set(longitude, latitude, height, ellipsoid)
+  }, [longitude, latitude, height, ellipsoid, group])
+
+  return (
+    <primitive ref={forwardedRef} object={group}>
+      {children}
+    </primitive>
+  )
+})

package/src/r3f/EllipsoidMesh.tsx

@@ -0,0 +1,36 @@
+import {
+  extend,
+  type BufferGeometryNode,
+  type MeshProps
+} from '@react-three/fiber'
+import { forwardRef, useRef } from 'react'
+import { mergeRefs } from 'react-merge-refs'
+import { type Mesh } from 'three'
+
+import { EllipsoidGeometry } from '../EllipsoidGeometry'
+
+declare module '@react-three/fiber' {
+  interface ThreeElements {
+    ellipsoidGeometry: BufferGeometryNode<
+      EllipsoidGeometry,
+      typeof EllipsoidGeometry
+    >
+  }
+}
+
+export interface EllipsoidMeshProps extends Omit<MeshProps, 'args'> {
+  args?: ConstructorParameters<typeof EllipsoidGeometry>
+}
+
+export const EllipsoidMesh = /*#__PURE__*/ forwardRef<Mesh, EllipsoidMeshProps>(
+  function Ellipsoid({ args, children, ...props }, forwardedRef) {
+    const ref = useRef<Mesh | null>(null)
+    extend({ EllipsoidGeometry })
+    return (
+      <mesh ref={mergeRefs([ref, forwardedRef])} {...props}>
+        <ellipsoidGeometry args={args} />
+        {children}
+      </mesh>
+    )
+  }
+)

package/src/r3f/index.ts

@@ -0,0 +1,2 @@
+export * from './EastNorthUpFrame'
+export * from './EllipsoidMesh'

package/src/shaders/depth.glsl

@@ -0,0 +1,15 @@
+float reverseLogDepth(const float depth, const float near, const float far) {
+  #ifdef USE_LOGDEPTHBUF
+  float d = pow(2.0, depth * log2(far + 1.0)) - 1.0;
+  float a = far / (far - near);
+  float b = far * near / (near - far);
+  return a + b / d;
+  #else
+  return depth;
+  #endif // USE_LOGDEPTHBUF
+}
+
+float linearizeDepth(const float depth, const float near, const float far) {
+  float ndc = depth * 2.0 - 1.0;
+  return 2.0 * near * far / (far + near - ndc * (far - near));
+}

package/src/shaders/packing.glsl

@@ -0,0 +1,20 @@
+// Reference: https://jcgt.org/published/0003/02/01/paper.pdf
+
+vec2 signNotZero(vec2 v) {
+  return vec2(v.x >= 0.0 ? 1.0 : -1.0, v.y >= 0.0 ? 1.0 : -1.0);
+}
+
+vec2 packNormalToVec2(vec3 v) {
+  vec2 p = v.xy * (1.0 / (abs(v.x) + abs(v.y) + abs(v.z)));
+  return v.z <= 0.0
+    ? (1.0 - abs(p.yx)) * signNotZero(p)
+    : p;
+}
+
+vec3 unpackVec2ToNormal(vec2 e) {
+  vec3 v = vec3(e.xy, 1.0 - abs(e.x) - abs(e.y));
+  if (v.z < 0.0) {
+    v.xy = (1.0 - abs(v.yx)) * signNotZero(v.xy);
+  }
+  return normalize(v);
+}

package/src/shaders/transform.glsl

@@ -0,0 +1,12 @@
+vec3 screenToView(
+  const vec2 uv,
+  const float depth,
+  const float viewZ,
+  const mat4 projectionMatrix,
+  const mat4 inverseProjectionMatrix
+) {
+  vec4 clip = vec4(vec3(uv, depth) * 2.0 - 1.0, 1.0);
+  float clipW = projectionMatrix[2][3] * viewZ + projectionMatrix[3][3];
+  clip *= clipW;
+  return (inverseProjectionMatrix * clip).xyz;
+}

package/src/typedArray.ts

@@ -0,0 +1,76 @@
+export type TypedArray =
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array
+
+export type TypedArrayConstructor =
+  | Int8ArrayConstructor
+  | Uint8ArrayConstructor
+  | Uint8ClampedArrayConstructor
+  | Int16ArrayConstructor
+  | Uint16ArrayConstructor
+  | Int32ArrayConstructor
+  | Uint32ArrayConstructor
+  | Float32ArrayConstructor
+  | Float64ArrayConstructor
+
+type GetValue = keyof {
+  [K in keyof DataView as DataView[K] extends (byteOffset: number) => number
+    ? K
+    : never]: DataView[K]
+}
+
+export function parseTypedArray<
+  T extends TypedArrayConstructor,
+  K extends GetValue
+>(
+  buffer: ArrayBuffer,
+  TypedArray: T,
+  getValue: K,
+  littleEndian?: boolean
+): InstanceType<T>
+
+export function parseTypedArray<K extends GetValue>(
+  buffer: ArrayBuffer,
+  TypedArray: TypedArrayConstructor,
+  getValue: K,
+  littleEndian = true
+): TypedArray {
+  const data = new DataView(buffer)
+  const array = new TypedArray(data.byteLength / TypedArray.BYTES_PER_ELEMENT)
+  for (
+    let index = 0, byteIndex = 0;
+    index < array.length;
+    ++index, byteIndex += TypedArray.BYTES_PER_ELEMENT
+  ) {
+    array[index] = data[getValue](byteIndex, littleEndian)
+  }
+  return array
+}
+
+export function parseInt16Array(
+  buffer: ArrayBuffer,
+  littleEndian?: boolean
+): Int16Array {
+  return parseTypedArray(buffer, Int16Array, 'getInt16', littleEndian)
+}
+
+export function parseUint16Array(
+  buffer: ArrayBuffer,
+  littleEndian?: boolean
+): Uint16Array {
+  return parseTypedArray(buffer, Uint16Array, 'getUint16', littleEndian)
+}
+
+export function parseFloat32Array(
+  buffer: ArrayBuffer,
+  littleEndian?: boolean
+): Float32Array {
+  return parseTypedArray(buffer, Float32Array, 'getFloat32', littleEndian)
+}

package/src/types.ts

@@ -0,0 +1,54 @@
+import {
+  type Matrix2,
+  type Matrix3,
+  type Matrix4,
+  type Vector2,
+  type Vector3,
+  type Vector4
+} from 'three'
+import { type ReadonlyTuple } from 'type-fest'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Callable = (...args: any) => any
+
+export type ReadonlyTuple2<T = number> = ReadonlyTuple<T, 2>
+export type ReadonlyTuple3<T = number> = ReadonlyTuple<T, 3>
+export type ReadonlyTuple4<T = number> = ReadonlyTuple<T, 4>
+
+// Non-readonly version of ReadonlyTuple. This is not type-safe because mutable
+// methods still exist in the type.
+// See https://github.com/sindresorhus/type-fest/blob/main/source/readonly-tuple.d.ts
+type BuildTupleHelper<
+  Element,
+  Length extends number,
+  Rest extends Element[]
+> = Rest['length'] extends Length
+  ? [...Rest]
+  : BuildTupleHelper<Element, Length, [Element, ...Rest]>
+
+export type Tuple<T, Length extends number> = number extends Length
+  ? readonly T[]
+  : BuildTupleHelper<T, Length, []>
+
+export type Tuple2<T = number> = BuildTupleHelper<T, 2, []>
+export type Tuple3<T = number> = BuildTupleHelper<T, 3, []>
+export type Tuple4<T = number> = BuildTupleHelper<T, 4, []>
+
+// Suppose return type of the mutable methods of classes like Vector3 is `this`.
+// TODO: How can we specify `this` as a constraint?
+type ReadonlyThreeInstance<T> = Readonly<{
+  [K in keyof T as T[K] extends Callable
+    ? ReturnType<T[K]> extends T
+      ? K extends 'clone'
+        ? K
+        : never
+      : K
+    : K]: T[K]
+}>
+
+export type ReadonlyVector2 = ReadonlyThreeInstance<Vector2>
+export type ReadonlyVector3 = ReadonlyThreeInstance<Vector3>
+export type ReadonlyVector4 = ReadonlyThreeInstance<Vector4>
+export type ReadonlyMatrix2 = ReadonlyThreeInstance<Matrix2>
+export type ReadonlyMatrix3 = ReadonlyThreeInstance<Matrix3>
+export type ReadonlyMatrix4 = ReadonlyThreeInstance<Matrix4>

package/types/ArrayBufferLoader.d.ts

@@ -0,0 +1,5 @@
+import { Loader } from 'three';
+
+export declare class ArrayBufferLoader extends Loader<ArrayBuffer> {
+    load(url: string, onLoad: (data: ArrayBuffer) => void, onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void): void;
+}