geovisio 2.8.1__py3-none-any.whl → 2.9.0__py3-none-any.whl

geovisio/web/annotations.py

@@ -1,17 +1,213 @@
-from geovisio.utils import auth
-from psycopg.rows import dict_row, class_row
-from psycopg.sql import SQL
-from geovisio.utils.semantics import Entity, EntityType, SemanticTagUpdate, update_tags
+from typing import List, Optional
+from geovisio.utils import auth, db
+from geovisio.utils.annotations import AnnotationCreationParameter, creation_annotation, get_annotation, update_annotation
+from geovisio.utils.tags import SemanticTagUpdate
 from geovisio.web.utils import accountIdOrDefault
-from psycopg.types.json import Jsonb
-from geovisio.utils import db
 from geovisio.utils.params import validation_error
 from geovisio import errors
-from pydantic import BaseModel, ConfigDict, ValidationError
+from pydantic import BaseModel, ValidationError
 from uuid import UUID
-from typing import List, Optional
-from flask import Blueprint, request, current_app
+from flask import Blueprint, current_app, request, url_for
 from flask_babel import gettext as _
 
 
 bp = Blueprint("annotations", __name__, url_prefix="/api")
+
+
+@bp.route("/collections/<uuid:collectionId>/items/<uuid:itemId>/annotations", methods=["POST"])
+@auth.login_required()
+def postAnnotation(collectionId, itemId, account):
+    """Create an annotation on a picture.
+
+    The geometry can be provided as a bounding box (a list of 4 integers, minx, miny, maxx, maxy) or as a geojson geometry.
+    All coordinates must be in pixel, starting from the top left of the picture.
+
+    If an annotation already exists on the picture with the same shape, it will be used.
+        ---
+        tags:
+            - Editing
+            - Semantics
+        parameters:
+            - name: collectionId
+              in: path
+              description: ID of collection to retrieve
+              required: true
+              schema:
+                type: string
+            - name: itemId
+              in: path
+              description: ID of item to retrieve
+              required: true
+              schema:
+                type: string
+        requestBody:
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/GeoVisioPostAnnotation'
+        security:
+            - bearerToken: []
+            - cookieAuth: []
+        responses:
+            200:
+                description: the annotation metadata
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/GeoVisioAnnotation'
+    """
+
+    account_id = UUID(accountIdOrDefault(account))
+
+    pic = db.fetchone(
+        current_app,
+        "SELECT 1 FROM sequences_pictures WHERE seq_id = %(seq)s AND pic_id = %(pic)s",
+        {"seq": collectionId, "pic": itemId},
+    )
+    if not pic:
+        raise errors.InvalidAPIUsage(_("Picture %(p)s wasn't found in database", p=itemId), status_code=404)
+
+    if request.is_json and request.json is not None:
+        try:
+            params = AnnotationCreationParameter(**request.json, account_id=account_id, picture_id=itemId)
+        except ValidationError as ve:
+            raise errors.InvalidAPIUsage(_("Impossible to create an annotation"), payload=validation_error(ve))
+    else:
+        raise errors.InvalidAPIUsage(_("Parameter for creating an annotation should be a valid JSON"), status_code=415)
+
+    annotation = creation_annotation(params)
+
+    return (
+        annotation.model_dump_json(exclude_none=True),
+        200,
+        {
+            "Content-Type": "application/json",
+            "Access-Control-Expose-Headers": "Location",  # Needed for allowing web browsers access Location header
+            "Location": url_for(
+                "annotations.getAnnotation", _external=True, annotationId=annotation.id, collectionId=collectionId, itemId=itemId
+            ),
+        },
+    )
+
+
+@bp.route("/collections/<uuid:collectionId>/items/<uuid:itemId>/annotations/<uuid:annotationId>", methods=["GET"])
+def getAnnotation(collectionId, itemId, annotationId):
+    """Get an annotation
+
+    ---
+    tags:
+        - Semantics
+    parameters:
+        - name: collectionId
+          in: path
+          description: ID of collection
+          required: true
+          schema:
+            type: string
+        - name: itemId
+          in: path
+          description: ID of item
+          required: true
+          schema:
+            type: string
+        - name: annotationId
+          in: path
+          description: ID of annotation
+          required: true
+          schema:
+            type: string
+    security:
+        - bearerToken: []
+        - cookieAuth: []
+    responses:
+        200:
+            description: the annotation metadata
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/GeoVisioAnnotation'
+    """
+    with db.conn(current_app) as conn:
+
+        annotation = get_annotation(conn, annotationId)
+        if not annotation or annotation.picture_id != itemId:
+            raise errors.InvalidAPIUsage(_("Annotation %(p)s not found", p=itemId), status_code=404)
+
+        return annotation.model_dump_json(exclude_none=True), 200, {"Content-Type": "application/json"}
+
+
+class AnnotationPatchParameter(BaseModel):
+    """Parameters used to update an annotation"""
+
+    semantics: Optional[List[SemanticTagUpdate]] = None
+    """Tags to update on the annotation. By default each tag will be added to the annotation's tags, but you can change this behavior by setting the `action` parameter to `delete`.
+
+    If you want to replace a tag, you need to first delete it, then add it again.
+
+    Like:
+[
+    {"key": "some_key", "value": "some_value", "action": "delete"},
+    {"key": "some_key", "value": "some_new_value"}
+]
+    """
+
+
+@bp.route("/collections/<uuid:collectionId>/items/<uuid:itemId>/annotations/<uuid:annotationId>", methods=["PATCH"])
+@auth.login_required()
+def patchAnnotation(collectionId, itemId, annotationId, account):
+    """Patch an annotation
+
+    Note that if the annotation has no associated tags anymore, it will be deleted.
+    ---
+    tags:
+        - Semantics
+    parameters:
+        - name: collectionId
+          in: path
+          description: ID of collection
+          required: true
+          schema:
+            type: string
+        - name: itemId
+          in: path
+          description: ID of item
+          required: true
+          schema:
+            type: string
+        - name: annotationId
+          in: path
+          description: ID of annotation
+          required: true
+          schema:
+            type: string
+    security:
+        - bearerToken: []
+        - cookieAuth: []
+    responses:
+        200:
+            description: the annotation metadata
+            content:
+                application/json:
+                    schema:
+                        $ref: '#/components/schemas/GeoVisioAnnotation'
+        204:
+            description: The annotation was empty, it has been correctly deleted
+    """
+    if request.is_json and request.json is not None:
+        try:
+            params = AnnotationPatchParameter(**request.json)
+        except ValidationError as ve:
+            raise errors.InvalidAPIUsage(_("Impossible to patch annotation, invalid parameters"), payload=validation_error(ve))
+    else:
+        raise errors.InvalidAPIUsage(_("Parameter for updating an annotation should be a valid JSON"), status_code=415)
+
+    with db.conn(current_app) as conn:
+
+        annotation = get_annotation(conn, annotationId)
+        if not annotation or annotation.picture_id != itemId:
+            raise errors.InvalidAPIUsage(_("Annotation %(p)s not found", p=itemId), status_code=404)
+
+        a = update_annotation(annotation, params.semantics, account.id)
+        if a is None:
+            return "", 204
+        return a.model_dump_json(exclude_none=True), 200, {"Content-Type": "application/json"}

