Added support for multiple root datablocks in a model

spslapi.yml

-sswagger: "2.0"
+swagger: "2.0"
 
 
 info:
 info:
   description: >
   description: >
     Simple REST API for access to massive clouds repositories in the project SPSLidar.
     Simple REST API for access to massive clouds repositories in the project SPSLidar.
     
     
-    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.
+    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"
+  version: "0.3"
   title: SPSLidar API
   title: SPSLidar API
   contact:
   contact:
     email: ajrueda@ujaen.es
     email: ajrueda@ujaen.es
@@ -94,20 +99,18 @@ paths:
         required: true
         required: true
         type: string
         type: string
       - in: query
       - in: query
-        name: west
-        description: West side of the box to filter models
-        type: number
-      - in: query
-        name: south
-        description: South side of the box to filter models
-        type: number
-      - in: query
-        name: east
-        description: East side of the box to filter models
-        type: number
+        name: southWest
+        description: >
+          South-west corner of the box in UTM coordinates
+          with the format ZZREE..EN..N where: ZZ is the zone
+          code, R is the region letter, EE..E is the easting 
+          and N..N is the northing. Coordinates can be given in km or m.
+        type: string
       - in: query
       - in: query
-        name: north
-        description: North side of the box to filter models
+        name: northEast
+        description: >
+          North-east corner of the box in UTM coordinates using
+          the same convention as the southWest corner.
         type: number
         type: number
         
         
       responses:
       responses:
@@ -177,9 +180,14 @@ paths:
       - "data"
       - "data"
       summary: Returns metadata asociated to a data block
       summary: Returns metadata asociated to a data block
       description: >
       description: >
-          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.
+          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.
           
           
-          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. 
+          The data associated to the data block is provided different endpoint, and several formats 
+          could be available. By now only LAZ/LAS format (for point data) is supported by 
+          .../data/{id}/laz or .../data/{id}/las endpoints. 
       produces:
       produces:
       - application/json
       - application/json
       parameters:
       parameters:
@@ -246,9 +254,12 @@ paths:
       - "data"
       - "data"
       summary: Defines the point data of the model in LAZ format 
       summary: Defines the point data of the model in LAZ format 
       description: >
       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 (see data block metadata) 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. 
+        The LAZ data blocks should be normalized, using the normalized coordinates with respect to 
+        the bounding box of the model. 
       consumes:
       consumes:
       - application/octet-stream
       - application/octet-stream
       parameters:
       parameters:
@@ -283,24 +294,35 @@ definitions:
 
 
   Workspace:
   Workspace:
       type: object
       type: object
-      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. 
+      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:
       properties:
         name:
         name:
           type: string
           type: string
           description: Name of the workspace (avoid spaces if possible)
           description: Name of the workspace (avoid spaces if possible)
-        type:
+        description:
           type: string
           type: string
           description: Description of the workspace and its purpose
           description: Description of the workspace and its purpose
+        cellSize:
+          type: integer
+          description: > 
+            Length in metres of the sides of the squared cells of the grid 
+            used for the spatial indexing of the models. If not given, a default value is used  
     
     
       required:
       required:
       - name
       - name
       example:
       example:
         name: CHJaen
         name: CHJaen
         description: Scanned models of cultural heritage sites in the province of Jaén
         description: Scanned models of cultural heritage sites in the province of Jaén
+        cellSize: 10000
 
 
   Model:
   Model:
     type: object
     type: object
-    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).
+    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:
     properties:
       name:
       name:
         type: string
         type: string
@@ -316,7 +338,21 @@ definitions:
         $ref: '#/definitions/GeorefBox'
         $ref: '#/definitions/GeorefBox'
       dataBlockSize:
       dataBlockSize:
         type: integer
         type: integer
-        description: Maximum size of a datablock (i.e., maximum number of points per datablock).
+        description: > 
+          Maximum size of a datablock (i.e., maximum number of points per datablock). 
+          If not given a default value is used.
+      dataBlockFormat:
+        type: string
+        description: Format of the data blocks. Currently, only LAS and LAZ are supported.
+      rootDataBlocks:
+        type: array
+        description: >
+          Root data blocks. Normally only one, but there are cases where the
+          model belongs to two different cells; then the model may be splitted in 
+          different root data blocks (i.e., octrees). 
+        items: 
+          type: integer
+
     required:
     required:
     - name
     - name
     - bbox
     - bbox
