Pix4Dengine Cloud - Volume computation

Follow

A volume can be computed via the Pix4Dengine Cloud API without using the Pix4Dcloud user interface, given a project available on Pix4Dcloud and a set of parameters identifying a base surface.

HTTP request

POST on https://api.webgis.pix4d.com/v1/project/{project ID}/volumes/

Path parameters

Parameter Type Description
project_id Number The ID of the project for which the volume needs to be calculated.

Implementation notes

The API requests the computation of a volume. The volume is computed between a base surface and the terrain surface.

The base surface boundary is given as an inputted set of vertex coordinates. The base surface allows to select the base plane for the volume calculation.

 
Warning: This functionality can only be used for a Pix4Dcloud / Pix4Dcloud Advanced project:
  • That already exists with a PROCESSED status
  • Whose DSM is already computed

Payload body fields

 
Important: All the numerical values from the payload must be given in the same coordinate system and unit as the project.

The payload body fields are contained in the following list.

Parameter Type Description
base_surface String

This parameter allows to select the base plane for the volume calculation. Accepted values are:

  • average
  • custom
  • fitPlane
  • triangulated
  • highest
  • lowest

When using custom, the custom_elevation parameter is required (see below).

More information about the different base surfaces at Menu View > Volumes > Sidebar > Objects.

coordinates Array[Array[Number]] Each set of coordinates refers to a vertex of the boundary.
custom_elevation Number

Optional. The elevation MUST be provided when the base_surface is set to custom.

If custom_elevation is provided, only X,Y vertex coordinates are needed, the Z is the custom_elevation.

More information on the recommended base surface at Which Base Surface is recommended for the Volume Calculation?

Response body fields

 
Note: The response parameters will be in the same coordinate system and units as the project.

The response body includes the fields contained in the following list.

Parameter Type Description
cut Number

The volume that is above the volume base. The volume is measured between the volume base and the surface defined by the DSM.

cut_error Number

Error estimation of the cut volume.

fill Number

The volume that is below the volume base. The volume is measured between the volume base and the surface defined by the DSM.

fill_error Number

Error estimation of the fill volume.

 
Note: The boundaries and volumes are not displayed in the user interface.

Response and failure modes

HTTP status code 200 - OK

If the request is successful, the body includes volumes and error estimations. The order of the response body fields doesn’t matter and is not guaranteed.

{ "cut": Number,
"cut_error": Number,
"fill": Number,
"fill_error": Number}

Type

json

HTTP status code 504 - Gateway Timeout

 

{"message": "Network error communicating with endpoint"}

Type

json

Cause
Likely a networking issue either in the API Gateway, or any server that failed to route the request properly to the next point.

Solution
Resend the request.

{"message": "Endpoint request timed out"}

Type

json

Cause
The request took more than 29 seconds to compute. One of the reasons might be that too many vertices to describe the polygon boundary are sent.

Solution
Reduce the number of the polygon vertices.

HTTP status code 404 - Not Found

 

{"title": "404 Not Found"}

Type

json

Cause
The project doesn’t exist.

Solution
Check that the project exists.

HTTP status code 400 - Bad Request

 

{"title": "No COG DSM found for this project"}

Type

json

Cause
The project doesn’t have a DSM. There may also be a delay between registering a DSM and the volume calculation being available, as Pix4Dcloud creates the COG DSM.

Solution
Check that the project has a DSM. Allow some time for the system to register the DSM and create the COG DSM.

{"title": "The polygon doesn't overlap the dataset"}

Type

json

Cause
The vertices of the defined polygon lie outside the DSM.

Solution
Check that the coordinates of the polygon vertices lie inside the DSM.

{"title": "Invalid Polygon"}

Type

json

Cause
The interpolation of elevations inside the polygon boundary failed.

{"title": "Too much data requested"}

Type

json

Cause
The DSM doesn’t have a high enough overview level, as a result it is not possible to extract the maximum amount of data that is defined by the API.

Solution
A possible solution could be to reduce the size of the area for which the volume needs to be computed. If it is not a suitable solution or the issue persists contact the Support.

Examples

  1. Visit Jupiter Notebook for a volume computation demo.
  2. Here is an example of how to calculate a volume with a triangulated base surface.
    POST on https://api.webgis.pix4d.com/v1/project/123456/volumes/
    {
    "base_surface": "triangulated",
    "coordinates": [
    [328726.692, 4688271.030, 159.725],
    [328728.351, 4688298.208, 150.376],
    [328750.527, 4688289.860, 150.250],
    [328744.430, 4688271.645, 150.056]
    ]
    }
  3. Here is an example of how to calculate a volume with a custom base surface.
    POST on https://api.webgis.pix4d.com/v1/project/123456/volumes/
    {
    "base_surface": "custom",
    "coordinates": [
    [419430.327, 3469059.806],
    [419429.338, 3469056.812],
    [419431.319, 3469060.816],
    [419433.329, 3469058.803]
    ],
    "custom_elevation": 40.52

    }

     

Was this article helpful?
1 out of 1 found this helpful

Article feedback (for troubleshooting, post here)

0 comments

Article is closed for comments.