Galuchat GIS SDK

English | 日本語

Galuchat GIS SDK helps applications use GIS data (WGSMapSet) generated with Galuchat's segmented-image storage model. Its primary use is implementing reverse geocoding from longitude and latitude coordinates to region codes and place names.

With the SDK and its bundled datasets, applications can retrieve a code and place name for a point, or a code raster for a specified area, without relying on an online GIS service or an external database.

GIS data can be stored directly in a browser or local application, enabling offline reverse geocoding. Because it does not require an external service, the SDK can also be used in embedded and mobile environments.

Data examples

The images below are pixel-for-pixel renderings of actual WGSMapSet data centered near Narashino, Japan. Blue represents unset areas such as the sea. Other colors distinguish region codes; the colors themselves have no semantic meaning.

Resolution determines how finely boundaries are represented. Region granularity determines whether a code represents a municipality, town block, census small area, or another unit. Higher resolution does not necessarily mean finer region granularity, so choose a dataset that fits the intended use.

See the dataset guide for dataset comparisons, all rendering examples, and file sizes.

Data structure

Data used by Galuchat GIS SDK primarily consists of a WGSMapSet and a GisWordBook.

A WGSMapSet stores a raster whose pixel values are numeric region identifiers, using Galuchat's spatially partitioned storage model.

The source data is a high-resolution raster generated by composing and rendering vector regions associated with region codes. WGSMapSet maps the image axes to longitude and latitude and stores the result in Galuchat format.

A GisWordBook restores an ordered place-name hierarchy from a numeric code. Internally, it combines a string dictionary with hierarchical indexes.

For reverse geocoding, a longitude and latitude are first converted to a code through WGSMapSet. GisWordBook then converts that code to the corresponding place-name information.

Features

The SDK focuses on reverse geocoding from longitude and latitude and provides the following capabilities:

• Retrieve an administrative-area or small-area code from longitude and latitude.
• Convert a region code into a place-name hierarchy such as prefecture, municipality, and town block.
• Read a specified area as a raster.
• Use the same GIS datasets from JavaScript, Java, Python, and C++.
• Keep both the data and readers locally.

Get started

The SDK is a file set and does not require a package manager. Reference the implementation for your language and the map and GisWordBook files under datasets/ directly.

• JavaScript Get Started
• Java Get Started
• Python Get Started
• C++/Arduino Get Started

SDK layout

javascript/                 Browser IIFE implementation and examples
java/                       Dependency-free reader JAR and examples
python/                     Python source and examples
cpp/                        C++17 readers, Arduino library, and examples
datasets/                   GIS data shared by all four languages
docs/image/                 Dataset rendering examples
docs/reference/             Public APIs and current file-format specifications
VERSION                     Version of the SDK itself

JavaScript, Java, Python, and C++ are equal target environments. Language artifacts are not placed in version-numbered directories; use the combination included in the SDK as distributed.

Included datasets

The dataset guide lists map resolutions and WordBook encodings. See each dataset's NOTICE.md for sources, processing, and terms of use.

File formats

The current SDK supports WGSMap/3, WGSMapSet/3, the GI01 image chunk, and GisWordBook/0. Pixel value 0 represents an unset area. A positive value is a one-based place-name code in the GisWordBook bundled with the same dataset.

See the technical reference for details of the public APIs and file formats. These documents use galuchat-core as their source of truth and are synchronized when the SDK is built.

About this repository

The SDK repository owns its README files, Get Started descriptions, dataset guide, NOTICE files, and VERSION. Implementation source, build artifacts, GLC files, and GisWordBook files are selectively updated by the synchronization process in galuchat-core.

License

Unless otherwise stated, Galuchat software code and documentation are provided under the Apache License 2.0. Bundled datasets are not covered by Apache License 2.0 and remain subject to their respective terms. See third-party notices and data attribution and each dataset's NOTICE.md for details.

For organizations that require contractual warranties, indemnification, support, additional patent assurances, or different terms, a separate commercial license may be available. No separate agreement is required to use the software under Apache License 2.0.