Input Formats¶
Portolan classifies input files by extension when you run portolan scan
or portolan add. The vocabulary below is generated from the typed
registry in portolan_cli/extension_registry.py, the single source of
truth for how each extension is recognized, routed, and converted.
Formats marked Content-inspected need a look inside the file: a
.parquet is GeoParquet only if it carries geo metadata, a .tif is
cloud-native only if it is a valid COG, and a .csv/.tsv routes to the
vector pipeline only when geometry columns are found (otherwise it is
tabular data, which requires tabular.enabled: true).
Geospatial and Cloud-Native Data¶
| Extension | Format | Routes As | Cloud-Native | Converts To | Notes |
|---|---|---|---|---|---|
.parquet |
GeoParquet | vector | Content-inspected | — | tabular when no geometry is found |
.geojson |
GeoJSON | vector | No | GeoParquet | — |
.shp |
SHP | vector | No | GeoParquet | — |
.gpkg |
GPKG | vector | No | GeoParquet | multi-layer; every layer converts |
.gdb |
GDB | vector | No | GeoParquet | directory format, multi-layer; every layer converts |
.fgb |
FlatGeobuf | vector | Yes | — | — |
.pmtiles |
PMTiles | vector | Yes | — | — |
.csv |
CSV | vector | No | GeoParquet | tabular when no geometry is found |
.tsv |
TSV | vector | No | GeoParquet | tabular when no geometry is found |
.tif |
COG | raster | Content-inspected | — | — |
.tiff |
COG | raster | Content-inspected | — | — |
.jp2 |
JP2 | raster | No | COG | — |
.zarr |
ZARR | — | Yes | — | directory format |
.copc.laz |
COPC.LAZ | — | Yes | — | compound extension |
Non-cloud-native formats are accepted with a conversion warning; Portolan converts vectors to GeoParquet and rasters to COG.
Tabular Data¶
Tabular (non-geospatial) support is opt-in (tabular.enabled: true).
| Extension | Format | Media Type | Notes |
|---|---|---|---|
.parquet |
GeoParquet | application/vnd.apache.parquet | routes to the vector pipeline when geometry is present |
.csv |
CSV | text/csv | routes to the vector pipeline when geometry is present |
.tsv |
TSV | — | routes to the vector pipeline when geometry is present |
.xlsx |
XLSX | — | tabular only |
.xls |
XLS | — | tabular only |
Unsupported Formats¶
These are recognized and rejected with a specific message rather than silently ignored.
| Extension | Format | Media Type | Message |
|---|---|---|---|
.nc |
NetCDF | application/x-netcdf | NetCDF is not yet supported. Support coming soon. |
.netcdf |
NetCDF | application/x-netcdf | NetCDF is not yet supported. Support coming soon. |
.h5 |
HDF5 | application/x-hdf5 | HDF5 is not yet supported. Support coming soon. |
.hdf5 |
HDF5 | application/x-hdf5 | HDF5 is not yet supported. Support coming soon. |
.las |
LAS | application/vnd.las | LAS/LAZ point clouds require COPC format. Use pdal or other tools to convert. |
.laz |
LAZ | application/vnd.laszip | LAS/LAZ point clouds require COPC format. Use pdal or other tools to convert. |
Sidecar Files¶
Sidecars ride along with a primary file and are tracked as assets of it.
| Extension | Media Type | Role |
|---|---|---|
.dbf |
— | — |
.shx |
— | — |
.prj |
— | — |
.cpg |
— | — |
.sbn |
— | — |
.sbx |
— | — |
.ovr |
— | — |
.xml |
application/xml | metadata |
Per-primary sidecar patterns (matched against the primary file's stem):
| Primary | Sidecar Suffixes |
|---|---|
.shp |
.dbf, .shx, .prj, .cpg, .sbn, .sbx, .qix, .xml, .shp.xml |
.tif |
.tfw, .xml, .aux.xml, .ovr |
.tiff |
.tfw, .xml, .aux.xml, .ovr |
.img |
.ige, .rrd, .rde, .xml |
Documentation, Thumbnails, and Visualization¶
| Extension | Media Type | Role |
|---|---|---|
.md |
text/markdown | documentation |
.txt |
text/plain | documentation |
.rst |
— | — |
.html |
text/html | documentation |
.htm |
— | — |
.png |
image/png | thumbnail |
.jpg |
image/jpeg | thumbnail |
.jpeg |
image/jpeg | thumbnail |
.webp |
image/webp | thumbnail |
.gif |
image/gif | thumbnail |
.svg |
image/svg+xml | thumbnail |
.mbtiles |
— | — |
.json |
application/json | metadata |
.pdf |
application/pdf | documentation |
Ignored¶
Build artifacts and binaries are classified as junk and never tracked.
| Extension | Media Type | Role |
|---|---|---|
.exe |
— | — |
.dll |
— | — |
.so |
— | — |
.dylib |
— | — |
.pyc |
— | — |
.pyo |
— | — |
.class |
— | — |
.o |
— | — |
.obj |
— | — |
Aliases that participate only in media-type and role maps (never in format detection):
| Extension | Media Type | Role |
|---|---|---|
.flatgeobuf |
application/vnd.flatgeobuf | data |