API Reference¶

A library for Vuforia Web Services.

class vws.VWS(*, server_access_key: str, server_secret_key: str, base_vws_url: str = 'https://vws.vuforia.com', database_id: str | None = None, request_timeout_seconds: float | tuple[float, float] = 30.0, transport: Transport | None = None)¶

An interface to Vuforia Web Services APIs.

Parameters:

• server_access_key – A VWS server access key.

• server_secret_key – A VWS server secret key.

• base_vws_url – The base URL for the VWS API.

• database_id – The ID of the database which the given keys belong to. This is shown in the target manager. It is needed only by request_database_reco_counts_report().

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The HTTP transport to use for requests. Defaults to RequestsTransport().

make_request(*, method: str, data: bytes, request_path: str, expected_result_code: str, content_type: str, extra_headers: dict[str, str] | None = None) → Response¶

Make a request to the Vuforia Target API.

Parameters:

• method – The HTTP method which will be used in the request.

• data – The request body which will be used in the request.

• request_path – The path to the endpoint which will be used in the request.

• expected_result_code – See “VWS API Result Codes” on https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api.

• content_type – The content type of the request.

• extra_headers – Additional headers to include in the request.

Returns:

The response to the request.

Raises:

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

• json.JSONDecodeError – The server did not respond with valid JSON. This may happen if the server address is not a valid Vuforia server.

add_target(*, name: str, width: float, image: BytesIO | BinaryIO, application_metadata: str | None, active_flag: bool) → str¶

Add a target to a Vuforia Web Services database.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#add for parameter details.

Parameters:

• name – The name of the target.

• width – The width of the target.

• image – The image of the target.

• active_flag – Whether or not the target is active for query.

• application_metadata –

  The application metadata of the target. This must be base64 encoded, for example by using:

  base64.b64encode('input_string').decode('ascii')
  

Returns:

The target ID of the new target.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• BadImageError – There is a problem with the given image. For example, it must be a JPEG or PNG file in the grayscale or RGB color space.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• MetadataTooLargeError – The given metadata is too large. The maximum size is 1 MB of data when Base64 encoded.

• ImageTooLargeError – The given image is too large.

• TargetNameExistError – A target with the given name already exists.

• ProjectInactiveError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers. This has been seen to happen when the given name includes a bad character.

• TooManyRequestsError – Vuforia is rate limiting access.

get_target_record(target_id: str) → TargetStatusAndRecord¶

Get a given target’s target record from the Target Management System.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record.

Parameters:

target_id – The ID of the target to get details of.

Returns:

Response details of a target from Vuforia.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

wait_for_target_processed(*, target_id: str, seconds_between_requests: float = 0.2, timeout_seconds: float = 300) → None¶

Wait up to five minutes (arbitrary) for a target to get past the processing stage.

Parameters:

• target_id – The ID of the target to wait for.

• seconds_between_requests – The number of seconds to wait between requests made while polling the target status. We wait 0.2 seconds by default, rather than less, than that to decrease the number of calls made to the API, to decrease the likelihood of hitting the request quota.

• timeout_seconds – The maximum number of seconds to wait for the target to be processed.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• TargetProcessingTimeoutError – The target remained in the processing stage for more than timeout_seconds seconds.

• UnknownTargetError – The given target ID does not match a target in the database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

list_targets() → list[str]¶

List target IDs.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#details-list.

Returns:

The IDs of all targets in the database.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

get_target_summary_report(target_id: str) → TargetSummaryReport¶

Get a summary report for a target.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.

Parameters:

target_id – The ID of the target to get a summary report for.

Returns:

Details of the target.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

get_database_summary_report() → DatabaseSummaryReport¶

Get a summary report for the database.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.

Returns:

Details of the database.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

request_database_reco_counts_report(*, year: int, month: Month) → RecoCountsReportRequest¶

Request a per-target recognition count report for the database.

Vuforia generates the report in the background, so the report is not available to download immediately. Use wait_for_reco_counts_report() to wait for it.

Parameters:

• year – The year to get recognition counts for.

• month – The month of the year to get recognition counts for. Vuforia accepts only the current month and the previous month. A month taken from a datetime.datetime needs wrapping, as in calendar.Month(value=now.month).

Returns:

The URL to download the report from, and the transaction ID of the request.

Raises:

• DatabaseIdNotSetError – No database_id was given to the client.

• AuthenticationFailureError – The secret key is not correct, or the client’s database_id is not the ID of the database which the client’s keys belong to.

• FailError – There was an error with the request. For example, the given year and month are not the current month or the previous month.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

download_reco_counts_report(*, presigned_url: str) → RecoCountsReport¶

Download a requested reco counts report.

The report’s URL is not part of the VWS API, so this request is not authorized with the client’s keys.

Parameters:

presigned_url – The URL of the report, as given by request_database_reco_counts_report().

Returns:

The downloaded report.

Raises:

• RecoCountsReportNotReadyError – Vuforia has not finished generating the report.

• RecoCountsReportDownloadError – The report could not be downloaded. For example, the report’s URL may have expired.

wait_for_reco_counts_report(*, presigned_url: str, seconds_between_requests: float = 0.2, timeout_seconds: float = 300) → RecoCountsReport¶

Wait for a requested reco counts report to be generated, then download it.

Parameters:

• presigned_url – The URL of the report, as given by request_database_reco_counts_report().

