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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:

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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:

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:
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:

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:
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:
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:
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:
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:
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:

Async interface to the Vuforia Model Target Web API.

class vws.async_model_target_service.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:
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:
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:
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:
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:
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:

Structures for describing Model Target datasets to create.

See https://developer.vuforia.com/library/vuforia-engine/web-api/model-target-web-api/.

class vws.model_target_datasets.ModelTargetDatasetType(*values)

The kinds of Model Target dataset which Vuforia generates.

Standard and advanced datasets are separate resources, so a dataset created as one type is not visible to requests for the other type.

STANDARD = 'standard'
ADVANCED = 'advanced'
class vws.model_target_datasets.AutomaticColoring(*values)

Options for a model’s automaticColoring.

ALWAYS = 'always'
AUTO = 'auto'
NEVER = 'never'
class vws.model_target_datasets.CadDataFormat(*values)

Options for a model’s cadDataFormat.

DAE = 'DAE'
FBX = 'FBX'
GLB = 'GLB'
IGES = 'IGES'
OBJ = 'OBJ'
PVZ = 'PVZ'
STL = 'STL'
VRML = 'VRML'
ZIP = 'ZIP'
class vws.model_target_datasets.MotionHint(*values)

Options for a model’s motionHint.

ADAPTIVE = 'adaptive'
DYNAMIC = 'dynamic'
STATIC = 'static'
class vws.model_target_datasets.OptimizeTrackingFor(*values)

Options for a model’s optimizeTrackingFor.

AR_CONTROLLER = 'ar_controller'
DEFAULT = 'default'
LOW_FEATURE_OBJECTS = 'low_feature_objects'
class vws.model_target_datasets.RealisticAppearance(*values)

Options for a model’s realisticAppearance.

This is documented for advanced datasets only.

AUTO = 'auto'
FALSE = 'false'
TRUE = 'true'
class vws.model_target_datasets.Simplify(*values)

Options for a model’s simplify.

ALWAYS = 'always'
AUTO = 'auto'
NEVER = 'never'
class vws.model_target_datasets.TrackingMode(*values)

Options for a model’s trackingMode.

CAR = 'car'
DEFAULT = 'default'
SCAN = 'scan'
class vws.model_target_datasets.GuideViewPosition(*, rotation: Sequence[float], translation: Sequence[float])

The position of a guide view.

rotation: Sequence[float]
translation: Sequence[float]
class vws.model_target_datasets.ModelTargetView(*, name: str, guide_view_position: GuideViewPosition, states: Sequence[str] | None = None)

A guide view of a model.

name: str
guide_view_position: GuideViewPosition
states: Sequence[str] | None = None

The State-Based Model Target states which this view applies to.

Every given state must be named by the model’s state_based_configuration_json_string.

class vws.model_target_datasets.ModelTargetModel(*, name: str, cad_data_url: str | None = None, cad_data_blob: str | None = None, automatic_coloring: AutomaticColoring | None = None, cad_data_format: CadDataFormat | None = None, motion_hint: MotionHint | None = None, optimize_tracking_for: OptimizeTrackingFor | None = None, realistic_appearance: RealisticAppearance | None = None, simplify: Simplify | None = None, tracking_mode: TrackingMode | None = None, state_based_configuration_json_string: str | None = None, views: Sequence[ModelTargetView] | None = None)

A model to generate a Model Target dataset from.

One and only one of cad_data_url and cad_data_blob is required.

name: str
cad_data_url: str | None = None
cad_data_blob: str | None = None
automatic_coloring: AutomaticColoring | None = None
cad_data_format: CadDataFormat | None = None
motion_hint: MotionHint | None = None
optimize_tracking_for: OptimizeTrackingFor | None = None
realistic_appearance: RealisticAppearance | None = None

This is documented for advanced datasets only.

simplify: Simplify | None = None
tracking_mode: TrackingMode | None = None
state_based_configuration_json_string: str | None = None
views: Sequence[ModelTargetView] | None = None

Classes for representing Vuforia reports.

class vws.reports.DatabaseSummaryReport(*, active_images: int, current_month_recos: int, failed_images: int, inactive_images: int, name: str, previous_month_recos: int, processing_images: int, reco_threshold: int, request_quota: int, request_usage: int, target_quota: int, total_recos: int)

A database summary report.

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

active_images: int
current_month_recos: int
failed_images: int
inactive_images: int
name: str
previous_month_recos: int
processing_images: int
reco_threshold: int
request_quota: int
request_usage: int
target_quota: int
total_recos: int
classmethod from_response_dict(response_dict: dict[str, Any]) → Self

Construct from a VWS API response dict.

class vws.reports.TargetStatuses(*values)

Constants representing VWS target statuses.

See the ‘status’ field in https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record

PROCESSING = 'processing'
SUCCESS = 'success'
FAILED = 'failed'
class vws.reports.TargetSummaryReport(*, status: TargetStatuses, database_name: str, target_name: str, upload_date: date, active_flag: bool, tracking_rating: int, total_recos: int, current_month_recos: int, previous_month_recos: int)

A target summary report.

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

status: TargetStatuses
database_name: str
target_name: str
upload_date: date
active_flag: bool
tracking_rating: int
total_recos: int
current_month_recos: int
previous_month_recos: int
classmethod from_response_dict(response_dict: dict[str, Any]) → Self

Construct from a VWS API response dict.

class vws.reports.TargetRecord(*, target_id: str, active_flag: bool, name: str, width: float, tracking_rating: int, reco_rating: str)

A target record.

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

target_id: str
active_flag: bool
name: str
width: float
tracking_rating: int
reco_rating: str
class vws.reports.TargetData(*, name: str, application_metadata: str | None, target_timestamp: datetime)

The target data optionally included with a query match.

