# Compatibility with STAC API

Panoramax viewer works best with a [Panoramax API](https://gitlab.com/panoramax/server/api), but is designed to be compatible with a wide range of [STAC API](https://github.com/radiantearth/stac-api-spec). Although, third-party STAC API needs the following requirements to work with our viewer.

## :octicons-search-16: Search endpoint

Your STAC API should offer a `/search` endpoint ([documentation](https://github.com/radiantearth/stac-api-spec/tree/main/item-search)).

## :fontawesome-regular-images: Collections and items

Collections should correspond to :fontawesome-regular-images: __pictures sequences__, and items corresponding to :fontawesome-regular-image: __individual pictures__.

Individual pictures should follow [STAC item specification](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md), plus some extensions:

- _Perspective imagery specification_ for its pictures and sequences metadata ([documentation](https://github.com/stac-extensions/perspective-imagery))
- _Tiled assets specification_ for smooth display of high-resolution pictures ([documentation](https://github.com/stac-extensions/tiled-assets))

??? info "List of support item metadata"

    - `assets`
        - [`roles`](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#asset-roles): `data`, `visual` and `thumbnail`
        - `type`: `image/jpeg` or `image/webp`
        - `href`
    - `assets_templates`
        - `tiles`
            - `role`: `data`
            - `href`
    - `geometry`
    - `collection`
    - `id`
    - `links`
        - [`rel`](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#link-object): `prev`, `next`, `related`, `via`
        - `type`: `application/geo+json` or `application/json`
        - `id`
        - `geometry`
        - `datetime`
    - `properties`
        - `pers:interior_orientation`
            - `field_of_view`
            - `focal_length`
        - `view:azimuth`
        - `pers:roll`
        - `pers:pitch`
        - `datetime` or `datetimetz`
        - `tiles:tile_matrix_sets`
            - `geovisio`
                - `type`: `TileMatrixSetType`
                - `tileMatrix`
                    - `matrixHeight`
                    - `matrixWidth`
                    - `tileHeight`
                    - `tileWidth`

## :map: Vector tiles

If you want to use map in viewer, your STAC API should offer :map: vector tiles, through one of these ways:

- A [MapLibre Style JSON](https://maplibre.org/maplibre-style-spec/) file, advertised through landing page (`/api`) with a `xyz-style` link.
- A direct tiles URL, pointing to tiles in [MVT format](https://mapbox.github.io/vector-tile-spec/) and following layer structure described below. It must be advertised in landing page (`/api`) using [Web Map Links](https://github.com/stac-extensions/web-map-links) STAC extension (as `xyz` link).

### Layers

MVT Vector tiles must have the following layers:

| Name | Zooms | Mandatory | Properties |
|------|-------|:---------:|------------|
| `sequences` | All | ✅ | - `id`: sequence ID |
| `pictures` | >= 15 | ✅ | - `id`: picture ID<br />- `ts`: picture date/time<br />- `heading`: picture heading in degrees |
| `grid` | < 6 | ❌ | __Mandatory:__<br />- `id`: grid cell ID<br />- `nb_pictures`: amount of pictures<br />- `coef`: value from 0 to 1, relative quantity of available pictures<br />__Optional:__<br />- `nb_360_pictures`<br />- `coef_360_pictures`<br />- `nb_flat_pictures`<br />- `coef_flat_pictures`<br />(similar to `nb_pictures` and `coef` but separated by picture type) |

### Translation

If your vector tiles support multiple languages, you can set in your `style.json` the list of supported languages :

```json
{
    "metadata": {
        "panoramax:locales": ["fr", "en", "latin"]
    }
}
```

The viewer will try to find the best matching `name:LANG` property according to user browser settings.