• seconds_between_requests – The number of seconds to wait between requests made while polling the report’s URL.

• timeout_seconds – The maximum number of seconds to wait for the report to be generated.

Returns:

The downloaded report.

Raises:

• RecoCountsReportTimeoutError – The report was not generated within timeout_seconds seconds.

• RecoCountsReportDownloadError – The report could not be downloaded. For example, the report’s URL may have expired.

delete_target(target_id: str) → None¶

Delete a given target.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#delete.

Parameters:

target_id – The ID of the target to delete.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• TargetStatusProcessingError – The given target is in the processing state.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

get_duplicate_targets(target_id: str) → list[str]¶

Get targets which may be considered duplicates of a given target.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#check.

Parameters:

target_id – The ID of the target to delete.

Returns:

The target IDs of duplicate targets.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• ProjectInactiveError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

update_target(*, target_id: str, name: str | None = None, width: float | None = None, image: BytesIO | BinaryIO | None = None, active_flag: bool | None = None, application_metadata: str | None = None) → None¶

Update a target in a Vuforia Web Services database.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#update for parameter details.

Parameters:

• target_id – The ID of the target to update.

• name – The name of the target.

• width – The width of the target.

• image – The image of the target.

• active_flag – Whether or not the target is active for query.

• application_metadata –

  The application metadata of the target. This must be base64 encoded, for example by using:

  base64.b64encode('input_string').decode('ascii')
  

  Giving None will not change the application metadata.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• BadImageError – There is a problem with the given image. For example, it must be a JPEG or PNG file in the grayscale or RGB color space.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• MetadataTooLargeError – The given metadata is too large. The maximum size is 1 MB of data when Base64 encoded.

• ImageTooLargeError – The given image is too large.

• TargetNameExistError – A target with the given name already exists.

• ProjectInactiveError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

class vws.AsyncCloudRecoService(*, client_access_key: str, client_secret_key: str, base_vwq_url: str = 'https://cloudreco.vuforia.com', request_timeout_seconds: float | tuple[float, float] = 30.0, transport: AsyncTransport | None = None)¶

An async interface to the Vuforia Cloud Recognition Web APIs.

Parameters:

• client_access_key – A VWS client access key.

• client_secret_key – A VWS client secret key.

• base_vwq_url – The base URL for the VWQ API.

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The async HTTP transport to use for requests. Defaults to AsyncHTTPXTransport().

async aclose() → None¶

Close the underlying transport if it supports closing.

async query(*, image: BytesIO | BinaryIO, max_num_results: int = 1, include_target_data: CloudRecoIncludeTargetData = CloudRecoIncludeTargetData.TOP) → list[QueryResult]¶

Use the Vuforia Web Query API to make an Image Recognition Query.

See https://developer.vuforia.com/library/web-api/vuforia-query-web-api for parameter details.

Parameters:

• image – The image to make a query against.

• max_num_results – The maximum number of matching targets to be returned.

• include_target_data – Indicates if target_data records shall be returned for the matched targets. Accepted values are top (default value, only return target_data for top ranked match), none (return no target_data), all (for all matched targets).

Raises:

• AuthenticationFailureError – The client access key pair is not correct.

• MaxNumResultsOutOfRangeError – max_num_results is not within the range (1, 50).

• InactiveProjectError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• BadImageError – There is a problem with the given image. For example, it must be a JPEG or PNG file in the grayscale or RGB color space.

• RequestEntityTooLargeError – The given image is too large.

• ServerError – There is an error with Vuforia’s servers.

• CloudRecoError – Vuforia returned a client error without a recognized JSON body.

• json.JSONDecodeError – Vuforia returned a successful response with an invalid JSON body.

Returns:

An ordered list of target details of matching targets.

class vws.AsyncModelTargetService(*, client_id: str, client_secret: str, base_vws_url: str = 'https://vws.vuforia.com', request_timeout_seconds: float | tuple[float, float] = 30.0, transport: AsyncTransport | None = None)¶

An async interface to the Vuforia Model Target Web API.

Parameters:

• client_id – A Model Target Web API OAuth2 client ID.

• client_secret – A Model Target Web API OAuth2 client secret.

• base_vws_url – The base URL for the VWS API, which also serves the Model Target Web API.

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The async HTTP transport to use for requests. Defaults to AsyncHTTPXTransport().

async aclose() → None¶

Close the underlying transport if it supports closing.

async get_access_token() → str¶

Get an OAuth2 access token for the Model Target Web API.

A token is requested only when the client has no token which is still valid, so this can be called before each request.

Returns:

A bearer token.

Raises:

ModelTargetOAuth2Error – Vuforia did not give an access token. For example, the given client ID and client secret may not match a set of Model Target Web API credentials.

async make_request(*, method: str, data: bytes, request_path: str, extra_headers: dict[str, str] | None = None) → Response¶

Make an authenticated request to the Model Target Web API.

Parameters:

• method – The HTTP method which will be used in the request.

• data – The request body which will be used in the request.

• request_path – The path to the endpoint which will be used in the request.

• extra_headers – Additional headers to include in the request.

Returns:

The response to the request.

Raises:

• ModelTargetError – Vuforia returned an error.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async create_dataset(*, name: str, target_sdk: str, models: Sequence[ModelTargetModel], dataset_type: ModelTargetDatasetType) → str¶

Start generating a Model Target dataset.

