# 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](https://docs.omniverse.nvidia.com/services/latest/services/usd-search/overview.html).
## 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](https://openapi-generator.tech) 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 package directly using:
```sh
pip install usd-search-client --extra-index-url https://pypi.nvidia.com
```
Then import the package:
```python
import usd_search_client
```
## Getting Started
Please follow the [installation procedure](#installation--usage) and then run the following:
```python
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**](docs/AGSAssetGraphApi.md#get_dependencies_flat_dependency_graph_flat_get) | **GET** /dependency_graph/flat | Get Dependencies Flat
*AGSAssetGraphApi* | [**get_dependencies_graph_dependency_graph_graph_get**](docs/AGSAssetGraphApi.md#get_dependencies_graph_dependency_graph_graph_get) | **GET** /dependency_graph/graph | Get Dependencies Graph
*AGSAssetGraphApi* | [**get_dependencies_inverse_dependency_graph_inverse_flat_get**](docs/AGSAssetGraphApi.md#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**](docs/AGSAssetGraphApi.md#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**](docs/AGSSceneGraphApi.md#get_prims_asset_graph_usd_prims_get) | **GET** /asset_graph/usd/prims | Get Prims
*AGSSceneGraphApi* | [**scene_summary_asset_graph_usd_scene_summary_get**](docs/AGSSceneGraphApi.md#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**](docs/AGSSpatialGraphApi.md#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**](docs/AGSSpatialGraphApi.md#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**](docs/IndexingStatusApi.md#get_asset_status_info_indexing_asset_status_get) | **GET** /info/indexing/asset/status | Get Asset Status
*SearchApi* | [**search_post_v2_deepsearch_search_post**](docs/SearchApi.md#search_post_v2_deepsearch_search_post) | **POST** /search | Search Post
*SearchApi* | [**search_v2_deepsearch_search_get**](docs/SearchApi.md#search_v2_deepsearch_search_get) | **GET** /search | Search
## Documentation For Models
- [AXIS](docs/AXIS.md)
- [Asset](docs/Asset.md)
- [AssetGraph](docs/AssetGraph.md)
- [AssetGraph1](docs/AssetGraph1.md)
- [AssetRelationship](docs/AssetRelationship.md)
- [BackendStatusType](docs/BackendStatusType.md)
- [DeepSearchSearchRequest](docs/DeepSearchSearchRequest.md)
- [EdgeType](docs/EdgeType.md)
- [EdgeType1](docs/EdgeType1.md)
- [Empty](docs/Empty.md)
- [Event](docs/Event.md)
- [EventMapping](docs/EventMapping.md)
- [HTTPValidationError](docs/HTTPValidationError.md)
- [HashValue](docs/HashValue.md)
- [LocationInner](docs/LocationInner.md)
- [Metadata](docs/Metadata.md)
- [Mounted](docs/Mounted.md)
- [PathType](docs/PathType.md)
- [PluginInfo](docs/PluginInfo.md)
- [PluginItemStatus](docs/PluginItemStatus.md)
- [PluginStatusType](docs/PluginStatusType.md)
- [Prediction](docs/Prediction.md)
- [Prim](docs/Prim.md)
- [Prim1](docs/Prim1.md)
- [ProcessingTimestamp](docs/ProcessingTimestamp.md)
- [SceneSummaryResponse](docs/SceneSummaryResponse.md)
- [SearchMethod](docs/SearchMethod.md)
- [SearchResult](docs/SearchResult.md)
- [SpatialQueryResponseItem](docs/SpatialQueryResponseItem.md)
- [StatusResult](docs/StatusResult.md)
- [StorageBackendInfo](docs/StorageBackendInfo.md)
- [TransactionId](docs/TransactionId.md)
- [ValidationError](docs/ValidationError.md)
- [VerifyAccessRequest](docs/VerifyAccessRequest.md)
<a id="documentation-for-authorization"></a>
## Documentation For Authorization
Authentication schemes defined for the API:
<a id="HTTPBearer"></a>
### HTTPBearer
- **Type**: Bearer authentication
<a id="HTTPBasic"></a>
### HTTPBasic
- **Type**: HTTP basic authentication
<a id="APIKeyHeader"></a>
### APIKeyHeader
- **Type**: API key
- **API key parameter name**: x-api-key
- **Location**: HTTP header
Raw data
{
"_id": null,
"home_page": "https://github.com/NVIDIA-Omniverse/usdsearch-client",
"name": "usd-search-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "OpenAPI, USD Search, Asset Graph Search, OpenUSD, Omniverse",
"author": "NVIDIA",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# usd-search-client\n# USD Search API Overview\n**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. \n\nWith these production-ready microservices, developers can deploy USD Search API onto their own infrastructure. With USD Search API\u2019s 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.\n\nFor more information please refer to [USD Search API documentation](https://docs.omniverse.nvidia.com/services/latest/services/usd-search/overview.html).\n\n## Features\n- **Natural Language Searches:** - Utilize AI to search for images and USD-based 3D models using simple, descriptive language.\n- **Image Similarity Searches:** - Find images similar to a reference image through AI-driven image comparisons.\n- **Metadata Filtering:** - Filter search results by file name, file type, creation/modification dates, file size, and creator/modifier metadata.\n- **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.\n- **Multiple Storage Backend Support:** - Compatible with various storage backends, including AWS S3 buckets and Omniverse Nucleus server.\n- **Advanced File Name, Extension, and Path Filters:** - Use wildcards for broad or specific file name and extension searches.\n- **Date and Size Range Filtering:** - Specify assets created or modified within certain date ranges or file sizes larger or smaller than a designated threshold.\n- **User-based Filtering:** - Filter assets based on their creator or modifier, allowing for searches tailored to particular users' contributions.\n- **Embedding-based Similarity Threshold:** - Set a similarity threshold for more nuanced control over search results in embedding-based searches.\n- **Custom Search Paths and Scenes:** - Specify search locations within the storage backend or conduct searches within specific scenes for targeted results.\n- **Return Detailed Results:** - Option to include images, metadata, root prims, and predictions in the search results.\n\n# Asset Graph Search (AGS) API Overview\n**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.\n## Features\n- **Proximity Queries:** - Find objects within a specified bounding box or radius. - Results sorted by distance with options for vector alignment using a transformation matrix.\n- **USD Property Queries:** - Enables querying objects in a 3D scene using USD properties, such as finding all assets with a specific semantic label.\n- **Asset Dependency Searches:** - Identify all assets referenced in a scene \u2014 including USD references, material references, or textures. - Reverse search to find all scenes containing a particular asset.\n- **Combined Query Capabilities:** - Enable complex scenarios for enhanced scene understanding, manipulation, and generation.\n- **Integration with USD Search:** - Provides in-scene search functionality.\n\n\nThis Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:\n\n- API version: 1.0.0\n- Package version: 1.0.0\n- Generator version: 7.8.0\n- Build package: org.openapitools.codegen.languages.PythonClientCodegen\n\n## Requirements.\n\nPython 3.8+\n\n## Installation & Usage\n### pip install\n\nYou can install the package directly using:\n\n```sh\npip install usd-search-client --extra-index-url https://pypi.nvidia.com\n```\n\nThen import the package:\n```python\nimport usd_search_client\n```\n\n## Getting Started\n\nPlease follow the [installation procedure](#installation--usage) and then run the following:\n\n```python\nimport asyncio\n\nimport usd_search_client\nfrom usd_search_client.rest import ApiException\nfrom pprint import pprint\n\n# See configuration.py for a list of all supported configuration parameters.\nconfiguration = usd_search_client.Configuration(\n host = \"http://api.my-usd-search-instance.example.com\"\n)\n\n\n# The client may configure the authentication and authorization parameters\n# in accordance with the API server security policy.\n# Examples for each auth method are provided below, use the example that\n# satisfies your auth use case.\n\n# Configure API key authorization: APIKeyHeader\n\n# configuration.api_key['APIKeyHeader'] = os.environ[\"API_KEY\"]\n\n# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed\n# configuration.api_key_prefix['APIKeyHeader'] = 'Bearer'\n\n# Configure HTTP basic authorization: HTTPBasic\n# configuration = usd_search_client.Configuration(\n# username = os.environ[\"USERNAME\"],\n# password = os.environ[\"PASSWORD\"]\n# )\n\n# Configure Bearer authorization: HTTPBearer\n# configuration = usd_search_client.Configuration(\n# access_token = os.environ[\"BEARER_TOKEN\"]\n# )\n\nasync def call_search_api(api_client_config):\n # Enter a context with an instance of the API client\n async with usd_search_client.ApiClient(api_client_config) as api_client:\n # Create an instance of the API class\n api_instance = usd_search_client.AISearchApi(api_client)\n deep_search_search_request = usd_search_client.DeepSearchSearchRequest(description=\"box\")\n\n try:\n # Search Post\n api_response = await api_instance.search_post_v2_deepsearch_search_post(deep_search_search_request)\n print(\"The response of AISearchApi->search_post_v2_deepsearch_search_post:\\n\")\n pprint(api_response)\n except Exception as e:\n print(\"Exception when calling AISearchApi->search_post_v2_deepsearch_search_post: %s\\n\" % e)\n\nasyncio.run(call_search_api(configuration))\n```\n\n## Documentation for API Endpoints\n\nAll URIs are relative to *http://api.my-usd-search-instance.example.com*\n\nClass | Method | HTTP request | Description\n------------ | ------------- | ------------- | -------------\n*AGSAssetGraphApi* | [**get_dependencies_flat_dependency_graph_flat_get**](docs/AGSAssetGraphApi.md#get_dependencies_flat_dependency_graph_flat_get) | **GET** /dependency_graph/flat | Get Dependencies Flat\n*AGSAssetGraphApi* | [**get_dependencies_graph_dependency_graph_graph_get**](docs/AGSAssetGraphApi.md#get_dependencies_graph_dependency_graph_graph_get) | **GET** /dependency_graph/graph | Get Dependencies Graph\n*AGSAssetGraphApi* | [**get_dependencies_inverse_dependency_graph_inverse_flat_get**](docs/AGSAssetGraphApi.md#get_dependencies_inverse_dependency_graph_inverse_flat_get) | **GET** /dependency_graph/inverse/flat | Get Dependencies Inverse\n*AGSAssetGraphApi* | [**get_inverse_dependencies_graph_dependency_graph_inverse_graph_get**](docs/AGSAssetGraphApi.md#get_inverse_dependencies_graph_dependency_graph_inverse_graph_get) | **GET** /dependency_graph/inverse/graph | Get Inverse Dependencies Graph\n*AGSSceneGraphApi* | [**get_prims_asset_graph_usd_prims_get**](docs/AGSSceneGraphApi.md#get_prims_asset_graph_usd_prims_get) | **GET** /asset_graph/usd/prims | Get Prims\n*AGSSceneGraphApi* | [**scene_summary_asset_graph_usd_scene_summary_get**](docs/AGSSceneGraphApi.md#scene_summary_asset_graph_usd_scene_summary_get) | **GET** /asset_graph/usd/scene_summary/ | Scene Summary\n*AGSSpatialGraphApi* | [**get_prims_within_bounding_box_asset_graph_usd_prims_spatial_bbox_get**](docs/AGSSpatialGraphApi.md#get_prims_within_bounding_box_asset_graph_usd_prims_spatial_bbox_get) | **GET** /asset_graph/usd/prims/spatial_bbox | Get Prims Within Bounding Box\n*AGSSpatialGraphApi* | [**get_prims_within_radius_asset_graph_usd_prims_spatial_get**](docs/AGSSpatialGraphApi.md#get_prims_within_radius_asset_graph_usd_prims_spatial_get) | **GET** /asset_graph/usd/prims/spatial | Get Prims Within Radius\n*IndexingStatusApi* | [**get_asset_status_info_indexing_asset_status_get**](docs/IndexingStatusApi.md#get_asset_status_info_indexing_asset_status_get) | **GET** /info/indexing/asset/status | Get Asset Status\n*SearchApi* | [**search_post_v2_deepsearch_search_post**](docs/SearchApi.md#search_post_v2_deepsearch_search_post) | **POST** /search | Search Post\n*SearchApi* | [**search_v2_deepsearch_search_get**](docs/SearchApi.md#search_v2_deepsearch_search_get) | **GET** /search | Search\n\n\n## Documentation For Models\n\n - [AXIS](docs/AXIS.md)\n - [Asset](docs/Asset.md)\n - [AssetGraph](docs/AssetGraph.md)\n - [AssetGraph1](docs/AssetGraph1.md)\n - [AssetRelationship](docs/AssetRelationship.md)\n - [BackendStatusType](docs/BackendStatusType.md)\n - [DeepSearchSearchRequest](docs/DeepSearchSearchRequest.md)\n - [EdgeType](docs/EdgeType.md)\n - [EdgeType1](docs/EdgeType1.md)\n - [Empty](docs/Empty.md)\n - [Event](docs/Event.md)\n - [EventMapping](docs/EventMapping.md)\n - [HTTPValidationError](docs/HTTPValidationError.md)\n - [HashValue](docs/HashValue.md)\n - [LocationInner](docs/LocationInner.md)\n - [Metadata](docs/Metadata.md)\n - [Mounted](docs/Mounted.md)\n - [PathType](docs/PathType.md)\n - [PluginInfo](docs/PluginInfo.md)\n - [PluginItemStatus](docs/PluginItemStatus.md)\n - [PluginStatusType](docs/PluginStatusType.md)\n - [Prediction](docs/Prediction.md)\n - [Prim](docs/Prim.md)\n - [Prim1](docs/Prim1.md)\n - [ProcessingTimestamp](docs/ProcessingTimestamp.md)\n - [SceneSummaryResponse](docs/SceneSummaryResponse.md)\n - [SearchMethod](docs/SearchMethod.md)\n - [SearchResult](docs/SearchResult.md)\n - [SpatialQueryResponseItem](docs/SpatialQueryResponseItem.md)\n - [StatusResult](docs/StatusResult.md)\n - [StorageBackendInfo](docs/StorageBackendInfo.md)\n - [TransactionId](docs/TransactionId.md)\n - [ValidationError](docs/ValidationError.md)\n - [VerifyAccessRequest](docs/VerifyAccessRequest.md)\n\n\n<a id=\"documentation-for-authorization\"></a>\n## Documentation For Authorization\n\n\nAuthentication schemes defined for the API:\n<a id=\"HTTPBearer\"></a>\n### HTTPBearer\n\n- **Type**: Bearer authentication\n\n<a id=\"HTTPBasic\"></a>\n### HTTPBasic\n\n- **Type**: HTTP basic authentication\n\n<a id=\"APIKeyHeader\"></a>\n### APIKeyHeader\n\n- **Type**: API key\n- **API key parameter name**: x-api-key\n- **Location**: HTTP header\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "USD Search and Asset Graph Search APIs",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/NVIDIA-Omniverse/usdsearch-client",
"Repository": "https://github.com/NVIDIA-Omniverse/usdsearch-client"
},
"split_keywords": [
"openapi",
" usd search",
" asset graph search",
" openusd",
" omniverse"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3b79642735dd4b6db5af0dfef5aec8c3a7820b4829b85c10dbfabd5a60b6e8e2",
"md5": "416cfae14219bc6b962229145c7f70eb",
"sha256": "9eb3be24bc4ac794e2689e4277cd40b3f2a9c33e6aa34bd048a8349663b29ccc"
},
"downloads": -1,
"filename": "usd_search_client-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "416cfae14219bc6b962229145c7f70eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 194165,
"upload_time": "2024-11-28T07:36:01",
"upload_time_iso_8601": "2024-11-28T07:36:01.580296Z",
"url": "https://files.pythonhosted.org/packages/3b/79/642735dd4b6db5af0dfef5aec8c3a7820b4829b85c10dbfabd5a60b6e8e2/usd_search_client-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-28 07:36:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NVIDIA-Omniverse",
"github_project": "usdsearch-client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "usd-search-client"
}
JSON
