WalkinsideJS Comprehensive API Documentation¶

Table of Contents¶

Adding WalkinsideJS to your application
Creating a View
Loading a Project
Executing Commands
Sending Notifications
Scenario Management
Project APIs
Label APIs
Measurement APIs
- Start Route Measurement
- Stop Route Measurement
Measurement Events
- Route Measurement Completed
Viewpoint APIs
- Jump to Viewpoint
Bounding Box APIs
- Get Bounding Box
Clipping Box APIs
- Clip
- Reset Clipping
Settings APIs

1. Adding WalkinsideJS to your application¶

To get started with WalkinsideJS, follow these three easy steps:

Set up COMOS Walkinside Server: Ensure you have a COMOS Walkinside Server, including the Rendering Service feature. This requires that the server has a GPU supported by COMOS Walkinside.
Load WalkinsideJS Script: Add the walkinside.js script to your HTML application:
```
<script src="[walkinside-server-address]/walkinside-js/walkinside.js"></script>
```
(If you customized your installation, the /walkinside-js/ path may be different.) 3. Add a Container Element: Include an HTML element in your page that will serve as a container for the 3D view. Any block element, like a <div>, will work.

After the script is loaded, you can start using the global walkinside object. Its interface is described in the "API Reference" section below.

Versioning¶