Vuforia generates the dataset in the background, so it is not available to download immediately. Use wait_for_dataset_generated() to wait for it.

Parameters:

• name – The name of the dataset.

• target_sdk – The Vuforia Engine version to generate the dataset for.

• models – The models to generate the dataset from. A standard dataset takes exactly one model.

• dataset_type – Whether to create a standard or an advanced dataset.

Returns:

The UUID of the new dataset.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• ModelTargetValidationError – Vuforia rejected the request. For example, a model may give neither a CAD data URL nor a CAD data blob.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

async get_dataset_status(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType) → ModelTargetDatasetStatusReport¶

Get the status of a Model Target dataset.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to get the status of.

Returns:

The status of the dataset.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

async wait_for_dataset_generated(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType, seconds_between_requests: float = 0.2, timeout_seconds: float = 300) → ModelTargetDatasetStatusReport¶

Wait for Vuforia to finish generating a Model Target dataset.

A dataset which failed to generate is also finished, so the returned report may have a status of FAILED.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to wait for.

• seconds_between_requests – The number of seconds to wait between requests made while polling the dataset’s status.

• timeout_seconds – The maximum number of seconds to wait for the dataset to be generated.

Returns:

The status of the dataset once it is no longer processing.

Raises:

• ModelTargetDatasetTimeoutError – The dataset was not generated within timeout_seconds seconds.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

async download_dataset(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType) → bytes¶

Download a generated Model Target dataset.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to download.

Returns:

The dataset, as the bytes of a zip file.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

• ModelTargetDatasetNotDoneError – Vuforia has not generated the dataset.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

async delete_dataset(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType) → None¶

Delete a Model Target dataset.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to delete.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

class vws.AsyncVWS(*, server_access_key: str, server_secret_key: str, base_vws_url: str = 'https://vws.vuforia.com', database_id: str | None = None, request_timeout_seconds: float | tuple[float, float] = 30.0, transport: AsyncTransport | None = None)¶

An async interface to Vuforia Web Services APIs.

Parameters:

• server_access_key – A VWS server access key.

• server_secret_key – A VWS server secret key.

• base_vws_url – The base URL for the VWS API.

• database_id – The ID of the database which the given keys belong to. This is shown in the target manager. It is needed only by request_database_reco_counts_report().

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The async HTTP transport to use for requests. Defaults to AsyncHTTPXTransport().

async aclose() → None¶

Close the underlying transport if it supports closing.

async make_request(*, method: str, data: bytes, request_path: str, expected_result_code: str, content_type: str, extra_headers: dict[str, str] | None = None) → Response¶

Make an async request to the Vuforia Target API.

Parameters:

• method – The HTTP method which will be used in the request.

• data – The request body which will be used in the request.

• request_path – The path to the endpoint which will be used in the request.

• expected_result_code – See “VWS API Result Codes” on https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api.

• content_type – The content type of the request.

• extra_headers – Additional headers to include in the request.

Returns:

The response to the request.

Raises:

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

• json.JSONDecodeError – The server did not respond with valid JSON. This may happen if the server address is not a valid Vuforia server.

async add_target(*, name: str, width: float, image: BytesIO | BinaryIO, application_metadata: str | None, active_flag: bool) → str¶

Add a target to a Vuforia Web Services database.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#add for parameter details.

Parameters:

• name – The name of the target.

• width – The width of the target.

• image – The image of the target.

• active_flag – Whether or not the target is active for query.

• application_metadata –

  The application metadata of the target. This must be base64 encoded, for example by using:

  base64.b64encode('input_string').decode('ascii')
  

Returns:

The target ID of the new target.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• BadImageError – There is a problem with the given image. For example, it must be a JPEG or PNG file in the grayscale or RGB color space.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• MetadataTooLargeError – The given metadata is too large. The maximum size is 1 MB of data when Base64 encoded.

• ImageTooLargeError – The given image is too large.

• TargetNameExistError – A target with the given name already exists.

• ProjectInactiveError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers. This has been seen to happen when the given name includes a bad character.

• TooManyRequestsError – Vuforia is rate limiting access.

async get_target_record(target_id: str) → TargetStatusAndRecord¶

Get a given target’s target record from the Target Management System.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record.

Parameters:

target_id – The ID of the target to get details of.

Returns:

Response details of a target from Vuforia.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async wait_for_target_processed(*, target_id: str, seconds_between_requests: float = 0.2, timeout_seconds: float = 300) → None¶

Wait up to five minutes (arbitrary) for a target to get past the processing stage.

Parameters:

• target_id – The ID of the target to wait for.

• seconds_between_requests – The number of seconds to wait between requests made while polling the target status. We wait 0.2 seconds by default, rather than less, than that to decrease the number of calls made to the API, to decrease the likelihood of hitting the request quota.

• timeout_seconds – The maximum number of seconds to wait for the target to be processed.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• TargetProcessingTimeoutError – The target remained in the processing stage for more than timeout_seconds seconds.

• UnknownTargetError – The given target ID does not match a target in the database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async list_targets() → list[str]¶

List target IDs.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#details-list.

Returns:

The IDs of all targets in the database.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async get_target_summary_report(target_id: str) → TargetSummaryReport¶

Get a summary report for a target.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.

Parameters:

target_id – The ID of the target to get a summary report for.

Returns:

Details of the target.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async get_database_summary_report() → DatabaseSummaryReport¶

