API docs by Redocly

USD Search and Asset Graph Search APIs (1.0.0)

Download OpenAPI specification:Download

USD Search API Overview

USD Search API is a collection of cloud-native microservices that enable developers, creators, and workflow specialists to efficiently search through vast collections of OpenUSD data, images, and other assets using natural language or image-based inputs. With these production-ready microservices, developers can deploy USD Search API onto their own infrastructure. With USD Search API's artificial intelligence (AI) features, you can quickly locate untagged and unstructured 3D data and digital assets, saving time navigating unstructured, untagged 3D data. USD Search API is capable of searching and indexing 3D asset databases, as well as navigating complex 3D scenes to perform spatial searches, without requiring manual tagging of assets.

Features

  • Natural Language Searches: - Utilize AI to search for images and USD-based 3D models using simple, descriptive language.
  • Image Similarity Searches: - Find images similar to a reference image through AI-driven image comparisons.
  • Metadata Filtering: - Filter search results by file name, file type, creation/modification dates, file size, and creator/modifier metadata.
  • USD Content Filtering with Asset Graph Search: - When used with the Asset Graph Search, search capabilities are expanded to include filtering based on USD properties and object dimensions.
  • Multiple Storage Backend Support: - Compatible with various storage backends, including AWS S3 buckets and Omniverse Nucleus server.
  • Advanced File Name, Extension, and Path Filters: - Use wildcards for broad or specific file name and extension searches.
  • Date and Size Range Filtering: - Specify assets created or modified within certain date ranges or file sizes larger or smaller than a designated threshold.
  • User-based Filtering: - Filter assets based on their creator or modifier, allowing for searches tailored to particular users' contributions.
  • Embedding-based Similarity Threshold: - Set a similarity threshold for more nuanced control over search results in embedding-based searches.
  • Custom Search Paths and Scenes: - Specify search locations within the storage backend or conduct searches within specific scenes for targeted results.
  • Return Detailed Results: - Option to include images, metadata, root prims, and predictions in the search results.

Asset Graph Search (AGS) API Overview

Asset Graph Search (AGS) provides advanced querying capabilities for assets and USD trees indexed in a graph database. It supports proximity queries based on coordinates or prims to find objects within specified areas or radii, sorted by distance, and includes transformation options for vector alignment. The API also offers dependency and reverse dependency searches, helping to identify all assets referenced in a scene or scenes containing a particular asset, which can optimize scene loading and track dependency changes. By combining different query types, the AGS API enables complex scenarios for scene understanding, manipulation, and generation. Integrated with USD Search it provides in-scene search functionality.

Features

  • Proximity Queries: - Find objects within a specified bounding box or radius. - Results sorted by distance with options for vector alignment using a transformation matrix.
  • USD Property Queries: - Enables querying objects in a 3D scene using USD properties, such as finding all assets with a specific semantic label.
  • Asset Dependency Searches: - Identify all assets referenced in a scene — including USD references, material references, or textures. - Reverse search to find all scenes containing a particular asset.
  • Combined Query Capabilities: - Enable complex scenarios for enhanced scene understanding, manipulation, and generation.
  • Integration with USD Search: - Provides in-scene search functionality.

Search

USD Search API search endpoint. All supported search parameters are available as query parameters.

Search endpoint enables comprehensive searches across images (e.g., .jpg, .png) and USD-based 3D models within various storage backends (Nucleus, S3, etc.). It enables users to use natural language, image similarity, and precise metadata criteria (file name, type, date, size, creator, etc.) to locate relevant content efficiently. Furthermore, when integrated with the Asset Graph Search service, USD Search extends its capabilities to include searches based on USD properties and spatial dimensions of 3D model bounding boxes, enhancing the ability to find assets that meet specific requirements.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
description
string (Description) <= 1024 characters
Default: ""
Examples:
  • description=box - Example search for 'box'
  • description=pallet - Example search for 'pallet'
  • description=red rusty barrel - Example search for 'red rusty barrel'

Conduct text-based searches powered by AI