geovisio/web/collections.py

@@ -1,14 +1,16 @@
+from copy import deepcopy
 from enum import Enum
 from attr import dataclass
 from geovisio import errors, utils, db
 from geovisio.utils import auth, sequences
 from geovisio.utils.params import validation_error
-from geovisio.utils.semantics import SemanticTagUpdate, Entity, EntityType, update_tags
+from geovisio.utils.semantics import Entity, EntityType, update_tags
+from geovisio.utils.tags import SemanticTagUpdate
 from geovisio.web.params import (
     parse_datetime,
     parse_datetime_interval,
     parse_bbox,
-    parse_filter,
+    parse_collection_filter,
     parse_sortby,
     parse_collections_limit,
 )
@@ -16,6 +18,7 @@ from geovisio.utils.sequences import (
     STAC_FIELD_MAPPINGS,
     CollectionsRequest,
     get_collections,
+    get_dataset_bounds,
 )
 from geovisio.utils.fields import SortBy, SortByField, SQLDirection, Bounds, BBox
 from geovisio.web.rss import dbSequencesToGeoRSS
@@ -248,12 +251,18 @@ def getAllCollections():
     if not sortBy:
         direction = SQLDirection.DESC if format == "rss" else SQLDirection.ASC
         sortBy = SortBy(fields=[SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=direction)])
