All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Loading...
Searching...
No Matches
Area Target Capture Controller

Classes

struct  VuAreaTargetCaptureConfig
 Configuration options for Area Target Capture instance creation. More...
 
struct  VuAreaTargetCaptureGenerationConfig
 Configuration options for Area Target generation. More...
 

Typedefs

typedef struct VuAreaTargetCapture_ VuAreaTargetCapture
 Area Target Capture instance.
 

Enumerations

enum  VuAreaTargetCaptureCreationError : int32_t {
  VU_AREA_TARGET_CAPTURE_CREATION_ERROR_NONE = 0x0 ,
  VU_AREA_TARGET_CAPTURE_CREATION_ERROR_INTERNAL = 0x1 ,
  VU_AREA_TARGET_CAPTURE_CREATION_ERROR_AUTOSTART_FAILED = 0x2 ,
  VU_AREA_TARGET_CAPTURE_CREATION_ERROR_FEATURE_NOT_SUPPORTED = 0x3 ,
  VU_AREA_TARGET_CAPTURE_CREATION_ERROR_MULTIPLE_INSTANCES_NOT_SUPPORTED ,
  VU_AREA_TARGET_CAPTURE_CREATION_ERROR_INVALID_DEVICE_POSE_OBSERVER = 0x5
}
 Area Target Capture creation error. More...
 
enum  VuAreaTargetCaptureStatus : int32_t {
  VU_AREA_TARGET_CAPTURE_STATUS_INITIALIZED = 0x1 ,
  VU_AREA_TARGET_CAPTURE_STATUS_PREPARING = 0x2 ,
  VU_AREA_TARGET_CAPTURE_STATUS_CAPTURING = 0x3 ,
  VU_AREA_TARGET_CAPTURE_STATUS_PAUSED = 0x4 ,
  VU_AREA_TARGET_CAPTURE_STATUS_STOPPED = 0x5 ,
  VU_AREA_TARGET_CAPTURE_STATUS_GENERATING = 0x6
}
 Area Target Capture status. More...
 
enum  VuAreaTargetCaptureStatusInfo : int32_t {
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_NORMAL = 0x1 ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_RELOCALIZING = 0x2 ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_EXCESSIVE_MOTION = 0x3 ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_CAPACITY_WARNING ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_INTERRUPTED = 0x5 ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_SUSPENDED = 0x6 ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_TRACKING_DATA_GENERATION = 0x7 ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_AUTHORING_DATA_GENERATION = 0x8 ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_DEVICE_DATABASE_GENERATION ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_PACKAGE_GENERATION = 0xA ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_SUCCESS = 0xB ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_CANCELED = 0xC ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_INTERNAL = 0xD ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_NO_NETWORK_CONNECTION ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_SERVICE_NOT_AVAILABLE ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_AUTHORIZATION_FAILED ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_MISSING_ALIGNMENT_DATA ,
  VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_ALIGNMENT_FAILED
}
 Area Target Capture status info. More...
 
enum  VuAreaTargetCaptureGenerationError : int32_t {
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_NONE = 0x0 ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INTERNAL = 0x1 ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_ENGINE_NOT_RUNNING = 0x2 ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INVALID_STATUS = 0x3 ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INSUFFICIENT_DATA ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_MISSING_AUTHENTICATION ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INVALID_OUTPUT_DIRECTORY ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INVALID_TARGET_NAME ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_AUTHORING_FILES_GENERATION_REQUIRED ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_DATABASE_GENERATION_REQUIRED ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_ALIGNMENT_DATABASE_LOAD_ERROR ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INVALID_ALIGNMENT_TARGET_NAME ,
  VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_ALIGNMENT_TARGET_NOT_FOUND
}
 Area Target Capture generation error. More...
 

Functions

VuAreaTargetCaptureConfig vuAreaTargetCaptureConfigDefault ()
 Default capture configuration.
 
VuAreaTargetCaptureGenerationConfig vuAreaTargetCaptureGenerationConfigDefault ()
 Default generation configuration.
 
VuResult vuEngineGetAreaTargetCaptureController (const VuEngine *engine, VuController **controller)
 Retrieve Area Target Capture Controller to get access to Area Target Capture functionality in Engine.
 
