Documentation

CLI

Suggest Edits

The Didimo CLI is a developer tool that assists in using the Didimo API from your terminal. It works on macOS, Windows and Linux and only requires Python 3 to be installed.

Quickstart

The CLI is written in Python 3 and is distributed as a package on PyPI, so it can be installed with pip. You may also find the code on our public Github repo.

pip3 install didimo-cli --upgrade # if you don't have a previous version already installed, you can omit the --upgrade

Create a new configuration and input your API Key. If you do not have an API Key, please refer to Generate an API Key.

didimo init <configuration name>

After setting up the CLI, you can check your account information.

didimo account

Now that the CLI is configured, let's generate a didimo based on a photo.

didimo new photo <path to the photo>

The CLI will wait for the didimo generation process to be completed and downloads the result as a zip file.
You can list your didimos with:

didimo list

Didimo generation

Generating a didimo may include several options, as described on Generate a New Didimo.

The tool allows the selection of the avatar structure (--avatar-structure), for which it currently accepts full-body or head-only (default) options. For full-body requests, some extra parameters are available:

  • the definition of the body pose (--body-pose);
  • the definition of the garments (--garment);
  • the definition of a gender (--gender).

Didimo CLI currently accepts the following features (-f):

  • oculus_lipsync
  • simple_poses
  • arkit
  • aws_polly

The CLI accepts the following output formats (-p):

  • glTF
  • FBX

In addition to those, it also accepts:

  • the definition of a profile (--profile), which will drive the output texture files dimensions and formats;
  • the definition of a default hair or baseball cap, from our collection of hairstyles (--hair).
didimo new photo <path to the photo> --avatar-structure full-body --garment sporty --gender female -f simple_poses -f aws_polly --profile standard -p fbx -p gltf

It's also possible to specify a PNG depth file (only available for Apple generated depth files) using

didimo new rgbd <path to the photo> -d <path to the depth file>.png --avatar-structure full-body --garment sporty --gender female -f simple_poses -f aws_polly --profile standard -p fbx -p gltf

Fit a custom hair on your didimo

In order to fit a hair on your didimo, you'll need the didimo DMX file, which you may find inside the didimo package, with the name deformation_matrix.dmx.
Using the CLI you may use the didimo package directly

didimo execute vertexdeform Ax817882ylatxKfa1h_gltf.zip hair_0XX.obj

or you can extract and use the DMX explicitly

# Assuming you have a package with the name Ax817882ylatxKfa1h_gltf.zip
unzip -p Ax817882ylatxKfa1h_gltf.zip deformation_matrix.dmx > Ax817882ylatxKfa1h_deformation_matrix.dmx

Now that we have the DMX file, we can execute the deformation on hair_0XX.obj (more information on hairstyles can be found here).

didimo execute vertexdeform Ax817882ylatxKfa1h_deformation_matrix.dmx hair_0XX.obj

Generate a set of default hairs for a didimo

Like in the previous example, in order to generate a set of default hairs for your didimo, you'll need the didimo DMX file, which you may find inside the didimo package, with the name deformation_matrix.dmx.
Again, you may choose to use the didimo package directly

didimo execute hairsdeform Ax817882ylatxKfa1h_gltf.zip

or the more explicit (and laborious) approach

# Assuming you have a package with the name Ax817882ylatxKfa1h_gltf.zip
unzip -p Ax817882ylatxKfa1h_gltf.zip deformation_matrix.dmx > Ax817882ylatxKfa1h_deformation_matrix.dmx

Now that we have the DMX file, we can request the hair bundle (more information on hairstyles can be found here).

didimo execute hairsdeform Ax817882ylatxKfa1h_deformation_matrix.dmx

Batch processing

The Didimo CLI supports batch processing of photo inputs automatically. Simply provide a path to a directory containing the input files and all files will be processed. Alternatively, you can point to a ZIP file containing the input files.

didimo new /path_to_batch_input_files photo

Currently, only photo input is supported by batch processing.

This feature will result in standard requests to generate didimos so you should consider bulk processing if you intend to generate a large number of didimos in one pass (please read the following section for more information on bulk processing).

Bulk processing

The Didimo CLI supports bulk processing of photo inputs automatically. Simply provide a path to a ZIP file containing the input files and all files will be processed as a bulk request. 

didimo bulk new didimos /path_to_batch_input_files photo

An important distinction between batch and bulk processing is that the batch process is controlled by the client application, which makes standard requests to generate didimos, while the bulk request handles the process as a whole. Resulting in a quicker registration of the job but may result on a lower turn-around-time (TAT) as the package is processed in the background, with lower priority. This feature is intended to be used in the generation of a large number of didimos without
blocking the user interface.

You can perform queries to assess the status of the processing of bulk requests, using the get command that outputs relevant progress information of each individual item.

didimo bulk get didimos bulk_uuid

You can also query all the existing bulk requests on your account with the list command.

didimo bulk list didimos

Currently, only photo input is supported by bulk processing.

Didimo generation templates

The commands related to didimo generation support the use of templates to facilitate the didimo generation process and prevent unintended errors while generating your didimos with reusable sets of options. We have predefined templates which are set at system level and you can generate your own at user level.

Use the following command to list available didimo generation templates.

didimo generation-templates list

You can add a new DGT, according to your current DGP signature, using the create command. Use the following command to get instructions on how to use it and see all the available features and options.

didimo generation-templates create -h

You will be able to use these templates as parameter on the commands:

  • "new" (to generate a new didimo): e.g. didimo new /path_to_batch_input_files --template templateUUID
  • "bulk" (to generate didimos in bulk): e.g. didimo bulk new didimos /path_to_batch_input_files --template templateUUID

You will still be able to override any template values if needed by providing the parameters as you normally would, and the remaining attributes will be fetched from the provided template.

NOTE: These templates need to be created for each DGP (didimo generation pipeline) signature if there are breaking changes to the DGP signature, but are shared across compatible DGP versions.

Explore

For further information on the available options and parameters, please use --help.

didimo --help

Updated about 2 years ago