3D Measure UP API Usage

  1. STEPS for using measure API and metrics API
  2. HTTP Specification
  3. API Documentation
    • /measure
    • /align
    • /metrics
  4. Response Syntax
  5. Retrieving metrics from the response
  6. Reference Guide for identifying metrics

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

Steps :

  1. 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
  2. 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 4×4 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

*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

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:

  1. If model is on url resource
  1. {

                       “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

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.

  1. 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”

}

  1. Open terminal in folder containing json.txt file.
  2. 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.

Login / Sign Up
Login / Sign Up
3D Measure Up Logo

About Us

ProtoTech’s 3D Measure Up is based on a proprietary algorithm which is a combination of 3D geometry, computational and machine learning algorithms to provide you with a highly accurate and reliable identification and measurement.

Quick Links

Contact Us

Facebook Instagram Linkedin
Powered by AWS
ProtoTech Solutions © 2024. All Rights Reserved | Terms Of Service | Privacy Policy
Scroll to Top