API Reference#

A library for Vuforia Web Services.

class vws.CloudRecoService(client_access_key: str, client_secret_key: str, base_vwq_url: str = 'https://cloudreco.vuforia.com')#

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.

query(image: 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://library.vuforia.com/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.VWS(server_access_key: str, server_secret_key: str, base_vws_url: str = 'https://vws.vuforia.com')#

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.

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

Add a target to a Vuforia Web Services database.

See https://library.vuforia.com/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:

  • AuthenticationFailure – The secret key is not correct.

  • BadImage – 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.

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

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

  • ImageTooLarge – The given image is too large.

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

  • ProjectInactive – The project is inactive.

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

  • OopsAnErrorOccurredPossiblyBadName – Vuforia returns an HTML page with the text “Oops, an error occurred”. This has been seen to happen when the given name includes a bad character.

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

  • TooManyRequests – 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://library.vuforia.com/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:

  • AuthenticationFailure – The secret key is not correct.

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

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

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

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

  • TooManyRequests – 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:

  • AuthenticationFailure – The secret key is not correct.

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

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

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

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

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

  • TooManyRequests – Vuforia is rate limiting access.

list_targets() → list[str]#

List target IDs.

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

Returns:

The IDs of all targets in the database.

Raises:

  • AuthenticationFailure – The secret key is not correct.

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

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

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

  • TooManyRequests – Vuforia is rate limiting access.

get_target_summary_report(target_id: str) → TargetSummaryReport#

Get a summary report for a target.

See https://library.vuforia.com/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:

  • AuthenticationFailure – The secret key is not correct.

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

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

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

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

  • TooManyRequests – Vuforia is rate limiting access.

get_database_summary_report() → DatabaseSummaryReport#

Get a summary report for the database.

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

Returns:

Details of the database.

Raises:

  • AuthenticationFailure – The secret key is not correct.

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

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

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

  • TooManyRequests – Vuforia is rate limiting access.

delete_target(target_id: str) → None#

Delete a given target.

See https://library.vuforia.com/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://library.vuforia.com/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: io.BytesIO | None = None, active_flag: bool | None = None, application_metadata: str | None = None) → None#

Add a target to a Vuforia Web Services database.

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

Parameters:

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

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

  • AuthenticationFailure – The secret key is not correct.

  • BadImage – 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.

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

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

  • ImageTooLarge – The given image is too large.

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

  • ProjectInactive – The project is inactive.

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

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

  • TooManyRequests – Vuforia is rate limiting access.

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://library.vuforia.com/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#
class vws.reports.TargetStatuses(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Constants representing VWS target statuses.

See the ‘status’ field in https://library.vuforia.com/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://library.vuforia.com/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#
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://library.vuforia.com/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://library.vuforia.com/web-api/vuforia-query-web-api.

target_id: str#
target_data: TargetData | None#
class vws.reports.TargetStatusAndRecord(status: TargetStatuses, target_record: TargetRecord)#

The target status and a target record.

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

status: TargetStatuses#
target_record: TargetRecord#

Tools for managing CloudRecoService.query’s include_target_data.

class vws.include_target_data.CloudRecoIncludeTargetData(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Options for the include_target_data parameter of CloudRecoService.query.

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