Installing XViewr SDK

XViewr SDK is published as a private npm package to Optellix Azure Artifacts.

Package name:

@optellix/xviewr-sdk

Azure Artifacts feed:

https://pkgs.dev.azure.com/Optellix/Optellix-XView/_packaging/company-packages-sdk/npm/registry/

Requirements

• Node.js 20 or newer.
• npm access to the Optellix Azure Artifacts feed.
• A valid XViewr SDK license key for runtime use.
• three installed in the consuming application. It is a peer dependency of the SDK.

Configure npm

Add an .npmrc file to the consuming application:

@optellix:registry=https://pkgs.dev.azure.com/Optellix/Optellix-XView/_packaging/company-packages-sdk/npm/registry/
//pkgs.dev.azure.com/Optellix/Optellix-XView/_packaging/company-packages-sdk/npm/registry/:always-auth=true

Do not commit access tokens into the project .npmrc.

Authenticate

Use one of the following approaches, depending on how the consuming environment is set up.

Azure DevOps Users

If the user has access to the Azure Artifacts feed, authenticate npm against the feed using the instructions from Azure DevOps:

1. Open Azure DevOps.
2. Go to Artifacts.
3. Select the company-packages-sdk feed.
4. Open Connect to feed.
5. Choose npm.
6. Follow the generated authentication instructions.

After authentication, verify access:

npm view @optellix/xviewr-sdk version

CI/CD Pipelines

In Azure Pipelines, authenticate using npmAuthenticate@0 against an .npmrc that contains the scoped registry.

Example:

- task: npmAuthenticate@0
  inputs:
    workingFile: .npmrc

- script: npm ci

For non-Azure CI systems, configure npm auth using a secure secret or token provided by the CI platform. Keep the token in the user-level or CI-generated .npmrc, not in source control.

Install

Install the SDK and its peer dependency:

npm install @optellix/xviewr-sdk three

If the project already has three, make sure the installed version satisfies the SDK peer dependency:

npm ls three

The SDK currently declares:

three >=0.176.0

Import

Use the main package entry for the standard SDK API:

import { ViewerCore } from "@optellix/xviewr-sdk";

Typed subpath imports are also available:

import { CameraPlugin } from "@optellix/xviewr-sdk/plugins";
import { CameraService } from "@optellix/xviewr-sdk/services";
import type { XViewerConfig } from "@optellix/xviewr-sdk/types";

Minimal Usage

import { ViewerCore, CameraType, LoaderService } from "@optellix/xviewr-sdk";

const container = document.getElementById("viewer")!;

const viewer = new ViewerCore(container, {
  viewer: {
    container,
    camera: {
      type: CameraType.Perspective,
      fov: 75,
      position: { x: 5, y: 5, z: 5 },
    },
    controls: {
      type: "TrackballControls",
    },
    environment: {
      preset: "outdoor",
    },
    licensing: {
      key: "YOUR_XVIEWR_LICENSE_KEY",
    },
  },
  plugins: [
    { name: "loader", enabled: true },
    { name: "selection", enabled: true },
    { name: "measurement", enabled: true },
  ],
  features: {
    enableCrossSection: true,
    enableMeasurement: true,
    enableSelection: true,
    enableTransform: true,
    enableLabels: true,
    enableAnimation: true,
    enableGrid: true,
    enableShadows: true,
    enableEnvironment: true,
  },
  rendering: {
    antialias: true,
    alpha: true,
  },
});

await viewer.ready();

Loading A Model

const loader = viewer.getService<LoaderService>("loader");

await loader?.loadFile({
  url: "/models/assembly.glb",
  type: "glb",
  filename: "assembly.glb",
});

For very large STEP/CAD workflows, STEP is converted by Xconvert before it reaches the browser. The SDK loads the Xconvert-generated chunk manifest:

const loader = viewer.getService<LoaderService>("loader");

await loader?.loadFile({
  url: "/converted/manifest.json",
  type: "chunked",
  filename: "assembly-manifest.json",
});

Supported Install Targets

The package exposes:

• ESM build through the module and exports.import fields.
• UMD/CommonJS-compatible build through the main and exports.require fields.
• TypeScript declarations through the types and exports.types fields.
• Subpath exports for core, plugins, services, types, and utils.

Troubleshooting

401 Or 403 During Install

The user is not authenticated to the Azure Artifacts feed, or the account/token does not have feed access. Re-run the Azure DevOps Connect to feed npm authentication steps and verify:

npm view @optellix/xviewr-sdk version

Package Not Found

Check that the consuming project has the scoped registry:

npm config get @optellix:registry

It should print:

https://pkgs.dev.azure.com/Optellix/Optellix-XView/_packaging/company-packages-sdk/npm/registry/

Peer Dependency Warning For three

Install or update three in the consuming application:

npm install three

Runtime License Error

The package installed successfully, but the viewer will not initialize until a valid XViewr SDK license key is supplied in viewer.licensing.key.

E57 Files

E57 is not currently supported. STEP workflows should go through Xconvert and be loaded as chunked manifests.