Measuring humans is hard. We’re not talking about measuring strength or endurance here, but about accurately sizing up folks in all our glorious variety of shapes and sizes. And for every body type, there’s a different opinion on how to measure it accurately. The complexity escalates when considering the fluid dynamics of human movement. Our bodies are not static, but constantly morphing entities — we twist, contort, and elongate various parts, adding layers of ambiguity to the measurement challenge.

Despite these difficulties, it’s crucial to have a standardized reference point for measurements, particularly in the realm of technological design. This is where the ISO 7250–1:2017 standard becomes an invaluable resource. By adhering to this internationally accepted guide for basic human body measurements, we can maintain consistency, improve accuracy, and advance our understanding of the human form in its myriad manifestations.

Starting from one or more measurements, the Meshcapade avatar creator utilizes these inputs to extrapolate the remaining body dimensions. This customization process ensures that your avatar closely mirrors your real-life proportions, resulting in a highly personalized and lifelike representation. Creating avatars from measurements on Meshcapade is also possible through the API.

Creating an avatar from measurements

With only one single measurement you can already create an avatar from measurements. It’s as straight forward as:

curl --location 'https://api.meshcapade.com/api/v1/avatars/create/from-measurements' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $TOKEN" \
--data '{
    "name": "Created from measurements API",
    "gender":"female",
    "measurements":{
                        "Height": 180.1
                    }
}'

Note: See the Avatar from images article about creating an account and authenticating your requests and how to set the $TOKEN

Breaking down the request we have a couple of components to look at.

'curl [...]/avatars/create/from-measurement`

Is one of several API endpoints to create avatars from many different sources. In this case from measurements, as the name suggests. Check out the docs for more options!

'{
    "name": "Created from measurements API",
    "gender":"female",
    "measurements":{
                        "Height": 180.1
                    }
}'

The body of the request contains the name of the avatar we want to create, the gender which is either female or male and finally the measurements.

For a comprehensive list of all available measurement points to utilize, please refer to our Notion document. Please note that the measurements provided are in centimeters. If any measurements are currently in imperial units, they will need to be converted to metric before running the request.

The somewhat shortened response to the request looks somewhat close to the following:

{
    "data": {
        "type": "asset",
        "id": "bbab51d3-b6bc-4484-94f0-d01a506eedb3",
        "attributes": {
            "metadata": {
                "bodyShape": {
                    "gender": "FEMALE",
                    "modelVersion": "SMPLX",
                    "shapeParameters": null
                }
            },
            "name": "Created from measurements API",
            "origin": "FROM_MEASUREMENTS",
            "state": "AWAITING_PROCESSING",
        }, 
        "links": {
            "self": "https://api.meshcapade.com/api/v1/avatars/bbab51d3-b6bc-4484-94f0-d01a506eedb3"
        }
    }
}

Seeing the “state”: “AWAITING_PROCESSING” tells us that we succesfully requested the creation of our avatar. Usually it takes only a couple of seconds until the avatar is ready.

Requesting the avatar

We can request the avatar simply by following the data["links"]["self"] link, which points to the newly created avatar asset:

curl --location "https://api.meshcapade.com/api/v1/avatars/$AVATAR_ID" 
--header "Authorization: Bearer $TOKEN"

If our avatar has already been processed, the response will look like this:

{
    "data": {
        "type": "asset",
        "id": "bbab51d3-b6bc-4484-94f0-d01a506eedb3",
        "attributes": {
            "created_at": 1685970096,
            "metadata": {
                "bodyShape": {
                    "gender": "FEMALE",
                    "modelVersion": "SMPLX",
                    "shapeParameters": [
                        2.1875213361916543,
                        -0.26719294316046005,
                        "lots of numbers here [...]" 
                        -0.07937182182457603
                    ]
                }
            },
            "name": "Created from measurements API",
            "origin": "FROM_MEASUREMENTS",
            "state": "READY",
            "type": "AVATAR"
        },
        "links": {
            "self": "https://api.meshcapade.com/api/v1/avatars/bbab51d3-b6bc-4484-94f0-d01a506eedb3"
        }
    }
}

