Panoramax

https://docs.panoramax.fr
Admin
Panoramax is an open-source digital resource and federated platform for capturing, hosting, and...
Tokens:129,933
Snippets:1,752
Trust Score:8.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setting Up and Serving General Documentation

Source: https://docs.panoramax.fr/backend/dev/develop_server?q=

Install documentation dependencies and start a local server to preview the Mkdocs documentation.

```bash
# Install dependencies
pip install -e . --group docs

# Generate swagger doc, and run mkdocs with a local server
make serve-doc
```

--------------------------------

### Install via uv

Source: https://docs.panoramax.fr/cli/INSTALL?q=

Install the CLI into a persistent environment using uv.

```bash
# install
uv tool install panoramax_cli

# run
panoramax_cli --help
```

--------------------------------

### Install with write-exif support

Source: https://docs.panoramax.fr/pictures-metadata/install

Install the package with the write-exif extra to enable tag writing capabilities.

```bash
pip install geopic_tag_reader[write-exif]
```

```bash
pipx install geopic_tag_reader[write-exif]
```

```bash
pip install -e .[write-exif]
```

--------------------------------

### Install via PyPI

Source: https://docs.panoramax.fr/cli/INSTALL

Install the package using pip and verify the installation.

```bash
pip install panoramax_cli
```

```bash
panoramax_cli --help
```

--------------------------------

### Install from Git repository

Source: https://docs.panoramax.fr/cli/INSTALL

Clone the source code and install dependencies within a virtual environment.

```bash
git clone https://gitlab.com/panoramax/clients/cli.git panoramax_cli
cd panoramax_cli/
```

```bash
# Create the virtual environment in a folder named "env"
python3 -m venv env

# Launches utilities to make environment available in your Bash
source ./env/bin/activate
```

```bash
pip install -e .
```

```bash
pip install -e .[dev,docs]
```

```bash
panoramax_cli --help
```

--------------------------------

### PyFilesystem URL Examples

Source: https://docs.panoramax.fr/backend/install/settings?q=

Examples of valid PyFilesystem strings for local disk or S3-compatible storage backends.

```text
example: 
    * `/path/to/pic/dir` for disk storage
    * `s3://mybucket/myfolder?endpoint_url=https%3A%2F%2Fs3.fr-par.scw.cloud&region=fr-par` for S3 storage
```

--------------------------------

### Install and run via uv

Source: https://docs.panoramax.fr/cli/INSTALL

Use uv to run the CLI directly or install it into a persistent environment.

```bash
uvx panoramax_cli --help
```

```bash
# install
uv tool install panoramax_cli

# run
panoramax_cli --help
```

--------------------------------

### Install Panoramax via Git

Source: https://docs.panoramax.fr/backend/install/install?q=

Install the API from the source repository using a virtual environment.

```bash
# Retrieve API source code
git clone https://gitlab.com/panoramax/server/api.git panoramax-api
cd panoramax-api/

# Enable Python environment
python3 -m venv env
source ./env/bin/activate

# Install Python dependencies
pip install -e .
```

--------------------------------

### Install write-exif dependency

Source: https://docs.panoramax.fr/pictures-metadata/tech/api_reference

Install the required dependencies for the writer module.

```bash
pip install -e .[write-exif]
```

--------------------------------

### Install development dependencies and run tests

Source: https://docs.panoramax.fr/federated-catalog/dev/harvester

Install the development requirements in a virtual environment and execute the test suite.

```bash
pip install -e .[dev]
pytest
```

--------------------------------

### Install and load spatial extension

Source: https://docs.panoramax.fr/federated-catalog/tutorials/duckdb

Required setup to enable spatial query capabilities in DuckDB.

```sql
INSTALL SPATIAL;
LOAD SPATIAL;
```

--------------------------------

### Install Rust toolchain

Source: https://docs.panoramax.fr/federated-catalog/install

Use the official rustup script to install the required Rust environment.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Build and run production

Source: https://docs.panoramax.fr/frontend/02_Setup

Compiles the application for production and starts the server.

```bash
pnpm build
```

```bash
yarn build
```

```bash
npm run build
```

```bash
node server.js
```

--------------------------------

### Install Panoramax via PyPI

Source: https://docs.panoramax.fr/backend/install/install?q=

Install the API package directly from PyPI into a virtual environment.

```bash
# Enable Python environment
python3 -m venv env
source ./env/bin/activate