VuResult vuAreaTargetCaptureControllerCreateAreaTargetCapture (VuController *controller, const VuAreaTargetCaptureConfig *config, VuAreaTargetCapture **capture, VuAreaTargetCaptureCreationError *error)
 Create a new capture with the specified configuration.
 
VuResult vuAreaTargetCaptureStart (VuAreaTargetCapture *capture)
 Start a capture.
 
VuResult vuAreaTargetCaptureStop (VuAreaTargetCapture *capture)
 Stop a running or paused capture.
 
VuResult vuAreaTargetCapturePause (VuAreaTargetCapture *capture)
 Pause a running capture.
 
VuResult vuAreaTargetCaptureResume (VuAreaTargetCapture *capture)
 Resume a paused capture.
 
VuResult vuAreaTargetCaptureGenerate (VuAreaTargetCapture *capture, const VuAreaTargetCaptureGenerationConfig *config, VuAreaTargetCaptureGenerationError *error)
 Start Area Target generation from a stopped capture.
 
VuResult vuAreaTargetCaptureGetStatus (const VuAreaTargetCapture *capture, VuAreaTargetCaptureStatus *status)
 Get status of the capture.
 
VuResult vuAreaTargetCaptureGetStatusInfo (const VuAreaTargetCapture *capture, VuAreaTargetCaptureStatusInfo *statusInfo)
 Get status info for the capture.
 
VuResult vuAreaTargetCaptureCancelGeneration (VuAreaTargetCapture *capture)
 Cancel Area Target generation.
 
VuResult vuAreaTargetCaptureGetGenerationProgress (const VuAreaTargetCapture *capture, float *progress)
 Get progress information of the current Area Target generation in the range [0.0f, 1.0f].
 
VuResult vuAreaTargetCaptureGetGenerationTimeEstimate (const VuAreaTargetCapture *capture, int32_t *remainingTimeSeconds)
 Get estimated time remaining to complete the current Area Target generation in seconds.
 
VuResult vuAreaTargetCaptureDestroy (VuAreaTargetCapture *capture)
 Destroy the given capture instance.
 

Detailed Description

This controller provides functionality to generate Area Targets by capturing all required data with Vuforia Engine.

Note
This feature is supported only on iOS devices with a LiDAR sensor.

Enumeration Type Documentation

◆ VuAreaTargetCaptureCreationError

Area Target Capture creation error.

Enumerator
VU_AREA_TARGET_CAPTURE_CREATION_ERROR_NONE 

No error.

VU_AREA_TARGET_CAPTURE_CREATION_ERROR_INTERNAL 

An internal error occurred while creating the capture.

VU_AREA_TARGET_CAPTURE_CREATION_ERROR_AUTOSTART_FAILED 

Auto-start of the capture failed.

VU_AREA_TARGET_CAPTURE_CREATION_ERROR_FEATURE_NOT_SUPPORTED 

Feature is not supported on the current device.

VU_AREA_TARGET_CAPTURE_CREATION_ERROR_MULTIPLE_INSTANCES_NOT_SUPPORTED 

Multiple captures are not allowed to exist at the same time.

VU_AREA_TARGET_CAPTURE_CREATION_ERROR_INVALID_DEVICE_POSE_OBSERVER 

Device pose observer is NULL or invalid.

◆ VuAreaTargetCaptureStatus

enum VuAreaTargetCaptureStatus : int32_t

Area Target Capture status.

Enumerator
VU_AREA_TARGET_CAPTURE_STATUS_INITIALIZED 

The capture was created and can be started.

VU_AREA_TARGET_CAPTURE_STATUS_PREPARING 

The capture has not collected sufficient data to create the initial reconstruction of the environment. A target cannot be generated yet

VU_AREA_TARGET_CAPTURE_STATUS_CAPTURING 

The capture created an initial reconstruction of the environment. A target can now be generated, or continue to capture more data

VU_AREA_TARGET_CAPTURE_STATUS_PAUSED 

The capture was paused.

VU_AREA_TARGET_CAPTURE_STATUS_STOPPED 

The capture was stopped.