name: str
application_metadata: str | None
target_timestamp: datetime
class vws.reports.QueryResult(*, target_id: str, target_data: TargetData | None)

One query match result.

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

target_id: str
target_data: TargetData | None
classmethod from_response_dict(response_dict: dict[str, Any]) → Self

Construct from a VWS API query result item dict.

class vws.reports.TargetStatusAndRecord(*, status: TargetStatuses, target_record: TargetRecord)

The target status and a target record.

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

status: TargetStatuses
target_record: TargetRecord
classmethod from_response_dict(response_dict: dict[str, Any]) → Self

Construct from a VWS API response dict.

class vws.reports.RecoCountsReportRequest(*, transaction_id: str, presigned_url: str)

A requested database reco counts report.

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

transaction_id: str
presigned_url: str

The URL to download the report from.

Real Vuforia’s URLs expire just under seven days after the report is requested.

classmethod from_response_dict(response_dict: dict[str, Any]) → Self

Construct from a VWS API response dict.

class vws.reports.ModelTargetDatasetStatuses(*values)

Constants representing Model Target dataset generation statuses.

See the ‘status’ field of the dataset status response at https://developer.vuforia.com/library/vuforia-engine/web-api/model-target-web-api/.

PROCESSING = 'processing'
DONE = 'done'
FAILED = 'failed'
class vws.reports.ModelTargetGenerationDetail(*, code: str, message: str)

One detail of a Model Target dataset generation warning.

code: str
message: str
class vws.reports.ModelTargetGenerationError(*, code: str, message: str)

The reason a Model Target dataset failed to generate.

code: str
message: str
class vws.reports.ModelTargetGenerationWarning(*, code: str, message: str, target: str, details: Sequence[ModelTargetGenerationDetail])

A warning about a generated Model Target dataset.

A dataset with a warning is generated, and can be downloaded.

code: str
message: str
target: str
details: Sequence[ModelTargetGenerationDetail]
class vws.reports.ModelTargetDatasetStatusReport(*, status: ModelTargetDatasetStatuses, dataset_uuid: str, created_at: datetime, eta: datetime | None, completed_at: datetime | None, error: ModelTargetGenerationError | None, warning: ModelTargetGenerationWarning | None)

The status of a Model Target dataset.

See https://developer.vuforia.com/library/vuforia-engine/web-api/model-target-web-api/.

status: ModelTargetDatasetStatuses
dataset_uuid: str
created_at: datetime
eta: datetime | None

When Vuforia expects to finish generating the dataset.

This is given only while the dataset is processing.

completed_at: datetime | None

When Vuforia finished generating the dataset.

This is given only once the dataset is no longer processing.

error: ModelTargetGenerationError | None

Why the dataset failed to generate.

This is given only for a failed dataset.

warning: ModelTargetGenerationWarning | None

A warning about the generated dataset.

This is given only for a generated dataset which has a warning.

classmethod from_response_dict(response_dict: dict[str, Any]) → Self

Construct from a Model Target Web API response dict.

class vws.reports.RecoCount(*, target_id: str, reco_count: int)

The number of recognitions of one target in a reco counts report.

target_id: str
reco_count: int
class vws.reports.RecoCountsReport(*, reco_counts: Sequence[RecoCount], raw_csv: bytes)

A downloaded database reco counts report.

A report for a month with no recognitions has no reco_counts.

reco_counts: Sequence[RecoCount]
raw_csv: bytes

The downloaded CSV, before it was parsed.

Vuforia does not document the format of the report, so it may include columns which reco_counts does not expose.

classmethod from_csv(csv_bytes: bytes) → Self

Construct from the CSV content of a downloaded report.

Tools for managing CloudRecoService.query’s include_target_data.

class vws.include_target_data.CloudRecoIncludeTargetData(*values)

Options for the include_target_data parameter of CloudRecoService.query.

TOP = 'top'
NONE = 'none'
ALL = 'all'

Tools for managing VWS.generate_vumark_instance’s accept.

class vws.vumark_accept.VuMarkAccept(*values)

Options for the accept parameter of VWS.generate_vumark_instance.

PNG = 'image/png'
SVG = 'image/svg+xml'
PDF = 'application/pdf'

Responses for requests to VWS and VWQ.

class vws.response.Response(*, text: str, url: str, status_code: int, headers: dict[str, str], request_body: bytes | str | None, tell_position: int, content: bytes)

A response from a request.

text: str
url: str
status_code: int
headers: dict[str, str]
request_body: bytes | str | None
tell_position: int
content: bytes

HTTP transport implementations for VWS clients.

class vws.transports.Transport(*args, **kwargs)

Protocol for HTTP transports used by VWS clients.

A transport is a callable that makes an HTTP request and returns a Response.

close() → None

Close the transport and release resources.

class vws.transports.RequestsTransport

HTTP transport using the requests library.

This is the default transport.

close() → None

Close the transport.

This is a no-op for RequestsTransport as it does not hold persistent connections.

class vws.transports.HTTPXTransport

HTTP transport using the httpx library.

Use this transport for environments where httpx is preferred over requests. A single httpx.Client is reused across requests for connection pooling.

Create an HTTPXTransport.

close() → None

Close the underlying httpx.Client.

class vws.transports.AsyncTransport(*args, **kwargs)

Protocol for async HTTP transports used by VWS clients.

An async transport is a callable that makes an HTTP request and returns a Response.

async aclose() → None

Close the transport and release resources.

class vws.transports.AsyncHTTPXTransport

Async HTTP transport using the httpx library.

This is the default transport for async VWS clients. A single httpx.AsyncClient is reused across requests for connection pooling.

Create an AsyncHTTPXTransport.

async aclose() → None

Close the underlying httpx.AsyncClient.