{"id":37085718,"url":"https://github.com/manaakiwhenua/raster2dggs","last_synced_at":"2026-01-14T10:32:44.160Z","repository":{"id":144719058,"uuid":"608857264","full_name":"manaakiwhenua/raster2dggs","owner":"manaakiwhenua","description":"DGGS indexer for raster data","archived":false,"fork":false,"pushed_at":"2025-12-19T04:07:50.000Z","size":10979,"stargazers_count":18,"open_issues_count":10,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-12-20T17:38:04.399Z","etag":null,"topics":["dggs","geohash","gis","h3","maidenhead","qth","raster","rhealpix","s2"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/raster2dggs/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/manaakiwhenua.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-02T22:02:44.000Z","updated_at":"2025-11-03T02:27:50.000Z","dependencies_parsed_at":"2023-09-25T15:46:04.336Z","dependency_job_id":"deb682f8-8cf3-46e6-825a-76196a8eac46","html_url":"https://github.com/manaakiwhenua/raster2dggs","commit_stats":{"total_commits":44,"total_committers":2,"mean_commits":22.0,"dds":"0.18181818181818177","last_synced_commit":"9f44292272ffc4e867d8c951a57fad249b2d3494"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/manaakiwhenua/raster2dggs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manaakiwhenua%2Fraster2dggs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manaakiwhenua%2Fraster2dggs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manaakiwhenua%2Fraster2dggs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manaakiwhenua%2Fraster2dggs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manaakiwhenua","download_url":"https://codeload.github.com/manaakiwhenua/raster2dggs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manaakiwhenua%2Fraster2dggs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28417497,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:25:19.714Z","status":"ssl_error","status_checked_at":"2026-01-14T10:22:49.371Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dggs","geohash","gis","h3","maidenhead","qth","raster","rhealpix","s2"],"created_at":"2026-01-14T10:32:44.103Z","updated_at":"2026-01-14T10:32:44.154Z","avatar_url":"https://github.com/manaakiwhenua.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# raster2dggs\n\n[![pypi](https://img.shields.io/pypi/v/raster2dggs?label=raster2ddgs)](https://pypi.org/project/raster2dggs/)\n\nPython-based CLI tool to index raster files to DGGS in parallel, writing out to Parquet.\n\nThis is the raster equivalent of [vector2dggs](https://github.com/manaakiwhenua/vector2dggs).\n\nCurrently this supports the following DGGSs:\n\n- [H3](https://h3geo.org/)\n- [rHEALPix](https://datastore.landcareresearch.co.nz/dataset/rhealpix-discrete-global-grid-system)\n- [S2](http://s2geometry.io/)\n- [A5](https://a5geo.org/)\n\nAnd these geocode systems:\n\n- [Geohash](https://en.wikipedia.org/wiki/Geohash)\n- [Maidenhead Locator System](https://en.wikipedia.org/wiki/Maidenhead_Locator_System)\n\nContributions (particularly for additional DGGSs), suggestions, bug reports and strongly worded letters are all welcome.\n\n![Example use case for raster2dggs, showing how an input raster can be indexed at different DGGS resolutions, while retaining information in separate, named bands](docs/imgs/raster2dggs-example.png \"Example use case for raster2dggs, showing how an input raster can be indexed at different H3 resolutions, while retaining information in separate, named bands\")\n\n## Installation\n\n`pip install raster2dggs`\n\n## Usage\n\n```\nraster2dggs --help\n\nUsage: raster2dggs [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --version  Show the version and exit.\n  --help     Show this message and exit.\n\nCommands:\n  a5          Index raster data into the A5 DGGS\n  geohash     Index raster data into the Geohash DGGS\n  h3          Index raster data into the H3 DGGS\n  healpix     Index raster data into the HEALPix DGGS\n  isea4r      Index raster data into the ISEA4R DGGS\n  isea7h      Index raster data into the ISEA7H DGGS\n  isea9r      Index raster data into the ISEA9R DGGS\n  ivea4r      Index raster data into the IVEA4R DGGS\n  ivea7h      Index raster data into the IVEA7H DGGS\n  ivea9r      Index raster data into the IVEA9R DGGS\n  maidenhead  Index raster data into the Maidenhead DGGS\n  rhp         Index raster data into the rHEALPix DGGS\n  rtea4r      Index raster data into the RTEA9R DGGS\n  rtea7h      Index raster data into the RTEA7H DGGS\n  rtea9r      Index raster data into the RTEA9R DGGS\n  s2          Index raster data into the S2 DGGS\n\n```\n\n```\nraster2dggs h3 --help\n\nUsage: raster2dggs h3 [OPTIONS] RASTER_INPUT OUTPUT_DIRECTORY\n\n  Ingest a raster image and index it to the H3 DGGS.\n\n  RASTER_INPUT is the path to input raster data; prepend with protocol like\n  s3:// or hdfs:// for remote data. OUTPUT_DIRECTORY should be a directory,\n  not a file, as it will be the write location for an Apache Parquet data\n  store, with partitions equivalent to parent cells of target cells at a fixed\n  offset. However, this can also be remote (use the appropriate prefix, e.g.\n  s3://).\n\nOptions:\n  -v, --verbosity LVL             Either CRITICAL, ERROR, WARNING, INFO or\n                                  DEBUG  [default: INFO]\n  -r, --resolution INTEGER RANGE  H3 resolution to index  [0\u003c=x\u003c=15; required]\n  -pr, --parent_res INTEGER RANGE\n                                  H3 parent resolution to index and aggregate\n                                  to. Defaults to max(0, resolution - 6)\n                                  [0\u003c=x\u003c=15]\n  -b, --band TEXT                 Band(s) to include in the output. Can\n                                  specify multiple, e.g. `-b 1 -b 2 -b 4` for\n                                  bands 1, 2, and 4 (all unspecified bands are\n                                  ignored). If unused, all bands are included\n                                  in the output (this is the default\n                                  behaviour). Bands can be specified as\n                                  numeric indices (1-based indexing) or string\n                                  band labels (if present in the input), e.g.\n                                  -b B02 -b B07 -b B12.\n  -u, --upscale INTEGER           Upscaling factor, used to upsample input\n                                  data on the fly; useful when the raster\n                                  resolution is lower than the target DGGS\n                                  resolution. Default (1) applies no\n                                  upscaling. The resampling method controls\n                                  interpolation.  [default: 1]\n  -c, --compression TEXT          Compression method to use for the output\n                                  Parquet files. Options include 'snappy',\n                                  'gzip', 'brotli', 'lz4', 'zstd', etc. Use\n                                  'none' for no compression.  [default:\n                                  snappy]\n  -t, --threads INTEGER           Number of threads to use when running in\n                                  parallel. The default is determined based\n                                  dynamically as the total number of available\n                                  cores, minus one.  [default: 19]\n  -a, --aggfunc [count|mean|sum|prod|std|var|min|max|median|mode]\n                                  Numpy aggregate function to apply when\n                                  aggregating cell values after DGGS indexing,\n                                  in case of multiple pixels mapping to the\n                                  same DGGS cell.  [default: mean]\n  -d, --decimals INTEGER          Number of decimal places to round values\n                                  when aggregating. Use 0 for integer output.\n                                  [default: 1]\n  -o, --overwrite\n  --warp_mem_limit INTEGER        Input raster may be warped to EPSG:4326 if\n                                  it is not already in this CRS. This setting\n                                  specifies the warp operation's memory limit\n                                  in MB.  [default: 12000]\n  --resampling [nearest|bilinear|cubic|cubic_spline|lanczos|average|mode|gauss|max|min|med|q1|q3|sum|rms]\n                                  Input raster may be warped to EPSG:4326 if\n                                  it is not already in this CRS. Or, if the\n                                  upscale parameter is greater than 1, there\n                                  is a need to resample. This setting\n                                  specifies this resampling algorithm.\n                                  [default: average]\n  -co, --compact                  Compact the cells up to the parent\n                                  resolution. Compaction is not applied for\n                                  cells without identical values across all\n                                  bands.\n  -g, --geo [point|polygon|none]  Write output as a GeoParquet (v1.1.0) with\n                                  either point or polygon geometry.  [default:\n                                  none]\n  --tempdir PATH                  Temporary data is created during the\n                                  execution of this program. This parameter\n                                  allows you to control where this data will\n                                  be written.\n  --version                       Show the version and exit.\n  --help                          Show this message and exit.\n```\n\n## Visualising output\n\nOutput is in the Apache Parquet format, hive partitioned with the parent resolution as partition key. The example below is with `-pr 3` with the H3 DGGS.\n\n```bash\ntree /home/user/example.pq\n\n/home/user/example.pq\n├── h3_03=83bb09fffffffff\n│   └── part.0.parquet\n└── h3_03=83bb0dfffffffff\n    └── part.0.parquet\n```\n\nOutput can also be written to GeoParquet (v1.1.0) by including the `-g/--geo` parameter, which accepts:\n- `polygon` for cells represented as boundary polygons\n- `point` for cells represented as centre points\n- `none` for standard Parquet output (not GeoParquet) ← this is the default if `-g/--geo` is not used\n\nGeoParquet output is useful if you want to use the spatial representations of the DGGS cells in traditional spatial analysis, or if you merely want to visualise the output.\n\nBelow are some ways to read and visualise it.\n\n### DuckDB\n\n```bash\n$ duckdb\nDuckDB v1.4.1 (Andium) b390a7c376\nEnter \".help\" for usage hints.\nConnected to a transient in-memory database.\nUse \".open FILENAME\" to reopen on a persistent database.\nD INSTALL spatial;\nD LOAD spatial;\nD SELECT * FROM read_parquet('se_island.pq') LIMIT 7;\n┌┌────────┬────────┬────────┬────────────────────────────────────────────────────────────────────────────────┬─────────────┬─────────┐\n│ band_1 │ band_2 │ band_3 │                                    geometry                                    │    s2_19    │  s2_08  │\n│ float  │ float  │ float  │                                    geometry                                    │   varchar   │ varchar │\n├────────┼────────┼────────┼────────────────────────────────────────────────────────────────────────────────┼─────────────┼─────────┤\n│    0.0 │    0.0 │    0.0 │ POLYGON ((-176.17946725380486 -44.33542073938414, -176.17946725380486 -44.33…  │ 72b47e01e24 │ 72b47   │\n│    0.0 │    0.0 │    0.0 │ POLYGON ((-176.18439390505398 -44.33543749229784, -176.18439390505398 -44.33…  │ 72b47e02a14 │ 72b47   │\n│    0.0 │    0.1 │    0.1 │ POLYGON ((-176.18550630891403 -44.33547457195554, -176.18550630891403 -44.33…  │ 72b47e1d54c │ 72b47   │\n│    0.0 │    0.0 │    0.0 │ POLYGON ((-176.17819578278952 -44.33537828938332, -176.17819578278952 -44.33…  │ 72b47e01d64 │ 72b47   │\n│    0.1 │    0.1 │    0.3 │ POLYGON ((-176.18344039674218 -44.335553297533835, -176.18344039674218 -44.3…  │ 72b47e0282c │ 72b47   │\n│    0.0 │    0.0 │    0.0 │ POLYGON ((-176.17899045588274 -44.335404822417665, -176.17899045588274 -44.3…  │ 72b47e01dfc │ 72b47   │\n│    0.1 │    0.1 │    0.3 │ POLYGON ((-176.1832814769592 -44.33554799806149, -176.1832814769592 -44.3356…  │ 72b47e02824 │ 72b47   │\n└────────┴────────┴────────┴────────────────────────────────────────────────────────────────────────────────┴─────────────┴─────────┘\n```\n\n### GDAL\n\n```bash\nogrinfo -so -al ./se_island.pq\nINFO: Open of `se_island.pq'\n      using driver `Parquet' successful.\n\nLayer name: se_island\nGeometry: Polygon\nFeature Count: 18390\nExtent: (-176.185824, -44.356933) - (-176.159915, -44.335364)\nLayer SRS WKT:\nGEOGCRS[\"WGS 84\",\n    ENSEMBLE[\"World Geodetic System 1984 ensemble\",\n        MEMBER[\"World Geodetic System 1984 (Transit)\"],\n        MEMBER[\"World Geodetic System 1984 (G730)\"],\n        MEMBER[\"World Geodetic System 1984 (G873)\"],\n        MEMBER[\"World Geodetic System 1984 (G1150)\"],\n        MEMBER[\"World Geodetic System 1984 (G1674)\"],\n        MEMBER[\"World Geodetic System 1984 (G1762)\"],\n        MEMBER[\"World Geodetic System 1984 (G2139)\"],\n        MEMBER[\"World Geodetic System 1984 (G2296)\"],\n        ELLIPSOID[\"WGS 84\",6378137,298.257223563,\n            LENGTHUNIT[\"metre\",1]],\n        ENSEMBLEACCURACY[2.0]],\n    PRIMEM[\"Greenwich\",0,\n        ANGLEUNIT[\"degree\",0.0174532925199433]],\n    CS[ellipsoidal,2],\n        AXIS[\"geodetic latitude (Lat)\",north,\n            ORDER[1],\n            ANGLEUNIT[\"degree\",0.0174532925199433]],\n        AXIS[\"geodetic longitude (Lon)\",east,\n            ORDER[2],\n            ANGLEUNIT[\"degree\",0.0174532925199433]],\n    USAGE[\n        SCOPE[\"Horizontal component of 3D system.\"],\n        AREA[\"World.\"],\n        BBOX[-90,-180,90,180]],\n    ID[\"EPSG\",4326]]\nData axis to CRS axis mapping: 2,1\nGeometry Column = geometry\nband_1: Real(Float32) (0.0)\nband_2: Real(Float32) (0.0)\nband_3: Real(Float32) (0.0)\ns2_19: String (0.0)\ns2_08: String (0.0)\n```\n\n### QGIS\n\n```bash\nqgis sample.pq\n```\n\nWith some styling applied:\n\n![Example output shown in QGIS](image.png)\n\n## Installation\n\nPyPi:\n\n```bash\npip install raster2dggs\n```\n\nConda environment:\n\n```yaml\nname: raster2dggs\nchannels:\n  - conda-forge\nchannel_priority: strict\ndependencies:\n  - python\u003e=3.11,\u003c3.12\n  - pip=23.1.*\n  - gdal\u003e=3.8.5\n  - pyproj=3.6.*\n  - pip:\n    - raster2dggs\u003e=0.7.1\n```\n\n\u003c!-- TODO: package raster2dggs and make available on Conda without pip --\u003e\n\n### For development\n\nIn brief, to get started:\n\n- Install [Poetry](https://python-poetry.org/docs/basic-usage/)\n- Install [GDAL](https://gdal.org/)\n    - If you're on Windows, `pip install gdal` may be necessary before running the subsequent commands.\n    - On Linux, install GDAL 3.6+ according to your platform-specific instructions, including development headers, i.e. `libgdal-dev`.\n- Create the virtual environment with `poetry init`. This will install necessary dependencies.\n- Subsequently, the virtual environment can be re-activated with `poetry env activate`.\n\nIf you run `poetry install`, the CLI tool will be aliased so you can simply use `raster2dggs` rather than `poetry run raster2dggs`, which is the alternative if you do not `poetry install`.\n\n#### Code formatting\n\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nPlease run `black .` before committing.\n\n#### Tests\n\nTests are included. To run them, set up a poetry environment, then follow these instructons:\n\n```bash\ncd tests\npython ./test_raster2dggs.py\n```\n\nTest data are included at `tests/data/`.\n\n#### Experimenting\n\nTwo sample files have been uploaded to an S3 bucket with `s3:GetObject` public permission.\n\n- `s3://raster2dggs-test-data/Sen2_Test.tif` (sample Sentinel 2 imagery, 10 bands, rectangular, Int16, LZW compression, ~10x10m pixels, 68.6 MB)\n- `s3://raster2dggs-test-data/TestDEM.tif` (sample LiDAR-derived DEM, 1 band, irregular shape with null data, Float32, uncompressed, 10x10m pixels, 183.5 MB)\n\nYou may use these for experimentation. However you can also use local files too, which will be faster. A good, small (5 MB) sample image is available [here](https://github.com/mommermi/geotiff_sample).\n\nA small test file is also available at [`tests/data/se-island.tif`] (tests/data/se-island.tif).\n\n## Example commands\n\n```bash\nraster2dggs h3 --resolution 11 -d 0 s3://raster2dggs-test-data/Sen2_Test.tif ./tests/data/output/11/Sen2_Test\n```\n\n```bash\nraster2dggs rhp --resolution 11 -d 0 s3://raster2dggs-test-data/Sen2_Test.tif ./tests/data/output/11/Sen2_Test_rhp\n```\n\n```bash\nraster2dggs h3 --resolution 13 --compression zstd --resampling nearest -a median -d 1 -u 2 --geo polygon s3://raster2dggs-test-data/TestDEM.tif ./tests/data/output/13/TestDEM\n```\n\n## Citation\n\n```bibtex\n@software{raster2dggs,\n  title={{raster2dggs}},\n  author={Ardo, James and Law, Richard and Di Maio, Nicoletta},\n  url={https://github.com/manaakiwhenua/raster2dggs},\n  version={0.7.1},\n  date={2025-12-23}\n}\n```\n\nAPA/Harvard\n\n\u003e Ardo, J., Law, R., \u0026 Di Maio, N. (2025). raster2dggs (0.7.1) [Computer software]. https://github.com/manaakiwhenua/raster2dggs\n\n[![manaakiwhenua-standards](https://github.com/manaakiwhenua/raster2dggs/workflows/manaakiwhenua-standards/badge.svg)](https://github.com/manaakiwhenua/manaakiwhenua-standards)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanaakiwhenua%2Fraster2dggs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanaakiwhenua%2Fraster2dggs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanaakiwhenua%2Fraster2dggs/lists"}