Get a summary report for the database.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.

Returns:

Details of the database.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async request_database_reco_counts_report(*, year: int, month: Month) → RecoCountsReportRequest¶

Request a per-target recognition count report for the database.

Vuforia generates the report in the background, so the report is not available to download immediately. Use wait_for_reco_counts_report() to wait for it.

Parameters:

• year – The year to get recognition counts for.

• month – The month of the year to get recognition counts for. Vuforia accepts only the current month and the previous month. A month taken from a datetime.datetime needs wrapping, as in calendar.Month(value=now.month).

Returns:

The URL to download the report from, and the transaction ID of the request.

Raises:

• DatabaseIdNotSetError – No database_id was given to the client.

• AuthenticationFailureError – The secret key is not correct, or the client’s database_id is not the ID of the database which the client’s keys belong to.

• FailError – There was an error with the request. For example, the given year and month are not the current month or the previous month.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async download_reco_counts_report(*, presigned_url: str) → RecoCountsReport¶

Download a requested reco counts report.

The report’s URL is not part of the VWS API, so this request is not authorized with the client’s keys.

Parameters:

presigned_url – The URL of the report, as given by request_database_reco_counts_report().

Returns:

The downloaded report.

Raises:

• RecoCountsReportNotReadyError – Vuforia has not finished generating the report.

• RecoCountsReportDownloadError – The report could not be downloaded. For example, the report’s URL may have expired.

async wait_for_reco_counts_report(*, presigned_url: str, seconds_between_requests: float = 0.2, timeout_seconds: float = 300) → RecoCountsReport¶

Wait for a requested reco counts report to be generated, then download it.

Parameters:

• presigned_url – The URL of the report, as given by request_database_reco_counts_report().

• seconds_between_requests – The number of seconds to wait between requests made while polling the report’s URL.

• timeout_seconds – The maximum number of seconds to wait for the report to be generated.

Returns:

The downloaded report.

Raises:

• RecoCountsReportTimeoutError – The report was not generated within timeout_seconds seconds.

• RecoCountsReportDownloadError – The report could not be downloaded. For example, the report’s URL may have expired.

async delete_target(target_id: str) → None¶

Delete a given target.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#delete.

Parameters:

target_id – The ID of the target to delete.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• TargetStatusProcessingError – The given target is in the processing state.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async get_duplicate_targets(target_id: str) → list[str]¶

Get targets which may be considered duplicates of a given target.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#check.

Parameters:

target_id – The ID of the target to delete.

Returns:

The target IDs of duplicate targets.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• ProjectInactiveError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async update_target(*, target_id: str, name: str | None = None, width: float | None = None, image: BytesIO | BinaryIO | None = None, active_flag: bool | None = None, application_metadata: str | None = None) → None¶

Update a target in a Vuforia Web Services database.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#update for parameter details.

Parameters:

• target_id – The ID of the target to update.

• name – The name of the target.

• width – The width of the target.

• image – The image of the target.

• active_flag – Whether or not the target is active for query.

• application_metadata –

  The application metadata of the target. This must be base64 encoded, for example by using:

  base64.b64encode('input_string').decode('ascii')
  

  Giving None will not change the application metadata.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• BadImageError – There is a problem with the given image. For example, it must be a JPEG or PNG file in the grayscale or RGB color space.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• MetadataTooLargeError – The given metadata is too large. The maximum size is 1 MB of data when Base64 encoded.

• ImageTooLargeError – The given image is too large.

• TargetNameExistError – A target with the given name already exists.

• ProjectInactiveError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

class vws.AsyncVuMarkService(*, server_access_key: str, server_secret_key: str, base_vws_url: str = 'https://vws.vuforia.com', request_timeout_seconds: float | tuple[float, float] = 30.0, transport: AsyncTransport | None = None)¶

An async interface to the Vuforia VuMark Generation Web API.

Parameters:

• server_access_key – A VWS server access key.

• server_secret_key – A VWS server secret key.

• base_vws_url – The base URL for the VWS API.

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The async HTTP transport to use for requests. Defaults to AsyncHTTPXTransport().

async aclose() → None¶

Close the underlying transport if it supports closing.

async generate_vumark_instance(*, target_id: str, instance_id: str, accept: VuMarkAccept) → bytes¶

Generate a VuMark instance image.

See https://developer.vuforia.com/library/vuforia-engine/web-api/vumark-generation-web-api/ for parameter details.

Parameters:

• target_id – The ID of the VuMark target.

• instance_id – The instance ID to encode in the VuMark.

• accept – The image format to return.

Returns:

The VuMark instance image bytes.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• AuthorizationFailedError – There was a general authentication problem.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• InvalidAcceptHeaderError – The Accept header value is not supported.

• InvalidInstanceIdError – The instance ID is invalid. For example, it may be empty.

• InvalidTargetTypeError – The target is not a VuMark template target.

• LicenseCheckFailedError – The license state and/or type does not allow this request.

• QuotaExceededError – No more instances can be created for the associated license.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• TargetStatusNotSuccessError – The target is not in the success state.

• UnknownTargetError – The given target ID does not match a target in the database.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

class vws.CloudRecoService(*, client_access_key: str, client_secret_key: str, base_vwq_url: str = 'https://cloudreco.vuforia.com', request_timeout_seconds: float | tuple[float, float] = 30.0, transport: Transport | None = None)¶

An interface to the Vuforia Cloud Recognition Web APIs.

