gis-tools

About

A collection of geospatial tools primarily designed for WGS84, Web Mercator, and S2.

Features

Notable features of GIS-Tools are:

• 🔗 Lightweight, fast, and memory efficient. no_std builds for Rust. Tree-shaking for Typescript.
• 🗺️ Full toolkit support for WGS84, Web Mercator, and S2 projections.
• 🌱 A large list of projections can be converted to/from one of the above 3 via Transformers.
• 📦 Build Vector Tiles, Raster Tiles, and Gridded Data Tiles. Vector supports 3 output formats (Mapbox Vector Tile, Open S2 Tiles, and Flat Open S2 Tiles).
• ✅ Most data structures support all projections, but primarily focus the big 3 states above. Also handle large data sets through working with the filesystem and mmap buffers.
• 📖 Contains 23 native GIS readers. The list of readers are: CSV, GBFS, GeoTIFF, GPX, GRIB2, GTFS, JPEG and JPEG2000, (Geo|S2)JSON, LineDelimted GeoJSON, GeoJSON Text Sequences, LAS, LAZ, NadGrids, NetCDF, OSM, (S2)PMTiles, Shapefiles, raster and vector tiles, WKT, and XML.
• 🦺 Secure code where the only external dependency is sharp for local image processing, otherwise all code is written internally by Open S2 in Typescript or Rust.
• 🧲 Full suite of tools for points, lines, polygons, greater-circle-arcs, predicates, and more.
• 🌌 Space specific tools for planets and satellite orbits.

Goals

Making GIS data easy to parse and work with. One of the biggest issues in GIS right now is how segmented various niche tools are. The other issue is how most solutions to read GIS data are half baked, deprecated, or partially parse results that need to be transformed one more time to use them.

So this tool exists to make GIS tools simple to use, various data fast to parse, and transformed to usable projections without having to worry about the details.

Lastly the goal is for all code to be accessible to both the browser and locally. An example was the shapefile reader where it can pull from online data or handle extremely large data as well.

Install

# NPM
npm install gis-tools-ts
# PNPM
pnpm add gis-tools-ts
# Yarn
yarn add gis-tools-ts
# Bun
bun add gis-tools-ts
# Deno
deno install gis-tools-ts

# Cargo
cargo add gis-tools

Components

💡 NOTE: The sizes are estimates and can change based on how you use them. Click the module link for documentation and more precise guides on file cost.

Converters

Module	Size	Description
toJSON		Convert any Reader to JSON data.
toTiles		Convert any Reader to vector and/or raster tiles.

Data Stores

Module	Size	Description
externalSort		Sort large files with uint64 keys
kv		Key-Value store that works in the browser and the filesystem.
multiMap		Multi-map that works in the browser and the filesystem.
vector		Vector store that works in the browser and the filesystem.

Data Structures

Module	Size	Description
cache		A KV cache for values with a max size. Least used dropped first.
pointGrid		Point grid tiling for number or raster data.
pointCluster		Point cluster tool with indexing.
pointIndex		Point indexing with range/radius queries.
pointIndexFast		Faster point indexing with range/radius queries.
priorityQueue		A priority queue.
tile		A tile/layer management tool for features.

Geometry

Module	Size	Description
angles		Spherical geodetic angle methods.
bbox		Bounding box creation/manipulation.
id		ID tools for S2 and WM.
lonlat		Longitude/Latitude convienience methods.
predicates		Reliability predicates for 2D and 3D orientation geometry.
s2		S2 geometry convienience methods.
tools		Geometry manipulation tools.
wm		Web Mercator (WM) geometry convienience methods.

PROJ4

Module	Size	Description
mgrs		Military Grid Reference System (MGRS) converter.
projections		Supports a large list of projections to be used by transformers.
transformer		Tool for transforming coordinates from one projection to another.

Readers

Most readers are parsers that take ReaderInputs as an input. This is to ensure both browser and file inputs are supported. You can learn more about readers here.

Module	Size	Description
jpeg		Read/parse JPEG data.
jpeg2000		Read/parse JPEG 2000 data.
lanczos		Apply a Lanczos filter that downsamples an image.
csv		CSV data reader with options on parsing.
gbfs		General Bikeshare Feed Specification reader.
geotiff		Geotiff image reader with projection support.
gpx		GPX (xml based) data reader.
grib2		GRIB 2 data reader.
gtfs		General Transit Feed Specification. Both Static and Realtime.
json		JSON data reader with line delimiter support.
las		LAS data reader.
laz		LASzipped data reader.
nadgrid		NAD Grid data reader.
netcdf		NetCDF data reader.
osm		OpenStreetMap PBF data reader
pmtiles		(S2)PMTiles data reader.
protobuf		Protobuf data reader/writer.
shapefile		Shapefile data reader supporting DBF and projections (PRJ).
tileReader		Tile data reader, usually from a local input folder.
wkt		Well Known Text data reader.
xml		XML data reader.

Space

Module	Size	Description
planets		Collection of planet constants with observation tools.
satellite		Satellite Orbit Class from TLE data

Tools

Module	Size	Description
delaunator		Delaunay triangulation of 2D points.
interpolators		Interpolate values from points and weights.
orthodrome		Find shortest path between two points or point on path.
polylabel		Find the labels for vector polygons

Writers

Module	Size	Description
pmtilesWriter		Write (S2)PMTiles data.
tileWriter		Write (S2)Tiles data. Supports time series as well.

Utils

Module	Size	Description
polyfills		Collection of polyfills that might add value for the browser.
compression		compression/decompression convenience methods.

---

Development

Requirements

You need the tool tarpaulin to generate the coverage report. Install it using the following command:

cargo install cargo-tarpaulin

The bacon coverage tool is used to generate the coverage report. To utilize the pycobertura package for a prettier coverage report, install it using the following command:

pip install pycobertura

Running Tests

To run the tests, use the following command:

# TYPESCRIPT
## basic test
bun run test
## live testing
bun run test:dev

# RUST
## basic test
cargo test
# live testing
bacon test

Generating Coverage Report

To generate the coverage report, use the following command:

# install
cargo +stable install cargo-llvm-cov --locked
# run test
cargo llvm-cov
# bacon
bacon coverage # or type `l` inside the tool

# output lcov
cargo llvm-cov --lcov --output-path coverage/lcov.info

Using Tokei

cargo install tokei