5 Reality Capture

Got a folder of overlapping photos and want a 3D mesh? That’s the Reality Capture API (also called Photo-to-3D). You upload the images, AutoDesk’s photogrammetry engine does the heavy lifting, and you download a georeferenced 3D model — no specialised hardware or software required.

Common uses: - As-built documentation — fly a drone over a construction site each week and generate a mesh for each visit - Heritage recording — photograph a structure with a phone and get a measurable 3D record - Site topography — turn aerial photos into a terrain mesh for civil design - Mesh analysis — feed the output into Rvcg via the 3D Geometry chapters

The full workflow goes like this:

flowchart LR
  A[Photos] --> B[createPhotoscene]
  B --> C[uploadImages]
  C --> D[processPhotoscene]
  D --> E{waitForPhotoscene\nor checkPhotoscene}
  E -- progress < 100 --> E
  E -- progress = 100 --> F[Download\nmesh / point cloud]

5.1 Before You Start

Tip

Good photos make good meshes. A few guidelines that will save you a lot of frustration:

At least 20 images per scene — 50–200 is typical for a small structure
60–80 % overlap between adjacent shots; every surface should appear in at least 3 photos
Consistent, diffuse lighting — harsh shadows and mirror-like reflections confuse the algorithm
Move the camera around the subject, don’t just zoom in from one spot
GPS/EXIF tags are optional but improve georeferencing accuracy

5.2 Step 1: Authenticate

Reality Capture needs data:read and data:write scopes:

library(AutoDeskR)

resp    <- getToken(
  id     = Sys.getenv("client_id"),
  secret = Sys.getenv("client_secret"),
  scope  = "data:read data:write"
)
myToken <- resp$content$access_token

5.3 Step 2: Create a Photoscene

A photoscene is the container for your images and output. The format parameter controls what comes out the other end:

Format	Output
`"rcm"`	AutoDesk ReCap project (default)
`"rcs"`	ReCap point cloud — feeds into Point Cloud Analysis
`"obj"`	Wavefront OBJ mesh — feeds into Reading OBJ and STL Meshes
`"ortho"`	Orthophoto + DSM GeoTIFF
`"report"`	PDF quality report

ps             <- createPhotoscene(name = "site-survey-2026", format = "obj", token = myToken)
myPhotosceneId <- ps$content$photoscene$photosceneid
myPhotosceneId
#> [1] "K2RDAPFIN0OPKGU9B65Q2TJD"

5.4 Step 3: Upload Images

Pass a character vector of local file paths. AutoDeskR bundles them into a single multipart POST. JPEG and PNG both work.

image_files <- list.files("photos/", pattern = "\\.jpg$", full.names = TRUE)

imgs <- uploadImages(
  photoscene_id = myPhotosceneId,
  files         = image_files,
  token         = myToken
)
imgs$content$Files$file[[1]]
#> $filename
#> [1] "site_001.jpg"
#>
#> $fileid
#> [1] "A1B2C3D4E5F6G7H8"
#>
#> $filesize
#> [1] 4718592

Warning

Free-tier limits: Maximum 1,000 images per photoscene and 10 photoscenes per month. Exceeding the quota returns a 403 Forbidden. Upgrade to a paid plan for higher limits.

5.5 Step 4: Start Processing

One call kicks off the reconstruction:

proc <- processPhotoscene(photoscene_id = myPhotosceneId, token = myToken)
proc$content$photoscene$progressmsg
#> [1] "Queued"

5.6 Step 5: Wait for It

5.6.1 Option A — Block until done (recommended)

waitForPhotoscene() polls on a schedule and returns when the job finishes. Set verbose = TRUE to watch the progress tick up:

done <- waitForPhotoscene(
  photoscene_id = myPhotosceneId,
  token         = myToken,
  interval      = 60,    # check every 60 seconds
  timeout       = 3600,  # give up after an hour
  verbose       = TRUE
)
#> Reality Capture progress: 0 - Queued
#> Reality Capture progress: 10 - Uploading files
#> Reality Capture progress: 35 - Calibrating cameras
#> Reality Capture progress: 60 - Building point cloud
#> Reality Capture progress: 85 - Generating mesh
#> Reality Capture progress: 100 - Done

5.6.2 Option B — Manual polling

If you want more control, call checkPhotoscene() yourself:

status <- checkPhotoscene(photoscene_id = myPhotosceneId, token = myToken)
status$content$photoscene$progress
#> [1] "75"
status$content$photoscene$progressmsg
#> [1] "Processing geometry"

Warning

Processing time scales with image count. A 50-image scene typically takes 5–15 minutes; 500 images may take over an hour. Set timeout generously — there’s nothing worse than a premature timeout on an 80-minute job.

5.7 Step 6: Download the Output

When progress hits "100", retrieve the download URL and save the mesh locally:

output_url <- done$content$photoscene$scenelink

download.file(
  url      = paste0(output_url, "/output.obj"),
  destfile = "site-survey-2026.obj",
  headers  = c(Authorization = paste("Bearer", myToken))
)

From here, the OBJ file is ready for Reading OBJ and STL Meshes or further translation via the Model Derivative API.