Parameters:

• client_access_key – A VWS client access key.

• client_secret_key – A VWS client secret key.

• base_vwq_url – The base URL for the VWQ API.

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The HTTP transport to use for requests. Defaults to RequestsTransport().

query(*, image: BytesIO | BinaryIO, max_num_results: int = 1, include_target_data: CloudRecoIncludeTargetData = CloudRecoIncludeTargetData.TOP) → list[QueryResult]¶

Use the Vuforia Web Query API to make an Image Recognition Query.

See https://developer.vuforia.com/library/web-api/vuforia-query-web-api for parameter details.

Parameters:

• image – The image to make a query against.

• max_num_results – The maximum number of matching targets to be returned.

• include_target_data – Indicates if target_data records shall be returned for the matched targets. Accepted values are top (default value, only return target_data for top ranked match), none (return no target_data), all (for all matched targets).

Raises:

• AuthenticationFailureError – The client access key pair is not correct.

• MaxNumResultsOutOfRangeError – max_num_results is not within the range (1, 50).

• InactiveProjectError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• BadImageError – There is a problem with the given image. For example, it must be a JPEG or PNG file in the grayscale or RGB color space.

• RequestEntityTooLargeError – The given image is too large.

• ServerError – There is an error with Vuforia’s servers.

• CloudRecoError – Vuforia returned a client error without a recognized JSON body.

• json.JSONDecodeError – Vuforia returned a successful response with an invalid JSON body.

Returns:

An ordered list of target details of matching targets.

class vws.ModelTargetService(*, client_id: str, client_secret: str, base_vws_url: str = 'https://vws.vuforia.com', request_timeout_seconds: float | tuple[float, float] = 30.0, transport: Transport | None = None)¶

An interface to the Vuforia Model Target Web API.

Parameters:

• client_id – A Model Target Web API OAuth2 client ID.

• client_secret – A Model Target Web API OAuth2 client secret.

• base_vws_url – The base URL for the VWS API, which also serves the Model Target Web API.

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The HTTP transport to use for requests. Defaults to RequestsTransport().

get_access_token() → str¶

Get an OAuth2 access token for the Model Target Web API.

A token is requested only when the client has no token which is still valid, so this can be called before each request.

Returns:

A bearer token.

Raises:

ModelTargetOAuth2Error – Vuforia did not give an access token. For example, the given client ID and client secret may not match a set of Model Target Web API credentials.

make_request(*, method: str, data: bytes, request_path: str, extra_headers: dict[str, str] | None = None) → Response¶

Make an authenticated request to the Model Target Web API.

Parameters:

• method – The HTTP method which will be used in the request.

• data – The request body which will be used in the request.

• request_path – The path to the endpoint which will be used in the request.

• extra_headers – Additional headers to include in the request.

Returns:

The response to the request.

Raises:

• ModelTargetError – Vuforia returned an error.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

create_dataset(*, name: str, target_sdk: str, models: Sequence[ModelTargetModel], dataset_type: ModelTargetDatasetType) → str¶

Start generating a Model Target dataset.

Vuforia generates the dataset in the background, so it is not available to download immediately. Use wait_for_dataset_generated() to wait for it.

Parameters:

• name – The name of the dataset.

• target_sdk – The Vuforia Engine version to generate the dataset for.

• models – The models to generate the dataset from. A standard dataset takes exactly one model.

• dataset_type – Whether to create a standard or an advanced dataset.

Returns:

The UUID of the new dataset.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• ModelTargetValidationError – Vuforia rejected the request. For example, a model may give neither a CAD data URL nor a CAD data blob.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

get_dataset_status(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType) → ModelTargetDatasetStatusReport¶

Get the status of a Model Target dataset.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to get the status of.

Returns:

The status of the dataset.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

wait_for_dataset_generated(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType, seconds_between_requests: float = 0.2, timeout_seconds: float = 300) → ModelTargetDatasetStatusReport¶

Wait for Vuforia to finish generating a Model Target dataset.

A dataset which failed to generate is also finished, so the returned report may have a status of FAILED.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to wait for.

• seconds_between_requests – The number of seconds to wait between requests made while polling the dataset’s status.

• timeout_seconds – The maximum number of seconds to wait for the dataset to be generated.

Returns:

The status of the dataset once it is no longer processing.

Raises:

• ModelTargetDatasetTimeoutError – The dataset was not generated within timeout_seconds seconds.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

download_dataset(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType) → bytes¶

Download a generated Model Target dataset.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to download.

Returns:

The dataset, as the bytes of a zip file.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

• ModelTargetDatasetNotDoneError – Vuforia has not generated the dataset.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

delete_dataset(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType) → None¶

Delete a Model Target dataset.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to delete.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

class vws.VuMarkService(*, server_access_key: str, server_secret_key: str, base_vws_url: str = 'https://vws.vuforia.com', request_timeout_seconds: float | tuple[float, float] = 30.0, transport: Transport | None = None)¶

An interface to the Vuforia VuMark Generation Web API.

Parameters:

• server_access_key – A VWS server access key.

• server_secret_key – A VWS server secret key.

• base_vws_url – The base URL for the VWS API.

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The HTTP transport to use for requests. Defaults to RequestsTransport().

generate_vumark_instance(*, target_id: str, instance_id: str, accept: VuMarkAccept) → bytes¶

Generate a VuMark instance image.