@@ -327,31 +363,48 @@ definitions:
         Captured with Leica RTC360 laser scanner
         Captured with Leica RTC360 laser scanner
       date: "2019-05-03T12:10:00Z"
       date: "2019-05-03T12:10:00Z"
       bbox:
       bbox:
-        east: 37.768673
-        north: 3.804588
-        west: 37.767032
-        south: -3.798777
+        southWestBottom:
+          easting: 429522
+          northing: 4180270
+          height: 790
+          zone: 30S
+        northEastTop:
+          easting: 429638
+          northing: 4180363
+          height: 820
+          zone: 30S
       dataBlockSize: 10000
       dataBlockSize: 10000
+      dataBlockFormat: LAZ
+      rootDataBlocks:
+      - 0
 
 
   DataBlock:
   DataBlock:
     type: object
     type: object
     description: > 
     description: > 
-      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. 
+      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 n
+      umber 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. 
+      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.
+      This object does not provide the actual data, but its associated metadata (bounding box, 
+      size of the LOD, ids of descendant datablocks). The ids of the descendant data blocks would 
+      not be really necessary, since they can be computed from the id of the parent (see descriptionco
+      nvenience. The minimal bounding box of the data is also given for convenience.
       
       
     properties:
     properties:
       id:
       id:
         type: integer
         type: integer
       bbox:
       bbox:
-        $ref: '#/definitions/GeomBox'
+        $ref: '#/definitions/GeorefBox'
       size:
       size:
         type: integer
         type: integer
         description: Size of data (i.e, number of points)
         description: Size of data (i.e, number of points)
       subDataBlocks:
       subDataBlocks:
         type: array
         type: array
+        description: Data blocks of the next level of detail.
         items: 
         items: 
           type: integer
           type: integer
     required:
     required:
@@ -362,14 +415,18 @@ definitions:
     example:
     example:
       id: 0
       id: 0
       bbox:
       bbox:
-        minX: 0
-        minY: 0
-        minZ: 0
-        maxX: 1
-        maxY: 1
-        maxZ: 1
+        southWestBottom:
+          easting: 429522
+          northing: 4180270
+          height: 790
+          zone: 30S
+        northEastTop:
+          easting: 429638
+          northing: 4180363
+          height: 820
+          zone: 30S
       size: 10000
       size: 10000
-      nextLevel:
+      subDataBlocks:
       - 1
       - 1
       - 2
       - 2
       - 3
       - 3
@@ -380,52 +437,33 @@ definitions:
       
       
   GeorefBox:
   GeorefBox:
     type: object
     type: object
-    description: Box defined by latitude and longitude
+    description: Box defined two UTM coordinates and their heights.
     properties:
     properties:
-      west:
-        type: number
-        description: West coordinate
-      north:
-        type: number
-        description: South coordinate
-      east:
-        type: number
-        description: East coordinate
-      south:
-        type: number
-        description: North coordinate
+      sourthWestBottom:
+        $ref: '#/definitions/UTMCoord'
+      northEastTop:
+        $ref: '#/definitions/UTMCoord'
     required:
     required:
-    - west
-    - north
-    - east
-    - south
+    - southWestBottom
+    - northEastTop
 
 
-  GeomBox:
+  UTMCoord:
     type: object
     type: object
-    description: Box defined in 3D space using normalized coordinates
+    description: UTM coordinate
     properties:
     properties:
-      minX:
-        type: number
-        description: Minimal X coordinate
-      minY:
-        type: number
-        description: Minimal Y coordinate
-      minZ:
-        type: number
-        description: Minimal Z coordinate
-      maxX:
-        type: number
-        description: Maximum X coordinate
-      maxY:
-        type: number
-        description: Maximum Y coordinate
-      maxZ:
-        type: number
-        description: Minimal Z coordinate
+      easting:
+        type: integer
+        description: Easting coordinate
+      northing:
+        type: integer
+        description: Northing coordinate
+      height:
+        type: integer
+        description: Height (only when refering to 3D point)
+      zone:
+        type: string
+        description: UTM Zone (e.g., 30S)
     required:
     required:
-      - minX
-      - minY
-      - minZ
-      - maxX
+      - easting
+      - northing
+      - zone
\ No newline at end of file
-      - maxY
-      - maxZ