New version of the API including a hierarchical organization of data

9ab1132d · Antonio · a01efbeb · 9ab1132d
Commit 9ab1132d authored Jan 22, 2020 by Antonio
Showing with 14 additions and 14 deletions
spslapi.yml
--- a/spslapi.yml
+++ b/spslapi.yml
-swagger: "2.0"
+sswagger: "2.0"
 info:
  description: >
    Simple REST API for access to massive clouds repositories in the project SPSLidar.
-    Point cloud models are spatially indexed using the coordinates of their bounding boxes. Each model has its data organized in a hierarchical structure of data blocks. Each data block represents a region of space and provides an approximated view of model for that region (a sampling or level of detail). Data associated to a data block is encoded in LAZ format.
+    Point cloud models are spatially indexed using the geographic coordinates of their bounding boxes. At the same time, each model has its data organized in a hierarchical structure of data blocks. Each data block represents a region of space and provides an approximated view of model for that region (i.e., a level of detail as a sampling of the point cloud). Data associated to a data block is encoded in LAZ format, although in the future, alternative formats can be considered.
  version: "0.2"
  title: SPSLidar API
  contact:
@@ -178,12 +177,7 @@ paths:
      - "data"
      summary: Returns metadata asociated to a data block
      description: >
-        A model is organized into a hierarchical structure of
+          This endpoint provides the metadata associated to the data block. Data block 0 represents the first LOD of the entire model. Its descendants have ids 0..7 (considering 8 descendants), and in general descendants ids are computed as 8 * <parent_data_block_id> + <num_descendant> where <num_descendant> varies between 0 and 7.
-        data blocks. Each data block represents a region of space enclosed in a box. This region is subdivided into a fixed number of region (usually 8) that are also represented by data blocks, and so forth. 
-          Each data block represents a level of detail (LOD) of the model in the associated region. In the case of a point model, this is a sampling of the points in the region. Data must not be redundant, i.e. data stored at a given data block must not be replicated in descendants. 
-          This endpoint does not provide the actual data but the metadata (i.e., bounding box, descendant data blocks etc.). Data block 0 represents the first LOD of the entire model. Its descendants have ids 0..7 (considering 8 descendants), and in general descendants ids are computed as 8 * <parent_data_block_id> + <num_descendant> where <num_descendant> varies between 0 and 7.
          The data associated to the data block is provided different endpoint, and several formats could be available. By now only LAZ format (for point data) is supported by .../data/{id}/laz endpoint. 
      produces:
@@ -252,7 +246,9 @@ paths:
      - "data"
      summary: Defines the point data of the model in LAZ format 
      description: >
-        After creating a model, data should be supplied using this endpoint. By now only LAZ format is supported. Internally, the server should open the original LAZ file and build a hierarchy of data blocks of the predefined size also in LAZ format.
+        After creating a model, data should be supplied using this endpoint. By now only LAZ format is supported. Internally, the server should open the original LAZ file and build a hierarchy of data blocks of the predefined size (see data block metadata) also in LAZ format.
+        The LAZ data blocks should be normalized, using the normalized coordinates with respect to the bounding box of the model. 
      consumes:
      - application/octet-stream
      parameters:
@@ -287,7 +283,7 @@ definitions:
  Workspace:
      type: object
-      description: Workspace containing one or more georreferenced point clouds
+      description: Workspace containing one or more georreferenced point clouds. Only a few should workspaces should exists (e.g., Iberian archaeology sites, civil engineering projects, etc.), since many workspaces would reduce the usefulness of the system. 
      properties:
        name:
          type: string
@@ -304,7 +300,7 @@ definitions:
  Model:
    type: object
-    description: Georreferenced model (normally a point cloud)
+    description: Georreferenced model (normally a point cloud). Models can overlap in space and time (evolution of a model over time or several models of the same site in different resolutions).
    properties:
      name:
        type: string
@@ -326,7 +322,7 @@ definitions:
    - bbox
    example:
      name: CastilloSCatalina
-      description: |
+      description: >
        Model of Castillo de Santa Catalina (Jaén). 
        Captured with Leica RTC360 laser scanner
      date: "2019-05-03T12:10:00Z"
@@ -340,7 +336,11 @@ definitions:
  DataBlock:
    type: object
    description: > 
-      Medatada associated to a data block. The bounding box of the data block is in normalized coordinates with respect to the bounding box of the entire model.
+      A model is organized into a hierarchical structure of data blocks. Each data block represents a region of space enclosed in a box. This region is subdivided into a fixed number of region (usually 8) that are also represented by data blocks, and so forth. 
+      Each data block represents a level of detail (LOD) of the model in the associated region. In the case of a point model, this is a sampling of the points in the region. Data must not be redundant, i.e. data stored at a given data block must not be replicated in descendants. 
+      This object does not provide the actual data, but its associated metadata (bounding box, size of the LOD, ids of descendant datablocks). The bounding box of the data block is in normalized coordinates with respect to the bounding box of the entire model. The ids of the descendant data blocks would not be really necessary, since they can be computed from the id of the parent (see description in /workspace/{workspaceName} /model/{modelName}/data/{id} endpoint) but they are provided for convenience.
    properties:
      id: