ros3djs Documentation

You can use ros3djs by including pre-built files directly in your project or via a CDN.

Using Pre-built Files

If you have cloned the repository, the files are located in the build/ directory:

• build/ros3d.js (Full version)
• build/ros3d.min.js (Minified version)

Using JsDelivr CDN

You can also load the library directly from the JsDelivr CDN:

• Full version: https://cdn.jsdelivr.net/npm/ros3d@1/build/ros3d.js
• Minified version: https://cdn.jsdelivr.net/npm/ros3d@1/build/ros3d.min.js

<!-- Example of including via CDN -->
<script src="https://cdn.jsdelivr.net/npm/ros3d@1/build/ros3d.min.js"></script>

Once the dependencies are installed, use Grunt to manage the build process. Navigate to the project root before running commands.

Build the project

Run grunt build to concatenate and minimize files in src/, update the files in the build/ directory, and run the linter and tests.

grunt build

Development mode

Run grunt dev to watch for changes in src/ files. It will automatically re-concatenate and re-minimize files whenever a change is detected. This is recommended during active development.

grunt dev

Rebuild JSDoc

Run grunt doc to rebuild all JSDoc documentation for the project.

grunt doc

To build ros3djs from source on Ubuntu 18.04/20.04, follow these steps to set up the build environment:

1. Install Node.js and NPM:

   sudo apt-get install nodejs nodejs-legacy npm

2. Install Grunt CLI:

   sudo npm install -g grunt-cli

3. Install project-specific Grunt tasks: Navigate to the ros3djs directory and run:

   cd /path/to/ros3djs/
   npm install .

These examples demonstrate using ROS3D as an ECMAScript (ES) module within a static webpage. Because these examples use HTML imports, they must be served via a webserver; they will not work if opened directly as local files due to browser security restrictions regarding same-origin resource loading and CORS.

To run the examples locally, follow these steps:

1. Install dependencies: Use yarn or npm to install the necessary packages.
2. Start the webserver: Run the provided start script to launch a simple Express webserver at http://localhost:3000.
3. View examples: Open your browser and navigate to http://localhost:3000.

# 1. install dependencies
yarn install # or npm install

# 2. start simple express webserver at localhost:3000
yarn start # or npm start

# 3. open app and view examples
# http://localhost:3000

To use ros3djs correctly, ensure the following dependencies are available in your environment. Note that specific versions are recommended for compatibility:

• EventEmitter3: Version 5.0 recommended.
• three.js: Version r89 recommended.
• roslibjs: Version 1.3.0 recommended.
• Loaders: THREE.ColladaLoader and THREE.STLLoader (from three.js r89) are required for 3D model loading.
• (ROS)ColladaLoader: A patched version of ColladaLoader is supported to work around rviz#1045.