WalkinsideJS Comprehensive API Documentation¶
Table of Contents¶
- Adding WalkinsideJS to your application
- Creating a View
- Loading a Project
- Executing Commands
- Sending Notifications
- UI Web Components
- Scenario Management
- Project APIs
- Label APIs
- Measurement APIs
- Measurement Events
- Viewpoint APIs
- Bounding Box APIs
- Clipping Box APIs
- Branch Operations
- Settings APIs
- Setting Events
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.jsscript 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. UI Web Components¶
Introduction¶
Web components in WalkinsideJS provide reusable and customizable UI elements that can be easily integrated into your application. These components are designed to enhance user interaction and simplify the development process by encapsulating functionality and styling.
To use web components, ensure the following files are included:
<script src="${WALKINSIDE-JS-LOCATION}/walkinside.js"></script>
<script src="${WALKINSIDE-JS-LOCATION}/main.js"></script>
<script src="${WALKINSIDE-JS-LOCATION}/polyfills.js"></script>
<script src="${WALKINSIDE-JS-LOCATION}/runtime.js"></script>
These files provide the necessary backend support for the web components.
wi-joystick-navigation¶
The wi-joystick-navigation web component is a customizable joystick control designed for navigation within the Walkinside 3D viewer. It allows users to interact with the 3D environment using a virtual joystick.
Usage¶
To use the wi-joystick-navigation component, include it in your HTML file as follows:
<wi-joystick-navigation class="joystick-style" style="bottom: 5px; right: 5px;"></wi-joystick-navigation>
Features¶
- Provides a virtual joystick for navigation.
- Supports both mouse and touch interactions.
- Emits keyboard-like events for seamless integration with the Walkinside 3D viewer.
Example¶
<!DOCTYPE html>
```html
<html>
<head>
<title>Joystick Navigation Example</title>
<script src="${WALKINSIDE-JS-LOCATION}/walkinside.js"></script>
<script src="${WALKINSIDE-JS-LOCATION}/main.js"></script>
<script src="${WALKINSIDE-JS-LOCATION}/polyfills.js"></script>
<script src="${WALKINSIDE-JS-LOCATION}/runtime.js"></script>
</head>
<body>
<div id="wi-viewer-container"></div>
<wi-joystick-navigation style="bottom: 5px; right: 5px;"></wi-joystick-navigation>
</body>
</html>
In this example, the wi-joystick-navigation component is added alongside the Walkinside viewer container. The joystick can be used to navigate the 3D environment interactively.
7. 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 asloadProjectAsync.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.');
});
8. 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);
});
9. 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);
});
10. 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);
});
11. 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);
});
12. 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);
});
13. Bounding Box APIs¶
Get Bounding Box¶
project.boundingBox.getBoundingBoxAsync(projectId, branchIds)
Retrieves the bounding box for specified branches within a project.
Parameters¶
branchIds(Array of numbers): 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);
});
14. 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);
});
15. Branch Operations APIs¶
Colorize¶
view.branchOperations.colorizeAsync(projectId, branchIds, color)
Applies a colorize operation to the branches with the specified color.
Parameters¶
projectId(string): The ID of the project containing the branches.branchIds(Array of numbers): An array of branch IDs where the color is applied.color(string): The color that will be applied to the branches.
Returns¶
Promise: Resolves when the colorizing is applied.
Example¶
view.branchOperations.colorizeAsync('project123', [1, 2, 3], 'color').then(function(response) {
console.log('Colorize status:', response);
}).catch(function(error) {
console.error('Error colorizing:', error);
});
Hide Operation¶
view.branchOperations.hideAsync(projectId, branchIds)
Hides the specified branches.
Parameters¶
projectId(string): The ID of the project containing the branches.branchIds(Array of numbers): An array of branch IDs that will be hidden.
Returns¶
Promise: Resolves when the hiding is applied.
Example¶
view.branchOperations.hideAsync('project123', [1, 2, 3]).then(function(response) {
console.log('Hide status:', response);
}).catch(function(error) {
console.error('Error hiding:', error);
});
Show Operation¶
view.branchOperations.showAsync(projectId, branchIds)
Shows the specified branches.
Parameters¶
projectId(string): The ID of the project containing the branches.branchIds(Array of numbers): An array of branch IDs that will be shown.
Returns¶
Promise: Resolves when the showing is applied.
Example¶
view.branchOperations.showAsync('project123', [1, 2, 3]).then(function(response) {
console.log('Show status:', response);
}).catch(function(error) {
console.error('Error showing:', error);
});
Hide Everything Operation¶
view.branchOperations.hideEverythingAsync(projectId)
Hides all the branches from the project.
Parameters¶
projectId(string): The ID of the project containing the branches.
Returns¶
Promise: Resolves when the hiding is applied.
Example¶
view.branchOperations.hideEverythingAsync('project123').then(function(response) {
console.log('Hide everything status:', response);
}).catch(function(error) {
console.error('Error hiding everything:', error);
});
Show Everything Operation¶
view.branchOperations.showEverythingAsync(projectId)
Shows all the branches from the project.
Parameters¶
projectId(string): The ID of the project containing the branches.
Returns¶
Promise: Resolves when the showing is applied.
Example¶
view.branchOperations.showEverythingAsync('project123').then(function(response) {
console.log('Show everything status:', response);
}).catch(function(error) {
console.error('Error showing everything:', error);
});
Show Only Operation¶
view.branchOperations.showOnlyAsync(projectId, branchIds)
Shows only the specified branches.
Parameters¶
projectId(string): The ID of the project containing the branches.branchIds(Array of numbers): An array of branch IDs that will be shown only.
Returns¶
Promise: Resolves when the showing is applied.
Example¶
view.branchOperations.showOnlyAsync('project123', [1, 2, 3]).then(function(response) {
console.log('Show only status:', response);
}).catch(function(error) {
console.error('Error showing only:', error);
});
Reset Operations¶
view.branchOperations.resetAsync()
Removes any applied branch operation from the project.
Example¶
view.branchOperations.resetAsync().then(function() {
console.log('Operations reset.');
}).catch(function(error) {
console.error('Error resetting operations:', error);
});
16. Settings APIs¶
Toggle Third Person¶
Get View Type¶
view.settings.getViewTypeAsync()
Retrieves the current view type (e.g., first person or third person).
Returns¶
Promise<string>: The current view type.
Example¶
view.settings.getViewTypeAsync().then(function(viewType) {
console.log('Current view type:', viewType);
}).catch(function(error) {
console.error('Error getting view type:', error);
});
Set View Type¶
view.settings.setViewTypeAsync(value)
Sets the view type for the project.
Parameters¶
value(string): The view type to set ('firstPersonMode'or'thirdPersonMode').
Example¶
view.settings.setViewTypeAsync('thirdPersonMode').then(function() {
console.log('View type set to third person.');
}).catch(function(error) {
console.error('Error setting view type:', error);
});
Toggle Gravity¶
Get Gravity¶
view.settings.getGravityAsync()
Retrieves the current gravity setting.
Returns¶
Promise<boolean>: Whether gravity is enabled.
Example¶
view.settings.getGravityAsync().then(function(isGravityEnabled) {
console.log('Gravity is enabled:', isGravityEnabled);
}).catch(function(error) {
console.error('Error getting gravity status:', error);
});
Set Gravity¶
view.settings.setGravityAsync(value)
Enables or disables gravity in the project environment.
Parameters¶
value(boolean):trueto enable gravity,falseto disable it.
Example¶
view.settings.setGravityAsync(true).then(function() {
console.log('Gravity enabled.');
}).catch(function(error) {
console.error('Error setting gravity:', error);
});
Toggle Collision¶
Get Collision¶
view.settings.getCollisionAsync()
Checks if collision detection is enabled.
Returns¶
Promise<boolean>: Whether collision detection is enabled.
Example¶
view.settings.getCollisionAsync().then(function(isCollisionEnabled) {
console.log('Collision is enabled:', isCollisionEnabled);
}).catch(function(error) {
console.error('Error getting collision status:', error);
});
Set Collision¶
view.settings.setCollisionAsync(value)
Enables or disables collision detection in the project.
Parameters¶
value(boolean):trueto enable collision,falseto disable it.
Example¶
view.settings.setCollisionAsync(true).then(function() {
console.log('Collision enabled.');
}).catch(function(error) {
console.error('Error setting collision:', error);
});
17. Setting Events¶
View Type Value Changed¶
view.settings.on('view_type_value_changed', eventHandler)
Event fired when the view type changes.
Handler Signature¶
eventHandler(viewType): Function to handle the view type change.
Example¶
view.settings.on('view_type_value_changed', function(newViewType) {
console.log('View type changed to:', newViewType);
});
Gravity Value Changed¶
view.settings.on('gravity_value_changed', eventHandler)
Event fired when the gravity setting changes.
Handler Signature¶
eventHandler(gravityEnabled): Function to handle the change in gravity setting.
Example¶
view.settings.on('gravity_value_changed', function(isGravityEnabled) {
console.log('Gravity setting changed. Gravity is now:', isGravityEnabled);
});
Collision Value Changed¶
view.settings.on('collision_value_changed', eventHandler)
Event fired when the collision detection setting changes.
Handler Signature¶
eventHandler(collisionEnabled): Function to handle the change in collision detection setting.
Example¶
view.settings.on('collision_value_changed', function(isCollisionEnabled) {
console.log('Collision setting changed. Collision detection is now:', isCollisionEnabled);
});