Package: vector2dggs
vector2dggsPython-based CLI tool to index raster files to DGGS in parallel, writing out to Parquet.This is the vector equivalent ofraster2dggs.Currently only supports H3 DGGS, and probably has other limitations since it has been developed for a specific internal use case, though it is intended as a general-purpose abstraction. Contributions, suggestions, bug reports and strongly worded letters are all welcome.Currently only supports polygons; but both coverages (strictly non-overlapping polygons), and sets of polygons that do/may overlap, are supported. Overlapping polygons are captured by ensuring that DGGS cell IDs may be non-unique (repeated) in the output.Installationpipinstallvector2dggsUsagevector2dggsh3--help
Usage:vector2dggsh3[OPTIONS]VECTOR_INPUTOUTPUT_DIRECTORYIngestavectordatasetandindexittotheH3DGGS.VECTOR_INPUTisthepathtoinputvectorgeospatialdata.OUTPUT_DIRECTORYshouldbeadirectory,notafileordatabasetable,asitwillinsteadbethewritelocationforanApacheParquetdatastore.

Options:-v,--verbosityLVLEitherCRITICAL,ERROR,WARNING,INFOorDEBUG[default:INFO]-r,--resolution[0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15]H3resolutiontoindex[required]-pr,--parent_res[0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15]H3Parentresolutionfortheoutputpartition.Defaultstoresolution-6-id,--id_fieldTEXTFieldtouseasanID;defaultstoaconstructedsingle0...nindexontheoriginalfeatureorder.-k,--keep_attributesRetainattributesinoutput.ThedefaultistocreateanoutputthatonlyincludesH3cellIDandtheIDgivenbythe-idfield(orthedefaultindexID).-ch,--chunksizeINTEGERThenumberofrowsperindexpartitiontousewhenspatiallypartioning.Adjustingthisnumberwilltradeoffmemoryuseandtime.[default:50;required]-s,--spatial_sorting[hilbert|morton|geohash]Spatialsortingmethodwhenperfomingspatialpartitioning.[default:hilbert]-crs,--cut_crsINTEGERSetthecoordinatereferencesystem(CRS)usedforcuttinglargepolygons(see`--cur-threshold`).DefaultstothesameCRSastheinput.ShouldbeavalidEPSGcode.-c,--cut_thresholdINTEGERCuttinguplargepolygonsintosmallerpiecesbasedonatargetlength.UnitsareassumedtomatchtheinputCRSunitsunlessthe`--cut_crs`isalsogiven,inwhichcaseunitsmatchtheunitsofthesuppliedCRS.[default:5000;required]-t,--threadsINTEGERAmountofthreadsusedforoperation[default:7]-tbl,--tableTEXTNameofthetabletoreadwhenusingaspatialdatabaseconnectionasinput-g,--geom_colTEXTColumnnametousewhenusingaspatialdatabaseconnectionasinput[default:geom]--tempdirPATHTemporarydataiscreatedduringtheexecutionofthisprogram.Thisparameterallowsyoutocontrolwherethisdatawillbewritten.-o,--overwrite--versionShowtheversionandexit.--helpShowthismessageandexit.Visualising outputOutput is in the Apache Parquet format, a directory with one file per partition.For a quick view of your output, you can read Apache Parquet with pandas, and then use h3-pandas and geopandas to convert this into a GeoPackage or GeoParquet for visualisation in a desktop GIS, such as QGIS. The Apache Parquet output is indexed by an ID column (which you can specify), so it should be ready for two intended use-cases:Joining attribute data from the original feature-level data onto computer DGGS cells.Joining other data to this output on the H3 cell ID. (The output has a column likeh3_\d{2}, e.g.h3_09orh3_12according to the target resolution.)Geoparquet output (hexagon boundaries):>>>importpandasaspd>>>importh3pandas>>>g=pd.read_parquet('./output-data/nz-property-titles.12.parquet').h3.h3_to_geo_boundary()>>>gtitle_nogeometryh3_128cbb53a734553ffNA94D/635POLYGON((174.28483-35.69315,174.28482-35.6...8cbb53a734467ffNA94D/635POLYGON((174.28454-35.69333,174.28453-35.6...8cbb53a734445ffNA94D/635POLYGON((174.28416-35.69368,174.28415-35.6...8cbb53a734551ffNA94D/635POLYGON((174.28496-35.69329,174.28494-35.6...8cbb53a734463ffNA94D/635POLYGON((174.28433-35.69335,174.28432-35.6............8cbb53a548b2dffNA62D/324POLYGON((174.30249-35.69369,174.30248-35.6...8cbb53a548b61ffNA62D/324POLYGON((174.30232-35.69402,174.30231-35.6...8cbb53a548b11ffNA57C/785POLYGON((174.30140-35.69348,174.30139-35.6...8cbb53a548b15ffNA57C/785POLYGON((174.30161-35.69346,174.30160-35.6...8cbb53a548b17ffNA57C/785POLYGON((174.30149-35.69332,174.30147-35.6...[52736rowsx2columns]>>>g.to_parquet('./output-data/parcels.12.geo.parquet')For developmentIn brief, to get started:InstallPoetryInstallGDALIf you're on Windows,pip install gdalmay be necessary before running the subsequent commands.On Linux, install GDAL 3.6+ according to your platform-specific instructions, including development headers, i.e.libgdal-dev.Create the virtual environment withpoetry init. This will install necessary dependencies.Subsequently, the virtual environment can be re-activated withpoetry shell.If you runpoetry install, the CLI tool will be aliased so you can simply usevector2dggsrather thanpoetry run vector2dggs, which is the alternative if you do notpoetry install.Code formattingPlease runblack .before committing.Example commandsWith a local GPKG:vector2dggsh3-vDEBUG-idtitle_no-r12-o~/Downloads/nz-property-titles.gpkg~/Downloads/nz-property-titles.parquetWith a PostgreSQL/PostGIS connection:vector2dggsh3-vDEBUG-idogc_fid-r9-p5-t4--overwrite-tbltopo50_lakepostgresql://user:password@host:port/db./topo50_lake.parquetCitation@software{vector2dggs,title={{vector2dggs}},author={Ardo, James and Law, Richard},url={https://github.com/manaakiwhenua/vector2dggs},version={0.6.0},date={2023-04-20}}APA/HarvardArdo, J., & Law, R. (2023). vector2dggs (0.6.0) [Computer software].https://github.com/manaakiwhenua/vector2dggs