WalkinsideJS follows the semantic versioning scheme (http://semver.org) to indicate to clients when there is compatibility breakage.

2. Creating a View¶

Global "walkinside" object

walkinside.createViewAsync(options) → Promise<View>

Initializes a new 3D viewer within a specified container element and connects it to the Walkinside backend.

Parameters¶

options (Object):
- backendAddress (string): The server URL where the Walkinside backend is hosted.
- targetElement (HTMLElement): The DOM element that will host the 3D view.

Example¶

walkinside.createViewAsync({
    backendAddress: 'https://example.com/walkinside-backend',
    targetElement: document.getElementById('wi-viewer-container')
}).then(function(view) {
    console.info('View created successfully.');
}).catch(function(error) {
    console.error('Error creating view:', error);
});

3. Loading a Project¶

view.loadProjectAsync(options) → Promise<Project>

Loads a specified project into the initialized view.

Parameters¶

options (Object):
- projectAddress (string): The URL of the Walkinside project.
- token (string): Authentication token.

Example¶

view.loadProjectAsync({
    projectAddress: 'https://example.com/projects/123',
    token: 'your_access_token'
}).then(function(project) {
    console.info('Project loaded successfully:', project);
}).catch(function(error) {
    console.error('Error loading project:', error);
});

4. Executing Commands¶

view.executeCommandAsync(options) → Promise

Executes a predefined command within the view.

Parameters¶

options (Object):
- commandName (string): The name of the command to execute.
- commandInput (string, optional): Additional input for the command.

Example¶

view.executeCommandAsync({
    commandName: 'ResetView',
    commandInput: 'optional_input'
}).then(function() {
    console.log('Command executed successfully.');
}).catch(function(error) {
    console.error('Error executing command:', error);
});

5. Sending Notifications¶

view.notifyAsync(options) → Promise

Sends a notification to all listeners within the view.

Parameters¶

options (Object):
- notificationName (string): The name of the notification to send.
- notificationInput (string, optional): Additional input for the notification.

Example¶

view.notifyAsync({
    notificationName: 'UpdateStatus',
    notificationInput: 'Updated to new status.'
}).then(function() {
    console.log('Notification sent successfully.');
}).catch(function(error) {
    console.error('Error sending notification:', error);
});

6. Scenario Management¶

Loading a Project with Scenario¶

view.loadProjectWithScenarioAsync(options, scenarioStartedHandler)

Loads a project with a specific scenario, triggering a callback when the scenario starts.

Parameters¶

options (Object): Same as loadProjectAsync.
scenarioStartedHandler (function): Callback function that handles the scenario start event.

Example¶

view.loadProjectWithScenarioAsync({
    projectAddress: 'https://example.com/projects/123?scenario=scenarioname',
    token: 'your_access_token'
}, function(scenario) {
    console.log('Scenario started with name:', scenario.id);
});

Scenario Actions¶

Show Scenario Action List¶

scenario.showScenarioActionListAsync()

Displays the action list for the current scenario in the 3D view.

Example¶

scenario.showScenarioActionListAsync().then(function() {
    console.log('Scenario action list displayed.');
}).catch(function(error) {
    console.error('Error displaying scenario action list:', error);
});

Hide Scenario Action List¶

scenario.hideScenarioActionListAsync()

Hides the action list for the current scenario in the 3D view.

Example¶

scenario.hideScenarioActionListAsync().then(function() {
    console.log('Scenario action list hidden.');
}).catch(function(error) {
    console.error('Error hiding scenario action list:', error);
});

Show Scenario Clock¶

scenario.showScenarioClockAsync()

Displays the scenario clock in the 3D view.

Example¶

scenario.showScenarioClockAsync().then(function() {
    console.log('Scenario clock displayed.');
}).catch(function(error) {
    console.error('Error displaying scenario clock:', error);
});

Hide Scenario Clock¶

scenario.hideScenarioClockAsync()

Hides the scenario clock in the 3D view.

Example¶

scenario.hideScenarioClockAsync().then(function() {
    console.log('Scenario clock hidden.');
}).catch(function(error) {
    console.error('Error hiding scenario clock:', error);
});

Scenario Event Handlers¶

Action Succeeded¶

scenario.onActionSucceeded(handler)

Fires when an action within the scenario is successfully completed.

Example¶

scenario.onActionSucceeded(function() {
    console.log('An action within the scenario succeeded.');
});

Scenario Succeeded¶

scenario.onScenarioSucceeded(handler)

Fires when the scenario is successfully completed.

Example¶

scenario.onScenarioSucceeded(function() {
    console.log('Scenario successfully completed.');
});

Scenario Failed¶

scenario.onScenarioFailed(handler)

Fires when the scenario fails to complete successfully.

Example¶

scenario.onScenarioFailed(function() {
    console.error('Scenario failed to complete.');
});

7. Project APIs¶

Select and Fly To¶

project.selectAndFlyToAsync(tagValue)

Selects an object by its tag and flies the camera to it.

Parameters¶

tagValue (string): The tag of the object to select.

Example¶

project.selectAndFlyToAsync('pump1').then(function() {
    console.log('Camera flown to selected object.');
}).catch(function(error) {
    console.error('Error selecting or flying:', error);
});

Jump to Home¶

project.jumpToHome()

Resets the camera to its default home position.

Example¶

project.jumpToHome();
console.log('Camera returned to home position.');

Apply Colors¶

project.applyColorsAsync(args)

Applies coloring to objects based on their tags.

Parameters¶

args (Object):
- colorGroups (Array): Groups of colors and the tags they apply to.

Type Definitions¶

interface IColorGroup {
    color: string;
    opacity: number;
    tagValues: Array<string>;
}

Example¶

project.applyColorsAsync({
    colorGroups: [
        {
            color: '#FF0000',
            opacity: 0.5,
            tagValues: ['valve1', 'valve2']
        }
    ]
}).then(function() {
    console.log('Colors applied to specified tags.');
}).catch(function(error) {
    console.error('Error applying colors:', error);
});

Unselect All¶

project.unselectAllAsync()

Unselects all currently selected objects.

Example¶

project.unselectAllAsync().then(function() {
    console.log('All selections cleared.');
}).catch(function(error) {
    console.error('Error unselecting:', error);
});

Fly to Selection¶

project.flyToSelectionAsync()

Flies the camera to currently selected objects.

Example¶

project.flyToSelectionAsync().then(function() {
    console.log('Camera flown to selected objects.');
}).catch(function(error) {
    console.error('Error flying to selection:', error);
});

Show Only Selection¶

project.showOnlySelectionAsync()

Hides all unselected objects, showing only the selected ones.

Example¶

project.showOnlySelectionAsync().then(function() {
    console.log('Only selected objects are now visible.');
}).catch(function(error) {
    console.error('Error showing only selection:', error);
});

Show All¶

project.showAllAsync()

Makes all objects in the project visible.

Example¶

project.showAllAsync().then(function() {
    console.log('All objects are now visible.');
}).catch(function(error) {
    console.error('Error showing all objects:', error);
});

Hide Selection¶

project.hideSelectionAsync()

Hides the selected objects.

Example¶

project.hideSelectionAsync().then(function() {
    console.log('Selected objects have been hidden.');
}).catch(function(error) {
    console.error('Error hiding selected objects:', error);
});

8. Label APIs¶

Add Label¶

project.label.addLabelAsync(labelText, labelPosition)

Adds a label to the project at a specific position.

Parameters¶

labelText (string): The text of the label.
labelPosition (ILabelPosition): The 3D coordinates to place the label.

Type Definitions¶

interface ILabelPosition {
    x: number;
    y: number;
    z: number;
}

Example¶

project.label.addLabelAsync("Important Component", { x: 10, y: 20, z: 30 }).then(function(labelId) {
    console.log('Label added with ID:', labelId);
}).catch(function(error) {
    console.error('Error adding label:', error);
});

Update Label Text¶

project.label.updateLabelTextAsync(labelId, newText)

Updates the text of an existing label.

Parameters¶

labelId (string): The ID of the label to update.
newText (string): The new text for the label.

Example¶

project.label.updateLabelTextAsync('1234', 'Updated Text').then(function() {
    console.log('Label text updated.');
}).catch(function(error) {
    console.error('Error updating label text:', error);
});

Update Label Position¶

project.label.updateLabelPositionAsync(labelId, newPosition)

Updates the position of an existing label.

Parameters¶

labelId (string): The ID of the label to update.
newPosition (ILabelPosition): The new position for the label.

Example¶

project.label.updateLabelPositionAsync('1234', { x: 15, y: 25, z: 35 }).then(function() {
    console.log('Label position updated.');
}).catch(function(error) {
    console.error('Error updating label position:', error);
});

Remove Label¶

project.label.removeLabelAsync(labelId)

Removes a label from the project.

Parameters¶

labelId (string): The ID of the label to remove.

Example¶

project.label.removeLabelAsync('1234').then(function() {
    console.log('Label removed.');
}).catch(function(error) {
    console.error('Error removing label:', error);
});

9. Measurement APIs¶

Start Route Measurement¶

project.measurement.startRouteMeasurementAsync()

Begins a new route measurement within the project.

Example¶

project.measurement.startRouteMeasurementAsync().then(function() {
    console.log('Route measurement started.');
}).catch(function(error) {
    console.error('Error starting route measurement:', error);
});

Stop Route Measurement¶

project.measurement.stopRouteMeasurementAsync()

Stops the current route measurement and returns the results.

Example¶

project.measurement.stopRouteMeasurementAsync().then(function(result) {
    console.log('Route measurement stopped:', result);
}).catch(function(error) {
    console.error('Error stopping route measurement:', error);
});

10. Measurement Events¶

Route Measurement Completed¶

project.measurement.on('route-measurement-completed', handler)

Event triggered when a route measurement is completed.

Handler Signature¶

handler(result): Function to handle the event.

Result¶

totalDistance (number): The total distance measured.
distanceFromLastPoint (number): The distance from the last measurement point.

Example¶

project.measurement.on('route-measurement-completed', function(result) {
    console.log('Measurement completed. Total distance:', result.totalDistance);
});

11. Viewpoint APIs¶

Jump to Viewpoint¶

project.viewpoint.jumpToViewpointAsync(projectId, viewpointId)

Moves the camera to a specific viewpoint identified by viewpointId.

Parameters¶

projectId (string): The ID of the project containing the viewpoint.
viewpointId (string): The ID of the viewpoint to jump to.

Example¶

project.viewpoint.jumpToViewpointAsync('project123', 'viewpoint456').then(function() {
    console.log('Jumped to viewpoint.');
}).catch(function(error) {
    console.error('Error jumping to viewpoint:', error);
});

12. Bounding Box APIs¶

Get Bounding Box¶

project.boundingBox.getBoundingBoxAsync(projectId, branchIds)

Retrieves the bounding box for specified branches within a project.

Parameters¶

branchIds (Array\<number>): An array of branch IDs for which to calculate the bounding box.

Returns¶

Promise: Resolves with coordinates for the bounding box.

Example¶

project.boundingBox.getBoundingBoxAsync('project123', [1, 2, 3]).then(function(bbox) {
    console.log('Bounding box coordinates:', bbox);
}).catch(function(error) {
    console.error('Error retrieving bounding box:', error);
});

13. Clipping Box APIs¶

Clip¶

project.clipping.clipAsync(min, max)

Applies a clipping box to the project to only display objects within specified coordinates.

Parameters¶

min (Coordinate): The minimum coordinates of the clipping box.
max (Coordinate): The maximum coordinates of the clipping box.

Returns¶

Promise: Resolves when the clipping is applied.

Example¶

project.clipping.clipAsync(
    { x: 0, y: 0, z: 0 }, 
    { x: 100, y: 100, z: 100 }
).then(function() {
    console.log('Clipping applied.');
}).catch(function(error) {
    console.error('Error applying clipping:', error);
});

Reset Clipping¶

project.clipping.resetClipAsync()

Removes any applied clipping boxes from the project.

Example¶

project.clipping.resetClipAsync().then(function() {
    console.log('Clipping reset.');
}).catch(function(error) {
    console.error('Error resetting clipping:', error);
});

14. Settings APIs¶

Toggle Third Person¶

project.settings.setThirdPersonMode(value)

Parameters¶

value (boolean): true to enable third-person, false to disable it.

Enables or disables third-person mode.

Example¶

project.settings.setThirdPersonMode(true);

Toggle Gravity¶

project.settings.setGravity(value)

Parameters¶

value (boolean): true to enable gravity, false to disable it.

Enables or disables gravity mode.

Example¶

project.settings.setGravity(true);

Toggle Collision¶

project.settings.setCollision(value)

Parameters¶

value (boolean): true to enable collision, false to disable it.

Enables or disables collision mode.

Example¶

project.settings.setCollision(true);