image_similarity_search
Array of strings (Image Similarity Search)
Examples:
  • - No image similarity search
  • image_similarity_search=iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mP8z8BQz0AEYBxVSF+FABJADveWkH6oAAAAAElFTkSuQmCC - Base64 encoded image example
  • image_similarity_search=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mP8z8BQz0AEYBxVSF+FABJADveWkH6oAAAAAElFTkSuQmCC - Base64 encoded image with format prefix example
  • image_similarity_search=s3://bucket-name/Project/asset1.usd - Storage backend URL example

Perform similarity searches based on a list of images

file_name
string (File Name)
Default: ""
Examples:
  • file_name=robot.usd - Example to find files matching 'robot.usd'
  • file_name=*scene* - Example to find files partially matching 'scene'

Filter results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

exclude_file_name
string (Exclude File Name)
Default: ""
Examples:
  • exclude_file_name=draft* - Example to exclude files with 'draft' prefix
  • exclude_file_name=*temp* - Example to exclude files with 'temp' in their names

Exclude results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

file_extension_include
string (File Extension Include)
Default: ""
Examples:
  • file_extension_include=usd - Example to filter for '.usd' files
  • file_extension_include=usd* - Example to filter for all types of USD files
  • file_extension_include=jpg - Example to filter for '.jpg' files
  • file_extension_include=jpg,png,gif - Example to filter for image files

Filter results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

file_extension_exclude
string (File Extension Exclude)
Default: ""
Examples:
  • file_extension_exclude=jpg - Example to exclude '.jpg' files
  • file_extension_exclude=jpg,png,gif - Example to exclude image files
  • file_extension_exclude=mdl - Example to exclude '.mdl' files

Exclude results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

created_after
string (Created After) \d{4}-\d{2}-\d{2}
Default: ""
Examples:
  • created_after=2023-01-01 - Example to filter assets created after '2023-01-01'
  • created_after=2023-06-01 - Example to filter assets created after '2023-06-01'

Filter results to only include assets created after a specified date

created_before
string (Created Before) \d{4}-\d{2}-\d{2}
Default: ""
Examples:
  • created_before=2023-01-01 - Example to filter assets created before '2023-01-01'
  • created_before=2023-06-01 - Example to filter assets created before '2023-06-01'

Filter results to only include assets created before a specified date

modified_after
string (Modified After) \d{4}-\d{2}-\d{2}
Default: ""
Examples:
  • modified_after=2023-02-01 - Example to filter assets modified after '2023-02-01'
  • modified_after=2023-07-01 - Example to filter assets modified after '2023-07-01'

Filter results to only include assets modified after a specified date

modified_before
string (Modified Before) \d{4}-\d{2}-\d{2}
Default: ""
Examples:
  • modified_before=2023-02-01 - Example to filter assets modified before '2023-02-01'
  • modified_before=2023-07-01 - Example to filter assets modified before '2023-07-01'

Filter results to only include assets modified before a specified date

file_size_greater_than
string (File Size Greater Than) \d+[KMGT]B
Default: ""
Examples:
  • file_size_greater_than=5MB - Example to filter files larger than 5MB
  • file_size_greater_than=10MB - Example to filter files larger than 10MB

Filter results to only include files larger than a specific size

file_size_less_than
string (File Size Less Than) \d+[KMGT]B
Default: ""
Examples:
  • file_size_less_than=1GB - Example to filter files smaller than 1GB
  • file_size_less_than=500MB - Example to filter files smaller than 500MB

Filter results to only include files smaller than a specific size

created_by
string (Created By)
Default: ""

Filter results to only include assets created by a specific user. In case AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

exclude_created_by
string (Exclude Created By)
Default: ""
Examples:
  • exclude_created_by=alex - Example to exclude assets created by 'Alex'
  • exclude_created_by=jordan - Example to exclude assets created by 'Jordan'

Exclude assets created by a specific user from the results

modified_by
string (Modified By)
Default: ""

Filter results to only include assets modified by a specific user. In the case, when AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

exclude_modified_by
string (Exclude Modified By)
Default: ""
Examples:
  • exclude_modified_by=Chris - Example to exclude assets modified by 'Chris'
  • exclude_modified_by=Pat - Example to exclude assets modified by 'Pat'

Exclude assets modified by a specific user from the results

similarity_threshold
number (Similarity Threshold) [ 0 .. 2 ]
Examples:
  • similarity_threshold=0 - Example similarity threshold set to 0
  • similarity_threshold=0.7 - Example similarity threshold set to 0.7

