File optimization

When you upload a file, Sarkoa builds a second copy of it that web maps can read quickly. Vectors become PMTiles, rasters become Cloud Optimized GeoTIFF (COG). Your original is left alone. Download always gives you back the bytes you sent.

Most people never need to think past that. This page covers the parts that do come up.

The four things worth knowing

  1. Your original is never modified. Optimization writes a new copy alongside it.
  2. Cloud optimization stops at 10 GB. Bigger files get optimized on your machine first.
  3. Rasters open in one of three display modes, chosen automatically. You can change it later.
  4. Optimization is not analysis. See the next section for exactly what that rules out.

What optimization does not do

Sarkoa is a hosting and delivery platform, not a processing pipeline. It will not:

  • Mask clouds or shadows
  • Apply atmospheric correction
  • Harmonize differences between sensors
  • Mosaic mixed-resolution sources into a single product

If your work needs any of those, run them first and upload the result.

Size limit for remote optimization

Cloud optimization accepts source files up to 10 GB. Anything larger is rejected for automatic processing, because the conversion would not finish reliably.

For a file over 10 GB, build the map-ready version on your own machine and upload that instead. The CLI takes a pre-built PMTiles or COG with sarkoa upload … --cloud-native …, and the QGIS plugin has an Optimize locally before upload checkbox.

Optimizing locally is also worth doing when you want to check the converted file before it leaves your workstation, or when you already have a PMTiles or COG on disk.

Watching it happen

Processing usually takes a few minutes. Status shows on the file row while it runs.

  • On the upload screen, expand How we'll optimize the copy for a summary of what will happen to the file you queued.
  • After processing, the info (ⓘ) control on the files table opens the optimized copy's details. It is read-only.
  • If processing fails, the app shows a reference code and a Download original file button. Your upload is still there.

Failures usually come down to an unsupported format, a missing coordinate system, or a source over the size limit. Troubleshooting walks through each one.

How rasters display

Every raster is sorted into one of three kinds at optimize time, based on what is actually in the file.

Kind What it is How it is drawn
Visual imagery Photographs: aerial shots, drone captures, satellite RGB Colours are baked into the tiles, which keeps them small and fast
Measurement values One band of numbers: elevation, temperature, a vegetation index Values are preserved in the tiles, so colour ramps and thresholds stay adjustable in the viewer
Categorical map Land cover, zoning, anything with a fixed colour table The file's own palette is used, so classes keep their intended colours

Sarkoa guesses from the file itself. A colour table means categorical. A three-band file tagged as RGB means visual. Anything else is treated as measurement.

The guess is usually right, and it matters most when it is wrong. A single-band elevation model read as visual imagery cannot be thresholded, and a photo read as measurement will look strange. If that happens, open Processing details on the file and switch between Visual and Measurement. Sarkoa rebuilds the map copy from your original upload, which takes a few minutes. The original is not affected.

One thing to expect: switching kinds resets the layer's saved style on that file, because a colour ramp and an RGB band mapping are not interchangeable. Maps that already use the layer keep their own copy of the style.

Advanced: what conversion actually changes

You can skip this section unless a layer is not drawing the way you expect.

Rasters

Rasters are reprojected to Web Mercator (EPSG:3857) and rewritten as a COG. Band count and bit depth are preserved. A 16-bit multi-band stack stays 16-bit. Nothing is quietly flattened to 8-bit.

Photographic RGB and scientific stacks are treated differently. A file tagged with RGB colour interpretation gets image-style resampling and transparency handling. A multi-band UInt16 export with undefined band roles is treated as data, so it gets no forced RGB tagging and no invented alpha channel. Declared nodata is respected either way.

Transparency is resolved in this order:

flowchart TB
  RIn[Source raster] --> RNodata{Transparency source?}
  RNodata -->|Internal mask| RMask[Keep mask as alpha]
  RNodata -->|Band-4 alpha| RAlpha[Keep existing alpha]
  RNodata -->|Declared nodata| RDecl[Use metadata nodata]
  RNodata -->|Corners exactly 0 or 255| RCorner[Treat border as transparent]
  RNodata -->|Photographic RGB otherwise| RZero[Treat 0 as transparent]
  RMask --> RStyle[Map-ready COG]
  RAlpha --> RStyle
  RDecl --> RStyle
  RCorner --> RStyle
  RZero --> RStyle

The corner rule only applies to photographic RGB, and only when at least three of the four corners are exactly 0 or exactly 255. That catches the black or white borders left by a rotated orthophoto without eating real data.

The rest, briefly:

  • Colour tables are carried over, so categorical rasters keep the colours the source intended.
  • Display range for continuous rasters is stored as 2nd to 98th percentile hints, so the default view is readable instead of being washed out by a handful of outliers.
  • Overviews use nearest-neighbour for categorical and masked rasters, which keeps class edges sharp, and averaging for continuous imagery, which looks better zoomed out.
  • Compression is lossless for float bands, 16-bit and up, and anything with a mask or alpha channel. Only 8-bit photographic RGB may use lossy compression, and only because the size saving is large and the quality cost is invisible on a photo.

Vectors

Vectors are encoded to PMTiles in WGS 84 (EPSG:4326).

  • Polygon outlines. Sarkoa adds separate outline lines so you can style a fill's border thicker than a hairline. Very large layers skip this and fall back to hairline outlines, since the extra geometry would push tiles over their size budget.
  • Feature retention. Encoding avoids the usual point-thinning at low zoom, so attribute filters and range sliders still see your features when the map is zoomed out. Dense layers may still drop some features at the coarsest zooms when a tile would otherwise be too big.
  • Detail. Overview zooms are simplified for size. The deepest zoom keeps every vertex from your source. City-scale layers get a higher detail floor so neighbourhoods do not look blocky, and worldwide layers stay coarser so encoding finishes in reasonable time. Shared borders between neighbouring polygons are simplified together, which avoids the gaps and spikes you get when each polygon is simplified on its own.
  • Concepts: supported formats, and how originals relate to map copies
  • Custom maps: styling a layer once it is ready
  • CLI and QGIS plugin: optimizing locally before upload