# Install Python dependencies
pip install geovisio
```

--------------------------------

### Verify CLI installation

Source: https://docs.panoramax.fr/pictures-metadata/install

Check that the tool is installed and accessible.

```bash
geopic-tag-reader --help
```

--------------------------------

### Initialize environment configuration

Source: https://docs.panoramax.fr/backend/install/tutorials/running_docker_keycloak

Create the .env file from the provided example template.

```bash
cp env.example .env
```

--------------------------------

### Install via pipx

Source: https://docs.panoramax.fr/cli/INSTALL

Install the CLI in an isolated virtual environment using pipx.

```bash
pipx install panoramax_cli
```

--------------------------------

### Start Database via Docker Compose

Source: https://docs.panoramax.fr/backend/dev/develop_server?q=

Alternative method to start the database service using the project's Docker Compose configuration.

```bash
docker compose -p panoramax_api_test up -d db
```

--------------------------------

### Install Formatting Dependencies

Source: https://docs.panoramax.fr/backend/dev/develop_server?q=

Installs the required development dependencies for code formatting.

```bash
pip install --group format
```

--------------------------------

### viewer.onceAllAPIsReady()

Source: https://docs.panoramax.fr/web-viewer/reference/components/core/Viewer?q=

Waits for all APIs setup.

```APIDOC
## viewer.onceAllAPIsReady()

### Description
Waits for all APIs setup. This is useful for two-APIs setup.

### Returns
- **Promise** - Fulfils with null when two APIs are ready, rejects with string error message.
```

--------------------------------

### Run Windows binary

Source: https://docs.panoramax.fr/cli/INSTALL

Execute the downloaded Windows executable to verify installation.

```bash
panoramax_cli-win-amd64.exe --help
```

--------------------------------

### Install Bacon for Hot Reloading

Source: https://docs.panoramax.fr/federated-catalog/dev/api

Install the bacon tool to enable automatic rebuilds during development.

```bash
cd api
cargo install --locked bacon
```

--------------------------------

### Install legacy version

Source: https://docs.panoramax.fr/cli/INSTALL

Install a specific older version of the CLI for compatibility with older APIs.

```bash
pip install panoramax_cli=0.3.13
```

--------------------------------

### Run development environments

Source: https://docs.panoramax.fr/frontend/09_Develop

Commands to start the development servers for the front-office and back-office applications.

```bash
pnpm dev:app
```

```bash
pnpm dev:admin
```

--------------------------------

### viewer.onceAPIReady()

Source: https://docs.panoramax.fr/web-viewer/reference/components/core/Viewer

Waits for initial API setup.

```APIDOC
## viewer.onceAPIReady() -> Promise

### Description
Waits for initial API setup.

### Returns
- **Promise** - Fulfils with null when API is ready, rejects with a string error message.
```

--------------------------------

### Install Linux binary to system path

Source: https://docs.panoramax.fr/cli/INSTALL

Move the binary to a system directory for global access.

```bash
chmod u+x panoramax_cli-linux-amd64
mv panoramax_cli-linux-amd64 /usr/local/bin/panoramax_cli

panoramax_cli --help
```

--------------------------------

### Start Keycloak Server

Source: https://docs.panoramax.fr/backend/dev/develop_server?q=

Launches a pre-configured Keycloak instance using Docker Compose.

```bash
docker-compose -f docker/docker-compose-keycloak.yml up
```

--------------------------------

### Start API with Docker

Source: https://docs.panoramax.fr/backend/install/running

Commands to run the API container with standard or SSL configurations.

```bash
docker run \
    -e DB_URL=<database connection string> \
    -p 5000:5000 \
    --name geovisio \
    -v <path where to persist pictures>:/data/geovisio \
    panoramax/api:develop \
    api
```

```bash
docker run \
    -e DB_URL=<database connection string> \
    -p 5000:5000 \
    --name geovisio \
    -v <path where to persist pictures>:/data/geovisio \
    panoramax/api:develop \
    ssl-api
