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 configuration 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

An asset is a very generic concept in HxDR: it can represent generic files, but also files that are processed into artifacts, of which some could be represented in the 3D viewer of the application. The following diagram illustrates the different states an asset can be in and the transitions between them.

The SDK provides a set of type guards to determine the current state of an asset. For each of the below types, there exists a type guard that can narrow the Asset type to that more specific variant, e.g.

if (AssetCore.isAssetRenderable(asset)) {
  // do something with asset, now there is guaranteed to be at least one renderable artifact
}

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.

AssetProcessGeneric

This means that the asset is fully uploaded to the platform, but it is not processable, meaning no artifacts will ever come out of it. This is used to represent generic assets such as PDFs, images, audio files, etc.

AssetProcessPending

This means that the asset is fully uploaded to the platform and can be processed, but processing has not started yet.

AssetProcessNoRenderables

From this point on, processing has happened on the asset, but there is no renderable artifact yet.

AssetProcessBusy

This means that the asset is currently being processed by the HxDR Platform. There are no renderable artifacts yet.

AssetProcessFailed

All processing for renderable artifacts that has happened on the asset has failed. There may still be non-renderable artifacts in a processing or completed state, though.

AssetRenderable

There is guaranteed to be at least one fully processed renderable artifact. From this point, the asset can be opened in the 3D viewer of the application, although there could be other (renderable) artifacts that have failed or are still being processed.

Artifacts

Any of the asset types that are considered "Processable" (i.e. AssetProcessPending, AssetProcessNoRenderables, AssetProcessBusy, AssetProcessFailed and AssetRenderable) have an artifacts property that contain AssetArtifact objects. There are various subtypes of AssetArtifact, with accompanying type guards.

Downloadable Artifacts

In the current iteration of this library, there exist downloadable artifacts that are not downloadable through the UI but downloadable through third-party applications. Artifacts that are downloadable through the UI live in a different property (see Downloadable Artifacts), any other downloadable artifact lives here. These can be determined through the isDownloadableAssetArtifact type guard.

Processed Artifacts

These are artifacts that have a processing pipeline associated with them. These artifacts have a 'status' field that determines the processing status of that artifact. These can be determined through the isProcessedAssetArtifact type guard.

Renderable Artifacts

These are processed artifacts that specifically resolve to something that's renderable in the 3D viewer of the application. These can be determined through the isRenderableAssetArtifact type guard.

There is even more specificity when a renderable asset is 'DONE': there exists a specific subtype CompleteRenderableAssetArtifact and accompanying type guard isCompleteRenderableAssetArtifact. This subtype has an additional field address that contains the data needed to render this specific artifact (such as the endpoint from which to load the data).

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
}