Set the similarity threshold for embedding-based searches. This functionality allows filterring duplicates and returning only those results that are different from each other. Assets are considered to be duplicates if the cosine distance betwen the embeddings a smaller than the similarity_threshold value, which could be in the [0, 2] range.

cutoff_threshold
number (Cutoff Threshold) >= 0
Examples:
  • cutoff_threshold=0 - Example cutoff threshold set to 0
  • cutoff_threshold=0.7 - Example cutoff threshold set to 0.7

Set the cutoff threshold for embedding-based searches

search_path
string (Search Path)
Default: ""
Examples:
  • search_path=/Projects - Example to specify search location under '/Projects'
  • search_path=/Archives/2021 - Example to specify search location in '/Archives/2021'

Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

exclude_search_path
string (Exclude Search Path)
Default: ""
Examples:
  • exclude_search_path=/Projects - Example to specify that '/Projects' is excluded
  • exclude_search_path=*/Archives/2021* - Example to specify that any path with this: '*/Archives/2021*' needs to be excluded

Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

search_in_scene
string (Search In Scene)
Default: ""
Examples:
  • search_in_scene=s3://bucket-name/Projects/scene1.usd - Example scene URL stored on an S3 bucket
  • search_in_scene=omniverse://example.org/scene2.usd - Example scene URL stored on an Omniverse Nucleus server

Conduct the search within a specific scene. Provide the full URL for the asset including the storage backend URL prefix.

filter_by_properties
string (Filter By Properties)
Default: ""
Examples:
  • filter_by_properties=color=red,size=S - Example filter by 'color=red' and 'size=S'
  • filter_by_properties=material=plastic,weight=light - Example filter by 'material=plastic' and 'weight=light'

Filter assets by USD attributes where at least one root prim matches (note: only supported for a subset of attributes indexed). Format: attribute1=abc,attribute2=456

min_bbox_x
number (Min Bbox X) >= 0

Filter by minimum X axis dimension of the asset's bounding box

min_bbox_y
number (Min Bbox Y) >= 0

Filter by minimum Y axis dimension of the asset's bounding box

min_bbox_z
number (Min Bbox Z) >= 0

Filter by minimum Z axis dimension of the asset's bounding box

max_bbox_x
number (Max Bbox X) > 0

Filter by maximum X axis dimension of the asset's bounding box

max_bbox_y
number (Max Bbox Y) > 0

Filter by maximum Y axis dimension of the asset's bounding box

max_bbox_z
number (Max Bbox Z) > 0

Filter by maximum Z axis dimension of the asset's bounding box

return_images
boolean (Return Images)
Default: false

Return images if set to True

return_metadata
boolean (Return Metadata)
Default: false

Return metadata if set to True

return_root_prims
boolean (Return Root Prims)
Default: false

Return root prims if set to True

return_default_prims
boolean (Return Default Prims)
Default: false

Return default prims if set to True

return_predictions
boolean (Return Predictions)
Default: false

Return predictions if set to True

return_in_scene_instances_prims
boolean (Return In Scene Instances Prims)
Default: false

[in-scene search only] Return prims of instances of objects found in the scene

embedding_knn_search_method
string (SearchMethod)
Enum: "exact" "approximate"

Search method, approximate should be faster but is less accurate. Default is exact

limit
integer (Limit) ( 0 .. 10000 ]

Set the maximum number of results to return from the search, default is 32

vision_metadata
string (Vision Metadata)

Uses a keyword match query on metadata fields that were generated using Vision Language Models

return_vision_generated_metadata
boolean (Return Vision Generated Metadata)
Default: false

Returns the metadata fields that were generated using Vision Language Models

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search Post

USD Search API search endpoint. All supported search parameters are available as body parameters.

Search endpoint enables comprehensive searches across images (e.g., .jpg, .png) and USD-based 3D models within various storage backends (Nucleus, S3, etc.). It enables users to use natural language, image similarity, and precise metadata criteria (file name, type, date, size, creator, etc.) to locate relevant content efficiently. Furthermore, when integrated with the Asset Graph Search service, USD Search extends its capabilities to include searches based on USD properties and spatial dimensions of 3D model bounding boxes, enhancing the ability to find assets that meet specific requirements.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
Request Body schema: application/json
required
description
string (Description)

