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

geovisio/web/annotations.py

@@ -1,11 +1,17 @@
 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.annotations import (
+    AnnotationCreationParameter,
+    creation_annotation,
+    get_annotation,
+    update_annotation,
+    InputAnnotationShape,
+)
 from geovisio.utils.tags import SemanticTagUpdate
 from geovisio.web.utils import accountIdOrDefault
 from geovisio.utils.params import validation_error
 from geovisio import errors
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel, ValidationError, Field
 from uuid import UUID
 from flask import Blueprint, current_app, request, url_for
 from flask_babel import gettext as _
@@ -14,86 +20,145 @@ from flask_babel import gettext as _
 bp = Blueprint("annotations", __name__, url_prefix="/api")
 
 
-@bp.route("/collections/<uuid:collectionId>/items/<uuid:itemId>/annotations", methods=["POST"])
+class AnnotationPostParameter(BaseModel):
+    shape: InputAnnotationShape
+    """Shape defining the annotation.
+The annotation shape is either a full geojson geometry or only a bounding box (4 floats).
+
+The coordinates should be given in pixel, starting from the bottom left of the picture.
+
+Note that the API will always output geometry as geojson geometry (thus will transform the bbox into a polygon).
+"""
+
+    semantics: List[SemanticTagUpdate] = Field(default_factory=list)
+    """Semantic tags associated to the annotation"""
+
+
+@bp.route("/pictures/<uuid:itemId>/annotations", methods=["POST"])
 @auth.login_required()
-def postAnnotation(collectionId, itemId, account):
+def postAnnotationNonStacAlias(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:
+
+    The is an alias to the `/api/collections/<collectionId>/items/<itemId>/annotations` endpoint (but you don't need to know the collection ID here).
+    ---
+    tags:
+        - Editing
+        - Semantics
+    parameters:
+        - 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/GeoVisioPostAnnotation'
-        security:
-            - bearerToken: []
-            - cookieAuth: []
-        responses:
-            200:
-                description: the annotation metadata
-                content:
-                    application/json:
-                        schema:
-                            $ref: '#/components/schemas/GeoVisioAnnotation'
+                        $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},
+        "SELECT 1 FROM pictures WHERE id = %(pic)s",
+        {"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)
+            post_params = AnnotationPostParameter(**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
-            ),
-        },
+    creation_params = AnnotationCreationParameter(
+        account_id=account_id, picture_id=itemId, shape=post_params.shape, semantics=post_params.semantics
     )
 
+    with db.conn(current_app) as conn:
+        annotation = creation_annotation(creation_params, conn)
+
+        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.getAnnotationById", _external=True, annotationId=annotation.id),
+            },
+        )
+
+
+@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'
+    """
+    return postAnnotationNonStacAlias(itemId=itemId, account=account)
+
 
 @bp.route("/collections/<uuid:collectionId>/items/<uuid:itemId>/annotations/<uuid:annotationId>", methods=["GET"])
 def getAnnotation(collectionId, itemId, annotationId):
     """Get an annotation
 
+    Note that this is the same route as `/api/annotations/<uuid:annotationId>` but you need to know the picture's and collection's IDs.
     ---
     tags:
         - Semantics
@@ -103,19 +168,19 @@ def getAnnotation(collectionId, itemId, annotationId):
           description: ID of collection
           required: true
           schema:
-            type: string
+              type: string
         - name: itemId
           in: path
           description: ID of item
           required: true
           schema:
-            type: string
+              type: string
         - name: annotationId
           in: path
           description: ID of annotation
           required: true
           schema:
-            type: string
+              type: string
     security:
         - bearerToken: []
         - cookieAuth: []
@@ -136,6 +201,41 @@ def getAnnotation(collectionId, itemId, annotationId):
         return annotation.model_dump_json(exclude_none=True), 200, {"Content-Type": "application/json"}
 
 
+@bp.route("/annotations/<uuid:annotationId>", methods=["GET"])
+def getAnnotationById(annotationId):
+    """Get an annotation.
+
+    This is the same route as `/api/collections/<uuid:collectionId>/items/<uuid:itemId>/annotations/<uuid:annotationId>` but you don't need to know the picture's and collection's IDs.
+
+    ---
+    tags:
+        - Semantics
+    parameters:
+        - 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:
+            raise errors.InvalidAPIUsage(_("Annotation %(p)s not found", p=annotationId), 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"""
 
@@ -152,34 +252,29 @@ class AnnotationPatchParameter(BaseModel):
     """
 
 
-@bp.route("/collections/<uuid:collectionId>/items/<uuid:itemId>/annotations/<uuid:annotationId>", methods=["PATCH"])
+@bp.route("/annotations/<uuid:annotationId>", methods=["PATCH"])
 @auth.login_required()
-def patchAnnotation(collectionId, itemId, annotationId, account):
+def patchAnnotationNonStacAlias(annotationId, account):
     """Patch an annotation
 
     Note that if the annotation has no associated tags anymore, it will be deleted.