See https://developer.vuforia.com/library/vuforia-engine/web-api/vumark-generation-web-api/ for parameter details.

Parameters:

• target_id – The ID of the VuMark target.

• instance_id – The instance ID to encode in the VuMark.

• accept – The image format to return.

Returns:

The VuMark instance image bytes.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• AuthorizationFailedError – There was a general authentication problem.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• InvalidAcceptHeaderError – The Accept header value is not supported.

• InvalidInstanceIdError – The instance ID is invalid. For example, it may be empty.

• InvalidTargetTypeError – The target is not a VuMark template target.

• LicenseCheckFailedError – The license state and/or type does not allow this request.

• QuotaExceededError – No more instances can be created for the associated license.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• TargetStatusNotSuccessError – The target is not in the success state.

• UnknownTargetError – The given target ID does not match a target in the database.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

Async tools for interacting with Vuforia APIs.

class vws.async_vws.AsyncVWS(*, server_access_key: str, server_secret_key: str, base_vws_url: str = 'https://vws.vuforia.com', database_id: str | None = None, request_timeout_seconds: float | tuple[float, float] = 30.0, transport: AsyncTransport | None = None)¶

An async interface to Vuforia Web Services APIs.

Parameters:

• server_access_key – A VWS server access key.

• server_secret_key – A VWS server secret key.

• base_vws_url – The base URL for the VWS API.

• database_id – The ID of the database which the given keys belong to. This is shown in the target manager. It is needed only by request_database_reco_counts_report().

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The async HTTP transport to use for requests. Defaults to AsyncHTTPXTransport().

async aclose() → None¶

Close the underlying transport if it supports closing.

async make_request(*, method: str, data: bytes, request_path: str, expected_result_code: str, content_type: str, extra_headers: dict[str, str] | None = None) → Response¶

Make an async request to the Vuforia Target API.

Parameters:

• method – The HTTP method which will be used in the request.

• data – The request body which will be used in the request.

• request_path – The path to the endpoint which will be used in the request.

• expected_result_code – See “VWS API Result Codes” on https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api.

• content_type – The content type of the request.

• extra_headers – Additional headers to include in the request.

Returns:

The response to the request.

Raises:

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

• json.JSONDecodeError – The server did not respond with valid JSON. This may happen if the server address is not a valid Vuforia server.

async add_target(*, name: str, width: float, image: BytesIO | BinaryIO, application_metadata: str | None, active_flag: bool) → str¶

Add a target to a Vuforia Web Services database.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#add for parameter details.

Parameters:

• name – The name of the target.

• width – The width of the target.

• image – The image of the target.

• active_flag – Whether or not the target is active for query.

• application_metadata –

  The application metadata of the target. This must be base64 encoded, for example by using:

  base64.b64encode('input_string').decode('ascii')
  

Returns:

The target ID of the new target.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• BadImageError – There is a problem with the given image. For example, it must be a JPEG or PNG file in the grayscale or RGB color space.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• MetadataTooLargeError – The given metadata is too large. The maximum size is 1 MB of data when Base64 encoded.

• ImageTooLargeError – The given image is too large.

• TargetNameExistError – A target with the given name already exists.

• ProjectInactiveError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers. This has been seen to happen when the given name includes a bad character.

• TooManyRequestsError – Vuforia is rate limiting access.

async get_target_record(target_id: str) → TargetStatusAndRecord¶

Get a given target’s target record from the Target Management System.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record.

Parameters:

target_id – The ID of the target to get details of.

Returns:

Response details of a target from Vuforia.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async wait_for_target_processed(*, target_id: str, seconds_between_requests: float = 0.2, timeout_seconds: float = 300) → None¶

Wait up to five minutes (arbitrary) for a target to get past the processing stage.

Parameters:

• target_id – The ID of the target to wait for.

• seconds_between_requests – The number of seconds to wait between requests made while polling the target status. We wait 0.2 seconds by default, rather than less, than that to decrease the number of calls made to the API, to decrease the likelihood of hitting the request quota.

• timeout_seconds – The maximum number of seconds to wait for the target to be processed.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• TargetProcessingTimeoutError – The target remained in the processing stage for more than timeout_seconds seconds.

• UnknownTargetError – The given target ID does not match a target in the database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async list_targets() → list[str]¶

List target IDs.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#details-list.

Returns:

The IDs of all targets in the database.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async get_target_summary_report(target_id: str) → TargetSummaryReport¶

Get a summary report for a target.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.

Parameters:

target_id – The ID of the target to get a summary report for.

Returns:

Details of the target.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async get_database_summary_report() → DatabaseSummaryReport¶

Get a summary report for the database.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.

Returns:

Details of the database.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async request_database_reco_counts_report(*, year: int, month: Month) → RecoCountsReportRequest¶

Request a per-target recognition count report for the database.

Vuforia generates the report in the background, so the report is not available to download immediately. Use wait_for_reco_counts_report() to wait for it.

Parameters:

• year – The year to get recognition counts for.

• month – The month of the year to get recognition counts for. Vuforia accepts only the current month and the previous month. A month taken from a datetime.datetime needs wrapping, as in calendar.Month(value=now.month).

Returns:

The URL to download the report from, and the transaction ID of the request.

Raises:

• DatabaseIdNotSetError – No database_id was given to the client.

• AuthenticationFailureError – The secret key is not correct, or the client’s database_id is not the ID of the database which the client’s keys belong to.

