@ranchhandrobotics/babylon_ros 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +224 -0
- package/dist/ros.js +3 -0
- package/dist/ros.js.LICENSE.txt +1686 -0
- package/dist/ros.js.map +1 -0
- package/package.json +75 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023 Lou Amadio
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# babylon_ros
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
Babylon_ROS is a Node.JS API for rendering ROS 2 based URDFs and Xacro in a web browser using Babylon.js 3D.
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- ๐ค **URDF and Xacro Object Model**: Loads and validates URDF and Xacro files into an object model you can access
|
|
10
|
+
- ๐ **Web Rendering Interface**: Access your robot's visualization from any device with a web browser
|
|
11
|
+
- ๐ธ **Screenshot API**: Capture clean screenshots of your robot scenes without UI elements as base64 PNG images
|
|
12
|
+
|
|
13
|
+
## Non-Features
|
|
14
|
+
- **No Real-time Visualization**: This package does not provide real-time visualization capabilities. It is focused on static visualization and interaction.
|
|
15
|
+
- **No Simulation**: Babylon ROS does not include a physics engine for simulating dynamics or collisions.
|
|
16
|
+
- **No Sensor visualization**: The package does not simulate or visualize sensors.
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
Babylon ROS is an npm package that can be installed in your web application. To install, run:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install --save @ranch-hand-robotics/babylon_ros
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Usage
|
|
26
|
+
To use Babylon ROS in your web application, you need to set up a basic HTML page and include the Babylon.js library along with the Babylon ROS package.
|
|
27
|
+
|
|
28
|
+
Hereโs a simple example which renders a the Test Page included in this package:
|
|
29
|
+
|
|
30
|
+
```html
|
|
31
|
+
<!DOCTYPE html>
|
|
32
|
+
<html lang="en">
|
|
33
|
+
<head>
|
|
34
|
+
<meta charset="UTF-8">
|
|
35
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
36
|
+
<style nonce="${nonce}">
|
|
37
|
+
html,
|
|
38
|
+
body {
|
|
39
|
+
overflow: hidden;
|
|
40
|
+
width: 100%;
|
|
41
|
+
height: 100%;
|
|
42
|
+
margin: 0;
|
|
43
|
+
padding: 0;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
#renderCanvas {
|
|
47
|
+
width: 100%;
|
|
48
|
+
height: 100%;
|
|
49
|
+
touch-action: none;
|
|
50
|
+
}
|
|
51
|
+
</style>
|
|
52
|
+
<title>URDF Preview</title>
|
|
53
|
+
</head>
|
|
54
|
+
<body>
|
|
55
|
+
<canvas id="renderCanvas" touch-action="none"></canvas>
|
|
56
|
+
<script src="../node_modules/babylonjs/babylon.js"></script>
|
|
57
|
+
<script src="./ros.js"></script>
|
|
58
|
+
<script>
|
|
59
|
+
|
|
60
|
+
window.addEventListener("load", babylon_ros.RenderTestMain);
|
|
61
|
+
|
|
62
|
+
</script>
|
|
63
|
+
|
|
64
|
+
</body>
|
|
65
|
+
</html>
|
|
66
|
+
```
|
|
67
|
+
To use your own hosting application, I suggest looking at how the Test Page is implemented in the `test` directory.
|
|
68
|
+
|
|
69
|
+
### Rendering URDF Files from GitHub
|
|
70
|
+
You can directly render URDF files hosted on GitHub using unpkg to load babylon_ros. This is perfect for embedding live robot visualizations in README files or documentation.
|
|
71
|
+
|
|
72
|
+
Here's a complete example that renders the mule robot from this repository:
|
|
73
|
+
|
|
74
|
+
```html
|
|
75
|
+
<!DOCTYPE html>
|
|
76
|
+
<html lang="en">
|
|
77
|
+
<head>
|
|
78
|
+
<meta charset="UTF-8">
|
|
79
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
80
|
+
<title>Mule Robot URDF Viewer</title>
|
|
81
|
+
<style>
|
|
82
|
+
html, body {
|
|
83
|
+
overflow: hidden;
|
|
84
|
+
width: 100%;
|
|
85
|
+
height: 100%;
|
|
86
|
+
margin: 0;
|
|
87
|
+
padding: 0;
|
|
88
|
+
font-family: Arial, sans-serif;
|
|
89
|
+
}
|
|
90
|
+
#renderCanvas {
|
|
91
|
+
width: 100%;
|
|
92
|
+
height: 100%;
|
|
93
|
+
touch-action: none;
|
|
94
|
+
}
|
|
95
|
+
#controls {
|
|
96
|
+
position: absolute;
|
|
97
|
+
top: 10px;
|
|
98
|
+
left: 10px;
|
|
99
|
+
background: rgba(0, 0, 0, 0.7);
|
|
100
|
+
color: white;
|
|
101
|
+
padding: 10px;
|
|
102
|
+
border-radius: 5px;
|
|
103
|
+
z-index: 100;
|
|
104
|
+
}
|
|
105
|
+
button {
|
|
106
|
+
margin: 2px;
|
|
107
|
+
padding: 5px 10px;
|
|
108
|
+
background: #4CAF50;
|
|
109
|
+
color: white;
|
|
110
|
+
border: none;
|
|
111
|
+
border-radius: 3px;
|
|
112
|
+
cursor: pointer;
|
|
113
|
+
}
|
|
114
|
+
button:hover {
|
|
115
|
+
background: #45a049;
|
|
116
|
+
}
|
|
117
|
+
</style>
|
|
118
|
+
</head>
|
|
119
|
+
<body>
|
|
120
|
+
<canvas id="renderCanvas" touch-action="none"></canvas>
|
|
121
|
+
<div id="controls">
|
|
122
|
+
<h3>Mule Robot</h3>
|
|
123
|
+
<button onclick="resetCamera()">Reset Camera</button>
|
|
124
|
+
<button onclick="takeScreenshot()">Screenshot</button>
|
|
125
|
+
</div>
|
|
126
|
+
|
|
127
|
+
<!-- Load dependencies from unpkg -->
|
|
128
|
+
<script src="https://unpkg.com/babylonjs@7.16.1/babylon.js"></script>
|
|
129
|
+
<script src="https://unpkg.com/babylonjs-gui@7.16.1/babylon.gui.min.js"></script>
|
|
130
|
+
<script src="https://unpkg.com/@ranch-hand-robotics/babylon_ros/web/ros.js"></script>
|
|
131
|
+
|
|
132
|
+
<script>
|
|
133
|
+
let robotScene;
|
|
134
|
+
|
|
135
|
+
async function loadMuleRobot() {
|
|
136
|
+
try {
|
|
137
|
+
// Fetch the URDF file from GitHub
|
|
138
|
+
const urdfUrl = 'https://raw.githubusercontent.com/Ranch-Hand-Robotics/babylon_ros/main/test/testdata/mule.urdf';
|
|
139
|
+
const response = await fetch(urdfUrl);
|
|
140
|
+
const urdfText = await response.text();
|
|
141
|
+
|
|
142
|
+
// Create the robot scene
|
|
143
|
+
const canvas = document.getElementById('renderCanvas');
|
|
144
|
+
robotScene = new babylon_ros.RobotScene();
|
|
145
|
+
await robotScene.createScene(canvas);
|
|
146
|
+
|
|
147
|
+
// Load and render the URDF
|
|
148
|
+
await robotScene.applyURDF(urdfText);
|
|
149
|
+
|
|
150
|
+
console.log('Mule robot loaded successfully!');
|
|
151
|
+
} catch (error) {
|
|
152
|
+
console.error('Error loading robot:', error);
|
|
153
|
+
alert('Failed to load robot: ' + error.message);
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function resetCamera() {
|
|
158
|
+
if (robotScene) {
|
|
159
|
+
robotScene.resetCamera();
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
async function takeScreenshot() {
|
|
164
|
+
if (robotScene) {
|
|
165
|
+
try {
|
|
166
|
+
const base64Data = await robotScene.takeScreenshot();
|
|
167
|
+
const link = document.createElement('a');
|
|
168
|
+
link.href = `data:image/png;base64,${base64Data}`;
|
|
169
|
+
link.download = 'mule_robot.png';
|
|
170
|
+
link.click();
|
|
171
|
+
} catch (error) {
|
|
172
|
+
console.error('Screenshot failed:', error);
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
// Load the robot when the page loads
|
|
178
|
+
window.addEventListener('load', loadMuleRobot);
|
|
179
|
+
</script>
|
|
180
|
+
</body>
|
|
181
|
+
</html>
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### GitHub README Integration
|
|
185
|
+
To embed a live robot viewer in your GitHub README, you can use GitHub Pages or any static hosting service. Here's how to set it up:
|
|
186
|
+
|
|
187
|
+
1. **Create the viewer HTML file** (as shown above) in your repository
|
|
188
|
+
2. **Enable GitHub Pages** for your repository
|
|
189
|
+
3. **Link to the live viewer** in your README:
|
|
190
|
+
|
|
191
|
+
```markdown
|
|
192
|
+
## Live Robot Visualization
|
|
193
|
+
|
|
194
|
+
[๐ View the Mule Robot in 3D](https://ranch-hand-robotics.github.io/babylon_ros/mule_viewer.html)
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
## Screenshot API
|
|
200
|
+
|
|
201
|
+
The library includes built-in screenshot functionality to capture clean images of your robot scenes:
|
|
202
|
+
|
|
203
|
+
```javascript
|
|
204
|
+
// Take a screenshot and get base64 PNG data
|
|
205
|
+
const base64Data = await robotScene.takeScreenshot();
|
|
206
|
+
|
|
207
|
+
// Take a screenshot with custom dimensions
|
|
208
|
+
const base64Data = await robotScene.takeScreenshot(1920, 1080);
|
|
209
|
+
|
|
210
|
+
// Get a data URL for immediate use
|
|
211
|
+
const dataUrl = await robotScene.takeScreenshotDataURL();
|
|
212
|
+
|
|
213
|
+
// Save screenshot as file (browser)
|
|
214
|
+
const link = document.createElement('a');
|
|
215
|
+
link.href = `data:image/png;base64,${base64Data}`;
|
|
216
|
+
link.download = 'robot_scene.png';
|
|
217
|
+
link.click();
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
The screenshot API automatically hides UI elements (buttons, gizmos, etc.) during capture, ensuring clean robot visualizations. See [SCREENSHOT_API.md](./SCREENSHOT_API.md) for complete documentation.
|
|
221
|
+
|
|
222
|
+
## Support
|
|
223
|
+
Support is available through the [GitHub Discussion at Ranch Hand Robotics](https://github.com/Ranch-Hand-Robotics/babylon_ros/discussions).
|
|
224
|
+
|