```

--------------------------------

### Start PostgreSQL Test Database with Docker

Source: https://docs.panoramax.fr/backend/dev/develop_server?q=

Initializes a temporary PostgreSQL/PostGIS container for testing purposes.

```bash
docker run -d --name geovisio_test -e POSTGRES_USER=gvs -e POSTGRES_PASSWORD=gvspwd -e POSTGRES_DB=geovisio -p 5445:5432 --shm-size=1g docker.io/postgis/postgis:17-3.5
```

--------------------------------

### Run development servers

Source: https://docs.panoramax.fr/frontend/02_Setup

Starts the development server for either the main application or the admin interface.

```bash
pnpm dev:app
```

```bash
yarn dev:app
```

```bash
npm run dev:app
```

```bash
pnpm dev:admin
```

```bash
yarn dev:admin
```

```bash
npm run dev:admin
```

--------------------------------

### Build and serve documentation with MkDocs

Source: https://docs.panoramax.fr/web-viewer/09_Develop

Installs the necessary dependencies and runs the local development server or builds the static site.

```bash
pip install mkdocs mkdocs-material
mkdocs serve
mkdocs build
```

--------------------------------

### Clone and navigate to the project directory

Source: https://docs.panoramax.fr/backend/install/tutorials/running_docker_osm_auth

Initial setup steps to access the required Docker configuration files.

```bash
git clone https://gitlab.com/panoramax/server/api.git panoramax-api
cd panoramax-api/docker/full-osm-auth/
```

--------------------------------

### GET /api/annotations/:annotationId

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Get a specific annotation by ID (alias).

```APIDOC
## GET /api/annotations/:annotationId

### Description
Get a specific annotation by ID (alias).

### Method
GET

### Endpoint
/api/annotations/:annotationId
```

--------------------------------

### Install dependencies

Source: https://docs.panoramax.fr/frontend/02_Setup

Installs project dependencies using the preferred package manager.

```bash
pnpm install
```

```bash
yarn install
```

```bash
npm install
```

--------------------------------

### Build and deploy application

Source: https://docs.panoramax.fr/frontend/09_Develop

Builds the project and prepares the production environment, followed by starting the Express server.

```bash
pnpm build:deploy
```

```bash
node server.js
```

--------------------------------

### Upgrade via uv tool

Source: https://docs.panoramax.fr/cli/INSTALL

Upgrade the installed tool using uv.

```bash
uv tool upgrade panoramax_cli
```

--------------------------------

### Initialize PhotoViewer with HTML

Source: https://docs.panoramax.fr/web-viewer/reference/components/core/PhotoViewer

Examples showing basic initialization, usage with slotted widgets, and disabling default widgets.

```html
<!-- Basic example -->
<pnx-photo-viewer
  endpoint="https://panoramax.openstreetmap.fr/"
  style="width: 300px; height: 250px"
/>

<!-- With slotted widgets -->
<pnx-photo-viewer
  endpoint="https://panoramax.openstreetmap.fr/"
  style="width: 300px; height: 250px"
>
  <p slot="top-right">My custom text</p>
  <p slot="editors"><a href="https://my.own.tool/">Edit in my own tool</a></p>
</pnx-photo-viewer>

<!-- With only your custom widgets -->
<pnx-photo-viewer
  endpoint="https://panoramax.openstreetmap.fr/"
  style="width: 300px; height: 250px"
  widgets="false"
>
  <p slot="top-right">My custom text</p>
</pnx-photo-viewer>
```

--------------------------------

### Implement Tutorial

Source: https://docs.panoramax.fr/frontend/Components-App

Displays static tutorial images for Android users.

```vue
<Tutorial />
```

--------------------------------

### Initialize SearchBar element

Source: https://docs.panoramax.fr/web-viewer/reference/components/ui/SearchBar?q=

Example of declaring the pnx-search-bar element with custom properties and event handling.

```html
<pnx-search-bar
  id="my-search-bar"
  placeholder="Search something..."
  .searcher=${mysearchfct}
  ._parent=${viewer}
  reduceable="false"
  reduced="false"
  size="xxl" @result=${e => console.log(e.detail)}
>
  <!-- Optional icon for display on left-side of search bar -->
</pnx-search-bar>
```

--------------------------------

### GET /api/collections/:collectionId/items/:itemId/annotations/:annotationId

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Get a specific annotation by ID.

```APIDOC
## GET /api/collections/:collectionId/items/:itemId/annotations/:annotationId

### Description
Get a specific annotation by ID.

### Method
GET

### Endpoint
/api/collections/:collectionId/items/:itemId/annotations/:annotationId
```

--------------------------------

### Run via uvx

Source: https://docs.panoramax.fr/cli/INSTALL?q=

Run the CLI directly using uvx without persistent installation.

```bash
uvx panoramax_cli --help
```

--------------------------------

### Initialize pnx-togglable-group

Source: https://docs.panoramax.fr/web-viewer/reference/components/ui/TogglableGroup

Usage example showing the component structure with a button slot and menu content.

```html
<pnx-togglable-group padded="false" ._parent=${viewer}>
  <pnx-button slot="button">
    Open menu
  </pnx-button>
  <div>Menu content</div>