Don’t panic if the avatar is not READY yet, give it a couple more seconds and try again.

Download your avatar

Downloading your newly created avatar is as easy as creating it. Follow the “Download your avatar” section of our previous article to easily create an obj or rigged fbx download.

You can also preview your avatar in the online Avatar vault and download them manually!

Measurements Meet Imagination: Creating accurate 3D Avatars with Meshcapade’s API was originally published in Meshcapade on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Meshcapade Me API is a RESTful API that allows you to create and edit avatars from images, measurements, scans, and more. All API replies adhere to the JSON:API schema guidelines. You can find detailed documentation for each endpoint here.

Step by step we will create an Avatar from a single image

Meshcapade Me Account

First we create an account on me.meshcapade.com. To make the authentication token retrieval a bit easier, sign up with an email adress instead of the SSO options.

New Avatar

Avatars are the central piece in the API. Almost every operation is focused on interacting with an avatar in one way or another. To create an avatar from an image, we first have to get an access token with our new account.

RESP=$(curl --location 'https://auth.meshcapade.com/realms/meshcapade-me/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=meshcapade-me' \
--data-urlencode 'username=<email>' \
--data-urlencode 'password=<password>')

The reply looks like this:

{
    "access_token": "<token>",
    "expires_in": 36000,
    "refresh_expires_in": 36000,
    "refresh_token": "<refresh_token>",
    "token_type": "Bearer",
    "not-before-policy": 123123123,
    "session_state": "...",
    "scope": "email profile"
}

With jq we can read out the acces token like this:

TOKEN=$(echo $RESP | jq ".access_token" -r)

Next, we can initiate the avatar from images creation. This request will prepare an empty avatar which will wait for us to upload an image before processing it.

Tip: You can upload up to 4 images from different angles to improve accuracy of the body. Talk to us to get this feature enabled on your account!

curl --location --request POST 'api.meshcapade.com/api/v1/avatars/create/from-images' \
--header "Authorization: Bearer $TOKEN"

The reply contains a single asset of the type AVATAR in JSON:API spec. An avatar is described by its id and a bunch of attributes. This empty avatar is not too interesting yet. Some API responses may contain a collection of assets in the data field.

{
    "data": {
        "type": "asset",
        "id": "e40ba1bd-2675-48ba-bda4-8b714cd3e4a7",
        "attributes": {
            "metadata": {
                "bodyShape": {
                    "shapeParameters": null,
                    "modelVersion": "SMPLX",
                }
            },
            "origin": "",
            "owner": "<your_user_id>",
            "source": "GENERATED",
            "source_build_id": "<some_id>",
            "state": "PENDING_AFI",
            "type": "AVATAR"
        },
        "links": {
            "image_upload": "https://api.meshcapade.com/api/v1/avatars/e40ba1bd-2675-48ba-bda4-8b714cd3e4a7/images",
            "self": "https://api.meshcapade.com/api/v1/avatars/e40ba1bd-2675-48ba-bda4-8b714cd3e4a7"
        }
    }
}

In the data.links.image_upload field, we already get an url pointing us to an endpoint outlining how to upload our image. Further described here.

Calling this endpoint informs the API that we have an intent to upload a file, and returns a presigned PUT url where we can upload the file to.

curl --location --request POST 'api.meshcapade.com/api/v1/avatars/e40ba1bd-2675-48ba-bda4-8b714cd3e4a7/images' \
--header "Authorization: Bearer $TOKEN"

The reply contains another asset, this time of type IMAGE and looks like this:

{
    "data": {
        "type": "asset",
        "id": "5ac5991f-dd79-46f0-8de6-235475361363",
        "attributes": {
            <attributes>
            "url": {
                "Link": "<presigned_PUT_url>",
                "Method": "PUT",
                "Internal": false
            }
        },
        "links": {
            "self": "https://api.meshcapade.com/api/v1/images/5ac5991f-dd79-46f0-8de6-235475361363",
            "upload": "<presigned_PUT_url>"
        }
    }
}

