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 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): Returns true if the asset is in the AssetComplete state.
• isAssetProcessIncomplete(asset: Asset): Returns true if the asset is in the AssetProcessIncomplete state, currently processing.
• isAssetProcessFailed(asset: Asset): Returns true if the asset is in the AssetProcessFailed state.
• isAssetLocalUploadProgress(asset: Asset): Returns true if the asset is in the AssetLocalUploadProgress 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
}