</pnx-togglable-group>
```

--------------------------------

### Manage Docker services

Source: https://docs.panoramax.fr/backend/install/tutorials/running_docker_keycloak

Commands to start, monitor, and verify the status of the Panoramax authentication services.

```bash
docker compose --project-name geovisio-auth up -d
```

```bash
docker compose -p geovisio-auth ps
```

```bash
docker compose -p geovisio-auth logs -f
```

```bash
curl --fail http://localhost:8080/api
```

--------------------------------

### Create database

Source: https://docs.panoramax.fr/backend/install/database_setup?q=

Initialize the database with UTF-8 encoding and set the owner.

```bash
$ sudo su - postgres -c "psql -c \"CREATE DATABASE panoramax ENCODING 'UTF-8' TEMPLATE template0 OWNER panoramax\""
```

--------------------------------

### Initialize pnx-mini component

Source: https://docs.panoramax.fr/web-viewer/reference/components/layout/Mini

Usage example for the pnx-mini element, showing how to pass an icon and a child component.

```html
<pnx-mini icon=${fa(faMap)} ._parent=${viewer}>
  <pnx-map />
</pnx-mini>
```

--------------------------------

### Start Stats Refresh Timer

Source: https://docs.panoramax.fr/federated-catalog/systemd/systemd?q=

Start the timer responsible for refreshing materialized views for stats.

```bash
systemctl start stats-refresh.timer
```

--------------------------------

### Example URL with Map and Picture Parameters

Source: https://docs.panoramax.fr/web-viewer/03_URL_settings?q=

A sample URL demonstrating the use of map coordinates and picture ID parameters.

```text
https://api.panoramax.xyz/?map=19.51/48.1204522/-1.7199004&pic=890b6268-7716-4e34-ada9-69985e6c1657
```

--------------------------------

### Installing Development Dependencies

Source: https://docs.panoramax.fr/backend/dev/develop_server?q=

Install the project in editable mode with development dependencies. Requires pip version 25.1 or higher.

```bash
pip install -e . --group dev
```

--------------------------------

### HATEOAS Link Structure Example

Source: https://docs.panoramax.fr/backend/api/api

Example of a JSON link object indicating an edit permission, including the HTTP method, endpoint, and editable attributes.

```json
"links": [
    ...
        {
            "rel": "edit",
            "type": "application/json",
            "method": "PATCH", // <-- HTTP verb to use to call the endpoint
            "href": "https://my_panoramax.org/api/collections/some_id", // <-- api endpoint
            "attributes": ["relative_heading", "semantics", "sortby", "title", "visibility"], // <-- the user can patch those fields
        },
    ]
```

--------------------------------

### Run and install Linux binary

Source: https://docs.panoramax.fr/cli/INSTALL

Set execution permissions and run the Linux binary, or move it to a system path for global access.

```bash
chmod u+x panoramax_cli-linux-amd64
./panoramax_cli-linux-amd64 --help
```

```bash
chmod u+x panoramax_cli-linux-amd64
mv panoramax_cli-linux-amd64 /usr/local/bin/panoramax_cli

panoramax_cli --help
```

--------------------------------

### Running the Panoramax API Locally

Source: https://docs.panoramax.fr/backend/dev/develop_server?q=

Start the backend server to access the API and Swagger documentation at localhost:5000/api/docs/swagger.

```bash
panoramax_backend run
```

--------------------------------

### GET /api/collections

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Retrieves a list of sequences.

```APIDOC
## GET /api/collections

### Description
Retrieves a list of sequences.

### Method
GET

### Endpoint
/api/collections

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Common Query Language expression for filtering; supports status='deleted'.
- **created_before** (string) - Optional - Deprecated.
- **created_after** (string) - Optional - Deprecated.
```

--------------------------------

### Initialize Basic Viewer Component

Source: https://docs.panoramax.fr/web-viewer

Create a viewer instance using the pnx-viewer web component.

```html
<pnx-viewer
  endpoint="https://api.panoramax.xyz/api"
/>
```

--------------------------------

### Deploy Meta-Catalog with Docker Compose

Source: https://docs.panoramax.fr/federated-catalog/install

Use Docker Compose to clone the repository and start the meta-catalog services.

```bash
git clone https://gitlab.com/panoramax/server/meta-catalog.git
cd meta-catalog/
docker compose -p meta-catalog up --build
```

--------------------------------

### api.getDataBbox()

Source: https://docs.panoramax.fr/web-viewer/reference/utils/API

Get available data bounding box.

```APIDOC
## api.getDataBbox()

