Skip to main content
Version: 3.3

class IModelPreloader

(Niantic.Lightship.AR.Utilities.Preloading.IModelPreloader)

Overview​

Interface for the ARDK class that pre-downloads necessary neural network model files for awareness features. If the files are not preloaded, they will take time to download when an AR session configured to use those features is run.

    class IModelPreloader: IDisposable {
    public:
        // methods
    
        virtual abstract PreloaderStatusCode DownloadModel(DepthMode depthMode) = 0;
        virtual abstract PreloaderStatusCode DownloadModel(SemanticsMode semanticsMode) = 0;
    
        virtual abstract PreloaderStatusCode RegisterModel(
            DepthMode depthMode,
            string filepath
        ) = 0;
    
        virtual abstract PreloaderStatusCode RegisterModel(
            SemanticsMode semanticsMode,
            string filepath
        ) = 0;
    
        virtual abstract PreloaderStatusCode CurrentProgress(
            DepthMode depthMode,
            out float progress
        ) = 0;
    
        virtual abstract PreloaderStatusCode CurrentProgress(
            SemanticsMode semanticsMode,
            out float progress
        ) = 0;
    
        virtual abstract bool ExistsInCache(DepthMode depthMode) = 0;
        virtual abstract bool ExistsInCache(SemanticsMode semanticsMode) = 0;
        virtual abstract bool ClearFromCache(DepthMode depthMode) = 0;
        virtual abstract bool ClearFromCache(SemanticsMode semanticsMode) = 0;
        virtual abstract void Dispose() = 0;
    };

Detailed Documentation​

Interface for the ARDK class that pre-downloads necessary neural network model files for awareness features. If the files are not preloaded, they will take time to download when an AR session configured to use those features is run.

Each awareness feature has one or more modes on a performance-to-quality curve, and each mode corresponds to a different model file. See Feature in Niantic.Lightship.AR.Utilities.Preloading.

Methods​

DownloadModel​

virtual abstract PreloaderStatusCode DownloadModel(DepthMode depthMode) = 0

Begins downloading the requested model file to the cache if not already present. The request status can be polled with CurrentProgress(DepthMode, out float) or ExistsInCache(DepthMode).

    Returns:

    Returns a PreloaderStatusCode indicating the initial status of the request. The final result of the request may be deferred due to asynchronous network operations, so if this request returns PreloaderStatusCode.Success or PreloaderStatusCode.RequestInProgress, the user should continue to query CurrentProgress(DepthMode, out float) every frame to confirm that the network request completes successfully.

DownloadModel​

virtual abstract PreloaderStatusCode DownloadModel(SemanticsMode semanticsMode) = 0

Begins downloading the requested model file to the cache if not already present. The request status can be polled with CurrentProgress(SemanticsMode, out float) or ExistsInCache(SemanticsMode).

    Returns:

    Returns a PreloaderStatusCode indicating the initial status of the request. The final result of the request may be deferred due to asynchronous network operations, so if this request returns PreloaderStatusCode.Success or PreloaderStatusCode.RequestInProgress, the user should continue to query CurrentProgress(SemanticsMode, out float) every frame to confirm that the network request completes successfully.

RegisterModel​

virtual abstract PreloaderStatusCode RegisterModel(
        DepthMode depthMode,
        string filepath
    ) = 0

Register a local neural network model file for a specific feature. This overrides Lightship's URI for the specified feature mode and remains in effect until Lightship is deinitialized. The file must be in a location accessible by the application and remain in place for the duration of the AR session.

    Returns:

    Returns a PreloaderStatusCode indicating the result of the request.

RegisterModel​

virtual abstract PreloaderStatusCode RegisterModel(
        SemanticsMode semanticsMode,
        string filepath
    ) = 0

Register a local neural network model file for a specific feature. This overrides Lightship's URI for the specified feature mode and remains in effect until Lightship is deinitialized. The file must be in a location accessible by the application and remain in place for the duration of the AR session.

    Returns:

    Returns a PreloaderStatusCode indicating the result of the request.

CurrentProgress​

virtual abstract PreloaderStatusCode CurrentProgress(
        DepthMode depthMode,
        out float progress
    ) = 0

Read the current status of a mode file request, if a request was previously made. The result of DownloadModel is asynchronous, so the caller must poll CurrentProgress(DepthMode, out float) for the status of the request to ensure that the HTTP request completed successfully.

    Parameters:

    progress - A value in the range of [0.0, 1.0] representing how much progress has been made downloading the model file of the specified feature mode. A progress of 1.0 means the file is present in the cache. The download progress value is server dependent and may not always support incremental progress updates.

    Returns:

    Returns a PreloaderStatusCode indicating the status of the request.

CurrentProgress​

virtual abstract PreloaderStatusCode CurrentProgress(
        SemanticsMode semanticsMode,
        out float progress
    ) = 0

Read the current status of a mode file request, if a request was previously made. The result of DownloadModel is asynchronous, so the caller must poll CurrentProgress(SemanticsMode, out float) for the status of the request to ensure that the HTTP request completed successfully.

    Parameters:

    progress - A value in the range of [0.0, 1.0] representing how much progress has been made downloading the model file of the specified feature mode. A progress of 1.0 means the file is present in the cache. The download progress value is server dependent and may not always support incremental progress updates.

    Returns:

    Returns a PreloaderStatusCode indicating the status of the request.

ExistsInCache​

virtual abstract bool ExistsInCache(DepthMode depthMode) = 0

Checks if a model associated with the specified DepthMode is present in the cache.

    Returns:

    True if the specified model was found in the application's cache.

ExistsInCache​

virtual abstract bool ExistsInCache(SemanticsMode semanticsMode) = 0

Checks if a model associated with the specified SemanticsMode is present in the cache.

    Returns:

    True if the specified model was found in the application's cache.

ClearFromCache​

virtual abstract bool ClearFromCache(DepthMode depthMode) = 0

Clears this model file from the application's cache. This function will fail if the download is currently in progress or if the file is not present in the cache. Calling this while the specified model is currently being loaded into a Lightship AR session is invalid and will result in undefined behavior.

    Returns:

    True if the specified feature was present in the application's cache and was successfully removed.

ClearFromCache​

virtual abstract bool ClearFromCache(SemanticsMode semanticsMode) = 0

Clears this model file from the application's cache. This function will fail if the download is currently in progress or if the file is not present in the cache. Calling this while the specified model is currently being loaded into a Lightship AR session is invalid and will result in undefined behavior.

    Returns:

    True if the specified feature was present in the application's cache and was successfully removed.

Dispose​

virtual abstract void Dispose() = 0

Dispose the handle to the native model preloader.