gistda-sphere-react

useSphereUtils

Format distances, areas and times, and convert WKT, KML, GPX, GML, Esri JSON and TopoJSON to GeoJSON

useSphereUtils wraps Sphere's helpers with typed, promise-based functions. Converters load the Sphere library they need the first time you call them.

import { useSphereUtils } from "gistda-sphere-react";

interface MeasurementsProps {
  meters: number;
  seconds: number;
  squareMeters: number;
}

function Measurements({ meters, squareMeters, seconds }: MeasurementsProps) {
  const { formatDistance, formatArea, formatThaiArea, formatInterval } = useSphereUtils();
  return (
    <ul>
      <li>{formatDistance(meters)}</li>         {/* "15.5 km" */}
      <li>{formatArea(squareMeters)}</li>       {/* "120 sq.km" */}
      <li>{formatThaiArea(squareMeters)}</li>   {/* "74,995 rai 3 ngan 76 sq.wa" */}
      <li>{formatInterval(seconds)}</li>        {/* "1 hr 2 min" */}
    </ul>
  );
}

Formatters use the map's language unless you pass one ("th" or "en").

Formatting

FunctionExampleDescription
formatDistance(meters, language?)"15.0 km"A distance.
formatArea(squareMeters, language?)"120 sq.km"An area in metric units.
formatThaiArea(squareMeters, language?)"74,995 ไร่ 3 งาน 76 ตร.ว."An area in rai, ngan and square wa.
formatInterval(seconds, language?)"1 ชม. 2 นาที"A duration.
formatDate(isoDate, language?)A date.
formatTime(isoTime)A time.
formatDateTimeRange(start, stop, language?)A date and time range.
latitudeLength(lat) / longitudeLength(lat)Meters in one degree of latitude / longitude at a latitude.

Converting to GeoJSON

All converters return promises, because the first call loads Sphere's converter library.

FunctionInput
wktToGeoJSON(text)Well-known text, e.g. "POINT(100.5 13.75)". Returns a geometry.
kmlToGeoJSON(document)KML as a string or XML Document.
gpxToGeoJSON(document)GPX as a string or XML Document.
gmlToGeoJSON(document)GML as a string or XML Document.
esriJsonToGeoJSON(json)An Esri JSON geometry.
topoJsonToGeoJSON(json, object)One object of a TopoJSON topology, by name or object.
import { useSphereUtils } from "gistda-sphere-react";

const { kmlToGeoJSON } = useSphereUtils();

async function showFile(file: File) {
  const data = await kmlToGeoJSON(await file.text());
  setData(data); // then render <GeoJson data={data} />
}

Projections

project transforms coordinates between coordinate systems given as proj4 strings, from WGS84 unless you say otherwise:

import { useSphereUtils } from "gistda-sphere-react";

const { project } = useSphereUtils();

// WGS84 → UTM zone 47N
const utm = await project("+proj=utm +zone=47 +datum=WGS84 +units=m", [100.5018, 13.7563]);

// UTM zone 47N → WGS84
const wgs84 = await project("+proj=longlat +datum=WGS84", [662_190, 1_521_385], "+proj=utm +zone=47 +datum=WGS84 +units=m");

Raw access

util and math are Sphere's raw sphere.Util and sphere.Math objects, or null before the API loads. isReady is true once it has.

On this page