### Description
Get available data bounding box.

### Returns
- **LngLatBoundsLike** - The bounding box or null if not available

### Throws
- Error: If API is not ready
```

--------------------------------

### api.getDataBbox()

Source: https://docs.panoramax.fr/web-viewer/reference/utils/API?q=

Get available data bounding box.

```APIDOC
## api.getDataBbox()

### Description
Get available data bounding box.

### Returns
- **LngLatBoundsLike** - The bounding box or null if not available
```

--------------------------------

### Build Panoramax from Source

Source: https://docs.panoramax.fr/web-viewer

Clone the repository and build the library locally using Node.js.

```bash
git clone https://gitlab.com/panoramax/clients/web-viewer.git
cd web-viewer/
npm install
npm build
```

--------------------------------

### GET /api/reports

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Retrieve a list of user reports.

```APIDOC
## GET /api/reports

### Description
Retrieve a list of user reports.

### Method
GET

### Endpoint
/api/reports
```

--------------------------------

### photo.playSequence()

Source: https://docs.panoramax.fr/web-viewer/reference/components/ui/Photo

Starts continuous playback of the current sequence.

```APIDOC
## photo.playSequence()

### Description
Goes continuously to next picture in sequence as long as possible.
```

--------------------------------

### Terminal

Source: https://docs.panoramax.fr/frontend/Components-App

A terminal-style component for displaying installation and upload commands.

```APIDOC
## Terminal

### Description
Displays installation and upload commands in a terminal-style UI.

### Props
- **textUpload** (String) - Optional - The upload command text.
- **textInstall** (String) - Optional - The installation command text.

### Usage Example
<Terminal text-install="pip install panoramax" text-upload="panoramax upload ./images" />
```

--------------------------------

### Initialize and Configure SemanticsEditor

Source: https://docs.panoramax.fr/web-viewer/reference/components/ui/SemanticsEditor

Demonstrates basic component usage, validity checking, and CSS styling via shadow parts.

```html
<!-- Basic example -->
<pnx-semantics-editor
   id="editor"
   semantics=${mypic.semantics}
   ._t=${viewer._t}
   onchange=${e => console.log(e.detail.semantics)}
/>

<!-- You can access editor and check its validity through native web browser functions -->
<script>
   const editor = document.getElementById("editor");
   console.log(editor.checkValidity()); // True if input is valid
</script>

<!-- You can change specifically style of textarea -->
<style>
  pnx-semantics-editor::part(text) {
     color: blue;
  }
</style>
```

--------------------------------

### api.getUserName(userId)

Source: https://docs.panoramax.fr/web-viewer/reference/utils/API

Get user name based on its ID.

```APIDOC
## api.getUserName(userId)

### Description
Get user name based on its ID.

### Parameters
- **userId** (string) - Required - The user UUID

### Returns
- **Promise<string|null>** - The user name (or null if not found)

### Throws
- Error: If API is not ready
```

--------------------------------

### Build and run the API

Source: https://docs.panoramax.fr/federated-catalog/install

Compile and execute the API with the specified database connection string.

```bash
cd api
cargo run --release -- --db-url=postgres://username:password@localhost:5432/panoramax
```

--------------------------------

### api.getUserName(userId)

Source: https://docs.panoramax.fr/web-viewer/reference/utils/API?q=

Get user name based on its ID.

```APIDOC
## api.getUserName(userId)

### Description
Get user name based on its ID.

### Parameters
- **userId** (string) - Required - The user UUID

### Returns
- **Promise<string|null>** - The user name (or null if not found)
```

--------------------------------

### GET /api/users/me/reports

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Retrieve reports for the currently authenticated user.

```APIDOC
## GET /api/users/me/reports

### Description
Retrieve reports for the currently authenticated user.

### Method
GET

### Endpoint
/api/users/me/reports
```

--------------------------------

### GET & POST /api/search

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Searches for pictures across the system.

```APIDOC
## GET & POST /api/search

### Description
Searches for pictures. Note that numberMatched and numberReturned properties are not returned in the response.

### Method
GET, POST

