Concepts

A handful of ideas turn up everywhere in Sarkoa: in the web app, the CLI, the plugins, and the API. They are all simple, but a few of the words are used loosely elsewhere in the industry, so it is worth pinning them down.

flowchart TB
  Org[Organization]
  Folder[Folders]
  File[File]
  Source[Your original upload]
  Opt[Map copy]
  Org --> Folder
  Org --> File
  Folder --> File
  File --> Source
  File --> Opt

Organizations

Everything belongs to an organization: your files, your maps, your plan, and your bill.

When you sign up you get one automatically, just for you. You can create more for teams, or be invited into someone else's. Plans are priced per organization rather than per person, so adding colleagues costs nothing.

If you belong to more than one, the switcher in the top bar moves between them. Files do not move with you. A file lives in exactly one organization.

Files and folders

Anything you upload is a file. Folders organize them, and nest as deep as you like.

You can move and rename files from the web app, the CLI (sarkoa mkdir, sarkoa mv, sarkoa upload --folder), or MCP (create_folder, move_file).

In the API and in map documents you will see files referred to by an assetId. That is the same object under its database name. If you are only using the app, you will never see it.

Your original and the map copy

Every file has two lives.

Your original is exactly what you uploaded. It is stored untouched and Download always returns it byte for byte. Sarkoa never edits it.

The map copy is a second file, built for speed, that the map viewer and tile URLs read from. Vectors become PMTiles, rasters become Cloud Optimized GeoTIFF.

That split is the whole idea. You keep an archival original in whatever format your work needs, and web maps get something they can stream a piece at a time. Neither compromises for the other.

Optimization tunes files for viewing, not for analysis. It will not mask clouds, correct for atmosphere, harmonize sensors, or mosaic mixed resolutions. Full detail in File optimization.

Maps

A custom map is a saved arrangement of layers, styles, and a basemap, with its own link and its own access setting. Adding a file to a map does not copy it; the map points at the file, so fixing the data fixes every map that uses it.

Maps have their own access rules, separate from file permissions. See Sharing and access.

Tiles

Web maps do not download a whole dataset. They fetch small square pieces, called tiles, for the area on screen at the zoom you are looking at. Pan or zoom and the map fetches more.

This is why cloud-optimized formats matter, and it is also the unit Sarkoa meters. See Tile requests.

Tiles are for drawing. When you need to ask which features match rather than draw them, Feature query reads the data itself and returns GeoJSON.

Supported formats

Vector, single files

• GeoJSON (.geojson, .json)
• GeoPackage (vector layers only, not raster tiles)
• GPX
• CSV (points in longitude and latitude, or Easting and Northing with an EPSG code)
• FlatGeobuf (.fgb)
• KML and KMZ
• GeoParquet (.parquet, .geoparquet)
• TopoJSON
• GML
• DXF (needs an EPSG code at upload)

Raster, single files

• GeoTIFF (.tif, .tiff, .geotiff)
• JPEG 2000 (.jp2, .j2k)
• ERDAS Imagine (.img, .hfa)
• NetCDF (.nc, pick a raster variable after upload)

Multi-file uploads

Select every part in one upload, or zip them together:

• Esri Shapefile: .shp, .shx, .dbf, and .prj
• File Geodatabase: a ZIP with one top-level .gdb folder, plus a layer name if it holds several
• Georeferenced raster with a worldfile: a ZIP holding the PNG or TIFF, its worldfile, and a .prj

Glossary

Related

• Quick start: upload something and look at it
• Sharing and access: who can see what
• File optimization: what happens to a file after upload