Creating a Model

Ensuring Folders Exist

To create a model, a Folder needs to exist to contain the models. It’s recommended to create Folders before attempting an upload. Then, when defining a filePath for said model for use in POST /v2/models endpoint, the Folder.name may be used for the folderName parameter.

Optionally, when calling POST /v2/models, the createMissingFolders boolean flag can be set to true. Any Folder names defined that do not exist will be created automatically. This also includes nested folders, denoted by slashes (/) in the path, e.g., implicitly/created/folders/for/file.prt will create any folders not already existing (implictly, created, etc.)

Single Models

To upload a model, first a model record needs to be created. Use POST /v2/models to create one or many models, up to 100 per request. Assemblies larger than 100 files will need split up across multiple upload requests.

Assembly Models

To upload an assembly, model records need to be created for both the assembly itself and for its individual parts. The POST /v2/models endpoint can be used to create multiple models at the same time. It’s important to make sure that all parts are in the assembly’s folder or within a subfolder of the assembly’s folder. This placement is important for the ingestion process to discover and link the parts to the assembly in order to have the complete assembly geometry.

Subparts and subassemblies can be loaded in any order. The system will automatically detect and link any missing parts in the assembly when new files are uploaded that meet the assembly’s requirements, so long as the part and assembly are in the same Folder. However, performance will be more optimal if all parts to an assembly are uploaded before attempting to upload the assembly to avoid unnecessary automatic reprocessing.

Missing Parts

If an assembly is missing parts, the system will still attempt to process it using what geometry is available. This will likely stop processing in a state like finished-incomplete or failed-incomplete. Any missing parts can be uploaded to satisfy missing dependencies, and the assembly will be reprocessed with the part if the part is uploaded to the assembly’s folder or its subfolders.

Metadata

Optionally, metadata can be created for a model when calling POST /v2/models by defining a list of metadataKeyId and value pairs for each model.

Complete the Model Upload

Once a model record has been successfully created, the file itself needs to be uploaded for processing. To upload a the file itself, follow these steps:

  1. Use the uploadInfo provided in the response when creating the model. The uploadInfo contains essential details for the upload process including the uploadUrl to PUT the model file to as well as required headers for making the request.

  2. Execute a PUT request to the specified uploadUrl with the model file and required headers. You can use tools like curl or any HTTP client of your choice. Note: The upload url is valid for 15 minutes. If expired, you can delete and then recreate the model for a new one.

Example

Here’s a full example of how to create and upload a model using curl. It assumes you already have authenticated and stored a bearer token in $TOKEN.

First, create the model record:

curl -X POST https://api.physna.com/v2/models?createMissingFolders=true \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $TOKEN" \
 -d '{"models": [{"filePath": "folderName/fileName.stl","name": "Display Name","metadata": [{"metadataKeyId": 1,"value": "example value"}]}]}'

# returns JSON like
#  { "models": [
#    {
#      "model": { ... info about your model, including id, metadata, ect ...}
#      "uploadUrl":  "<upload-url>",
#      "headers": {
#        "<header1-name>": "<header1-value>",
#        "<header2-name>": "<header2-value>",
#        ... }'
#      }
# ]}
# Note that the models.headers object is dynamic, all headers are _required_ in the next request

Finally, use the <upload-url> and all headers from models.headers above to send the actual file itself:

curl -X PUT "<upload-url>" \
 --upload-file local/path/to/fileName.stl \
 -H '<header1-name>: <header1-value>' \
 -H '<header2-name>: <header2-value>' \

Tracking Ingestion Progress

After uploading, processing can be monitored through the GET /v2/models/{id} API endpoint and viewing the model.state attribute. Here are a few key states to look out for:

  1. incomplete-upload: The file for the model has not been uploaded to our system yet. If the upload-url provided during the creation of the model has expired, delete the model and re-create the record.
  2. unsupported: model is either too old/new of a version, or is some other unsupported type.
  3. failed-incomplete: The model is an assembly, it is missing parts, and it failed to process. If there is no geometry in the assembly provided, then the missing parts with geometry will need to be provided. If there is geometry in the parts provided and it continues to fail after a reprocess, please reach out to your contact at Physna for further assistance.
  4. failed: The model failed to process. If if continues to fail after a reprocess, please reach out to your contact at Physna for further assistance.
  5. finished-incomplete: The model is an assembly that is missing parts. However there is enough geometry given that it is ready for search and matching.
  6. finished: The model has fully processed and is ready for search and matching.