VIEWAR API

The VIEWAR API is supposed to work with the VIEWAR SDK. For more information about VIEWAR, visit our developer portal at developer.viewar.com, our website.

For more information on the API, visit our API Reference.

Installation

We recommend installing the VIEWAR API via the VIEWAR CLI. To create a new app you need @viewar/cli package (https://www.npmjs.com/package/@viewar/cli).

Usage

The VIEWAR API needs to be initialized only once. This is done with the asynchronous init method.

import viewarApi from '@viewar/api';

await viewarApi.init({ appId: 'com.viewar.sdk' });

After the initialization the user has access to all the functionalities of the VIEWAR API, e.g. setting up ARKit tracking:

// Check if tracker is available.
const tracker = viewarApi.trackers.ARKit;
if (tracker) {
  // Activate the augmented reality camera and the tracking and wait for tracking.
  await viewarApi.cameras.arCamera.activate();

  await new Promise(function (resolve) {
    tracker.on('trackingTargetStatusChanged', resolve);
    tracker.activate();
  });
} else {
  // Activate the perspective camera if no tracker available..
  await viewarApi.cameras.perspectiveCamera.activate();
}

How to insert a sample model:

// Get the model id 20 from the model repository.
const sheep = await viewarApi.modelManager.fetchModelFromRepository('20');

// Create instance of the model at 0/0/0 with a uniform scaling of 2.
const instance = await viewarApi.sceneManager.insertModel(sheep, {
  pose: {
    position: {
      x: 0,
      y: 0,
      z: 0,
    },
    scale: {
      x: 2,
      y: 2,
      z: 2,
    },
  },
});

Changelog

[1.60.1]

Fixed

• Fixed type definitions

[1.60.0]

Added

• New call getNearestWaypoint.
• TSDoc for interface.
• File system interface viewarApi.fileSystem for emscripten.

[1.59.2]

Fixed

• Crash during WebAssembly initialization

Added

• New parameter advancedCollision for model insertion to enable BVH tree for intersection testing.

[1.59.1]

• Fix WebAssembly version.

[1.59.0]

• Support new core version 12.x.x.

[1.58.0]

• Fix 'saveCustomFile' and 'readCustomFile' calls on Android by spitting large files into chunks.

[1.57.2]

• Fix prepareMaterial mock.

[1.57.1]

• Fixes for panorama stage in emscripten and mock.

[1.57.0]

• Add deviceManufacturer to appConfig.

[1.56.0]

• Fix coreInterface.emit on emscripten platform.

[1.55.0]

• Avoid double core calls if state has not changed for camera.activate(), appUtils.pauseRenderLoop() and appUtils.resumeRenderLoop().
• Add coreInterface call setAuthenticationData.

[1.54.0]

Added

• New call validations: registerScreenspaceUpdates, unregisterScreenspaceUpdates.

Fixed

• emscriptenAdapter now correctly dispatches own exceptions to coreInterface
• Added a few missing typings to CoreInterfaceNotification

[1.53.1]

Fixed

• Fixed the arguments of core-interface call setGridCameraPose.

[1.53.0]

Added

• Completed list of core calls (type CoreInterfaceMethod).
• Added list of core notifications (type CoreInterfaceNotification).

[1.52.0]

Added

• New call validations: getGPSData, getSceneCoordinatesForLatLng, setGridCameraPose, freeze frame related calls.

Fixed

• Updated call validation for setAuthenticationData.

[1.51.0]

Added

• New call validations: getIntersections, registerVoiceCommand, unregisterVoiceCommand.

Fixed

• Backwards compatibility for getIntersections with core changes.

[1.50.9]

Fixed

• Allow non-UTF-8 strings for textToSpeech core calls.

[1.50.8]

Fixed

• Fix JSON Type
• Remove enum CoreInterfaceMethod. Instead, CoreInterfaceMethod is exported as type with all valid methods for coreInterface.call.

[1.50.0]

Added

• New call validations: findPath

• Added enum CoreInterfaceMethod and type CoreInterfaceMethodType for coreInterface calls. If a call method is missing, you can pass it by typing its name as any. For example:

// Deprecated but still working:
await viewarApi.coreInterface.call('enableCameraTouchForExperienceStage');

// New preferred way:
import { CoreInterfaceMethod } from '@viewar/api';

await viewarApi.coreInterface.call(
  CoreInterfaceMethod.ENABLE_CAMERA_TOUCH_FOR_EXPERIENCE_STAGE
);

[1.49.0]

Added

• New call validations: getAuthenticationData and setAuthenticationData.

[1.48.0]

Added

• New call validations: storePersistentData, loadPersistentData, toggleFlashlight, nativeShare.

[1.47.0]

Added

• Validation of nativeShare call.

Changed

• Use api.viewar.com in mock mode instead of dev2.viewar.com.

[1.46.1]

Fixed

• Workaround for core bug VCS3414: Prepare all model materials, even if overwritten with surfaceMaterials.

[1.46.0]

Added

• Added support for core v12.x.x.

[1.45.3]

Fixed

• Remove null values before validating call parameters.

[1.45.2]

Fixed

• Fix crashes with invalid utf-16 call parameters.

[1.45.1]

Fixed

• Fix insertModels call definition.

[1.45.0]

Added

• Core call schema validation with core-interface-definition repo as git submodule.

[1.44.2]

Fixed

• Fixed package setup problem where npm install @viewar/api didn't work.

[1.44.1]

Fixed

• Fixed CI: automated docs creation.

[1.44.0]

Added

• Introduced appUtils.lowPowerMode and corresponding events to detect if the device is in low power mode.

[1.42.4]

Fixed

• Disabled setJSWindowSize update events to core since it causes crashes.

[1.42.3]

Fixed

• Removed unnecessary log.

[1.42.2]

Added

• Log console.log messages also to server if enabled.
• Added appUtils.downloadFile() for emscripten.

[1.42.1]

Fixed

• Make sure WebAssembly is compiled when using emscripten.

[1.42.0]

Added

• Send window dimension changes to core.

[1.41.0]

Fixed

• Make sure web core loads constantly.

[1.40.4]

Fixed

• Handle inertia in api.perspectiveCamera.setPose.

[1.40.3]

Fixed

• Added inertia to api.perspectiveCamera.setPose arguments.

[1.40.2]

Fixed

• Avoid doing camera pose update calls for non-active cameras.

[1.40.1]

Fixed

• Correctly sync pose for panoramaCamera with core.

[1.40.0]

Changed

• Renamed panoramaCamera's internal name.

[1.39.0]

Added

• Allow different serverUrl in init parameters.

Fixed

• Correctly fetch appConfig.bundleInfo in web version.

[1.38.0]

Changed

• Upgraded code & dependencies to node v16.

[1.37.0]

Added

• New camera panoramaCamera.

[1.36.2]

Fixed

• Undo JSONType changes.

[1.36.2]

Changed

• Improved typings for JSONType.

[1.36.1]

Changed

• Improved type definitions.

[1.36.0]

Added

• Added licensing information to api.appConfig.license.

[1.35.1]

Added

• Added instance.hasChangeableProperties.

Fixed

• Fix mock mode for old apps with hash URL content.

[1.34.4]

Fixed

• Improved sceneManager.setSceneState performance.

[1.34.3]

Fixed

• Fixed sceneManager.sceneTree log output.

[1.34.2]

Fixed

• Fixed storage.local.delete method.

[1.34.1]

Fixed

• Fix surfaceMaterials in model insertion.

[1.34.0]

Changed

• Moved to new core result format for call findPath.

[1.33.0]

Added

• Added core support for surfaceMaterials in model insertion.

[1.32.1]

Fixed

• Fix removeNavigationData call and emit new event sceneStateUpdateDone after sceneManager.setSceneState has finished.

[1.32.0]

Added

• Add mocked addNavigationData and removeNavigationData calls.

[1.31.0]

Added

• Added optional parameter shutdown to appUtils.closeApp().

[1.30.1]

Fixed

• Avoid concurrency issues when setting scene state.

[1.30.0]

Added

• Added support for appclips usage.

[1.29.0]

Added

• Added support for core controlled AR labels.

[1.28.0]

Changed

• Log also pending core calls to history.
• Renamed config flag to log core history to console from logCoreCalls to logCoreHistory.

Added

• Added config flag disableCoreHistory.

[1.27.5]

Fixed

• Correctly check for invalid configurations.

[1.27.4]

Fixed

• Fixed deletion of configurable instances.

[1.27.3]

Changed

• Change internal CI configuration.

[1.27.0]

Added

• Added config flag debugConfigurations.

[1.26.1]

Added

• Log app id and version to console on startup.

Fixed

• Fixed storage.local.remove() functionality.

[1.26.0]

Added

• Added support for async core call addNavigationData.

[1.25.0]

Added

• Add server logging logger.logToServer.

[1.24.0]

Added

• Added beacon handling to Vuforia tracker (trackers.Vuforia.rangedBeacons).
• Added event rangedBeaconsChanged to Vuforia tracker.

[1.23.0]

Added

• Added appConfig.bundleInfo.

Fixed

• http incorrectly returned a failed result with coui:// protocol.
• Correctly recognize touches while waiting for debugger to be attached.

[1.22.0]

Added

• Use app specific local storage.

[1.21.2]

Fixed

• Fix scene state update (removing nodes).

[1.21.1]

Fixed

• Correctly clean up plugin when removing a scene state model instance.
• Fix update for scene state models.

[1.21.0]

Added

• Improvements for scene state model type.

Fixed

• Don't throw exception if null or undefined is passed as argument into appUtils.getSecureUrl.

[1.20.0]

Added

• Added EasyAR tracker support.

Fixed

• Fixed insertion poses for mock mode.

[1.19.0]

Added

• Enable getExternalParams and externalCommand when running in an iframe with @viewar/webview.

[1.18.1]

Added

• Add realWorldPlanes to simulateTouchRay result.

Fixed

• Fix setSceneState comparison between undefined and false
• Improve type definitions for ContainerInsertionParams

[1.18.0]

Added

• Add flag meshInstance to model insertion params for improved rendering performance.
• Inject custom CSS in mock mode.
• Log emits to coreInterface.history.

Changed

• Improved mock behavior for: bulk insertion, core version, set tracking targets.

[1.17.0]

Added

• Add customUI to appConfig.

Changed

• Renamed viewar-api to @viewar/api;

[1.16.2]

Fixed

• Don't call applyMaterialToSurfaces with empty arguments.

[1.16.1]

Fixed

• Use only one core call to set multiple surface materials.

[1.16.0]

Added

• Added target.data for tracking targets.

[1.15.1]

Fixed

• Correctly log core events to coreInterface.history.

[1.15.0]

Added

• Added model.price information from tree.

[1.14.2]

Fixed

• Don't throw exception if using modelManager.fetchModelFromRepository with invalid model id.

[1.14.1]

Added

• Throw error if tracker is activated without arCamera being active.

[1.14.0]

Added

• Added mock calls requestPermissions and queryPermissions.

[1.13.0]

Fixed

• Fix touches for core versions >= 11.83.0.

[1.12.1]

Fixed

• Fix error while fetching models from repository via model manager.

[1.12.0]

Added

• Don't only consider the first snapping point for configuration snapping.

[1.11.4]

Changed

• Emit transferBegin and transferEnd from model manager.
• Cache model description after fetching.

[1.11.3]

Changed

• Add "exitFullscreen" to list of ignored errors for DOM exception logging.

[1.11.2]

Changed

• Allow setting the authentication manager's token from outside.

[1.11.1]

Changed

• Remove previous cloud projects if user token has changed.

[1.11.0]

Added

• Set grouping correctly in the core after node.setParent().

Changed

• Improved scene mutex behavior.

[1.10.0]

Added

• Check for delimiter '@' in storage and use http or https connections for storage.
• Added Visualix tracking provider support.

[1.9.2]

Fixed

• Consider meta tags for all model type instances for getSceneState.

[1.9.1]

Fixed

• Correctly round floats in scene sync.

[1.9.0]

Added

• Add mesh scan methods to ARKit tracker.

[1.8.0]

Added

• Add meshes to ARKit tracker.

Fixed

• Fixed error logger with non-existing method.
• Correctly load floor wall dummy model from model tree.
• Don't download room related models if room manager is not initialized in downloadAll.
• Fixed type definitions for SceneNode, Category and RoomManager.

[1.7.0]

Added

• Added MediaPipe tracking provider support.

[1.6.1]

Added

• Added IndoorAtlas tracking provider support.
• Added NavVis tracking provider support.

Fixed

• Fixed node removal after calling clear scene.

[1.6.0]

Added

• Added instance plugins.

[1.5.0]

Added

• Added support for scene state models.
• Improved mock call for pose updates.

[1.4.2]

Fixed

• Added missing methods to plugin models.

[1.4.1]

Fixed

• Plugin system parameters and ViewarModelPlugin class.

[1.4.0]

Added

• Added plugin system to register model plugins (e.g. for intelligent graphics scenes).
• New method getFloorPerimeter for roomManager.

[1.3.3]

Fixed

• Fixed bug in emitter when unregistering from a non-registered event.
• Throw more detailed connection error.

[1.3.2]

Fixed

• Fixed reference model insertion.

[1.3.1]

Fixed

• Removed uint8 conversion for emscripten (viewar-api@no-uint8-conversion).

[1.3.0]

Added

• Expose active freeze frame in AR camera.

[1.2.0]

Added

• Allow model trees with mixed children and model content.
• Improved error output for invalid range properties.

[1.1.1]

Fixed

• Insert configuration container grouped.

[1.1.0]

Added

• Add partial getting and setting of scene state.

[1.0.0]

• Release version 1.0.0.

[0.58.0]

Added

• Add 'meta' property to SceneNodes

[0.57.0]

Added

• Add WebAssembly support.

[0.56.6]

Fixed

• Fix scene node's setInteraction method for scaling.

[0.56.5]

Fixed

• Fix modelManager's downloadAll.

[0.56.4]

Fixed

• Fix surfaceMaterial with bulk insertion in setSceneState.

[0.56.3]

Fixed

• Fix interaction update with setSceneState.

[0.56.2]

Fixed

• Further improve setSceneState performance with bulk updating of node visibilities.

[0.56.1]

Fixed

• Improve setSceneState performance.

[0.56.0]

Added

• Added EighthWallTracker.
• Improve setSceneState performance when using surfaceMaterials.
• Tracking provider emits notification on newly learned qr code.

[0.55.2]

Fixed

• Correctly parse data in modelManager.fetchCategoryFromRepository.

[0.55.1]

Fixed

• Do not set low texture quality if platform is Emscripten.

Added

• Moved changelog to README.

[0.55.0]

Added

• Use bulk insertion when setting a scene state.

[0.54.0]

Added

• Don't automatically initialize roomManager models.

Fixed

• Correctly set tracking target types for new QR codes.

[0.53.0]

Added

• Added sceneManager.insertModels for (faster) bulk insertion of models.

Fixed

• Only create container for image targets if handling is 'object'.

[0.52.0]

Added

• Added Infsoft tracker.

[0.51.1]

Fixed

• saveProjectedCameraImage is now an async call.

[0.51.0]

Added

• Add load and save feature map functionality to SixDegrees.

[0.50.1]

Fixed

• Fixed material property switch.

[0.50.0]

Added

• Introduce container types 'normal', 'stationary' and 'tracked'. Introduce boolean flag 'grouped' instead of old 'grouped' or 'ungrouped' type.

[0.49.0]

Added

• Add container for image targets to scene.

[0.48.1]

Added

• Added exception if invalid property values are set.

[0.48.0]

Added

• Integration of Quuppa tracker.

[0.47.1]

Fixed

• Overwrite existing category when fetching category from repository.

[0.47.0]

Added

• Added ability to use a (offline) proxy server for mock mode (set 'mockProxy' in init's ApiConfig parameter).

Fixed

• Fixed type definitions for ModelInstance properties.

[0.46.2]

Fixed

• Fixed insertion info compilation.

[0.46.1]

Changed

• Improved robustness of sceneManager's setSceneState.

[0.46.0]

Added

• Added advanced error output for model insertion.
• Added bulk insertion call 'insertModels'.

[0.45.0]

Added

• Added GPS tracking provider.

[0.44.0]

Added

• Added authentication logic to authenticationManager.

[0.43.4]

Changed

• Improved type defintions for the usage with typescript.

[0.43.3]

Changed

• Rename 'DefaultLayer' to 'scene' in scene tree.

Fixed

• Fix interaction params for already cached (downloaded) models.

[0.43.2]

Added

• Adapted readme for typescript.

[0.43.1]

Fixed

• Fixed saving of project (custom data and freeze frames).

[0.43.0]

Changed

• Improved app bundling.

[0.42.1]

Fixed

• Correctly fetch model from repository if foreign key of the new model is already existing in the tree.

[0.42.0]

Added

• Freeze frame support for projects.
• Custom data field for projects.

Fixed

• Screenshot url for downloaded freeze frames.

[0.41.3]

Fixed

• Fixed saving of tracking map in placenote provider (correctly wait for core events).

[0.41.2]

Fixed

• Add 'createMaterial' and 'updateMaterial' to async call list.

[0.41.1]

Fixed

• Fixed saving/loading of room visibility in projects.
• Fixed room visibility setting when inserting a new room.

[0.41.0]

Added

• Added shopUrl to model.

[0.40.1]

Fixed

• Correctly add tracker name to core call setTrackingTargets.

[0.40.0]

Added

• Added appUtils function getResourceInfo for detailed memory usage for each resource.

[0.39.0]

Added

• Add ability to mute speaker (appUtils.muteSpeaker() and appUtils.speakerMuted).
• Add ability to mute microphone (appUtils.muteMicrophone() and appUtils.microphoneMuted).

[0.38.0]

Added

• Auto confirm ground & tracker options for ARCore tracker.

[0.37.0]

Added

• Added profiler to show FPS/CPU usage/memory usage as UI overlay.
• Read last generated tracking map id for placenote with placenote.trackingMapId.

[0.36.6]

Fixed

• Let placenote tracker's loadTrackingMap return correctly if map cannot be loaded.

[0.36.5]

Fixed

• Correctly set rotation interaction insertion param when inserting an environment model.
• Correctly handle custom tracking info notifications in structure tracker.

[0.36.4]

Fixed

• Correctly use default interaction if no interaction params are given on model insertion.

[0.36.3]

Added

• Add response to call history.

Fixed

• Improved error handling when model description is cached locally but model is deleted on the server.

[0.36.2]

Fixed

• Correctly unfreeze after showFreezeFrame in arCamera.

[0.36.1]

Added

• Fix surfaceMaterials in sceneExport for configurable models.

[0.36.0]

Added

• Support for 6dai tracker.
• Added sceneTree to sceneManager.

[0.35.1]

Added

• Consider surfaceMaterials in scene state saving/loading.

[0.35.0]

Added

• Send api version to core.

[0.34.0]

Added

• First complete version of type definitions.
• Tracking map load/save progress in mock mode.

Fixed

• Error with clearScene in mock mode.

[0.33.0]

Changed

• Moved coreInterface.callHistory to coreInterface.history.

Added

• Log core events too (previously only calls were logged).
• Typings for sceneManager and coreInterface.
• Catch errors while inserting model + advanced error logging when foreign key of a configuration model is not found.

[0.32.1]

• Bundle typings with viewar-api.

[0.32.0]

• New method getFloorSurface for roomManager.

[0.31.0]

Added

• New method applyFloorMaterial for roomManager.

[0.30.3]

Added

• Suppress 'Document not active' error.

Changed

• Improved JSDoc for modelManager.

[0.30.2]

Changed

• Improve appUtils.prepareCustomImage:
  • Swap url and fileName parameters.
  • Make fileName parameter optional (use md5 hash of url if no fileName provided).
  • Returns uri ready to use in app.

[0.30.1]

Fixed

• Adapted model's getDescription to ignore empty strings and use fallback instead.

[0.30.0]

Added

• Get insertion time in ms of a model instance with instance.insertionTime.

[0.29.3]

Fixed

• Expose foreignKey of categories.

[0.29.2]

Added

• exportScene requires viewar-core version ^11.17.3.

Fixed

• Use host from app config for usdz converting and project saving.

[0.29.1]

Added

• viewarApi.tracker now returns the default tracker (first in list) if no tracker is active.

[0.29.0]

Added

• Add ability to fetch categories from repository by id.

[0.28.3]

Fixed

• Fixed missing import for setTrackingTargets.
• Set camera pose update state to false on app start (adjust to core default).

[0.28.2]

Fixed

• Fixed bug in httpPost with non-string arguments.

[0.28.1]

Fixed

• Fixed bug in custom notifications for trackers.

[0.28.0]

Added

• Method to get a model's translated description. Sample usage:

model.getDescription('en'); // Return the english translation for description.
model.getDescription('en', 'de'); // Return the german translation if the englisch one doesn't exist.
model.getDescription('en', 'de', true); // Return model.data.description or model.description if neither english nor german translation exists.

[0.27.0]

Added

• Access currently active tracker with viewarApi.tracker.

[0.26.5]

Fixed

• Fixed exportScene to match coreVersion 11.16.1

[0.26.4]

Added

• Added useful README information.

[0.26.3]

Fixed

• Missing methods for camera and selection pose state updates.

[0.26.2]

Changed

• Changed type of unrecognized wikitude targets to "image".

[0.26.1]

Fixed

• Fix bug with ground confirm.

[0.26.0]

Added

• Reenabled camera.updatePose().
• Functionality to stop and start automatic pose updates for cameras and selection.

Stopping selection pose updating will stop pose from updating while draggin. When user stops dragging the object, the pose will still be updated. Sample usage:

viewarApi.cameras.arCamera.stopPoseUpdate(); // Stop pose update for every camera.
viewarApi.cameras.arCamera.updatePose(); // Use this while pose updates are stopped to get camera pose.
viewarApi.cameras.arCamera.startPoseUpdate(); // Start pose update for every camera.
viewarApi.sceneManager.stopSelectionUpdate(); // Stop selection pose update while dragging.
viewarApi.sceneManager.startSelectionUpdate(); // Start selection pose update while dragging.

Changed

• Refactored trackers to inherit from different tracking type providers (e.g. floor offset, ground confirm,...).

[0.25.0]

Added

• AppUtils now emits 'deviceBackButtonPressed' event when back button is pressed on android devices.

[0.24.1]

Fixed

• Fix bug introduced in v0.24.0 where zoomToFit used empty camera name.

[0.24.0]

Added

• Introduced cameras.activeCamera.

Should be backwards compatible when iterating over camera values. But take care when iterating over camera keys, e.g.:

function getActiveCameraName() {
  // ERROR: Will propably return "activeCamera" instead of the real camera name.
  return Object.keys(viewarApi.cameras).find(
    (cameraName) => viewarApi.cameras[cameraName].active
  );
}

Proposed solution for iterating over cameras (if not using cameras.activeCamera directly):

function getActiveCameraName() {
  return Object.values(viewarApi.cameras).find((camera) => camera.active).name;
}