Skip to main content

viewgeom

Downloads PyPI version Python version

Quick viewer for vector datasets from the command line.

The viewer now includes data filtering and processing tools (>v0.1.4). You can run SQL queries with DuckDB for fast and flexible selection or apply attribute filters with pandas query syntax. You can also send the dataset to QGIS with one command for full desktop visualization, or save as a new file with --save.

Supports:

  • Shapefile (.shp)
  • GeoJSON (.geojson, .json)
  • GeoPackage (.gpkg)
  • GeoParquet (.parquet, .geoparquet)
  • FileGDB (.gdb)*
  • KML, KMZ (.kml, .kmz)*

It automatically detects layers and columns and allows switching visualization columns.

*Saving to KML, KMZ, or FileGDB is not supported. Please use GeoPackage, GeoJSON, JSON, Shapefile, or Parquet for full attribute export (see "Update in v0.1.4").

Installation

pip install viewgeom

Note: Requires Python 3.9 or later.

GeoParquet and Parquet support requires pyarrow, which is optional:

pip install "viewgeom[parquet]"

DuckDB support requires duckdb:

pip install duckdb

Usage

viewgeom <path> [--column <name>] [--layer <name>] \
         [--filter <expr>] [--duckdb <SQL>] \
         [--limit <N>] [--simplify <tol|off>] \
         [--point-size <px>] [--qgis] [--save <file>]

Options

Option Description
--column <name> Choose a numeric or categorical column for coloring
--layer <name> Select a layer in a .gpkg file
--limit N Max number of features to load (default: 100000)
--simplify <tol/off> Geometry simplification; numeric tolerance or off to disable
--point-size px Set point size in pixels (overrides automatic sizing)
--filter "<expr>" Filter using pandas query syntax
--duckdb "<SQL>" Attribute-only SQL filtering using DuckDB
--qgis Export results to a temporary GeoPackage and open in QGIS
--save <path> Save filtered results to the provided file path; format is determined by the filename (e.g. filtered.json, result.kmz, subset.gpkg)
--version Show version information

Examples

# View a GeoJSON
viewgeom gadm41_JPN_1.json

# Color by a numeric column
viewgeom landuse.shp --column area_sqkm

# View a GeoPackage and its specific layer
viewgeom countries.gpkg --layer ADM_ADM_2

# View a geoparquet
viewgeom mangrove_with_EAD.geoparquet --limit 150000 --simplify off

# Attribute filtering with pandas
viewgeom earthquake.geojson --filter "mag > 5"

# Attribute filtering with DuckDB and export to QGIS
viewgeom earthquake.geojson --duckdb "SELECT * FROM data WHERE mag > 5" --qgis

# Save the output as a new file
viewgeom earthquake.geojson --duckdb "SELECT mag FROM data WHERE mag > 5" --save "filtered.geojson"

Keyboard Controls

Key Action
+ / - Zoom in / out
Arrow keys Pan
[ / ] Switch columns
M Switch colormap
B Toggle basemap
R Reset view

Notes

• For fast performance, only the first 100,000 features are displayed by default. Adjust with --limit (e.g., --limit 500000 or --limit 0 for no limit).
• Complex geometries are simplified by default (--simplify 0.01).
Use --simplify off to fully disable simplification.

Update in v0.1.3

  • Viewgeom supports both numeric and categorical columns for visualization, while still giving the option to display outlines only by entering 'x' when prompted.
  • For a numeric column, the tool prints the data range as well as the visualization stretch range. For a categorical column, it prints the number of unique categories and show the first few (up to five).
  • For point data, the tool prints the automatically chosen point size. You can override this by using the --point-size option.
  • KML/KMZ files are fully supported and their attribute columns can be used for coloring.
  • If an internet connection is slow or unavailable, the basemap will be sipped and the viewer will continue without it.
  • The default behavior still limits large datasets to 100000 features. In addition to this, if the feature density is high, the tool further limits the sample to 1000 features. Users can adjust this behavior with the --limit option.
  • As a safeguard, if drawing takes more than 30 seconds, viewgeom will exit automatically.

