Create a 3D Mesh from Photos
This tutorial guides you through the steps of generating a 3D mesh from a set of overlapping photos and downloading the processed output.
Before You Begin
Ensure that you have registered an app and successfully acquired an OAuth access token with data:read
and data:write
OAuth scopes.
Step 1: Obtaining an Access Token
All calls to Autodesk Reality Capture API must be authenticated and valid access token is required for each API call. Please refer to this step-by-step guide on how an access token can be obtained.
Step 2: Create a Photoscene
A “photoscene” is a container for a photo-to-3D project. Before you upload images to be converted, you need to create a photoscene with the necessary metadata (only scenename is a mandatory field):
- scenename (mandatory): Photoscene/project name. There are restrictions on the characters used in the Photoscene name. See the API documentation for details.
- format (optional): Output file format; multiple file formats can be listed in a comma-delimited list. Supported values are
rcm
,rcs
,obj
,fbx
,ortho
andreport
. If noformat
is specified, it will default torcm
.
- rcs: Autodesk ReCap Point Cloud
- rcm: Autodesk ReCap Photo Mesh
- obj: Wavefront Object
- fbx: Autodesk FBX 3D asset exchange format
- ortho: Ortho Photo and Elevation Map
- report: Quality Report
- metadata_name/metadata_value pairs (optional): These pairings specify processing-specific options.
The following example shows how a photoscene can be created through POST /photo-to-3d/v1/photoscene
endpoint. Note that these are just a subset of the available options, please refer to the API Reference for details.
POST /photo-to-3d/v1/photoscene
curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/photoscene'
-X 'POST'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6...'
-d 'scenename=testscene'
-d 'format=rcm,ortho'
-d 'metadata_name[0]=targetcs'
-d 'metadata_value[0]=UTM84-32N'
Note that line breaks have been added to the cURL command above for ease of reading. Make sure to remove them before executing any code in your terminal.
If successful, the response body looks like:
{
"msg": "No error",
"Photoscene": {
"photosceneid": "hcYJcrnHUsNSPII9glhVe8lRF6lFXs4NHzGqJ3zdWMU"
}
}
The response contains a generated photoscene ID hash, which is vital information to be used for the next steps.
Step 3: Add Images
Images can be added to photoscene either by uploading them directly or by providing HTTP/HTTPS/FTP links. Both methods will be illustrated below. After adding files to a photoscene, they will remain associated with the photoscene. Currently only JPEG images are supported.
Uploading Files Directly
The following method uploads files directly:
POST /photo-to-3d/v1/file
curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/file'
-X 'POST'
-H 'Authorization: Bearer eyjhbGCIOIjIuzI1NiISimtpZCI6...'
-F "photosceneid=hcYJcrnHUsNSPII9glhVe8lRF6lFXs4NHzGqJ3zdWMU"
-F "type=image"
-F "file[0]=@c:/sample_data/_MG_9026.jpg"
-F "file[1]=@c:/sample_data/_MG_9027.jpg"
Note: It is recommended that large file uploads be sent in separate REST requests to prevent API timeouts.
Adding Files by Reference
The following method uploads files through their HTTP references:
POST /photo-to-3d/v1/file
curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/file'
-X 'POST'
-H 'Authorization: Bearer eyjhbGCIOIjIuzI1NiISimtpZCI6...'
-d "photosceneid=HCyjCRNHUsNsPII9GlhvE8LrF6LFxS4NHzgQj3ZDWmU"
-d "type=image"
-d "file[0]=http://www.autodesk.com/_MG_9026.jpg"
-d "file[1]=http://www.autodesk.com/_MG_9027.jpg"
In both cases (direct upload and referenced external file links), a successful response will look like:
{
"photosceneid": "AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz",
"Files": {
"file": [{
"filename": "_MG_9026.jpg",
"filesize": "364436",
"msg": "No error"
}, {
"filename": "_MG_9027.jpg",
"filesize": "332689",
"msg": "No error"
}]
}
}
Step 4: Process a Photoscene
At this stage, your photoscene is ready to be processed; all files have been associated with the project. The next step is to process your images. The main processing steps involve: camera calibration, mesh reconstruction, texturing, and any necessary output file format conversions, in that order. Any options that you previously applied to your photoscene (including metadata_name/metadata_value
tags) will be applied to those processing steps.
Photoscene processing is performed with the POST request:
POST /photo-to-3d/v1/photoscene/:photosceneid
curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/photoscene/AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbzxHQ'
-X 'POST'
-H 'Authorization: Bearer eyjhbGCIOIjIuzI1NiISimtpZCI6...'
For a successful request, the response will look like:
{
"msg": "No error",
"Photoscene": {
"photosceneid": "AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbzxHQ"
}
}
Step 5: Poll Photoscene Processing Progress
Now that your photoscene is processing, you can periodically poll it to track progress with the GET request:
GET /photo-to-3d/v1/photoscene/:photosceneid/progress
curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/photoscene/AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz/progress'
-X 'GET'
-H 'Authorization: Bearer eyjhbGCIOIjIuzI1NiISimtpZCI6...'
For a project that is still being processed, the response will look like:
{
"Photoscene": {
"photosceneid": "AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz",
"progressmsg": "Processing",
"progress": "58.4"
}
}
For a project that has completed successfully, the response will look like:
{
"Photoscene": {
"photosceneid": "AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz",
"progressmsg": "DONE",
"progress": "100"
}
}
Step 6: Download Processed Data
Once your photoscene has completed processing, you can download results for the file formats that you requested.
Photoscene output download links are obtained with the GET request:
- format (mandatory): The file format to get a download link for. Supported values are
rcm
,rcs
,obj
,ortho
andreport
. Download links for each file format should be requested separately.
GET /photo-to-3d/v1/photoscene/:photosceneid
curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/photoscene/AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz?format=rcm'
-X 'GET'
-H 'Authorization: Bearer eyjhbGCIOIjIuzI1NiISimtpZCI6...'
For a successfully completed project, the response will look like:
{
"Photoscene": {
"photosceneid": "AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz",
"progressmsg": "DONE",
"progress": "100",
"scenelink": "https://s3.amazonaws.com/com.autodesk.storage...",
"filesize": "41640100",
"resultmsg": {}
}
}
The response includes a download link (scenelink
) field that corresponds to the data of the requested output format. This link will be valid for 7 days from the date of project completion.