VU_AREA_TARGET_CAPTURE_STATUS_GENERATING 

The capture is generating a target from the captured data.

◆ VuAreaTargetCaptureStatusInfo

Area Target Capture status info.

Enumerator
VU_AREA_TARGET_CAPTURE_STATUS_INFO_NORMAL 

The capture is running normally.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_RELOCALIZING 

The capture is relocalizing, the user should move around or return towards a previously mapped area in order to resume normal capturing

VU_AREA_TARGET_CAPTURE_STATUS_INFO_EXCESSIVE_MOTION 

The user is moving too quickly.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_CAPACITY_WARNING 

The capture is removing old data to make room for new data and should be stopped soon.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_INTERRUPTED 

The capture is unable to add new data, the user should stop the capture.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_SUSPENDED 

The capture is suspended until Engine is started.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_TRACKING_DATA_GENERATION 

The capture is processing the captured data.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_AUTHORING_DATA_GENERATION 

The capture is generating the authoring files.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_DEVICE_DATABASE_GENERATION 

The capture is generating the Area Target database and the occlusion mesh.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_PACKAGE_GENERATION 

The capture is generating the package(s)

VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_SUCCESS 

Generation successful.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_CANCELED 

Generation was canceled.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_INTERNAL 

Generation failed because an internal error occurred.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_NO_NETWORK_CONNECTION 

Generation failed because the device has no network connection.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_SERVICE_NOT_AVAILABLE 

Generation failed because the server was not found, is unreachable, or overloaded.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_AUTHORIZATION_FAILED 

Generation failed because the credentials are wrong or outdated.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_MISSING_ALIGNMENT_DATA 

Generation failed because of a problem during asynchronous loading of the alignment target data.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR_ALIGNMENT_FAILED 

Generation failed because it was not possible to align the capture with the specified alignment target.

◆ VuAreaTargetCaptureGenerationError

Area Target Capture generation error.

Note
These errors report the cause for Area Target generation failing to start. Errors that arise during Area Target generation are reported in VuAreaTargetCaptureStatusInfo.
Enumerator
VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_NONE 

No error.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INTERNAL 

An internal error occurred.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_ENGINE_NOT_RUNNING 

Generation failed because Engine is not running.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INVALID_STATUS 

Generation failed because the capture is in the wrong status.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INSUFFICIENT_DATA 

Generation failed because the capture has not yet created an initial reconstruction of the environment.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_MISSING_AUTHENTICATION 

Generation failed because authentication details are missing (user authentication or authentication secret)

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INVALID_OUTPUT_DIRECTORY 

Generation failed because the output directory does not exist or can not be written to.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INVALID_TARGET_NAME 

Generation failed because the target name does not satisfy requirements.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_AUTHORING_FILES_GENERATION_REQUIRED 

Generation failed because authoring files generation is required, but was not enabled.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_DATABASE_GENERATION_REQUIRED 

Generation failed because database generation is required, but was not enabled.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_ALIGNMENT_DATABASE_LOAD_ERROR 

Generation failed because the alignment database file was not found or an error occurred when reading data from it (potentially unknown or corrupted file)

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INVALID_ALIGNMENT_TARGET_NAME 

Generation failed because the alignment target name is invalid.

VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_ALIGNMENT_TARGET_NOT_FOUND 

Generation failed because the alignment target with the specified name AND target type matching Area Target was not found in database

Function Documentation

◆ vuAreaTargetCaptureConfigDefault()

VuAreaTargetCaptureConfig vuAreaTargetCaptureConfigDefault ( )

Default capture configuration.

Note
Use this function to initialize the VuAreaTargetCaptureConfig data structure with default values.

◆ vuAreaTargetCaptureGenerationConfigDefault()

VuAreaTargetCaptureGenerationConfig vuAreaTargetCaptureGenerationConfigDefault ( )

Default generation configuration.

Note
Use this function to initialize the VuAreaTargetCaptureGenerationConfig data structure with default values.

◆ vuAreaTargetCaptureControllerCreateAreaTargetCapture()

