Skip to main content

Lines and Shapes

The GsplatLines script renders line-based debug primitives using Gaussian splats. It supports lines, arrows, and axis-aligned bounding boxes (AABBs), making it useful for CAD-style visualizations and debugging.

note

This feature builds on the splat rendering architecture.

Overview​

GsplatLines is a Script component that:

  • Creates splat-based lines, arrows, and wireframe boxes
  • Supports gradient colors along lines
  • Uses a handle system for adding/removing primitives
  • Automatically rebuilds when primitives change

Basic Usage​

// Import the script
const { GsplatLines } = await import('path/to/gsplat-lines.mjs');

// Add script component to an entity
entity.addComponent('script');
const lines = entity.script.create(GsplatLines);

// Add primitives
const lineHandle = lines.addLine(
    new pc.Vec3(0, 0, 0),
    new pc.Vec3(1, 1, 1),
    new pc.Color(1, 0, 0),  // Start color (red)
    new pc.Color(0, 0, 1),  // End color (blue)
    0.05                     // Thickness
);

// Remove later if needed
lines.removePrimitive(lineHandle);

API​

addLine(start, end, startColor, endColor, thickness)​

Adds a line with gradient color from start to end.

const handle = lines.addLine(
    new pc.Vec3(0, 0, 0),
    new pc.Vec3(1, 0, 0),
    new pc.Color(1, 0, 0),
    new pc.Color(0, 1, 0),
    0.02
);

addLineSimple(start, end, color, thickness)​

Adds a line with a single color.

const handle = lines.addLineSimple(
    new pc.Vec3(0, 0, 0),
    new pc.Vec3(1, 0, 0),
    new pc.Color(1, 1, 0),
    0.02
);

addArrow(start, end, color, thickness, headSize?)​

Adds an arrow with a pyramid-shaped head.

const handle = lines.addArrow(
    new pc.Vec3(0, 0, 0),
    new pc.Vec3(0, 1, 0),
    new pc.Color(0, 1, 0),
    0.02,
    0.1  // Optional head size (default: thickness * 9)
);

addAABB(min, max, color, thickness)​

Adds an axis-aligned bounding box as a wireframe.

const handle = lines.addAABB(
    new pc.Vec3(-1, -1, -1),
    new pc.Vec3(1, 1, 1),
    new pc.Color(1, 1, 0),
    0.01
);

removePrimitive(handle)​

Removes a primitive by its handle.

const removed = lines.removePrimitive(handle);  // Returns true if found

clear()​

Removes all primitives.

lines.clear();

primitiveCount (read-only)​

Returns the number of primitives.

console.log(`${lines.primitiveCount} primitives`);

How It Works​

Lines are rendered as a series of splats placed along the line path:

  • Splat count is based on line length and thickness
  • Splats are evenly distributed along the line
  • Color is interpolated from start to end
  • Arrows use 5 lines (main shaft + 4 pyramid edges)
  • AABBs use 12 lines (one per edge)

Use Cases​

  • CAD-style annotations: Dimension lines, measurement arrows
  • Debug visualization: Bounding boxes, direction indicators
  • Scene decoration: Wireframe overlays, guides

Live Example​

See the Procedural Shapes example which demonstrates CAD-style dimension annotations on a Gaussian splat scene.

Procedural Shapes example

Script Location​

The script is available in the PlayCanvas Engine repository:

scripts/esm/gsplat/gsplat-lines.mjs

See Also​