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