### Endpoint
/api/search
```

--------------------------------

### Initialize pnx-viewer component

Source: https://docs.panoramax.fr/web-viewer/reference/components/core/Viewer

Examples of embedding the viewer with different configurations, including metacatalog settings, custom slotted widgets, and map options.

```html
<!-- Basic example (embeds metacatalog) -->
<pnx-viewer
  endpoint="https://panoramax.openstreetmap.fr/"
  style="width: 300px; height: 250px"
/>

<!-- Basic example (without metacatalog) -->
<pnx-viewer
  endpoint="https://panoramax.openstreetmap.fr/"
  metacatalog="false"
  style="width: 300px; height: 250px"
/>

<!-- With slotted widgets -->
<pnx-viewer
  endpoint="https://panoramax.openstreetmap.fr/"
  style="width: 300px; height: 250px"
>
  <p slot="top-right">My custom text</p>
  <p slot="editors"><a href="https://my.own.tool/">Edit in my own tool</a></p>
</pnx-viewer>

<!-- With only your custom widgets -->
<pnx-viewer
  endpoint="https://panoramax.openstreetmap.fr/"
  style="width: 300px; height: 250px"
  widgets="false"
>
  <p slot="top-right">My custom text</p>
</pnx-viewer>

<!-- With map options -->
<pnx-viewer
  endpoint="https://panoramax.openstreetmap.fr/"
  style="width: 300px; height: 250px"
  map-options="{'maxZoom': 15, 'background': 'aerial', 'raster': '...'}"
/>
```

--------------------------------

### GET & POST /api/search

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility?q=

Search for pictures across the system.

```APIDOC
## GET & POST /api/search

### Description
Search for pictures. Note that numberMatched and numberReturned properties are not returned.

### Method
GET, POST

### Endpoint
/api/search
```

--------------------------------

### Initialize pnx-location-precision-doc

Source: https://docs.panoramax.fr/web-viewer/reference/components/menus/LocationPrecisionDoc

Use this element to render the location precision documentation summary within a Lit template.

```html
<pnx-location-precision-doc ._t=${viewer._t} />
```

--------------------------------

### GET /api/collections

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility?q=

Retrieve a list of sequences with optional filtering.

```APIDOC
## GET /api/collections

### Description
Retrieve a list of sequences. Supports filtering via CQL expressions.

### Method
GET

### Endpoint
/api/collections

### Parameters
#### Query Parameters
- **filter** (string) - Optional - CQL expression for filtering (e.g., status='deleted')
- **created_before** (string) - Optional - Deprecated
- **created_after** (string) - Optional - Deprecated
```

--------------------------------

### Generate project documentation

Source: https://docs.panoramax.fr/pictures-metadata/develop

Update the USAGE.md file or serve the Mkdocs documentation locally.

```bash
make docs
```

```bash
pip install -e .[docs]
mkdocs serve
```

--------------------------------

### GET /api/configuration/excluded_areas

Source: https://docs.panoramax.fr/backend/install/deep_dive/excluded_areas

Retrieves the list of general excluded areas.

```APIDOC
## GET /api/configuration/excluded_areas

### Description
Lists general excluded areas. If `all=true` is provided, it returns all areas; otherwise, it returns publicly visible areas.

### Method
GET

### Endpoint
/api/configuration/excluded_areas

### Parameters
#### Query Parameters
- **all** (boolean) - Optional - If true, returns all areas including non-public ones.
```

--------------------------------

### api.getPictureThumbnailURL(picId, [seqId])

Source: https://docs.panoramax.fr/web-viewer/reference/utils/API

Get thumbnail URL for a specific picture.

```APIDOC
## api.getPictureThumbnailURL(picId, [seqId])

### Description
Get thumbnail URL for a specific picture.

### Parameters
- **picId** (string) - Required - The picture unique identifier
- **seqId** (string) - Optional - The sequence ID

### Returns
- **Promise<string|null>** - The corresponding URL on resolve, or null if no thumbnail could be found

### Throws
- Error: If API is not ready
```

--------------------------------

### Perform a release

Source: https://docs.panoramax.fr/cli/DEVELOP

Steps to update versioning, documentation, and merge changes from develop to main.

```bash
git checkout develop
git pull

vim CHANGELOG.md                # Edit version + links at bottom
vim panoramax_cli/__init__.py   # Edit version
make docs ci

git add *
git commit -m "Release x.x.x"
git tag -a x.x.x -m "Release x.x.x"
git push origin develop
git checkout main
git merge develop
git push origin main --tags
```

--------------------------------

### Loading Panoramax Web Viewer Dependencies

Source: https://docs.panoramax.fr/web-viewer/tutorials/migrate_v5

Examples for loading the viewer via ES Modules or the legacy bundled approach.

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@5.0.0/build/esm/index.js"></script>
```