• FailError – There was an error with the request. For example, the given year and month are not the current month or the previous month.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async download_reco_counts_report(*, presigned_url: str) → RecoCountsReport¶

Download a requested reco counts report.

The report’s URL is not part of the VWS API, so this request is not authorized with the client’s keys.

Parameters:

presigned_url – The URL of the report, as given by request_database_reco_counts_report().

Returns:

The downloaded report.

Raises:

• RecoCountsReportNotReadyError – Vuforia has not finished generating the report.

• RecoCountsReportDownloadError – The report could not be downloaded. For example, the report’s URL may have expired.

async wait_for_reco_counts_report(*, presigned_url: str, seconds_between_requests: float = 0.2, timeout_seconds: float = 300) → RecoCountsReport¶

Wait for a requested reco counts report to be generated, then download it.

Parameters:

• presigned_url – The URL of the report, as given by request_database_reco_counts_report().

• seconds_between_requests – The number of seconds to wait between requests made while polling the report’s URL.

• timeout_seconds – The maximum number of seconds to wait for the report to be generated.

Returns:

The downloaded report.

Raises:

• RecoCountsReportTimeoutError – The report was not generated within timeout_seconds seconds.

• RecoCountsReportDownloadError – The report could not be downloaded. For example, the report’s URL may have expired.

async delete_target(target_id: str) → None¶

Delete a given target.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#delete.

Parameters:

target_id – The ID of the target to delete.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• TargetStatusProcessingError – The given target is in the processing state.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async get_duplicate_targets(target_id: str) → list[str]¶

Get targets which may be considered duplicates of a given target.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#check.

Parameters:

target_id – The ID of the target to delete.

Returns:

The target IDs of duplicate targets.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• UnknownTargetError – The given target ID does not match a target in the database.

• ProjectInactiveError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

async update_target(*, target_id: str, name: str | None = None, width: float | None = None, image: BytesIO | BinaryIO | None = None, active_flag: bool | None = None, application_metadata: str | None = None) → None¶

Update a target in a Vuforia Web Services database.

See https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#update for parameter details.

Parameters:

• target_id – The ID of the target to update.

• name – The name of the target.

• width – The width of the target.

• image – The image of the target.

• active_flag – Whether or not the target is active for query.

• application_metadata –

  The application metadata of the target. This must be base64 encoded, for example by using:

  base64.b64encode('input_string').decode('ascii')
  

  Giving None will not change the application metadata.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• BadImageError – There is a problem with the given image. For example, it must be a JPEG or PNG file in the grayscale or RGB color space.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• MetadataTooLargeError – The given metadata is too large. The maximum size is 1 MB of data when Base64 encoded.

• ImageTooLargeError – The given image is too large.

• TargetNameExistError – A target with the given name already exists.

• ProjectInactiveError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

Async tools for interacting with the Vuforia Cloud Recognition Web APIs.

class vws.async_query.AsyncCloudRecoService(*, client_access_key: str, client_secret_key: str, base_vwq_url: str = 'https://cloudreco.vuforia.com', request_timeout_seconds: float | tuple[float, float] = 30.0, transport: AsyncTransport | None = None)¶

An async interface to the Vuforia Cloud Recognition Web APIs.

Parameters:

• client_access_key – A VWS client access key.

• client_secret_key – A VWS client secret key.

• base_vwq_url – The base URL for the VWQ API.

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The async HTTP transport to use for requests. Defaults to AsyncHTTPXTransport().

async aclose() → None¶

Close the underlying transport if it supports closing.

async query(*, image: BytesIO | BinaryIO, max_num_results: int = 1, include_target_data: CloudRecoIncludeTargetData = CloudRecoIncludeTargetData.TOP) → list[QueryResult]¶

Use the Vuforia Web Query API to make an Image Recognition Query.

See https://developer.vuforia.com/library/web-api/vuforia-query-web-api for parameter details.

Parameters:

• image – The image to make a query against.

• max_num_results – The maximum number of matching targets to be returned.

• include_target_data – Indicates if target_data records shall be returned for the matched targets. Accepted values are top (default value, only return target_data for top ranked match), none (return no target_data), all (for all matched targets).

Raises:

• AuthenticationFailureError – The client access key pair is not correct.

• MaxNumResultsOutOfRangeError – max_num_results is not within the range (1, 50).

• InactiveProjectError – The project is inactive.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• BadImageError – There is a problem with the given image. For example, it must be a JPEG or PNG file in the grayscale or RGB color space.

• RequestEntityTooLargeError – The given image is too large.

• ServerError – There is an error with Vuforia’s servers.

• CloudRecoError – Vuforia returned a client error without a recognized JSON body.

• json.JSONDecodeError – Vuforia returned a successful response with an invalid JSON body.

Returns:

An ordered list of target details of matching targets.

Async interface to the Vuforia VuMark Generation Web API.

class vws.async_vumark_service.AsyncVuMarkService(*, server_access_key: str, server_secret_key: str, base_vws_url: str = 'https://vws.vuforia.com', request_timeout_seconds: float | tuple[float, float] = 30.0, transport: AsyncTransport | None = None)¶

An async interface to the Vuforia VuMark Generation Web API.

Parameters:

• server_access_key – A VWS server access key.

• server_secret_key – A VWS server secret key.