+    # we always add the creation date fields in the sort list (after the selected ones), this will we'll get the `created` bounds of the dataset
+    # we'll also get
+    if not any(s.field == STAC_FIELD_MAPPINGS["created"] for s in sortBy.fields):
+        sortBy.fields.append(SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.ASC))
+    if not any(s.field == STAC_FIELD_MAPPINGS["id"] for s in sortBy.fields):
+        sortBy.fields.append(SortByField(field=STAC_FIELD_MAPPINGS["id"], direction=SQLDirection.ASC))
 
     collection_request = CollectionsRequest(sort_by=sortBy)
 
     # Filter parameter
-    collection_request.user_filter = parse_filter(request.args.get("filter"))
-    collection_request.pagination_filter = parse_filter(request.args.get("page"))
+    collection_request.user_filter = parse_collection_filter(request.args.get("filter"))
+    collection_request.pagination_filter = parse_collection_filter(request.args.get("page"))
 
     # Limit parameter
     collection_request.limit = parse_collections_limit(request.args.get("limit"))
@@ -298,14 +307,14 @@ def getAllCollections():
         },
     ]
 
-    with db.cursor(current_app, row_factory=dict_row) as cursor:
-        stats = cursor.execute("SELECT min(inserted_at) as min, max(inserted_at) as max FROM sequences").fetchone()
-        if stats is None:
+    with db.conn(current_app) as conn:
+        datasetBounds = get_dataset_bounds(conn, collection_request.sort_by, additional_filters=collection_request.user_filter)
+        if datasetBounds is None:
             return ({"collections": [], "links": links}, 200, {"Content-Type": "application/json"})
-        datasetBounds = Bounds(min=stats["min"], max=stats["max"])
-        if collection_request.created_after and collection_request.created_after > datasetBounds.max:
+        creation_date_index = collection_request.sort_by.get_field_index("created")
+        if collection_request.created_after and collection_request.created_after > datasetBounds.last[creation_date_index]:
             raise errors.InvalidAPIUsage(_("There is no collection created after %(d)s", d=collection_request.created_after))
-        if collection_request.created_before and collection_request.created_before < datasetBounds.min:
+        if collection_request.created_before and collection_request.created_before < datasetBounds.first[creation_date_index]:
             raise errors.InvalidAPIUsage(_("There is no collection created before %(d)s", d=collection_request.created_before))
 
     db_collections = get_collections(collection_request)
@@ -322,10 +331,9 @@ def getAllCollections():
     pagination_links = sequences.get_pagination_links(
         route="stac_collections.getAllCollections",
         routeArgs={"limit": collection_request.limit},
-        field=sortBy.fields[0].field.stac,
-        direction=sortBy.fields[0].direction,
+        sortBy=sortBy,
         datasetBounds=datasetBounds,
-        dataBounds=db_collections.query_first_order_bounds,
+        dataBounds=db_collections.query_bounds,
         additional_filters=additional_filters,
     )
 