```html
<script src="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@5.0.0/build/cjs/index.cjs"></script>
```

```html
<link rel="stylesheet" type="text/css" href="web-viewer/build/index.css" />
<script src="web-viewer/build/index.js"></script>
```

--------------------------------

### api.getPictureThumbnailURL(picId, [seqId])

Source: https://docs.panoramax.fr/web-viewer/reference/utils/API?q=

Get thumbnail URL for a specific picture.

```APIDOC
## api.getPictureThumbnailURL(picId, [seqId])

### Description
Get thumbnail URL for a specific picture.

### Parameters
- **picId** (string) - Required - The picture unique identifier
- **seqId** (string) - Optional - The sequence ID

### Returns
- **Promise<string|null>** - The corresponding URL on resolve, or null if no thumbnail could be found
```

--------------------------------

### GET /api/auth/logout

Source: https://docs.panoramax.fr/backend/api/api?q=

Logs the user out of the current Panoramax instance session.

```APIDOC
## GET /api/auth/logout

### Description
Performs a logout from the current Panoramax instance.

### Method
GET

### Endpoint
/api/auth/logout
```

--------------------------------

### Initialize Viewer with Plugin

Source: https://docs.panoramax.fr/web-viewer/tutorials/plugins

Create the viewer component programmatically in JavaScript to pass the plugin configuration via psv-options.

```javascript
<script type="module">
    // Import the plugin
    import { CompassPlugin } from "@photo-sphere-viewer/compass-plugin";

    // Create PhotoViewer element
    const viewer = document.createElement("pnx-photo-viewer");
    viewer.id = "viewer";
    viewer.classList.add("fullpage");
    viewer.setAttribute("picture", "329af5c6-4761-4a6d-9c1e-674fd6daa8b6");

    // Define plugins list in PSV options
    viewer["psv-options"] = { plugins: [
        CompassPlugin.withConfig({ position: "top right"})
    ] };

    // Set Panoramax endpoint last, to avoid premature PSV loading
    viewer.setAttribute("endpoint", "https://explore.panoramax.fr/api");
    document.body.appendChild(viewer);
</script>
```

--------------------------------

### GET /api/auth/login

Source: https://docs.panoramax.fr/backend/api/api?q=

Redirects the user to the configured OAuth provider for authentication.

```APIDOC
## GET /api/auth/login

### Description
Redirects the user to the configured instance's OAuth provider to initiate the authentication flow.

### Method
GET

### Endpoint
/api/auth/login
```

--------------------------------

### Start API with Gunicorn or Waitress

Source: https://docs.panoramax.fr/backend/install/running

Commands to run the Panoramax API using production-ready WSGI servers.

```bash
gunicorn -b :5000 'geovisio:create_api()'
```

```bash
pip install waitress
python3 -m waitress --port 5000 --url-scheme=https --call 'geovisio:create_api'
```

--------------------------------

### GET /api/users/me/tokens

Source: https://docs.panoramax.fr/backend/api/api

Retrieves a list of Panoramax tokens for the authenticated user.

```APIDOC
## GET /api/users/me/tokens

### Description
Retrieves a list of tokens associated with the currently authenticated user. This requires an active session cookie.

### Method
GET

### Endpoint
/api/users/me/tokens

### Response
#### Success Response (200)
- **tokens** (array) - List of token objects containing id, description, and links.
```

--------------------------------

### Start services with optional blurring

Source: https://docs.panoramax.fr/backend/install/tutorials/running_docker_keycloak

Launch the Docker containers including the optional blurring service using multiple compose files.

```bash
docker compose --project-name geovisio-osm -f docker-compose.yml -f ../docker-compose-blurring.yml up -d
```

--------------------------------

### GET /api/pictures/:itemId/annotations

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

List annotations for a specific picture (alias).

```APIDOC
## GET /api/pictures/:itemId/annotations

### Description
List annotations for a specific picture (alias).

### Method
GET

### Endpoint
/api/pictures/:itemId/annotations
```

--------------------------------

### Run Docker Compose with Blurring API

Source: https://docs.panoramax.fr/backend/install/install?q=

Start a full Panoramax instance including the optional blurring service.

```bash
docker compose -f docker/docker-compose-full.yml -f docker/docker-compose-blurring.yml up
```

--------------------------------

### GET /api/pictures/:itemId

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Retrieve a specific picture by ID (alias).