Conduct text-based searches powered by AI

image_similarity_search
Array of strings (Image Similarity Search)

Perform similarity searches based on images

file_name
string (File Name)

Filter results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

exclude_file_name
string (Exclude File Name)

Exclude results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

file_extension_include
string (File Extension Include)

Filter results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

file_extension_exclude
string (File Extension Exclude)

Exclude results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

created_after
string (Created After) \d{4}-\d{2}-\d{2}

Filter results to only include assets created after a specified date

created_before
string (Created Before) \d{4}-\d{2}-\d{2}

Filter results to only include assets created before a specified date

modified_after
string (Modified After) \d{4}-\d{2}-\d{2}

Filter results to only include assets modified after a specified date

modified_before
string (Modified Before) \d{4}-\d{2}-\d{2}

Filter results to only include assets modified before a specified date

file_size_greater_than
string (File Size Greater Than) \d+[KMGT]B

Filter results to only include files larger than a specific size

file_size_less_than
string (File Size Less Than) \d+[KMGT]B

Filter results to only include files smaller than a specific size

created_by
string (Created By)

Filter results to only include assets created by a specific user. In case AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

exclude_created_by
string (Exclude Created By)

Exclude assets created by a specific user from the results

modified_by
string (Modified By)

Filter results to only include assets modified by a specific user. In the case, when AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

exclude_modified_by
string (Exclude Modified By)

Exclude assets modified by a specific user from the results

similarity_threshold
number (Similarity Threshold) [ 0 .. 2 ]

Set the similarity threshold for embedding-based searches. This functionality allows filtering duplicates and returning only those results that are different from each other. Assets are considered to be duplicates if the cosine distance betwen the embeddings a smaller than the similarity_threshold value, which could be in the [0, 2] range.

cutoff_threshold
number (Cutoff Threshold) >= 0

Set the cutoff threshold for embedding-based searches

search_path
string (Search Path)

Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

exclude_search_path
string (Exclude Search Path)

Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

search_in_scene
string (Search In Scene)

Conduct the search within a specific scene. Provide the full URL for the asset including the storage backend URL prefix.

filter_by_properties
string (Filter By Properties)

Filter assets by USD attributes where at least one root prim matches (note: only supported for a subset of attributes indexed). Format: attribute1=abc,attribute2=456

min_bbox_x
number (Min Bbox X) >= 0

Filter by minimum X axis dimension of the asset's bounding box

min_bbox_y
number (Min Bbox Y) >= 0

Filter by minimum Y axis dimension of the asset's bounding box

min_bbox_z
number (Min Bbox Z) >= 0

Filter by minimum Z axis dimension of the asset's bounding box

max_bbox_x
number (Max Bbox X) >= 0

Filter by maximum X axis dimension of the asset's bounding box

max_bbox_y
number (Max Bbox Y) >= 0

Filter by maximum Y axis dimension of the asset's bounding box

max_bbox_z
number (Max Bbox Z) >= 0

Filter by maximum Z axis dimension of the asset's bounding box

return_images
boolean (Return Images)
Default: false

Return images if set to True

return_metadata
boolean (Return Metadata)
Default: false

Return metadata if set to True

return_root_prims
boolean (Return Root Prims)
Default: false

Return root prims if set to True

return_predictions
boolean (Return Predictions)
Default: false

Return predictions if set to True

return_in_scene_instances_prims
boolean (Return In Scene Instances Prims)
Default: false

[in-scene search only] Return prims of instances of objects found in the scene

embedding_knn_search_method
string (SearchMethod)
Enum: "exact" "approximate"

Search method, approximate should be faster but is less accurate. Default is exact

limit
integer (Limit) ( 0 .. 10000 ]

Set the maximum number of results to return from the search, default is 32

vision_metadata
string (Vision Metadata)

Uses a keyword match query on metadata fields that were generated using Vision Language Models

return_vision_generated_metadata
boolean (Return Vision Generated Metadata)
Default: false

Returns the metadata fields that were generated using Vision Language Models

Responses

Request samples

Content type
application/json
{
  • "description": "pallet",
  • "return_metadata": true,
  • "limit": 16
}

Response samples