@@ -402,7 +410,7 @@ def getCollection(collectionId):
                 SELECT sequence_id, json_agg(json_strip_nulls(json_build_object(
                     'key', key,
                     'value', value
-                ))) AS semantics
+                )) ORDER BY key, value) AS semantics
                 FROM sequences_semantics
                 GROUP BY sequence_id
             ) t ON t.sequence_id = s.id
@@ -607,7 +615,7 @@ If unset, sort order is unchanged."""
             if relHeading < -180 or relHeading > 180:
                 raise ValueError()
             return relHeading
-        except ValueError:
+        except (ValueError, TypeError):
             raise errors.InvalidAPIUsage(
                 _("Relative heading is not valid, should be an integer in degrees from -180 to 180"), status_code=400
             )
@@ -629,7 +637,7 @@ def patchCollection(collectionId, account):
     ---
     tags:
         - Editing
-        - Tags
+        - Semantics
     parameters:
         - name: collectionId
           in: path
@@ -749,13 +757,7 @@ def patchCollection(collectionId, account):
                     sqlUpdates.append(SQL("last_account_to_edit = %(account)s"))
 
                     cursor.execute(
-                        SQL(
-                            """
-                            UPDATE sequences
-                            SET {updates}
-                            WHERE id = %(id)s
-                            """
-                        ).format(updates=SQL(", ").join(sqlUpdates)),
+                        SQL("UPDATE sequences SET {updates} WHERE id = %(id)s").format(updates=SQL(", ").join(sqlUpdates)),
                         sqlParams,
                     )
 
@@ -924,7 +926,12 @@ def send_collections_as_csv(collection_request: CollectionsRequest):
         raise errors.InvalidAPIUsage(_("CSV export does not support pagination"), status_code=400)
     if collection_request.filters():
         raise errors.InvalidAPIUsage(_("CSV export does not support filters"), status_code=400)
-    if collection_request.sort_by != SortBy(fields=[SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.DESC)]):
+    if collection_request.sort_by != SortBy(
+        fields=[
+            SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.DESC),
+            SortByField(field=STAC_FIELD_MAPPINGS["id"], direction=SQLDirection.ASC),
+        ]
+    ):
         raise errors.InvalidAPIUsage(_("CSV export does not support sorting by anything but creation date"), status_code=400)
 
     def generate_csv():
@@ -957,7 +964,7 @@ SELECT
     s.computed_gps_accuracy AS computed_gps_accuracy
 FROM sequences s 
 WHERE {filter}
-ORDER BY s.inserted_at DESC
+ORDER BY s.inserted_at DESC, id ASC
 ) TO STDOUT CSV HEADER"""
                 ).format(filter=SQL(" AND ").join(filters)),
                 params,
@@ -966,7 +973,7 @@ ORDER BY s.inserted_at DESC
                 for a in copy:
                     yield bytes(a)
 
-    return stream_with_context(generate_csv()), {"Content-Disposition": "attachment"}
+    return stream_with_context(generate_csv()), {"Content-Type": "text/csv", "Content-Disposition": "attachment"}
 
 
 @bp.route("/users/<uuid:userId>/collection")
@@ -1033,13 +1040,17 @@ def getUserCollection(userId, userIdMatchesAccount=False):
     if not sortBy:
         sortBy = SortBy(fields=[SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.DESC)])
 
+    if not any(s.field == STAC_FIELD_MAPPINGS["created"] for s in sortBy.fields):
+        sortBy.fields.append(SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.ASC))
+    if not any(s.field == STAC_FIELD_MAPPINGS["id"] for s in sortBy.fields):
+        sortBy.fields.append(SortByField(field=STAC_FIELD_MAPPINGS["id"], direction=SQLDirection.ASC))
     collection_request = CollectionsRequest(sort_by=sortBy, userOwnsAllCollections=userIdMatchesAccount)
 
     # Filter parameter