```APIDOC
## GET /api/pictures/:itemId

### Description
Retrieve a specific picture by ID (alias).

### Method
GET

### Endpoint
/api/pictures/:itemId
```

--------------------------------

### GET /api/collections/:collectionId/items/:itemId/annotations

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

List all annotations for a specific picture.

```APIDOC
## GET /api/collections/:collectionId/items/:itemId/annotations

### Description
List all annotations for a specific picture.

### Method
GET

### Endpoint
/api/collections/:collectionId/items/:itemId/annotations
```

--------------------------------

### Run Docker Compose on Linux

Source: https://docs.panoramax.fr/backend/install/install?q=

Start a full Panoramax instance using host networking, specifically for Linux environments.

```bash
docker compose -f docker/docker-compose-full.yml -f docker/docker-compose-full-linux.yml up
```

--------------------------------

### GET /api/reports/:id

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Retrieve a specific user report by ID.

```APIDOC
## GET /api/reports/:id

### Description
Retrieve a specific user report by ID.

### Method
GET

### Endpoint
/api/reports/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the report.
```

--------------------------------

### View upload command help

Source: https://docs.panoramax.fr/cli/USAGE

Displays the help menu for the upload subcommand.

```bash
panoramax_cli upload --help
```

--------------------------------

### GET /api/collections/:collectionId/items/:itemId

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Retrieves metadata for a specific picture.

```APIDOC
## GET /api/collections/:collectionId/items/:itemId

### Description
Retrieves metadata for a specific picture. Note that response status 102 indicates the picture is still under process.

### Method
GET

### Endpoint
/api/collections/:collectionId/items/:itemId

### Parameters
#### Path Parameters
- **collectionId** (string) - Required - The ID of the collection.
- **itemId** (string) - Required - The ID of the picture item.
```

--------------------------------

### Configure API via .env Files

Source: https://docs.panoramax.fr/backend/install/settings?q=

Load configuration from a specified .env file using various tools.

```bash
panoramax_backend --env-file my_config.env <command>
```

```bash
flask --env-file my_config.env <command>
```

```bash
dotenv --file my_config.env run waitress-serve --port 5000 --call geovisio:create_api
```

```bash
dotenv --file my_config.env run gunicorn -b :5000 'geovisio:create_api()'
```

```bash
docker run --env-file my_config.env panoramax/api:latest <command>
```

--------------------------------

### GET /api/collections/:collectionId/items/:itemId

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility?q=

Retrieve metadata for a specific picture.

```APIDOC
## GET /api/collections/:collectionId/items/:itemId

### Description
Retrieve metadata for a specific picture. Response status 102 indicates processing, 200 indicates ready.

### Method
GET

### Endpoint
/api/collections/:collectionId/items/:itemId

### Parameters
#### Path Parameters
- **collectionId** (string) - Required - The ID of the collection
- **itemId** (string) - Required - The ID of the item
```

--------------------------------

### Execute release commands

Source: https://docs.panoramax.fr/web-viewer/90_Releases

Run these commands sequentially to prepare, commit, and push a new version release.

```bash
git checkout develop

vim package.json        # Change version
vim package-lock.json   # Change version
npm run doc
npm run build           # To re-generate code snippets

vim CHANGELOG.md    # Replace unreleased to version number (and links at bottom)

git add *
git commit -m "Release x.x.x"
git tag -a x.x.x -m "Release x.x.x"
git push origin develop
git checkout main
git merge develop
git push origin main --tags
```

--------------------------------

### Initialize pnx-popup component

Source: https://docs.panoramax.fr/web-viewer/reference/components/ui/Popup

Displays a basic usage example of the pnx-popup element with a close event listener.

```html
<pnx-popup @close=${() => alert("closed")}>
   <h3>Popup content</h3>
</pnx-popup>
```

--------------------------------

### GET /api/collections/:collectionId/items

Source: https://docs.panoramax.fr/backend/dev/STAC_compatibility

Retrieves a list of pictures in a specific sequence.

```APIDOC
## GET /api/collections/:collectionId/items

### Description
Retrieves a list of pictures in a specific sequence.

### Method
GET

### Endpoint
/api/collections/:collectionId/items

### Parameters
#### Path Parameters
- **collectionId** (string) - Required - The ID of the collection.

#### Query Parameters
- **startAfterRank** (integer) - Optional - Pagination parameter.
- **withPicture** (boolean) - Optional - Include picture details.
```
Tokens:
Raw