Work with Semantics API

The Panoramax API offer various levels of Semantics to help describe what's visible inside the pictures.

You can find semantics in:

• Upload sets, for generic metadata applying to all pictures you send
• Collections / Sequences, for common metadata accross many pictures
• Items / Pictures, for specific context of a single picture
• Annotations, for outlining part of a single picture

They mainly consist in a succession of tags, in a similar fashion of OpenStreetMap's tags.

Structure of semantics in responses

API routes retrieving collections, items or annotations share a common format, stored as semantics property. For example:

{
    "semantics": [
        { "key": "osm|traffic_sign", "value": "stop" },
        { "key": "detection_model[osm|traffic_sign]", "value": "SGBlur/1.0.0" }
    ]
}

A semantics array list each individual tag (key/value) available for the object. Note that keys can be present several times (contrarily to OpenStreetMap), but the key/value pair needs to be unique. For example, if hashtags are set on a picture:

{
    "semantics": [
        { "key": "hashtag", "value": "PanneauBiche" },
        { "key": "hashtag", "value": "Panneauramax" }
    ]
}

You can find them in the following API routes:

• GET /api/upload_sets/{uploadSetId}
• GET /api/collections/{collectionId}
• GET /api/collections/{collectionId}/items/{itemId} (or GET /api/pictures/{itemId})
• GET /api/collections/{collectionId}/items/{itemId}/annotations/{annotationId} (or GET /api/annotations/{annotationId})

Editing object's semantics

You can as well create and edit your own semantics on pictures, sequences and annotations. All available routes are listed in our API documentation.

The semantics update logic we use is differential (or atomic): you only list the tags you want to add or delete. You don't have to repeat all existing tags of the feature.

• This logic is similar to a patch file logic, or to a git commit, which only needs a delta of changes.
• This logic is different from the OSM API, which expects you to always list all tags you want to end with.

Let's see some examples.

Set transport mode at upload

The website upload page allows you to change the transport mode used for capturing a sequence. This is done through the API, when setting the Upload set metadata. For example, when you create an Upload set, beyond other parameters you can set semantics and add the transport mode:

curl -X POST "https://my-panoramax.fr/api/upload_sets" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    --data '{
        ...,
        "semantics": [
            { "action": "add", "key": "transport", "value": "walk" }
        ],
        ...
    }'

Categorize a picture as having a post box

To make pictures easier to find, you can add generic tags that describe the picture as a whole. For example, we could add a tag on the picture to mark it as having a post box, without setting precisely where it is located in the image. This is usually done later, once all your uploads are finished, so using a PATCH over a picture:

curl -X PATCH "https://my-panoramax.fr/api/collections/1234/items/4567" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    --data '{
        "semantics": [
            { "action": "add", "key": "osm|amenity", "value": "post_box" }
        ]
    }'

Draw a bench on a picture

If you're willing to work with detection algorithm (aka AI), you may want to draw various features over pictures in order to train your algorithm. You can do it through the API by creating Annotations on pictures.

The annotations needs two information to be created:

• Semantics, in a similar fashion as seen before
• Shape, to locate it over the picture

The shape is expressed in pixel, with the origin on top-left corner. They can be defined either as a list of coordinates or a GeoJSON-like geometry:

• [minx, miny, maxx, maxy]
• { "type": "Polygon", "coordinates": [ [ [x1, y1], [x2, y2], ... ] ] }

So, to add a bench on our image:

curl -X POST "https://my-panoramax.fr/api/collections/1234/items/4567/annotations" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    --data '{
        "semantics": [
            { "action": "add", "key": "osm|amenity", "value": "bench" }
        ],
        "shape": [100,250,600,900]
    }'

Classify a traffic sign

Panoramax offers a basic detection of traffic signs on public instances. Oldest ones were only setting a basic osm|traffic_sign=yes value on an annotation. If you're willing to make this information more precise, you can replace existing tag of an annotation:

curl -X PATCH "https://my-panoramax.fr/api/collections/1234/items/4567/annotations/1789" \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -H "Content-Type: application/json" \
     --data '{
        "semantics": [
            { "action": "delete", "key": "osm|traffic_sign", "value": "yes" },
            { "action": "add", "key": "osm|traffic_sign", "value": "stop" },
            { "action": "add", "key": "classification_model[osm|traffic_sign=stop]", "value": "MyModel/1.2.3" },
            { "action": "add", "key": "classification_confidence[osm|traffic_sign=stop]", "value": "0.759" },
        ]
    }'

General recommendations

Automated edits, detections & classifications

If you're willing to run automated edits, for example apply on a large amount of pictures results of an automated detection or classification, we strongly recommend that you use tags that allow to track your changes.

In particular, you can add qualifiers for detection and classification, for example:

osm|traffic_sign=yes
detection_model[osm|traffic_sign=yes]=SGBlur/1.0.0
detection_confidence[osm|traffic_sign=yes]=0.999

osm|traffic_sign=FR:A15b
classification_model[osm|traffic_sign=FR:A15b]=Panoramax-Signs/0.1.0
classification_confidence[osm|traffic_sign=FR:A15b]=0.888