@diginestai/3d — 3D Layer Components

@diginestai/3d provides Three.js-backed React components that render into the MapLibre GL JS scene. The package is bundled separately so bundlers can code-split its Three.js payload; it is never included in the core bundle when 3D components are unused.

---

Peer Dependencies

pnpm add three @types/three

Three.js (three) is a required peer dependency. The minimum supported version is Three.js r160.

---

Installation

pnpm add @diginestai/3d

---

Lazy-Import Pattern (Recommended)

Import 3D components via the lazy shim exported from @diginestai/core so bundlers can code-split the Three.js chunk:

// Preferred — Three.js bytes excluded from core bundle when unused
import { ShapeLayer, ModelLayer, Text3DLayer } from '@diginestai/core';

Or import directly from the package (eager load):

import { ShapeLayer, ModelLayer, Text3DLayer } from '@diginestai/3d';

---

<ShapeLayer>

Renders extruded 3D shapes (boxes, cylinders, spheres, custom polygon extrusions) anchored to geographic coordinates.

Quick Example

import { ShapeLayer } from '@diginestai/core';

<ShapeLayer
  id="zones"
  data={[
    {
      id: 'zone-a',
      type: 'box',
      center: [-122.41, 37.78],
      width: 10,
      depth: 10,
      height: 3,
      color: [0.2, 0.6, 1.0, 0.8],
    },
  ]}
/>

Props

Prop	Type	Default	Description
id	string	—	Unique layer ID. Required.
data	ShapeItem[]	[]	Array of shape descriptors.
opacity	number	1	Global opacity multiplier (0–1).
pickable	boolean	false	Enable pointer events on shapes.
onClick	(shape: ShapeItem) => void	—	Fired when a shape is clicked (requires pickable: true).
beforeId	string	—	MapLibre layer ID to insert before (controls z-order).

ShapeItem Fields

Field	Type	Description
id	string	Unique identifier.
type	'box' | 'cylinder' | 'sphere'	Primitive geometry type.
center	[lon, lat]	Geographic anchor.
width	number	Width in metres.
depth	number	Depth in metres.
height	number	Extrusion height in metres.
color	Color	RGBA tuple [r, g, b, a] in 0–1 range.

---

<ModelLayer>

Renders a GLTF/GLB 3D model anchored to a geographic coordinate.

Quick Example

import { ModelLayer } from '@diginestai/core';

<ModelLayer
  id="robot"
  url="https://cdn.example.com/robot.glb"
  center={[-122.41, 37.78]}
  altitude={0}
  scale={1}
  rotation={[0, 0, 0]}
/>

Props

Prop	Type	Default	Description
id	string	—	Unique layer ID. Required.
url	string	—	URL of the GLTF or GLB model. Required.
center	[lon, lat]	—	Geographic anchor. Required.
altitude	number	0	Height above ground in metres.
scale	number	1	Uniform scale factor.
rotation	[rx, ry, rz]	[0, 0, 0]	Euler rotation in radians.
opacity	number	1	Model opacity (0–1).
onLoad	() => void	—	Fired after the model file is fetched and parsed.

---

<Text3DLayer>

Renders billboarded 3D text labels anchored to geographic coordinates.

Quick Example

import { Text3DLayer } from '@diginestai/core';

<Text3DLayer
  id="space-labels"
  items={[
    { id: 'l1', center: [-122.41, 37.78], text: 'Lobby', color: [1, 1, 1, 1] },
    { id: 'l2', center: [-122.412, 37.781], text: 'Café', color: [1, 0.8, 0, 1] },
  ]}
/>

Props

Prop	Type	Default	Description
id	string	—	Unique layer ID. Required.
items	Text3DItem[]	[]	Array of label descriptors.
fontSize	number	0.5	Font size in metres.
billboard	boolean	true	Always face the camera.

Text3DItem Fields

Field	Type	Description
id	string	Unique identifier.
center	[lon, lat]	Geographic anchor.
text	string	Label text.
color	Color	RGBA tuple [r, g, b, a].
altitude	number	Height above ground in metres (optional).