VuResult vuAreaTargetCaptureControllerCreateAreaTargetCapture ( VuController * controller,
const VuAreaTargetCaptureConfig * config,
VuAreaTargetCapture ** capture,
VuAreaTargetCaptureCreationError * error )

Create a new capture with the specified configuration.

Any previously created capture has to be destroyed before creating a new capture.

This function creates an Area Target capture based on the specified configuration. On successful creation the capture has status VU_AREA_TARGET_CAPTURE_STATUS_INITIALIZED, unless the configuration's start flag is VU_TRUE, then the capture has status VU_AREA_TARGET_CAPTURE_STATUS_PREPARING. If creation of the capture fails, then VU_FAILED is returned and the optional error parameter will hold an error code that reflects the cause of the error.

Note
If Engine is not running and the configuration's start flag is VU_TRUE, then on successful creation the capture has status VU_AREA_TARGET_CAPTURE_STATUS_PAUSED and status info VU_AREA_TARGET_CAPTURE_STATUS_INFO_SUSPENDED. The capture will then be started automatically during the next call to vuEngineStart().
Parameters
controllerArea Target Capture Controller
configThe configuration for the new capture
captureOutput variable storing the newly created capture
errorOptional output variable providing additional error information. Can be NULL.
Returns
VU_SUCCESS on successful creation of the capture, VU_FAILED otherwise

◆ vuAreaTargetCaptureStart()

VuResult vuAreaTargetCaptureStart ( VuAreaTargetCapture * capture)

Start a capture.

The capture starts data acquisition and switches to status VU_AREA_TARGET_CAPTURE_STATUS_PREPARING.

Note
If Engine is not running, then the capture switches to status VU_AREA_TARGET_CAPTURE_STATUS_PAUSED and status info VU_AREA_TARGET_CAPTURE_STATUS_INFO_SUSPENDED. The capture will then be started automatically during the next call to vuEngineStart().
Returns
VU_SUCCESS if the capture is in status VU_AREA_TARGET_CAPTURE_STATUS_INITIALIZED and start is successful, VU_FAILED otherwise

◆ vuAreaTargetCaptureStop()

VuResult vuAreaTargetCaptureStop ( VuAreaTargetCapture * capture)

Stop a running or paused capture.

The capture stops data acquisition, and switches to status VU_AREA_TARGET_CAPTURE_STATUS_STOPPED.

Note
An Area Target can be generated only when the capture is stopped.
This function fails if Engine is not running.
Returns
VU_SUCCESS if the capture is in status VU_AREA_TARGET_CAPTURE_STATUS_PREPARING, VU_AREA_TARGET_CAPTURE_STATUS_CAPTURING, or VU_AREA_TARGET_CAPTURE_STATUS_PAUSED and stop is successful, VU_FAILED otherwise

◆ vuAreaTargetCapturePause()

VuResult vuAreaTargetCapturePause ( VuAreaTargetCapture * capture)

Pause a running capture.

Data acquisition of the capture can be paused and resumed. vuAreaTargetCapturePause() pauses data acquisition and switches the capture to status VU_AREA_TARGET_CAPTURE_STATUS_PAUSED. vuAreaTargetCaptureResume() resumes data acquisition and switches the capture to the status it was in before the pause.

Note
If Engine is stopped while a capture is running, then the capture will be automatically paused during vuEngineStop(), and it will be automatically resumed during the next call to vuEngineStart(). A capture that is automatically paused by Engine has status info VU_AREA_TARGET_CAPTURE_STATUS_INFO_SUSPENDED.
This function fails if Engine is not running.
Returns
VU_SUCCESS if the capture is in status VU_AREA_TARGET_CAPTURE_STATUS_PREPARING or VU_AREA_TARGET_CAPTURE_STATUS_CAPTURING and pause is successful, VU_FAILED otherwise

◆ vuAreaTargetCaptureResume()

VuResult vuAreaTargetCaptureResume ( VuAreaTargetCapture * capture)

Resume a paused capture.

The capture resumes data acquisition, and switches to the status it was in before the pause.

Note
This function fails if Engine is not running.
Returns
VU_SUCCESS if the capture is in status VU_AREA_TARGET_CAPTURE_STATUS_PAUSED and resume is successful, VU_FAILED otherwise

