Usage - 3D Measure Up

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

Please follow below steps to get the auto-detected measurement over a mesh body.

Steps :

Send your request body data to 'https://api.3dmu.prototechsolutions.com/v3/models/measure' as a POST request
- You will either get requestId in response or error in case of invalid parameters
- Let say you receive 163e9760-69c5-11ea-ab70-21d66db68acf as a requestId
Using the requestId as fetched from the first API send a GET request to 'https://api.3dmu.prototechsolutions.com/v3/models/metrics?requestId=163e9760-69c5-11ea-ab70-21d66db68acf'
- This API will either return 200 success, 202 pending, or 500 error based on the processed result
- You need to continuously poll for the response after certain intervals until the status is pending (202) or you get success or failure

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

API Documentation

/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

type: all

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:

If model is on url resource

{

"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

type: girth

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

method : within-selection-range

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

type: distance

There are two methods to calculate distance between two points : free-fall and on surface

method: free-fall

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

method: surface

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 https://api.3dmu.prototechsolutions.com/v3/models/metrics
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.

Create/ Download json.txt file.

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"

}

Open terminal in folder containing json.txt file.
Run the following command in the terminal.

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

Response Syntax

(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.

API Documentation

type: all

type: girth

method : within-selection-range

type: distance

method: free-fall

method: surface

/align

Response Syntax

Subscribe to our mailing list

ABOUT US

QUICK LINKS

CONTACT US