-    collection_request.user_filter = parse_filter(request.args.get("filter"))
+    collection_request.user_filter = parse_collection_filter(request.args.get("filter"))
 
     # Filters added by the pagination
-    collection_request.pagination_filter = parse_filter(request.args.get("page"))
+    collection_request.pagination_filter = parse_collection_filter(request.args.get("page"))
 
     # Limit parameter
     # if not specified, the default with CSV it 1000. if there are more, the paginated API should be used
@@ -1095,8 +1106,6 @@ def getUserCollection(userId, userIdMatchesAccount=False):
                 MAX(LEAST(90, ST_YMax(s.bbox))) AS maxy,
                 MIN(s.inserted_at) AS created,
                 MAX(s.updated_at) AS updated,
-                MIN({order_column}) AS min_order,
-                MAX({order_column}) AS max_order,
                 ROUND(SUM(ST_Length(s.geom::geography))) / 1000 AS length_km
             FROM sequences s
             WHERE {filter}
@@ -1115,6 +1124,13 @@ def getUserCollection(userId, userIdMatchesAccount=False):
             else:
                 raise errors.InvalidAPIUsage(_("No matching sequences found"), 404)
 
+        datasetBounds = get_dataset_bounds(
+            cursor.connection,
+            collection_request.sort_by,
+            additional_filters=SQL(" AND ").join(meta_filter),
+            additional_filters_params={"account": userId},
+        )
+
     collections = get_collections(collection_request)
 
     sequences_links = [
@@ -1164,10 +1180,9 @@ def getUserCollection(userId, userIdMatchesAccount=False):
     pagination_links = sequences.get_pagination_links(
         route="stac_collections.getUserCollection",
         routeArgs={"userId": str(userId), "limit": collection_request.limit},
-        field=sortBy.fields[0].field.stac,
-        direction=sortBy.fields[0].direction,
-        datasetBounds=Bounds(min=meta_collection["min_order"], max=meta_collection["max_order"]),
-        dataBounds=collections.query_first_order_bounds,
+        sortBy=sortBy,
+        datasetBounds=datasetBounds,
+        dataBounds=collections.query_bounds,
         additional_filters=additional_filters,
     )
 

geovisio/web/configuration.py

@@ -29,7 +29,7 @@ def configuration():
             "name": _get_translated(apiSum.name, userLang),
             "description": _get_translated(apiSum.description, userLang),
             "geo_coverage": _get_translated(apiSum.geo_coverage, userLang),
-            "logo": apiSum.logo,
+            "logo": str(apiSum.logo),
             "color": str(apiSum.color),
             "email": apiSum.email,
             "auth": _auth_configuration(),
@@ -53,6 +53,7 @@ def _auth_configuration():
         return {
             "enabled": True,
             "user_profile": {"url": auth.oauth_provider.user_profile_page_url()},
+            "registration_is_open": flask.current_app.config["API_REGISTRATION_IS_OPEN"],
             "enforce_tos_acceptance": flask.current_app.config["API_ENFORCE_TOS_ACCEPTANCE"],
         }
 

geovisio/web/docs.py

@@ -1,5 +1,10 @@
-from geovisio.web import annotations, collections, items, prepare, users, utils, upload_set, reports, excluded_areas, pages
-from geovisio.utils import upload_set as upload_set_utils, reports as reports_utils, excluded_areas as excluded_areas_utils
+from geovisio.web import collections, items, prepare, users, utils, upload_set, reports, excluded_areas, pages
+from geovisio.utils import (
+    upload_set as upload_set_utils,
+    reports as reports_utils,
+    excluded_areas as excluded_areas_utils,
+    annotations as annotations_utils,
+)
 from importlib import metadata
 import re
 
@@ -258,6 +263,9 @@ Note that you may not rely only on these ID that could change through time.
             "GeoVisioUploadSetFiles": upload_set_utils.UploadSetFiles.model_json_schema(
                 ref_template="#/components/schemas/GeoVisioUploadSetFiles/$defs/{model}", mode="serialization"
             ),
+            "UploadSetUpdateParameter": upload_set.UploadSetUpdateParameter.model_json_schema(
+                ref_template="#/components/schemas/UploadSetUpdateParameter/$defs/{model}", mode="serialization"
+            ),
             "GeoVisioCollectionOfCollection": {
                 "allOf": [
                     {"$ref": "#/components/schemas/STACCollection"},
@@ -462,6 +470,11 @@ The CSV headers will be:
                                     "geovisio:producer": {"type": "string"},
                                     "geovisio:image": {"type": "string", "format": "uri"},
                                     "geovisio:thumbnail": {"type": "string", "format": "uri"},
+                                    "geovisio:rank_in_collection": {
+                                        "type": "integer",
+                                        "minimum": 1,
+                                        "title": "Rank of the picture in its collection.",
+                                    },
                                     "original_file:size": {"type": "integer", "minimum": 0, "title": "Size of the original file, in bytes"},
                                     "original_file:name": {"type": "string", "title": "Original file name"},
                                     "panoramax:horizontal_pixel_density": {
@@ -742,6 +755,10 @@ Available properties are:
                         "properties": {
                             "user_profile": {"type": "object", "properties": {"url": {"type": "string"}}},
                             "enabled": {"type": "boolean"},
+                            "registration_is_open": {
+                                "type": "boolean",
+                                "description": "If true, users can create their own account on the instance. Only used for reference in the federation for the moment",
+                            },
                             "enforce_tos_acceptance": {"type": "boolean"},
                         },
                         "required": ["enabled"],
@@ -821,6 +838,12 @@ Available properties are:
                     "payload": {"type": "object", "description": "The error payload"},
                 },
             },
+            "GeoVisioAnnotation": annotations_utils.Annotation.model_json_schema(
+                ref_template="#/components/schemas/GeoVisioAnnotation/$defs/{model}", mode="serialization"
+            ),
+            "GeoVisioPostAnnotation": annotations_utils.AnnotationCreationParameter.model_json_schema(
+                ref_template="#/components/schemas/GeoVisioPostAnnotation/$defs/{model}", mode="serialization"
+            ),
         },
         "parameters": {
             "STAC_bbox": {"$ref": f"https://api.stacspec.org/v{utils.STAC_VERSION}/item-search/openapi.yaml#/components/parameters/bbox"},
@@ -916,6 +939,33 @@ Note that this parameter is not taken in account for 360° pictures, as by defin
                 "required": False,
                 "schema": {"type": "integer", "minimum": 2, "maximum": 180, "default": 30},
             },
+            "searchCQL2_filter": {
+                "name": "filter",
+                "in": "query",
+                "description": """
+A CQL2 filter expression for filtering search results.
+
+Only works for semantic search for the moment.
+
+The attributes must start with "semantics." and formated like "semantics.some_key"='some_value'.
+
+Note: it's important for the attribute to be quoted (`"`) and the value to around simple quotes (`'`) to avoid issues with CQL2 parsing.
+
+For the moment only equality (`=`) and list (`IN`) filters are supported. We do not support searching for multiple different tags at once with an `AND` operator (for example, `"semantics.traffic_sign"='yes' AND "semantics.colour"='red'` __will not work__). We suggest to filter data on your side, after retrieving by the main attribute depending on your interest.
+
+To search for any values of a semantic tag, use `semantics.some_key IS NOT NULL` (case matter here).
+
+Examples:
+
+* "semantics.osm|traffic_sign"='yes'
+* "semantics.osm|traffic_sign" IS NOT NULL'
+* "semantics.osm|amenity" IN ('bench', 'whatever') OR "semantics.osm|traffic_sign"='yes'
+""",
+                "required": False,
+                "schema": {
+                    "type": "string",
+                },
+            },
             "GeoVisioReports_filter": {
                 "name": "filter",
                 "in": "query",