We can upload the image using the data.links.upload url. This will automatically link the image to the empty avatar.

The uploaded image should be a full body shot with as much contrast as possible between the body itself and the background.

UPLOADURL=$(echo $RESP | jq ".data.links.upload" -r)

curl --upload-file "ballerina_ashley.png" \
      --header "Content-Type: image/png" \
      "${UPLOADURL}"

Start the creation process

After having uploaded the image, we can start the fitting process. We need a couple more parameters. While most are optional, the more we use, the higher the accuracy of the resulting avatar.

Request body can include these parameters:

{
    "avatarname": "Ashley", <- Optional
    "height":180, <- Optional
    "weight":65, <- Optional
    "gender":"female" <-  female/male/neutral,
    "imageMode": "AFI2" <- AFI2/AFI
}

About the imageMode

Instant mode (AFI2)

Use photos of people in dynamic poses and outfits. Results will focus more on poses than body shape.

Classic mode (AFI)

Ensure your input photo features tight-fitting clothing and a relaxed pose to achieve the best results.

What is the difference?

Running the request:

curl --location "api.meshcapade.com/api/v1/avatars/e40ba1bd-2675-48ba-bda4-8b714cd3e4a7/fit-to-images" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "avatarname": "Ashley",
    "height":180,
    "weight":65,
    "gender":"female"
}'

The reply will contain the same avatar asset as earlier, with the only difference being the state now in PROCESSING

{
    "data": {
        "type": "asset",
        "id": "e40ba1bd-2675-48ba-bda4-8b714cd3e4a7",
        "attributes": {
            "metadata": {
                "bodyShape": {
                    "shapeParameters": null,
                    "modelVersion": "SMPLX",
                }
            },
            "origin": "",
            "owner": "<your_user_id>",
            "source": "GENERATED",
            "source_build_id": "<some_id>",
            "state": "PROCESSING",
            "type": "AVATAR"
        },
        "links": {
            "image_upload": "https://api.meshcapade.com/api/v1/avatars/e40ba1bd-2675-48ba-bda4-8b714cd3e4a7/images",
            "self": "https://api.meshcapade.com/api/v1/avatars/e40ba1bd-2675-48ba-bda4-8b714cd3e4a7"
        }
    }
}

Now, we keep on requesting the same endpoint of data.links.self from the reply until the state is READY, which should roughly take a minute.
This should point at GET /assets/{assetID}. Then, you’ll also find big blob of floats in data.attributes.metadata.bodyShape.shapeParameters . Those are the shape parameters of the underlying SMPL model.

You can always take a look at your avatars in your vault

Or request all your owned avatars

Download your avatar!

Finally we can download your avatar. This requires a simple export job. We can choose between a couple of poses, namely T , A and the same pose as in the image SCAN. At this time only obj export is supported, but a fully rigged fbx download will soon be added as well!

Edit: fbx is now available too. Just change format:"obj" to format:"fbx" . Ceck out the documentation if you want to have an animation applied to your rigged avatar

Export request:

curl --location 'api.meshcapade.com/api/v1/avatars/e40ba1bd-2675-48ba-bda4-8b714cd3e4a7/export' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "pose":"scan",
    "format":"obj"
}'

Similar to how we started the fitting process from earlier, we can keep on requesting the same endpoint with the same data body, until the returned mesh asset has aREADY state. Then, the url attribute of the asset will contain a direct download link to the resulting obj 🎉

Congratulations, you have created your own avatar from a single image!

Follow Meshcapade on twitter, contact us here or write an email at support@meshcapade.com

Streamline Avatar Creation with Meshcapade Me API: From One Image to an Accurate Avatar in Seconds was originally published in Meshcapade on Medium, where people are continuing the conversation by highlighting and responding to this story.