Retrieving Material Changes
The REST interface allows to retrieve voxel sagas. The interface returns sagas in singularities and in space.
Method
GET
URL
<server>/entity.ashx
Parameters
To retrieve the contents of a singularity, use the following parameters:
|
project |
Must be set to the ID for the project that contains the material tracking layer |
|
org |
Must be set to “2343243456678890” |
|
layer |
Contains the ID for the Material Tracking Layer that will be queried |
|
singularity |
Contains the ID if the singularity that will be queried |
|
result_begin |
Contains the initial timestamp to be included in the query results |
|
result_end |
Contains the final timestamp to be included in the query results |
To retrieve the material tracking data for a region of space, use the following parameters:
|
project |
Must be set to the ID for the project that contains the material tracking layer |
|
org |
Must be set to “2343243456678890” |
|
layer |
Contains the ID for the Material Tracking Layer that will be queried |
|
aabb |
Contains an axis-aligned bounding box, in project coordinates, for the region of space that will be queried. The bounding box is comprised of six numbers, separated by commas. The first three numbers are the X,Y,Z coordinates of the lower corner of the bounding box. The next three numbers are the X,Y,Z coordinates of the upper corner. |
|
result_begin |
Contains the initial timestamp to be included in the query results |
|
result_end |
Contains the final timestamp to be included in the query results |
|
search_begin |
Contains the initial timestamp for the time search range |
|
search_end |
Contains the final timestamp for the time search range |
Returns
This call returns a JSON file. The file defines a dictionary where the entity’s properties appear as key-value pairs.
The REST call will return a JSON file that contains an array of operations. Each entry in this array is a JSON object with the following properties:
|
operation |
Will be one of the seven available operation types:
|
|
id |
Unique identifier for material volume |
|
from_t |
Origin time for the operation |
|
from_x |
Origin coordinate X for the operation |
|
from_y |
Origin coordinate Y for the operation |
|
from_z |
Origin coordinate Z for the operation |
|
from_id |
Origin singularity ID for the operation |
|
to_t |
Final time for the operation |
|
to_x |
Final coordinate X for the operation |
|
to_y |
Final coordinate Y for the operation |
|
to_z |
Final coordinate Z for the operation |
|
to_id |
Final singularity ID for the operation |
In addition to these fields, the JSON object will include the attribute values for the voxel.
Making sense of "search_begin/search_end" and "result_begin/result_end"
When retrieving voxel sagas from a singularities or regions of space, the API requires two time ranges as input. The result_begin and result_end parameters filter out events from the sagas that are outside this time window. This allows to reduce the amount of information returned by the API call.
The search_begin and search_end parameters are used to determine the region of time that will be searched. For instance, imagine there is a truck singularity in the system and we would like to know the last month of material history for the material the truck carried yesterday. In this case, the search region will be limited to yesterday but the results region would include the entire previous month.
Example
http://localhost/entity.ashx?org=2343243456678890&project=A14B73E10AD04796A64490AA1056B16A&layer=BC2C849D0A4A44CE9D40714BED2E9143&singularity=86E634C260E74E888C542CC2C87BBE02&result_begin=200&result_end=300