+
+    Note that is an alias to the `/api/collections/<collectionId>/items/<itemId>/annotations/<annotationId>` endpoint (but you don't need to know the collection/item ID here).
     ---
     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
+              type: string
+    requestBody:
+        content:
+            application/json:
+                schema:
+                    $ref: '#/components/schemas/GeoVisioPatchAnnotation'
     security:
         - bearerToken: []
         - cookieAuth: []
@@ -204,10 +299,56 @@ def patchAnnotation(collectionId, itemId, annotationId, account):
     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)
+        if not annotation:
+            raise errors.InvalidAPIUsage(_("Annotation %(p)s not found", p=annotationId), 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"}
+
+
+@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.
+
+    Note that is the an alias to the `/api/annotations/<annotationId>` endpoint (but you need to know the collection/item ID here).
+    ---
+    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
+    """
+    return patchAnnotationNonStacAlias(annotationId=annotationId, account=account)

geovisio/web/auth.py

@@ -112,7 +112,7 @@ def auth():
 def logout():
     """Log out from geovisio
     * If the OAuth Provider is keycloak, this will redirect to a keycloak confirmation page,
-            and uppon confirmation keycloak will call post_logout_redirect that will invalidate the session
+            and upon confirmation keycloak will call post_logout_redirect that will invalidate the session
     * If the OAuth Provider is not keycloak, this will invalidate the session
     ---
     tags:

geovisio/web/collections.py

@@ -1,6 +1,4 @@
-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
@@ -11,7 +9,7 @@ from geovisio.web.params import (
     parse_datetime_interval,
     parse_bbox,
     parse_collection_filter,
-    parse_sortby,
+    parse_collection_sortby,
     parse_collections_limit,
 )
 from geovisio.utils.sequences import (
@@ -20,7 +18,7 @@ from geovisio.utils.sequences import (
     get_collections,
     get_dataset_bounds,
 )
-from geovisio.utils.fields import SortBy, SortByField, SQLDirection, Bounds, BBox
+from geovisio.utils.fields import SortBy, SortByField, SQLDirection, BBox, parse_relative_heading
 from geovisio.web.rss import dbSequencesToGeoRSS
 from psycopg.rows import dict_row
 from psycopg.sql import SQL
@@ -97,7 +95,7 @@ def dbSequenceToStacCollection(dbSeq, description="A sequence of geolocated pict
             "title": str(dbSeq["name"]),
             "description": description,
             "keywords": ["pictures", str(dbSeq["name"])],
-            "semantics": dbSeq["semantics"] if "semantics" in dbSeq else None,
+            "semantics": dbSeq.get("semantics", []),
             "license": current_app.config["API_PICTURES_LICENSE_SPDX_ID"],
             "created": dbTsToStac(dbSeq["created"]),
             "updated": dbTsToStac(dbSeq.get("updated")),
@@ -160,6 +158,16 @@ def dbSequenceToStacCollection(dbSeq, description="A sequence of geolocated pict
                         "href": url_for("stac_collections.getCollection", _external=True, collectionId=dbSeq["id"]),
                     },
                     get_license_link(),
+                    (
+                        {
+                            "rel": "upload_set",
+                            "type": "application/json",
+                            "title": "Link to the upload set",
+                            "href": url_for("upload_set.getUploadSet", _external=True, upload_set_id=dbSeq["upload_set_id"]),
+                        }
+                        if dbSeq.get("upload_set_id")
+                        else None
+                    ),
                 ]
             ),
         }
@@ -247,7 +255,7 @@ def getAllCollections():
         format = "rss"
 
     # Sort-by parameter
-    sortBy = parse_sortby(request.args.get("sortby"))
+    sortBy = parse_collection_sortby(request.args.get("sortby"))
     if not sortBy:
         direction = SQLDirection.DESC if format == "rss" else SQLDirection.ASC
         sortBy = SortBy(fields=[SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=direction)])
