Asset Core SDK
The @sdk/asset-core
SDK provides a set of tools for managing and manipulating asset metadata within your application. It offers functionalities to move, update, and delete assets, as well as retrieve asset information and perform other asset-related operations.
Installation
To install this package, you need to have access to the private @sdk
npm scope.
To install the library, run the following command in your project directory:
npm install @sdk/asset-core
Asset Core Service
The AssetCoreService
class is the main entry point for interacting with the @sdk/asset-core
library.
To instantiate the AssetCoreService
, we provide a handy factory function that takes the necessary dependencies as arguments.
connectClient
: The Connect client instance to use for making API requests.config
: The configuratin object for the service.
import { assetCoreServiceFactory } from '@sdk/asset-core';
import connectClient from './my-connect-client';
import config from './my-config';
const assetCoreService = assetCoreServiceFactory(connectClient, config);
Once the service is instantiated, you can use it to interact with the asset metadata in your application.
The Asset
Type
Assets are a very complex concept in the HxDR Platform. They can represent a wide range of entities, from simple images to complex 3D models in different states of processing.
To help manage this complexity, the @sdk/asset-core
library provides an Asset
type that tries to condense all the complexity into a single type that can be used throughout your application
and interacted with to determine the state of an asset.
Interactions with the AssetCoreService
will often return or require an object of this Asset
type.
Lifecycle of an Asset
The lifecycle of an asset can be complex, with many different states and transitions. The following diagram illustrates the different states an asset can be in and the transitions between them.
The SDK provides a set of functions to determine the current state of an asset. These utilities will also narrow down the type from Asset
to a more specific type based on the current state of the asset so that it can provide
type safety.
isAssetComplete(asset: Asset)
: Returnstrue
if the asset is in theAssetComplete
state.isAssetProcessIncomplete(asset: Asset)
: Returnstrue
if the asset is in theAssetProcessIncomplete
state, currently processing.isAssetProcessFailed(asset: Asset)
: Returnstrue
if the asset is in theAssetProcessFailed
state.isAssetLocalUploadProgress(asset: Asset)
: Returnstrue
if the asset is in theAssetLocalUploadProgress
state, currently uploading.
AssetLocalUploadProgress
This means that the asset is currently being uploaded from the local machine to the HxDR Platform. The asset is not yet complete and should not be used in the application.
When the asset is in this state, the upload
field of the asset will contain the current upload progress.
AssetUploadIncomplete
This can mean two things:
- The asset was being uploaded, but the upload failed and the upload state is gone. This means the asset still is present in the system, but as the upload failed it is now in an unrecoverable state. It should only be deleted.
- The asset is currently uploaded from an external source, and the upload is not yet complete.
There is currently now way to distinguish between these two possibilities.
AssetProcessIncomplete
This means that the asset is currently being processed by the HxDR Platform. This is true even if parts of the asset are already available, like a Point Cloud could be successfully processed, but the Mesh is still being processed.
AssetProcessFailed
The asset has parts of it's processing that have failed. Some parts of an asset might still be available, but at least one part of the asset has failed processing.
AssetComplete
There are currently no running or failed processes on the asset.
Streamable/Renderable Artifacts
When the asset is uploaded and in processing or complete, it will have a set of streamable/renderable artifacts accessible in the field renderArtifacts
. These artifacts are the result of the processing of the asset and can be used to display the asset in the application.
Only if the processing of an artifact is complete and was sucessfull then the artifact will be available in the renderArtifacts
field.
Downloadable Artifacts
Similar to streamable/renderable artifacts, the asset will have a set of downloadable artifacts accessible in the field downloadArtifacts
. These artifacts are the result of the processing of the asset and can be used to download the asset in the application.
React
The @sdk/asset-core
library provides a set of React hooks to interact with the AssetCoreService
and the Asset
type in a React application.
To integrate with your React application, first, install the React-specific package:
npm install @sdk/asset-core-react react react-dom
Then, wrap your app with the AssetCoreProvider
to make AssetCoreService
accessible throughout your component tree:
import { AssetCoreProvider } from '@sdk/asset-core-react';
function App() {
return (
<AssetCoreProvider onNavigateToAssetDetail={id => router.push(`/assets/${id}`)}>
<Component />
</AssetCoreProvider>
);
}
Accessing the Asset Core Service
To access the AssetCoreService
in your components, use the useAssetCoreService
hook:
import AssetCoreService from '@sdk/asset-core';
import { useAssetCoreService } from '@sdk/asset-core-react';
function Component() {
const { assetCoreService } = useAssetCoreService<AssetCoreService>();
// Now you can use the asset core service in your component
}
Asset Core Service Operations
This is an abstraction on top of the AssetCoreService
that provides a set of operations that are already connected to the UI to display appropriate loading states, confirm dialogs, and error messages.
import { useAssetCoreOperations } from '@sdk/asset-core-react';
function Component() {
const { initiateDeleteAsset } = useAssetCoreOperations();
const handleDelete = (assetId: string) => {
// This will show a confirmation dialog before deleting the asset
initiateDeleteAsset(assetId);
};
}
The useAsset
Hook
The useAsset
hook provides access to the current asset and its state. It will automatically update the component when the asset changes.
import { useAsset } from '@sdk/asset-core-react';
function Component() {
const { asset, loading } = useAsset();
// Now you can use the asset in your component
}