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.5]

Added

Added flag to set tracking targets without sending to core.

[1.60.4]

Added

Added new CoreInterfaceMethods for better performance for mobile devices (Old Methods are still available for backwards compatibility and webversion):

findDestinations to computeDistances
findPath to computePath
queryCylinderTags to queryCylinderTagNames

[1.60.3]

Added

PortalModelEditorAppId in host config

[1.60.2]

Added

Display average FPS in profiler
Add matterportClientId to hostConfig

[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;
}

FAQs

What is @viewar/api?

Is @viewar/api popular?

Is @viewar/api well maintained?

Package last updated on 20 Oct 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install