◆ vuAreaTargetCaptureGenerate()

VuResult vuAreaTargetCaptureGenerate ( VuAreaTargetCapture * capture,
const VuAreaTargetCaptureGenerationConfig * config,
VuAreaTargetCaptureGenerationError * error )

Start Area Target generation from a stopped capture.

This function starts Area Target generation based on the specified configuration. Once successfully started, Area Target generation runs in the background. For Area Target generation to successfully start, the following requirements have to be met:

  • Engine is required to be running.
  • The capture is required to have status VU_AREA_TARGET_CAPTURE_STATUS_STOPPED.
  • The capture is required to have accumulated sufficient data to switch from the VU_AREA_TARGET_CAPTURE_STATUS_PREPARING status to the VU_AREA_TARGET_CAPTURE_STATUS_CAPTURING status.
  • The generation configuration is required to be valid. It has to provide the path to an existing output directory that can be written to, and it has to provide a valid target name. If database generation is enabled, then the configuration has to hold valid credentials for communication with the Vuforia server.
  • For aligned generation, the generation configuration must also provide the path to a valid Area Target database and the name of the target that will be used for alignment. If generation is successful, then the newly generated Area Target will be aligned to the alignment target coordinate system.

If all the requirements are met, this function starts Area Target generation in the background, switches the capture to status VU_AREA_TARGET_CAPTURE_STATUS_GENERATING, and returns VU_SUCCESS. If any of the requirements are not met, VU_FAILED is returned and the optional error parameter will hold an error code that reflects the cause of the error.

Area Target generation runs in the background. When it completes, the capture switches back to status VU_AREA_TARGET_CAPTURE_STATUS_STOPPED. On successful Area Target generation, status info reports VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_SUCCESS. If Area Target generation failed, then status info holds one of the values prefixed with VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_ERROR to report on the failure cause. If Area Target generation was canceled, status info holds the value VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_CANCELED.

Note
If database generation is enabled, then a network connection is required.
If Engine is stopped while Area Target generation is running, then Area Target generation is automatically canceled.
Parameters
captureThe Area Target Capture instance
configThe configuration for the Area Target generation
errorOptional output variable providing additional error information. Can be NULL.
Returns
VU_SUCCESS if the Area Target generation has successfully started, VU_FAILED otherwise

◆ vuAreaTargetCaptureCancelGeneration()

VuResult vuAreaTargetCaptureCancelGeneration ( VuAreaTargetCapture * capture)

Cancel Area Target generation.

A helper function to abort a running target generation. If the target generation has been canceled successfully, then status info will hold the value VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_CANCELED.

Note
This function blocks until target generation has aborted
This is a potentially long running operation
Returns
VU_SUCCESS if the capture is in status VU_AREA_TARGET_CAPTURE_STATUS_GENERATING and cancelation is successful, VU_FAILED otherwise

◆ vuAreaTargetCaptureGetGenerationProgress()

VuResult vuAreaTargetCaptureGetGenerationProgress ( const VuAreaTargetCapture * capture,
float * progress )

Get progress information of the current Area Target generation in the range [0.0f, 1.0f].

Returns
VU_SUCCESS if the capture is in status VU_AREA_TARGET_CAPTURE_STATUS_GENERATING, VU_FAILED otherwise

◆ vuAreaTargetCaptureGetGenerationTimeEstimate()

VuResult vuAreaTargetCaptureGetGenerationTimeEstimate ( const VuAreaTargetCapture * capture,
int32_t * remainingTimeSeconds )

Get estimated time remaining to complete the current Area Target generation in seconds.

It may take few seconds after the Area Target generation started for the time estimate to become available.

Returns
VU_SUCCESS if the capture is in status VU_AREA_TARGET_CAPTURE_STATUS_GENERATING and the time estimate is available, VU_FAILED otherwise

◆ vuAreaTargetCaptureDestroy()

VuResult vuAreaTargetCaptureDestroy ( VuAreaTargetCapture * capture)

Destroy the given capture instance.

If the capture is running data acquisition, it is automatically stopped. If the capture is running target generation, it is automatically canceled.

Note
This is a potentially long running operation