• base_vws_url – The base URL for the VWS API.

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The async HTTP transport to use for requests. Defaults to AsyncHTTPXTransport().

async aclose() → None¶

Close the underlying transport if it supports closing.

async generate_vumark_instance(*, target_id: str, instance_id: str, accept: VuMarkAccept) → bytes¶

Generate a VuMark instance image.

See https://developer.vuforia.com/library/vuforia-engine/web-api/vumark-generation-web-api/ for parameter details.

Parameters:

• target_id – The ID of the VuMark target.

• instance_id – The instance ID to encode in the VuMark.

• accept – The image format to return.

Returns:

The VuMark instance image bytes.

Raises:

• AuthenticationFailureError – The secret key is not correct.

• AuthorizationFailedError – There was a general authentication problem.

• FailError – There was an error with the request. For example, the given access key does not match a known database.

• InvalidAcceptHeaderError – The Accept header value is not supported.

• InvalidInstanceIdError – The instance ID is invalid. For example, it may be empty.

• InvalidTargetTypeError – The target is not a VuMark template target.

• LicenseCheckFailedError – The license state and/or type does not allow this request.

• QuotaExceededError – No more instances can be created for the associated license.

• RequestTimeTooSkewedError – There is an error with the time sent to Vuforia.

• TargetStatusNotSuccessError – The target is not in the success state.

• UnknownTargetError – The given target ID does not match a target in the database.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

Interface to the Vuforia Model Target Web API.

class vws.model_target_service.ModelTargetService(*, client_id: str, client_secret: str, base_vws_url: str = 'https://vws.vuforia.com', request_timeout_seconds: float | tuple[float, float] = 30.0, transport: Transport | None = None)¶

An interface to the Vuforia Model Target Web API.

Parameters:

• client_id – A Model Target Web API OAuth2 client ID.

• client_secret – A Model Target Web API OAuth2 client secret.

• base_vws_url – The base URL for the VWS API, which also serves the Model Target Web API.

• request_timeout_seconds – The timeout for each HTTP request. This can be a float to set both the connect and read timeouts, or a (connect, read) tuple.

• transport – The HTTP transport to use for requests. Defaults to RequestsTransport().

get_access_token() → str¶

Get an OAuth2 access token for the Model Target Web API.

A token is requested only when the client has no token which is still valid, so this can be called before each request.

Returns:

A bearer token.

Raises:

ModelTargetOAuth2Error – Vuforia did not give an access token. For example, the given client ID and client secret may not match a set of Model Target Web API credentials.

make_request(*, method: str, data: bytes, request_path: str, extra_headers: dict[str, str] | None = None) → Response¶

Make an authenticated request to the Model Target Web API.

Parameters:

• method – The HTTP method which will be used in the request.

• data – The request body which will be used in the request.

• request_path – The path to the endpoint which will be used in the request.

• extra_headers – Additional headers to include in the request.

Returns:

The response to the request.

Raises:

• ModelTargetError – Vuforia returned an error.

• ServerError – There is an error with Vuforia’s servers.

• TooManyRequestsError – Vuforia is rate limiting access.

create_dataset(*, name: str, target_sdk: str, models: Sequence[ModelTargetModel], dataset_type: ModelTargetDatasetType) → str¶

Start generating a Model Target dataset.

Vuforia generates the dataset in the background, so it is not available to download immediately. Use wait_for_dataset_generated() to wait for it.

Parameters:

• name – The name of the dataset.

• target_sdk – The Vuforia Engine version to generate the dataset for.

• models – The models to generate the dataset from. A standard dataset takes exactly one model.

• dataset_type – Whether to create a standard or an advanced dataset.

Returns:

The UUID of the new dataset.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• ModelTargetValidationError – Vuforia rejected the request. For example, a model may give neither a CAD data URL nor a CAD data blob.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

get_dataset_status(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType) → ModelTargetDatasetStatusReport¶

Get the status of a Model Target dataset.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to get the status of.

Returns:

The status of the dataset.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

wait_for_dataset_generated(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType, seconds_between_requests: float = 0.2, timeout_seconds: float = 300) → ModelTargetDatasetStatusReport¶

Wait for Vuforia to finish generating a Model Target dataset.

A dataset which failed to generate is also finished, so the returned report may have a status of FAILED.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to wait for.

• seconds_between_requests – The number of seconds to wait between requests made while polling the dataset’s status.

• timeout_seconds – The maximum number of seconds to wait for the dataset to be generated.

Returns:

The status of the dataset once it is no longer processing.

Raises:

• ModelTargetDatasetTimeoutError – The dataset was not generated within timeout_seconds seconds.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

download_dataset(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType) → bytes¶

Download a generated Model Target dataset.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to download.

Returns:

The dataset, as the bytes of a zip file.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

• ModelTargetDatasetNotDoneError – Vuforia has not generated the dataset.

• ModelTargetOAuth2Error – Vuforia did not give an access token.

delete_dataset(*, dataset_uuid: str, dataset_type: ModelTargetDatasetType) → None¶

Delete a Model Target dataset.

Parameters:

• dataset_uuid – The UUID of the dataset, as given by create_dataset().

• dataset_type – The kind of dataset to delete.

Raises:

• ModelTargetAuthenticationError – The request was not authenticated.

• UnknownModelTargetDatasetError – No dataset of the given type matches the given UUID.

• ModelTargetOAuth2Error – Vuforia did not give an access token.