Update in v0.1.4

  • DuckDB SQL support is now available with --duckdb, allowing you to query any vector dataset using SQL. It works with .shp, .geojson, .gpkg, .parquet, .geoparquet, .kml, and .kmz, and supports column selection, filtering, ordering, and numeric expressions (current limitations: only one dataset at a time, and no spatial queries yet). For more information, please see DuckDB SQL Support.
  • The --filter option evaluates expressions using pandas query syntax. It is a lightweight alternative to SQL for simple filtering.
  • The --qgis export option lets you send filtered results directly to QGIS. A temporary .gpkg file is generated, and QGIS opens automatically on macOS, Linux, and Windows.
  • The --filter option evaluates expressions using pandas query syntax, offering an additional, efficient way to filter attributes without SQL.
  • FileGDB (.gdb) is now supported. Use --layer to select one if it contains multiple layers.
  • You can save outputs with --save. The file format is determined by the filename you provide (e.g., --save filtered.json, --save result.shp, or --save subset.gpkg). Saving to KML or KMZ is disabled because the OGR KML driver (used through pyogrio) does not preserve attribute fields. FileGDB export is also disabled, since full write support requires the proprietary ESRI FileGDB driver. Please use GeoPackage, GeoJSON, JSON, Shapefile, or Parquet for complete attribute export.

Credit & License

viewgeom, which followed from viewtif, was inspired by the NASA JPL Thermal Viewer — Semi-Automated Georeferencer (GeoViewer v1.12) developed by Jake Longenecker (University of Miami Rosenstiel School of Marine, Atmospheric & Earth Science) while at the NASA Jet Propulsion Laboratory, California Institute of Technology, with inspiration from JPL’s ECOSTRESS geolocation batch workflow by Andrew Alamillo. The original GeoViewer was released under the MIT License (2025) and may be freely adapted with citation.

Citation

Longenecker, Jake; Lee, Christine; Hulley, Glynn; Cawse-Nicholson, Kerry; Gleason, Art; Otis, Dan; Galdamez, Ileana; Meiseles, Jacquelyn. GeoViewer v1.12: NASA JPL Thermal Viewer—Semi-Automated Georeferencer User Guide & Reference Manual. Jet Propulsion Laboratory, California Institute of Technology, 2025. PDF.

License

This project is released under the MIT License © 2025 Keiko Nomura.

If you find this tool useful, please consider supporting or acknowledging the author.

Metadata

Release files for viewgeom 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for viewgeom 0.1.4
File Size Uploaded Provenance Actions
viewgeom-0.1.4.tar.gz 17.7 kB Without provenance Details for viewgeom-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for viewgeom 0.1.4
File Interpreter ABI Platform Actions
viewgeom-0.1.4-py3-none-any.whl Python 3 none any Details for viewgeom-0.1.4-py3-none-any.whl

Total release size: 35.4 kB

Release files / viewgeom-0.1.4.tar.gz

Download URL viewgeom-0.1.4.tar.gz
Size 17.7 kB
Tags Source
SHA-256 checksum
How to use checksums
0e9343bc93cee81a4722994417a8f07fb8b30b0393b1c94120b0bdd1b3f05835
BLAKE2b-256 checksum
How to use checksums
54d18c76d069ea5c3a48048cbe96a823e2680e8264616acdfe312bdb76d95a6f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.12

Release files / viewgeom-0.1.4-py3-none-any.whl

Download URL viewgeom-0.1.4-py3-none-any.whl
Size 17.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
64cc0658ef6aadd67ac3cbdaf88092d2e25cc9c063190d6b2362a3e9667a5492
BLAKE2b-256 checksum
How to use checksums
0ad4b601b52fce92130215c4cb0bff19dc58171b687e653c0904a4c4d5956159
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.12

Security for viewgeom 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page