@@ -382,8 +390,7 @@ def getCollection(collectionId):
 
     record = db.fetchone(
         current_app,
-        """
-            SELECT
+        """SELECT
                 s.id,
                 s.metadata->>'title' AS name,
                 ST_XMin(s.bbox) AS minx,
@@ -393,6 +400,7 @@ def getCollection(collectionId):
                 s.status AS status,
                 accounts.name AS account_name,
                 s.account_id AS account_id,
+                s.upload_set_id,
                 s.inserted_at AS created,
                 s.updated_at AS updated,
                 s.current_sort AS current_sort,
@@ -404,7 +412,7 @@ def getCollection(collectionId):
                 ROUND(ST_Length(s.geom::geography)) / 1000 as length_km,
                 s.computed_h_pixel_density,
                 s.computed_gps_accuracy,
-                t.semantics
+                COALESCE(seq_sem.semantics, '[]'::json) AS semantics
             FROM sequences s
             LEFT JOIN (
                 SELECT sequence_id, json_agg(json_strip_nulls(json_build_object(
@@ -413,7 +421,7 @@ def getCollection(collectionId):
                 )) ORDER BY key, value) AS semantics
                 FROM sequences_semantics
                 GROUP BY sequence_id
-            ) t ON t.sequence_id = s.id
+            ) seq_sem ON seq_sem.sequence_id = s.id
             JOIN accounts ON s.account_id = accounts.id, (
                 SELECT
                     array_agg(DISTINCT jsonb_build_object(
@@ -502,6 +510,10 @@ def getCollectionThumbnail(collectionId):
 @auth.login_required_by_setting("API_FORCE_AUTH_ON_UPLOAD")
 def postCollection(account=None):
     """Create a new sequence
+
+    Note that this is the legacy API, upload should be done using the [UploadSet](#UploadSet) endpoints if possible.
+
+    Using an upload set makes it possible to handle more use cases like dispatching pictures into several collections, removing capture duplicates, parralele upload, ...
     ---
     tags:
         - Upload
@@ -511,7 +523,7 @@ def postCollection(account=None):
           required: false
           schema:
             type: string
-          description: An explicit User-Agent value is prefered if you create a production-ready tool, formatted like "PanoramaxCLI/1.0"
+          description: An explicit User-Agent value is preferred if you create a production-ready tool, formatted like "PanoramaxCLI/1.0"
     requestBody:
         content:
             application/json:
@@ -565,7 +577,7 @@ class PatchCollectionParameter(BaseModel):
     """Parameters used to add an item to an UploadSet"""
 
     relative_heading: Optional[int] = None
-    """The relative heading (in degrees), offset based on movement path (0° = looking forward, -90° = looking left, 90° = looking right). Headings are unchanged if this parameter is not set."""
+    """The relative heading (in degrees), offset based on movement path (0° = looking forward, -90° = looking left, 90° = looking right). For single picture collections, 0° is heading north). Headings are unchanged if this parameter is not set."""
     visible: Optional[bool] = None
     """Should the sequence be publicly visible ?"""
     title: Optional[str] = Field(max_length=250, default=None)
@@ -610,15 +622,7 @@ If unset, sort order is unchanged."""
     @field_validator("relative_heading", mode="before")
     @classmethod
     def parse_relative_heading(cls, value):
-        try:
-            relHeading = int(value)
-            if relHeading < -180 or relHeading > 180:
-                raise ValueError()
-            return relHeading
-        except (ValueError, TypeError):
-            raise errors.InvalidAPIUsage(
-                _("Relative heading is not valid, should be an integer in degrees from -180 to 180"), status_code=400
-            )
+        return parse_relative_heading(value)
 
     def has_only_semantics_updates(self):
         return self.model_fields_set == {"semantics"}
@@ -1036,7 +1040,7 @@ def getUserCollection(userId, userIdMatchesAccount=False):
         format = "csv"
 
     # Sort-by parameter
-    sortBy = parse_sortby(request.args.get("sortby"))
+    sortBy = parse_collection_sortby(request.args.get("sortby"))
     if not sortBy:
         sortBy = SortBy(fields=[SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.DESC)])
 

geovisio/web/configuration.py

@@ -1,15 +1,20 @@
 import flask
 from typing import Dict, Any
-from flask import jsonify
+from flask import jsonify, current_app
 from flask_babel import get_locale
 from geovisio.web.utils import get_api_version
+from geovisio.utils import db
+from psycopg.rows import class_row
+from typing import Optional
+from pydantic import BaseModel, Field, ConfigDict, field_serializer
+import datetime
 
 bp = flask.Blueprint("configuration", __name__, url_prefix="/api")
 
 
 @bp.route("/configuration")
 def configuration():
-    """Return instance configuration informations
+    """Return instance configuration information
     ---
     tags:
         - Metadata
@@ -36,6 +41,7 @@ def configuration():
             "license": _license_configuration(),
             "version": get_api_version(),
             "pages": _get_pages(),
+            "defaults": _get_default_values(),
         }
     )
 
@@ -67,9 +73,23 @@ def _license_configuration():
 
 
 def _get_pages():
-    from geovisio.utils import db
-    from flask import current_app
 
     pages = db.fetchall(current_app, "SELECT distinct(name) FROM pages")
 
     return [p[0] for p in pages]
+
+
+class Config(BaseModel):
+    collaborative_metadata: Optional[bool]
+    split_distance: Optional[int] = Field(validation_alias="default_split_distance")
+    split_time: Optional[datetime.timedelta] = Field(validation_alias="default_split_time")
+    duplicate_distance: Optional[float] = Field(validation_alias="default_duplicate_distance")
+    duplicate_rotation: Optional[int] = Field(validation_alias="default_duplicate_rotation")
+
+    @field_serializer("split_time")
+    def split_time_to_s(self, s: datetime.timedelta, _):
+        return s.total_seconds()
+
+
+def _get_default_values():
+    return db.fetchone(current_app, "SELECT * FROM configurations", row_factory=class_row(Config)).model_dump()