Add particles layer and use it in satellites example

README.md

@@ -76,6 +76,7 @@ Make sure to load these two script tags in your application, required for `AR.js
 * [Hex Bin Layer](#hex-bin-layer)
 * [Hexed Polygons Layer](#hexed-polygons-layer)
 * [Tiles Layer](#tiles-layer)
+* [Particles Layer](#particles-layer)
 * [Rings Layer](#rings-layer)
 * [Labels Layer](#labels-layer)
 * [HTML Elements Layer](#html-elements-layer)
@@ -247,6 +248,20 @@ new GlobeAR(<domElement>, { configOptions })
 | <b>tileCurvatureResolution</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Tile object accessor function, attribute or a numeric constant for the resolution (in angular degrees) of the surface curvature. The finer the resolution, the more the tile geometry is fragmented into smaller faces to approximate the spheric surface, at the cost of performance. | 5 |
 | <b>tilesTransitionDuration</b>([<i>num</i>]) | Getter/setter for duration (ms) of the transition to animate tile changes involving geometry modifications. A value of `0` will move the tiles immediately to their final position. New tiles are animated by scaling them from the centroid outwards. | 1000 |
 
+### Particles Layer
+
+| Method | Description | Default |
+| --- | --- | :--: |
+| <b>particlesData</b>([<i>array</i>]) | Getter/setter for the list of particle sets to represent in the particles map layer. Each particle set is displayed as a group of [Points](https://threejs.org/docs/#api/en/objects/Points). Each point in the group is a geometry vertex and can be individually positioned anywhere relative to the globe. | `[]` |
+| <b>particlesList</b>([<i>str</i> or <i>fn</i>]) | Particle set accessor function or attribute for the list of particles in the set. By default, the data structure is expected to be an array of arrays of individual particle objects. | `d => d` |
+| <b>particleLat</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Particle object accessor function, attribute or a numeric constant for the latitude coordinate. | `lat` |
+| <b>particleLng</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Particle object accessor function, attribute or a numeric constant for the longitude coordinate. | `lng` |
+| <b>particleAltitude</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Particle object accessor function, attribute or a numeric constant for the altitude in terms of globe radius units. | 0.01 |
+| <b>particlesSize</b>([<i>num</i>, <i>str</i> or <i>fn</i>]) | Particle set accessor function, attribute or a numeric constant for the size of all the particles in the group. | `0.01` |
+| <b>particlesSizeAttenuation</b>([<i>boolean</i>, <i>str</i> or <i>fn</i>]) | Particle set accessor function, attribute or a boolean constant for whether the size of each particle on the screen should be attenuated according to the distance to the camera. | `true` |
+| <b>particlesColor</b>([<i>str</i> or <i>fn</i>]) | Particle set accessor function or attribute for the color of all the particles in the group. This setting will be ignored if `particlesTexture` is defined. | `white` |
+| <b>particlesTexture</b>([<i>str</i> or <i>fn</i>]) | Particle set accessor function or attribute for the [Texture](https://threejs.org/docs/#api/en/textures/Texture) to be applied to all the particles in the group. | - |
+
 ### Rings Layer
 
 | Method | Description | Default |

example/satellites/index.html

@@ -12,31 +12,24 @@
   <div id="globeViz"></div>
 
   <script type="module">
-    import * as THREE from 'https://esm.sh/three';
     import * as satellite from 'https://esm.sh/satellite.js';
 
     const EARTH_RADIUS_KM = 6371; // km
-    const SAT_SIZE = 100; // km
     const TIME_STEP = 3 * 1000; // per frame
 
     const world = new GlobeAR(document.getElementById('globeViz'))
       .globeImageUrl('//unpkg.com/three-globe/example/img/earth-blue-marble.jpg')
-      .objectLat('lat')
-      .objectLng('lng')
-      .objectAltitude('alt')
-      .objectFacesSurface(false);
-
-    const satGeometry = new THREE.OctahedronGeometry(SAT_SIZE * world.getGlobeRadius() / EARTH_RADIUS_KM / 2, 0);
-    const satMaterial = new THREE.MeshLambertMaterial({ color: 'palegreen', transparent: true, opacity: 0.7 });
-    world.objectThreeObject(() => new THREE.Mesh(satGeometry, satMaterial));
+      .particleLat('lat')
+      .particleLng('lng')
+      .particleAltitude('alt')
+      .particlesColor(() => 'palegreen');
 
     fetch('//unpkg.com/globe.gl/example/datasets/space-track-leo.txt').then(r => r.text()).then(rawData => {
       const tleData = rawData.replace(/\r/g, '').split(/\n(?=[^12])/).map(tle => tle.split('\n'));
       const satData = tleData.map(([name, ...tle]) => ({
         satrec: satellite.twoline2satrec(...tle),
         name: name.trim().replace(/^0 /, '')
-      }))
-      .slice(0, 1000);
+      }));
 
       // time ticker
       let time = new Date();
@@ -57,7 +50,7 @@
           }
         });
 
-        world.objectsData(satData);
+        world.particlesData([satData.filter(d => !isNaN(d.lat) && !isNaN(d.lng) && !isNaN(d.alt))]);
       })();
     });
   </script>

package.json

@@ -44,20 +44,20 @@
     "dist/**/*"
   ],
   "dependencies": {
-    "aframe-globe-component": "^1.15",
+    "aframe-globe-component": "^1.16",
     "kapsule": "^1.16"
   },
   "devDependencies": {
     "@babel/core": "^7.26.0",
     "@babel/preset-env": "^7.26.0",
     "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^28.0.1",
-    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-commonjs": "^28.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.0",
     "@rollup/plugin-terser": "^0.4.4",
     "rimraf": "^6.0.1",
-    "rollup": "^4.28.0",
+    "rollup": "^4.31.0",
     "rollup-plugin-dts": "^6.1.1",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.3"
   },
   "engines": {
     "node": ">=12"

rollup.config.js

@@ -4,7 +4,7 @@ import babel from '@rollup/plugin-babel';
 import terser from "@rollup/plugin-terser";
 import dts from 'rollup-plugin-dts';
 
-import pkg from './package.json' assert { type: 'json' };
+import pkg from './package.json' with { type: 'json' };
 const { name, homepage, version, dependencies } = pkg;
 
 const umdConf = {

src/globe-ar.js

@@ -117,6 +117,15 @@ export default Kapsule({
     tileMaterial: {},
     tileCurvatureResolution: { default: 5 }, // in angular degrees
     tilesTransitionDuration: { default: 1000 }, // ms
+    particlesData: { default: [] },
+    particlesList: { default: d => d }, // arrays of arrays
+    particleLat: { default: 'lat' },
+    particleLng: { default: 'lng' },
+    particleAltitude: { default: 0.01 }, // in units of globe radius
+    particlesSize: { default: 0.01 },
+    particlesSizeAttenuation: { default: true },
+    particlesColor: { default: () => 'white' },
+    particlesTexture: {},
     ringsData: { default: [] },
     ringLat: { default: 'lat' },
     ringLng: { default: 'lng' },
@@ -178,6 +187,7 @@ export default Kapsule({
       this.hexBinPointsData([]);
       this.hexPolygonsData([]);
       this.tilesData([]);
+      this.particlesData([]);
       this.labelsData([]);
       this.objectsData([]);
       this.customLayerData([]);
@@ -334,6 +344,15 @@ export default Kapsule({
       'tileMaterial',
       'tileCurvatureResolution',
       'tilesTransitionDuration',
+      'particlesData',
+      'particlesList',
+      'particleLat',
+      'particleLng',
+      'particleAltitude',
+      'particlesSize',
+      'particlesSizeAttenuation',
+      'particlesColor',
+      'particlesTexture',
       'ringsData',
       'ringLat',
       'ringLng',