3D Measure UP API Usage
- STEPS for using measure API and metrics API
- HTTP Specification
- API Documentation
- /measure
- /align
- /metrics
- Response Syntax
- Retrieving metrics from the response
- Reference Guide for identifying metrics
3D Measure UP API Usage
Please follow below steps to get the auto-detected measurement over a mesh body.
Steps :
Refer below screenshot for using the API using POSTMAN
Fig_1: Specify api-key in header of the request (POST/GET)
Fig_2 : Sending POST request to measure API
Fig_3 : Getting a 202 (pending) response for the corresponding requestId
Fig_4 : Getting a 200 (Success) for the corresponding requestId (request is send at certain interval to this API [polling])
HTTP Specification
API | Description |
POST measure | Submit a request to generate metrics. |
GET metrics | Retrieve metrics generated by the measure method. |
POST align | Returns a 4x4 projection matrix to align model with Y axis |
/measure
Method and URI | POST https://api.3dmu.prototechsolutions.com/v3/models/measure |
Authentication | Header x-api-key |
Data Format | JSON |
Request
Headers
x-api-key | Must be x-api-key: <API_KEY> where API_KEY is assigned to clients by PTS. |
Content-Type | application/json |
Body Structure
*: mandatory
*fileurl | Contain either file name or public URL of model |
filesource | ‘url’ |
*type | Type of measurement required |
*method | Specify calculation method |
orientation_matrix | Projection matrix required to align model with Y axis. Default it is a unit matrix |
*filetype | obj OR stl file format |
output | Specify output format, csv OR json. Default in json |
ids | Refer id from List. Usable only if the method is “all”. |
Parameters | Contains calculation type and co-ordinates p1, p2, p3. “type” is optional. Default value of type is concave. |
Usage Example
This API is called to put a request for computing a collection of common human body landmarks automatically by 3D Measure Up. It returns a request Id which can be used by metrics APIs to get all the data.
Body Structure Example:
"type": "all", "fileurl:"https"://<url>”, "orientation_matrics": "1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1", "filesource": "url", "filetype": "obj", "output": "json" } |
Response
HTTP Status Code Summary
200 | Success |
500 | Internal Server Error |
Response
Body Structure (200)
requestId | The UUID identifier for result file |
Use type girth when you want to measure girth length
method : within-finite-plane
This API is called to get a collection of girths generated by intersection of a finite rectangular Plan ABCD.
parameters
type: type of girth i.e. concave / convex
p1: point A in rectangle ABCD
p2: point B in rectangle ABCD
p3: point D in rectangle ABCD
Example:
Request Body: { type : girth, fileurl:"https://<url>”, filesource: "url", method : within-finite-plane, orientation_matrix: "1,0,0,0,0,1,0,0,0,0,0,1,0,0,0,0,1", filetype: obj, output: json, parameters : { type : concave, P1:{1.0, 2.0, -2.0}, p2: {-1.0, 2.0, -2.0}, p3:{1.0, 1.0, -2.0}, } } |
Response
HTTP Status Code Summary
200 | Success |
400 | Bad request |
500 | not able to parse the model |
501 | computational error |
512 | Unknown Error |
513 | Unable to parse file |
Response
Body Structure (200)
statusCode | Response status code |
type | Response type e.g json |
body | Array of coordinates |
This API is called to get the collection of all the girth which are within the selection range of two selection points provided.
parameters
type: type of girth i.e. concave / convex
p1: selection point 1
p2: selection point 2
p3: camera position
Request Body: { type : girth, fileurl:"https://<url>”, filesource: "url", method : within-selection-range, orientation_matrix: "1,0,0,0,0,1,0,0,0,0,0,1,0,0,0,0,1", filetype: obj, output: json, parameters : { type : concave, P1:{1.0, 2.0, -2.0}, p2: {-1.0, 2.0, -2.0}, p3:{1.0, 1.0, -2.0}, } } |
Response
HTTP Status Code Summary
200 | Success |
400 | Bad request |
500 | not able to parse the model |
501 | computational error |
512 | Unknown Error |
513 | Unable to parse file |
Response
Body Structure (200)
statusCode | Response status code |
type | Response type e.g json |
body | Array of 3D coordinates |
There are two methods to calculate distance between two points : free-fall and on surface
This API is called to get the length of trajectory followed by a dew drop starting at a point on the body and flowing down the body by effect of gravity..
parameters
height: Height from ground
p1: point A in rectangle ABCD
p2: point B in rectangle ABCD
p3: point D in rectangle ABCD
Example:
Request Body: { type : distance, method : free-fall, fileurl:"https://<url>”, filesource: "url", orientation_matrix: "1,0,0,0,0,1,0,0,0,0,0,1,0,0,0,0,1", filetype: obj, output: json, parameters : { height: 2.0, P1:{1.0, 2.0, -2.0}, p2: {-1.0, 2.0, -2.0}, p3:{1.0, 1.0, -2.0}, } } |
Response
HTTP Status Code Summary
200 | Success |
400 | Bad request |
500 | not able to parse the model |
501 | computational error |
512 | Unknown Error |
513 | Unable to parse file |
Response
Body Structure (200)
statusCode | Response status code |
body | Array of 3D coordinates |
This API is called to get distance over the human body surface, measured between two points on the body..
parameters
type: type of girth i.e. concave / convex
p1: selection point 1
p2: selection point 2
p3: camera position
Request Body: { type : girth, method : within-selection-range, fileurl:"https://<url>”, filesource: "url", orientation_matrix: "1,0,0,0,0,1,0,0,0,0,0,1,0,0,0,0,1", filetype: obj, output: json, parameters : { type : concave, P1:{1.0, 2.0, -2.0}, p2: {-1.0, 2.0, -2.0}, p3:{1.0, 1.0, -2.0}, } } |
Response
HTTP Status Code Summary
200 | Success |
400 | Bad request |
500 | not able to parse the model |
501 | computational error |
512 | Unknown Error |
513 | Unable to parse file |
Response
Body Structure (200)
statusCode | Response status code |
body | Array of 3D coordinates |
/align |
Method and URI | POST https://api.3dmu.prototechsolutions.com/v3/models/align |
Authentication | Header x-api-key |
Data Format | JSON |
Request
Headers
x-api-key | Must be x-api-key: <API_KEY> where API_KEY is assigned to clients by Prototech. |
Content-Type | application/json |
Body Structure
*: mandatory
filetype | obj | stl |
fileurl | Contain either file name or public URL of model |
filesource | ‘url’ |
Response
HTTP Status Code Summary
200 | Success |
400 | Bad request |
500 | not able to parse the model |
501 | computational error |
512 | Unknown Error |
513 | Unable to parse file |
Response
Body Structure (200)
statusCode | Response status code |
body | Elements of Alignment Matrix |
/metrics
Method and URI | GET |
Authentication | Header x-api-key |
Data Format | JSON |
Request
Headers
x-api-key | Must be x-api-key: <API_KEY> where API_KEY is assigned to clients by PTS. |
Content-Type | application/json |
Query Params
requestId | requestId, which was the output of measure API |
Response
HTTP Status Code Summary
200 | Success |
202 | Pending |
404 | Invalid requestId (Data not found) |
500 | Internal Server Error |
Response
Body Structure (200)
statusCode | Status code of Process |
type | Result data format |
body | Contains resultant measurements |
Curl Usage Sample
NOTE: Before you use this API, please make sure you replace <Your API Key> with the API key provided to you separately. If it is not, please contact info@prototechsolutions.com for your API key.
Contents of requestBody.json file:
{
"type": "all",
"fileurl": "https://3dmu-app.prototechsolutions.com/obj/shijuka.stl",
"orientation_matrix": "1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1",
"filesource": "url",
"filetype": "stl",
"output": "json"
}
curl -X POST -H "Content-Type: application/json" -d @t1.json --header "x-api-key:<API_KEY>" https://api.3dmu.prototechsolutions.com/v3/models/measure --insecur |
(Partial output for reference)
{ "results": { "metrics": { "girths": [ { "id": 101, "name": "head_start", "label": "Head Start", "girth": [], "level": 1.6556999683380127, "confidence": 0 }, { "id": 102, "name": "head_end", "label": "Head End", "girth": [ 0.44 ], "level": 1.440644410850525, "confidence": 10 }, { "id": 103, "name": "neck_end", "label": "Neck End", "girth": [ 0.42 ], "level": 1.386880521478653, "confidence": 10 }, { "id": 104, "name": "shoulder", "label": "Shoulder", "girth": [ 0.92 ], "level": 1.333116632106781, "confidence": 90 }, { "id": 121, "name": "right_wrist_girth", "label": "Right Wrist", "girth": [ 0.13 ], "level": 0.9047205306301773, "confidence": 90 }, … ] } } } |
Retrieving metrics from the response
Example of JSON Path to retrieve the girth from the response object
results.metrics.griths[0].girth results.metrics.griths[0].name |
Example of JSON Path to retrieve the surface length from the response object
measurement => results.metrics.surfaceLengths[0].length name => results.metrics.surfaceLengths[0].name |
Example of JSON Path to retrieve the landmarks from the response object
Note: In the 3D space the center of the model is the origin (0,0,0). The level of the landmark is the distance from the base of the model.
name => results.metrics.landmarkPoints[0].name measurement => results.metrics.landmarkPoints[0].level position - x co-ordinate => results.metrics.landmarkPoints[0].position.x position - y co-ordinate => results.metrics.landmarkPoints[0].position.y position - z co-ordinate => results.metrics.landmarkPoints[0].position.z |
Reference Guide for identifying metrics
A comprehensive metrics guide can be accessed from here.