Content type
application/json
[
  • {
    }
]

AGS Spatial Graph

Spatial graph queries APIs.

Get Prims Within Radius

Perform a spatial search within a scene to retrieve prims from a USD scene based on their proximity to a reference prim center_prim_usd_path or specific coordinates [center_x, center_y, center_z] within a specified radius.

Note: You must specify either center_prim_usd_path or the coordinates [center_x, center_y, center_z].

Returns prim objects including: attributes, dimensions, and min, max, midpoint coordinates of the bounding box, distance from the query center, vector from the query center to the prim midpoint.

If searching using center_prim_usd_path the center prim at center_prim_usd_path is included in the results (unless excluded by filters used).

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
scene_url
required
string (Scene Url)

URL of the scene to search.

radius
required
number (Radius)

Radius of the proximity query

center_prim_usd_path
string (Center Prim Usd Path)

USD path of the reference Prim. (Returned in results unless excluded by filters)

center_x
number (Center X)

X coordinate of the query center.

center_y
number (Center Y)

Y coordinate of the query center.

center_z
number (Center Z)

Z coordinate of the query center.

transformation_matrix
string (Transformation Matrix)
Default: "1,0,0;0,1,0;0,0,1"

Transformation matrix for the vector space. By default does not apply any transformation.

limit
integer (Limit) > 0
Default: 1000

Page size

Array of Prim Type (strings) or Prim Type (string) or Prim Type (null) (Prim Type)
Examples:
  • - Any prim type
  • prim_type=Xform - Xform prim type
  • prim_type=Xform&prim_type=Mesh - Xform and Mesh prim types

Retrieve prims of the specified types. Can provide either a single type or a list of types.

Usd Path Prefix (string) or Usd Path Prefix (null) (Usd Path Prefix)
Examples:
  • - Any USD path
  • usd_path_prefix=/Root - Root prim
  • usd_path_prefix=/Root/Car - /Root/Car

Retrieve prims with USD paths that begin with this prefix (i.e., the children of the prim at the specified path).

Properties Filter (string) or Properties Filter (null) (Properties Filter)
Examples:
  • - Any attribute
  • properties_filter=class=lamp - Prims labeled class=lamp

Filter prims based on USD attributes (note: only a subset of attributes configured in the indexing service is available). Format: attribute1=abc,attribute2=456

Min Bbox Dimension X (number) or Min Bbox Dimension X (null) (Min Bbox Dimension X)

Minimum bounding box X dimension

Min Bbox Dimension Y (number) or Min Bbox Dimension Y (null) (Min Bbox Dimension Y)

Minimum bounding box Y dimension

Min Bbox Dimension Z (number) or Min Bbox Dimension Z (null) (Min Bbox Dimension Z)

Minimum bounding box Z dimension

Max Bbox Dimension X (number) or Max Bbox Dimension X (null) (Max Bbox Dimension X)
Default: 4e+38

Max bounding box X dimension

Max Bbox Dimension Y (number) or Max Bbox Dimension Y (null) (Max Bbox Dimension Y)
Default: 4e+38

Max bounding box Y dimension

Max Bbox Dimension Z (number) or Max Bbox Dimension Z (null) (Max Bbox Dimension Z)
Default: 4e+38

Max bounding box Z dimension

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Prims Within Bounding Box

Perform a spatial search within a scene to retrieve prims from a USD scene that fall within a specified bounding box. The bounding box is defined by two points: [min_bbox_x, min_bbox_y, min_bbox_z] and [max_bbox_x, max_bbox_y, max_bbox_z].

A prim is considered to be within the bounding box if its bounding box midpoint falls within the specified query bounding box.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
scene_url
required
string (Scene Url)

Retrieve prims from the scene at specified URL.

min_bbox_x
required
number (Min Bbox X)

Query bounding box minimum X

min_bbox_y
required
number (Min Bbox Y)

Query bounding box minimum Y

min_bbox_z
required
number (Min Bbox Z)

Query bounding box minimum Z

max_bbox_x
required
number (Max Bbox X)

Query bounding box maximum X

max_bbox_y
required
number (Max Bbox Y)

Query bounding box maximum Y

max_bbox_z
required
number (Max Bbox Z)

Query bounding box maximum Z

