{"_id":"@bertt/3dtilesrenderer-styling-plugin","name":"@bertt/3dtilesrenderer-styling-plugin","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bertt/3dtilesrenderer-styling-plugin","version":"0.1.0","description":"Cesium 3D Tiles Styling Specification plugin for 3DTilesRendererJS","main":"src/index.js","module":"src/index.js","exports":{".":{"import":"./src/index.js","require":"./src/index.js"}},"type":"module","keywords":["3dtiles","3d-tiles","three.js","gis","maplibre","styling","cesium"],"author":{"name":"Bert Temme"},"license":"MIT","peerDependencies":{"three":">=0.150.0","3d-tiles-renderer":">=0.3.0"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/bertt/3dtilesrenderer-styling-plugin.git"},"gitHead":"92800964f3eb10a938abc7fa6b54d29fe6d790d6","_id":"@bertt/3dtilesrenderer-styling-plugin@0.1.0","bugs":{"url":"https://github.com/bertt/3dtilesrenderer-styling-plugin/issues"},"homepage":"https://github.com/bertt/3dtilesrenderer-styling-plugin#readme","_nodeVersion":"24.14.1","_npmVersion":"11.10.0","dist":{"integrity":"sha512-lDiDQMwOVA2kyBSB+DjoE0qQ9scvtbrapibxJbXfDwhCQNvqM8AsIjaGiYONITEClWDMiGU+75i+7KKIuWumSQ==","shasum":"bc21010457a095c61cdb4a817832f529209aa25a","tarball":"https://registry.npmjs.org/@bertt/3dtilesrenderer-styling-plugin/-/3dtilesrenderer-styling-plugin-0.1.0.tgz","fileCount":5,"unpackedSize":17484,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC4gLXjq/XgEvU0eZisYv2ag5kmR0nFMdr2XdeJL9eKugIhAKnJK2RhkOTCwB46MjmZeO+7BKxLTEkOWpMTDCMKYX5X"}]},"_npmUser":{"name":"bertt","email":"btemme@hotmail.com"},"directories":{},"maintainers":[{"name":"bertt","email":"btemme@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/3dtilesrenderer-styling-plugin_0.1.0_1774643678208_0.9074551084114548"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-27T20:34:38.116Z","0.1.0":"2026-03-27T20:34:38.344Z","modified":"2026-03-27T20:34:38.555Z"},"maintainers":[{"name":"bertt","email":"btemme@hotmail.com"}],"description":"Cesium 3D Tiles Styling Specification plugin for 3DTilesRendererJS","homepage":"https://github.com/bertt/3dtilesrenderer-styling-plugin#readme","keywords":["3dtiles","3d-tiles","three.js","gis","maplibre","styling","cesium"],"repository":{"type":"git","url":"git+https://github.com/bertt/3dtilesrenderer-styling-plugin.git"},"author":{"name":"Bert Temme"},"bugs":{"url":"https://github.com/bertt/3dtilesrenderer-styling-plugin/issues"},"license":"MIT","readme":"# 3dtilesrenderer-styling-plugin\r\n\r\nA plugin for 3DTilesRendererJS that applies Cesium 3D Tiles Styling Specification color conditions to 3D tile features. It reads feature properties from GLB tiles via EXT_structural_metadata, evaluates color conditions based on property values, and applies per-feature vertex colors using Three.js materials.\r\n\r\nOriginal styling specs see https://github.com/CesiumGS/3d-tiles/tree/main/specification/Styling\r\n\r\n## Architecture\r\n\r\nThe plugin implements the TilesRenderer plugin pattern and intercepts the `load-model` event to style GLB tiles as they are loaded.\r\n\r\n```mermaid\r\nflowchart LR\r\n    A[\"TilesRenderer<br/>loads GLB tile\"] -->|load-model<br/>event| B[\"CesiumStylingPlugin<br/>intercepts\"]\r\n    B --> C[\"Read EXT_structural_metadata<br/>property tables\"]\r\n    C --> D[\"Extract _FEATURE_ID_0<br/>vertex attribute\"]\r\n    D --> E[\"Evaluate color conditions<br/>for each feature\"]\r\n    E --> F[\"Apply vertex colors<br/>to Three.js mesh\"]\r\n    F --> G[\"Browser renders<br/>styled tile\"]\r\n```\r\n\r\nThe plugin processes each tile independently. For every mesh in the loaded GLB:\r\n1. It retrieves the feature ID for each vertex via the `_FEATURE_ID_0` attribute\r\n2. It looks up the feature's property values in the structural metadata tables\r\n3. It evaluates the color conditions against the property value\r\n4. It creates per-vertex colors in a Float32Array\r\n5. It sets the vertex color attribute and enables `vertexColors` on the material\r\n\r\n## Demo\r\n\r\nColor buildings by height\r\n\r\nhttps://bertt.github.io/3dtilesrenderer-styling-plugin/sample/sibbe/\r\n\r\n<img width=\"1279\" height=\"818\" alt=\"image\" src=\"https://github.com/user-attachments/assets/ec87a2a1-9735-42e1-8672-5982110440ad\" />\r\n\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @bertt/3dtilesrenderer-styling-plugin\r\n```\r\n\r\nRequires Three.js and 3d-tiles-renderer as peer dependencies.\r\n\r\n## Usage\r\n\r\n### Prerequisites\r\n\r\nBefore using the plugin, register the required GLTF extensions on your GLTFLoader:\r\n\r\n```javascript\r\nimport { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';\r\nimport { GLTFMeshFeaturesExtension } from '3d-tiles-renderer';\r\nimport { GLTFStructuralMetadataExtension } from '3d-tiles-renderer';\r\n\r\nconst gltfLoader = new GLTFLoader();\r\ngltfLoader.register(parser => new GLTFMeshFeaturesExtension(parser));\r\ngltfLoader.register(parser => new GLTFStructuralMetadataExtension(parser));\r\n```\r\n\r\n### Basic example\r\n\r\n```javascript\r\nimport { TilesRenderer } from '3d-tiles-renderer';\r\nimport { CesiumStylingPlugin } from '@bertt/3dtilesrenderer-styling-plugin';\r\n\r\n// Create the tiles renderer\r\nconst tiles = new TilesRenderer('https://example.com/tileset.json');\r\ntiles.setCamera(camera);\r\ntiles.setResolutionFromRenderer(renderer);\r\n\r\n// Define the style\r\nconst style = {\r\n  color: {\r\n    conditions: [\r\n      [\"${height} <= 10\", \"color('#430719')\"],\r\n      [\"${height} > 10 && ${height} <= 20\", \"color('#740320')\"],\r\n      [\"${height} > 20\", \"color('#f72585')\"],\r\n      [\"true\", \"color('#ffffff')\"]\r\n    ]\r\n  }\r\n};\r\n\r\n// Create and register the plugin\r\nconst plugin = new CesiumStylingPlugin({ style });\r\ntiles.registerPlugin(plugin);\r\n\r\n// Add to scene and render\r\nscene.add(tiles.group);\r\n```\r\n\r\n### How color conditions work\r\n\r\nThe plugin evaluates conditions in order. The first condition that evaluates to `true` determines the color for that feature.\r\n\r\nEach condition is an array: `[expression, colorFunction]`\r\n\r\n- **Expression**: A string that evaluates to boolean, using property names from the tileset's structural metadata\r\n- **Color function**: A string like `\"color('#RRGGBB')\"` that specifies the output color\r\n\r\n## Style Syntax\r\n\r\n### Supported features\r\n\r\n| Feature | Example | Status |\r\n|---------|---------|--------|\r\n| Property access (bracket) | `${feature['height']}` | ✓ Supported |\r\n| Property access (shorthand) | `${height}` | ✓ Supported |\r\n| Comparison operators | `<=`, `>=`, `<`, `>`, `===`, `!==`, `==`, `!=` | ✓ Supported |\r\n| Boolean operators | `&&`, `\\|\\|` | ✓ Supported |\r\n| Catch-all condition | `\"true\"` | ✓ Supported |\r\n| RGB color | `color('#RRGGBB')` | ✓ Supported |\r\n| RGBA color | `color('#RRGGBB', alpha)` | ✓ Supported |\r\n| CSS rgb() | `rgb(255, 0, 128)` | ✓ Supported |\r\n| CSS rgba() | `rgba(255, 0, 128, 0.5)` | ✓ Supported |\r\n\r\n### Not supported in V1\r\n\r\n| Feature | Reason |\r\n|---------|--------|\r\n| `show` property | Requires feature-level visibility control |\r\n| `defines` property | Not applicable to client-side rendering |\r\n| Mathematical functions | `clamp()`, `min()`, `max()` not yet implemented |\r\n| Regular expressions | Pattern matching not implemented |\r\n| `meta` property | Metadata about the style not supported |\r\n| String comparisons | Property values assumed to be numeric |\r\n| Ternary expressions | Syntax not parsed |\r\n| `pointSize` property | Not applicable to polygon/mesh rendering |\r\n\r\n### Color expression examples\r\n\r\n```javascript\r\n// Hex colors\r\n\"color('#FF0000')\"           // Solid red\r\n\"color('#00FF00', 0.5)\"      // Half-transparent green\r\n\r\n// RGB/RGBA functions\r\n\"rgb(255, 165, 0)\"           // Orange\r\n\"rgba(0, 0, 255, 0.8)\"       // Semi-transparent blue\r\n\r\n// Conditional examples\r\n\"${height} > 100\"            // Compare height property\r\n\"${type} === 'residential' && ${height} > 15\"\r\n\"${population} >= 10000 || ${area} > 5000\"\r\n```\r\n\r\n## Options\r\n\r\n### Constructor options\r\n\r\n```javascript\r\nnew CesiumStylingPlugin(options)\r\n```\r\n\r\n| Option | Type | Required | Description |\r\n|--------|------|----------|-------------|\r\n| `style` | object | yes | Style object with `color.conditions` array |\r\n\r\nThe `style` object shape:\r\n\r\n```javascript\r\n{\r\n  color: {\r\n    conditions: [\r\n      [expression, colorFunction],\r\n      [expression, colorFunction],\r\n      // ...\r\n      [\"true\", fallbackColor]  // Recommended catch-all\r\n    ]\r\n  }\r\n}\r\n```\r\n\r\n## Sample\r\n\r\nA working sample is included in `sample/sibbe/index.html`. It demonstrates styling of BAG (Basisregistratie Adressen en Gebouwen) building data in Sibbe, Limburg, colored by building height.\r\n\r\nThe sample uses a color gradient:\r\n- Dark navy (`#430719`) for buildings 0–10 meters\r\n- Rose (`#f72585`) for buildings above 30 meters\r\n\r\n### Running the sample locally\r\n\r\n1. Open a terminal in the repository root\r\n2. Start a local HTTP server:\r\n   ```bash\r\n   npx http-server\r\n   ```\r\n3. Open `http://localhost:8080/sample/sibbe/` in your browser\r\n\r\nOr open `sample/sibbe/index.html` directly in your browser if using a modern browser with CORS enabled for file:// URLs (some browsers restrict this).\r\n\r\n## Publishing\r\n\r\nTo publish a new version to npm:\r\n\r\n```bash\r\nnpm login\r\nnpm publish --access public\r\n```\r\n\r\nNotes:\r\n- The package is configured as a public scoped package (`@bertt/`), so `--access public` is required\r\n- Ensure you have permissions for the `@bertt` scope\r\n- No build step is required; the source files are published as-is (ES modules)\r\n- Update the version number in `package.json` before publishing\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md","_rev":"1-2b3612e1cc39b16ff0623ac070e71b5a"}