usd-search-client

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.

For more information please refer to USD Search API documentation.

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.

This Python package is automatically generated by the OpenAPI Generator project:

• API version: 1.0.0
• Package version: 1.0.0
• Generator version: 7.8.0
• Build package: org.openapitools.codegen.languages.PythonClientCodegen

Requirements.

Python 3.8+

Installation & Usage

pip install

You can install the latest package from source as follows:

pip install git+https://github.com/NVIDIA-Omniverse/usdsearch-client

Then import the package:

import usd_search_client

Getting Started

Please follow the installation procedure and then run the following:

import asyncio

import usd_search_client
from usd_search_client.rest import ApiException
from pprint import pprint

# See configuration.py for a list of all supported configuration parameters.
configuration = usd_search_client.Configuration(
    host = "http://api.my-usd-search-instance.example.com"
)


# The client may configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: APIKeyHeader

# configuration.api_key['APIKeyHeader'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['APIKeyHeader'] = 'Bearer'

# Configure HTTP basic authorization: HTTPBasic
# configuration = usd_search_client.Configuration(
#     username = os.environ["USERNAME"],
#     password = os.environ["PASSWORD"]
# )

# Configure Bearer authorization: HTTPBearer
# configuration = usd_search_client.Configuration(
#     access_token = os.environ["BEARER_TOKEN"]
# )

async def call_search_api(api_client_config):
    # Enter a context with an instance of the API client
    async with usd_search_client.ApiClient(api_client_config) as api_client:
        # Create an instance of the API class
        api_instance = usd_search_client.AISearchApi(api_client)
        deep_search_search_request = usd_search_client.DeepSearchSearchRequest(description="box")

        try:
            # Search Post
            api_response = await api_instance.search_post_v2_deepsearch_search_post(deep_search_search_request)
            print("The response of AISearchApi->search_post_v2_deepsearch_search_post:\n")
            pprint(api_response)
        except Exception as e:
            print("Exception when calling AISearchApi->search_post_v2_deepsearch_search_post: %s\n" % e)

asyncio.run(call_search_api(configuration))

Documentation for API Endpoints

All URIs are relative to http://api.my-usd-search-instance.example.com

Class	Method	HTTP request	Description
AGSAssetGraphApi	get_dependencies_flat_dependency_graph_flat_get	GET /dependency_graph/flat	Get Dependencies Flat
AGSAssetGraphApi	get_dependencies_graph_dependency_graph_graph_get	GET /dependency_graph/graph	Get Dependencies Graph
AGSAssetGraphApi	get_dependencies_inverse_dependency_graph_inverse_flat_get	GET /dependency_graph/inverse/flat	Get Dependencies Inverse
AGSAssetGraphApi	get_inverse_dependencies_graph_dependency_graph_inverse_graph_get	GET /dependency_graph/inverse/graph	Get Inverse Dependencies Graph
AGSSceneGraphApi	get_prims_asset_graph_usd_prims_get	GET /asset_graph/usd/prims	Get Prims
AGSSceneGraphApi	scene_summary_asset_graph_usd_scene_summary_get	GET /asset_graph/usd/scene_summary/	Scene Summary
AGSSpatialGraphApi	get_prims_within_bounding_box_asset_graph_usd_prims_spatial_bbox_get	GET /asset_graph/usd/prims/spatial_bbox	Get Prims Within Bounding Box
AGSSpatialGraphApi	get_prims_within_radius_asset_graph_usd_prims_spatial_get	GET /asset_graph/usd/prims/spatial	Get Prims Within Radius
IndexingStatusApi	get_asset_status_info_indexing_asset_status_get	GET /info/indexing/asset/status	Get Asset Status
SearchApi	search_post_v2_deepsearch_search_post	POST /search	Search Post
SearchApi	search_v2_deepsearch_search_get	GET /search	Search

Documentation For Models

• AXIS
• Asset
• AssetGraph
• AssetGraph1
• AssetRelationship
• BackendStatusType
• DeepSearchSearchRequest
• EdgeType
• EdgeType1
• Empty
• Event
• EventMapping
• HTTPValidationError
• HashValue
• LocationInner
• Metadata
• Mounted
• PathType
• PluginInfo
• PluginItemStatus
• PluginStatusType
• Prediction
• Prim
• Prim1
• ProcessingTimestamp
• SceneSummaryResponse
• SearchMethod
• SearchResult
• SpatialQueryResponseItem
• StatusResult
• StorageBackendInfo
• TransactionId
• ValidationError
• VerifyAccessRequest

Documentation For Authorization

Authentication schemes defined for the API:

HTTPBearer

• Type: Bearer authentication

HTTPBasic

• Type: HTTP basic authentication

APIKeyHeader

• Type: API key
• API key parameter name: x-api-key
• Location: HTTP header