limit
integer (Limit) > 0
Default: 1000

Page size

Array of Prim Type (strings) or Prim Type (string) or Prim Type (null) (Prim Type)
Examples:
  • - Any prim type
  • prim_type=Xform - Xform prim type
  • prim_type=Xform&prim_type=Mesh - Xform and Mesh prim types

Retrieve prims of the specified types. Can provide either a single type or a list of types.

Usd Path Prefix (string) or Usd Path Prefix (null) (Usd Path Prefix)
Examples:
  • - Any USD path
  • usd_path_prefix=/Root - Root prim
  • usd_path_prefix=/Root/Car - /Root/Car

Retrieve prims with USD paths that begin with this prefix (i.e., the children of the prim at the specified path).

Properties Filter (string) or Properties Filter (null) (Properties Filter)
Examples:
  • - Any attribute
  • properties_filter=class=lamp - Prims labeled class=lamp

Filter prims based on USD attributes (note: only a subset of attributes configured in the indexing service is available). Format: attribute1=abc,attribute2=456

Min Bbox Dimension X (number) or Min Bbox Dimension X (null) (Min Bbox Dimension X)

Minimum bounding box X dimension

Min Bbox Dimension Y (number) or Min Bbox Dimension Y (null) (Min Bbox Dimension Y)

Minimum bounding box Y dimension

Min Bbox Dimension Z (number) or Min Bbox Dimension Z (null) (Min Bbox Dimension Z)

Minimum bounding box Z dimension

Max Bbox Dimension X (number) or Max Bbox Dimension X (null) (Max Bbox Dimension X)
Default: 4e+38

Max bounding box X dimension

Max Bbox Dimension Y (number) or Max Bbox Dimension Y (null) (Max Bbox Dimension Y)
Default: 4e+38

Max bounding box Y dimension

Max Bbox Dimension Z (number) or Max Bbox Dimension Z (null) (Max Bbox Dimension Z)
Default: 4e+38

Max bounding box Z dimension

Responses

Response samples

Content type
application/json
[
  • {
    }
]

AGS Scene Graph

Scene graph queries APIs.

Get Prims

Retrieve prims from a USD scene.

This API can be used for scene understanding, returns all objects in a scene together with their locations and dimensions.

NOTE: Calling without any parameters will return ALL prims. scene_url must be provided to fetch prims from the specified scene.

A globally unique prim id consists of (scene_url, usd_path) tuple. usd_path is unique only within a single scene. To retrieve prims from a specified scene, scene_url must be set. To retrieve a single prim from a specified scene, provide both scene_url and usd_path.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
scene_url
string (Scene Url)

Retrieve prims from the scene at specified URL.

Array of Usd Path (strings) or Usd Path (string) (Usd Path)
Examples:
  • - Any USD path
  • usd_path=/Root - Root prim
  • usd_path=Path1&usd_path=Path2&usd_path=Path3 - Multiple USD paths

Retrieve prims from the specified USD paths. Can provide either a single path or a list of paths.

root_prim
boolean (Root Prim)

Retrieve root prims. Note: combined with default_prim returns both root and default prims.

default_prim
boolean (Default Prim)

Retrieve default prims. Note: combined with root_prim returns both root and default prims.

source_asset_url
string (Source Asset Url)

Filter prims based on their source asset URL, i.e. the asset they have a reference to

limit
integer (Limit) > 0
Default: 1000

Page size

Array of Prim Type (strings) or Prim Type (string) or Prim Type (null) (Prim Type)
Examples:
  • - Any prim type
  • prim_type=Xform - Xform prim type
  • prim_type=Xform&prim_type=Mesh - Xform and Mesh prim types

Retrieve prims of the specified types. Can provide either a single type or a list of types.

Usd Path Prefix (string) or Usd Path Prefix (null) (Usd Path Prefix)
Examples:
  • - Any USD path
  • usd_path_prefix=/Root - Root prim
  • usd_path_prefix=/Root/Car - /Root/Car

Retrieve prims with USD paths that begin with this prefix (i.e., the children of the prim at the specified path).

Properties Filter (string) or Properties Filter (null) (Properties Filter)
Examples:
  • - Any attribute
  • properties_filter=class=lamp - Prims labeled class=lamp

