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 |
|
*type |
Type of measurement required (all, girth, surfacelength) |
|
*method |
Specify calculation method |
|
*filetype |
file format : obj OR stl |
|
orientation_matrix |
Projection matrix required to align model with Y axis. Default it is a unit matrix |
|
filesource |
‘url’ |
|
output |
Specify output format, csv OR json. Default in json |
|
ids |
Refer id from List. Usable only if the "type" 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_matrix": "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.
