file
Adds one or more files to a photoscene.
Files can be added to photoscene either by uploading them directly or by providing public HTTP/HTTPS links. Although uploading multiple files at the same time might be more efficient, you should limit the number of files per request depending on your available bandwidth to avoid timeouts.
Note: Uploaded files will be deleted after 30 days.
Limitations
- Only JPEG images are supported.
- Maximum number of files in a single request: 20
- Maximum size of a single file: 128 MB
- Maximum uncompressed size of image in memory: 512 MB
Resource Information
Method and URI | POST https://developer.api.autodesk.com/photo-to-3d/v1/file |
Authentication Context | user context optional |
Required OAuth Scopes | data:write |
Data Format | JSON |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via either a two-legged or three-legged OAuth flow. |
Content-Type* string | Must be application/x-www-form-urlencoded |
Request
Body Structure
Image File
For image files, this method does not have a request body structure.
Survey File
To specify GCPs (Ground Control Points) in a reconstruction, add an XML-formatted GCP definition file to the photoscene.
- The coordinatesystem string attribute is required, and must be an id from the Autodesk supported library of coordinate systems.
- Use
LL84
for LLA. - Important: only
LL84
is supported for now. - Marker id values must be unique.
- In the gcp node, use long, lat & alt attribute names for degree based coordinate systems.
- Units are inferred from the coordinate system definition. For example,
AZ83-WIF
implies that all coordinates specified in the xml are in US feet.
<?xml version="1.0" encoding="UTF-8"?>
<surveydata coordinatesystem="string" epsgcode="int" description="string (optional)">
<markers>
<marker id="id1 (int)" name="marker1 (string)">
<images>
<image name="image1 (string)" xpixel="int" ypixel="int"/>
<image name="image2 (string)" xpixel="int" ypixel="int"/>
</images>
<!-- marker treated as a tie point if no gcp node specified -->
<gcp long="double" lat="double" alt="double" checkpoint="bool (default=false)"/>
</marker>
<marker id="id2 (int)" name="marker2 (string)">
<images>
<image name="image1 (string)" xpixel="int" ypixel="int"/>
<image name="image2 (string)" xpixel="int" ypixel="int"/>
</images>
<!-- marker treated as a tie point if no gcp node specified -->
<gcp long="double" lat="double" alt="double" checkpoint="bool (default=false)"/>
</marker>
</markers>
</surveydata>
Survey File Example
<?xml version="1.0" encoding="UTF-8"?>
<surveydata coordinatesystem="LL84" description="WGS84 datum, Latitude-Longitude; Degrees" epsgcode="4326">
<markers>
<marker id="0" name="10">
<images>
<image name="IMG_0001.JPG" xpixel="2831" ypixel="396"/>
</images>
<gcp long="38.005412" lat="-122.530565" alt="2000.100000" checkpoint="false"/>
</marker>
<marker id="1" name="11">
<images>
<image name="IMG_0002.JPG" xpixel="3941" ypixel="695"/>
<image name="IMG_0003.JPG" xpixel="3472" ypixel="1026"/>
<image name="IMG_0004.JPG" xpixel="3351" ypixel="875"/>
</images>
<gcp long="38.014125" lat="-122.540530" alt="2010.200000" checkpoint="false"/>
</marker>
<marker id="2" name="12">
<images>
<image name="IMG_0002.JPG" xpixel="2616" ypixel="2702"/>
<image name="IMG_0005.JPG" xpixel="2910" ypixel="2505"/>
</images>
<gcp long="38.021250" lat="-122.510412" alt="2015.000000" checkpoint="true"/>
</marker>
</markers>
</surveydata>
photosceneid* string | Specifies the ID of the photoscene to add the files to |
type enum:string | Specifies the type of file being uploaded
Possible values: image , survey |
file[0] string | Specifies the files to be uploaded - these may be URLs (i.e. http:// , https:// ) or local files
For externally stored files, please verify that the URLs are publically accessible |
Response
HTTP Status Code Summary
200 OK | File was successfully uploaded |
403 Forbidden | Unauthorized |
Response
Body Structure (200)
photosceneid string | ID of the photoscene. |
Files object | An array of objects, where each element contains a file object. |
file object | An object that represents an uploaded file. |
fileid string | Internal ID assigned to the image file upon upload |
filename string | Name of the file uploaded |
filesize string | Size of the image file, in kilobytes; can be used to verify upload integrity |
msg string | Message indicating the status of the file, can be empty |
Error object | Even though the the service returns a HTTP Status Code of 200, it may return an error payload, which provides details on why the operation failed. |
code int | A code that identifies the error type. See Error List for possible values |
msg string | A short, human readable explanation of the error |
Example 1
This example demonstrates sucessfully uploading of two image files from a remote server.
Request
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"
Response
{
"photosceneid": "AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz",
"Files": {
"file": [{
"filename": "_MG_9026.jpg",
"filesize": "364436",
"msg": "No error"
}, {
"filename": "_MG_9027.jpg",
"filesize": "332689",
"msg": "No error"
}]
}
}
Example 2
This example demonstrates sucessfully uploading of two image files from a local drive.
Request
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 requests to prevent API timeouts.
Response
{
"photosceneid": "AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz",
"Files": {
"file": [{
"filename": "_MG_9026.jpg",
"filesize": "364436",
"msg": "No error"
}, {
"filename": "_MG_9027.jpg",
"filesize": "332689",
"msg": "No error"
}]
}
}
Example 3
This example demonstrates an unsucessfull attempt at uploading two image files to a non-existent photoscene.
Request
curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/file' \
-X 'POST' \
-H 'Authorization: Bearer eyjhbGCIOIjIuzI1NiISimtpZCI6...' \
-F "photosceneid=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-F "type=image" \
-F "file[0]=@c:/sample_data/_MG_9026.jpg" \
-F "file[1]=@c:/sample_data/_MG_9027.jpg"
Response
{
"Error": {
"code": "19",
"msg": "Specified Photoscene ID doesn't exist in the database"
}
}