Filter prims based on USD attributes (note: only a subset of attributes configured in the indexing service is available). Format: attribute1=abc,attribute2=456

Min Bbox Dimension X (number) or Min Bbox Dimension X (null) (Min Bbox Dimension X)

Minimum bounding box X dimension

Min Bbox Dimension Y (number) or Min Bbox Dimension Y (null) (Min Bbox Dimension Y)

Minimum bounding box Y dimension

Min Bbox Dimension Z (number) or Min Bbox Dimension Z (null) (Min Bbox Dimension Z)

Minimum bounding box Z dimension

Max Bbox Dimension X (number) or Max Bbox Dimension X (null) (Max Bbox Dimension X)

Max bounding box X dimension

Max Bbox Dimension Y (number) or Max Bbox Dimension Y (null) (Max Bbox Dimension Y)

Max bounding box Y dimension

Max Bbox Dimension Z (number) or Max Bbox Dimension Z (null) (Max Bbox Dimension Z)

Max bounding box Z dimension

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Scene Summary

Retrieve summary info about a USD scene.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
scene_url
required
string (Scene Url)

Scene summary.

Responses

Response samples

Content type
application/json
{
  • "scene_url": "string",
  • "scene_mpu": 0,
  • "scene_up_axis": "X",
  • "n_prims": 0,
  • "prim_types": {
    },
  • "unique_property_keys": {
    },
  • "unique_properties": {
    },
  • "referenced_assets": {
    },
  • "default_prim": {
    }
}

AGS Asset Graph

Asset graph/dependencies graph queries APIs.

Get Dependencies Graph

Get a graph of dependencies (unique files) for the specified asset.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
root_node_url
required
string (Root Node Url)

URL of the asset

max_level
integer (Max Level) > 0

Max level of dependency tree traversal (by default unlimited)

limit
integer (Limit) > 0
Default: 1000

Page size

Responses

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "edges": [
    ]
}

Get Dependencies Flat

Get a flat list of dependencies (unique files) for the specified asset.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
root_node_url
required
string (Root Node Url)

URL of the asset

max_level
integer (Max Level) > 0

Max level of dependency tree traversal (by default unlimited)

limit
integer (Limit) > 0
Default: 1000

Page size

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Dependencies Inverse

Get a flat list of all assets (unique files) that depend on the specified asset.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
root_node_url
required
string (Root Node Url)

URL of the asset

max_level
integer (Max Level) > 0

Max level of dependency tree traversal (by default unlimited)

limit
integer (Limit) > 0
Default: 1000

Page size

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Inverse Dependencies Graph

Get a graph of all assets (unique files) that depend on the specified asset.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
root_node_url
required
string (Root Node Url)

URL of the asset

max_level
integer (Max Level) > 0

Max level of dependency tree traversal (by default unlimited)

limit
integer (Limit) > 0
Default: 1000

Page size

Responses

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "edges": [
    ]
}

Indexing Status

Indexing pipeline status APIs.

Get Asset Status

For each URL the service checks caches of all plugins that support processing this asset and reports the following information:

  • indexing_status [not_found / in_sync / out_of_sync ] - this parameter checks the difference between cached value of asset hash and the actual (up-to-date) asset hash from the storage backend.
    • if these two values match - then the asset is considered to be up-to-date, in other words in_sync
    • otherwise, the final version of the asset has not be processed yet.
    • The not_found status is assigned in case the asset has never been processed.
  • plugin_status_history - is a list of last statuses that were assigned to the asset, while it was being processed. Each item of this list has the following structure:
    • status [ok / processing / failed_retries_exhausted / other string] - shows whether the asset was
      • ok - successfully processed
      • processing - processing for the asset has started
      • failed_retries_exhausted - processing of the asset failed and reached the retry limit
      • any other string - indicates that that processing has failed with this message.
    • processing_timestamp - the moment when the status was assigned
    • exception - optional exception explanation

The service could additionally report asset metadata from the storage backend if return_asset_metadata flag is set to True.

query Parameters
url
required
string (Url)

Asset URL for which processing status needs to be retrieved

return_asset_metadata
boolean (Return Asset Metadata)
Default: false

Return metadata for the asset if set to True

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "plugins_statuses": {
    },
  • "storage_backend_info": {
    }
}