GuideNode

Overview

The GuideNode represents a 2D reference image that can be overlaid in the scene as a guide. This is useful for importing floor plans, elevation drawings, or other 2D reference imagery to use as a basis for creating the building model. Key features:

Reference to 2D image asset via URL
Position, rotation, and scale transformations
Opacity control for overlay visualization

Type Signature

import { z } from 'zod'
import { BaseNode, nodeType, objectId } from '../base'

const GuideNode = BaseNode.extend({
  id: objectId('guide'),
  type: nodeType('guide'),
  url: z.string(),
  position: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
  rotation: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
  scale: z.number().default(1),
  opacity: z.number().min(0).max(100).default(50),
})

type GuideNode = z.infer<typeof GuideNode>

Source: /home/daytona/workspace/source/packages/core/src/schema/nodes/guide.ts

Fields

Inherited from BaseNode

string

required

Unique guide identifier.Format: guide_{randomString}Example: "guide_a1b2c3d4e5f6g7h8"

type

string

required

Always set to "guide".Default: "guide"

name

string

Optional name for the guide.Example: "Ground Floor Plan", "North Elevation"

parentId

string | null

required

Reference to the parent node’s ID (typically a Level or Building).Example: "level_abc123"Default: null

visible

boolean

Controls guide visibility.Default: true

camera

CameraSchema

Optional camera viewpoint for the guide.

metadata

any

Custom metadata for the guide.Default: {}

Guide-Specific Fields

url

string

required

URL or path to the 2D reference image asset.Example: "https://example.com/plans/floor1.png", "/assets/elevation.jpg"Supported formats typically include: PNG, JPG, JPEG, SVG, or other image formats.

position

[number, number, number]

required

Position of the guide in 3D space.Format: [x, y, z] in metersDefault: [0, 0, 0]Example: [5, 0, 5] (positioned at ground level, 5m along X and Z)Typically, floor plan guides are positioned at Y=0 (ground level) or at the level elevation.

rotation

[number, number, number]

required

Rotation of the guide around X, Y, and Z axes in radians.Format: [rx, ry, rz] in radiansDefault: [0, 0, 0]Example: [-Math.PI / 2, 0, 0] (rotate to lie flat on ground plane)For floor plans, typically rotate -90° around X axis to lay flat.

scale

number

required

Uniform scale factor for the guide image.Default: 1Example: 1.0 (original size), 0.1 (10% size), 10.0 (10x size)Adjust this to match the image to the scene’s coordinate system scale.

opacity

number

required

Opacity of the guide visualization (0-100).Default: 50Range: 0 (fully transparent) to 100 (fully opaque)Example: 50 (50% transparent), 30 (faint reference)Lower opacity values are useful for using the guide as a background reference while modeling.

Example

import { GuideNode } from '@pascal/core/schema/nodes/guide'

const guide: GuideNode = {
  object: 'node',
  id: 'guide_abc123',
  type: 'guide',
  name: 'Ground Floor Plan',
  parentId: 'level_ground',
  visible: true,
  url: 'https://storage.example.com/plans/ground_floor.png',
  position: [0, 0, 0],
  rotation: [-Math.PI / 2, 0, 0], // Lay flat on ground
  scale: 0.05, // Scale to match meters
  opacity: 40,
  metadata: {
    source: 'architect drawings',
    date: '2024-01-15',
    scale: '1:100',
  },
}

Usage

Creating a Floor Plan Guide

import { GuideNode } from '@pascal/core/schema/nodes/guide'

const floorPlan = GuideNode.parse({
  name: 'First Floor Plan',
  parentId: 'level_first',
  url: '/assets/floor_plans/first_floor.png',
  position: [0, 0, 0],
  rotation: [-Math.PI / 2, 0, 0], // Rotate to horizontal plane
  scale: 0.05, // Adjust scale to match scene units
  opacity: 50,
})

Creating an Elevation Guide

const elevationGuide = GuideNode.parse({
  name: 'North Elevation',
  parentId: 'building_main',
  url: '/assets/elevations/north.jpg',
  position: [0, 1.5, -10], // Position in front of building
  rotation: [0, 0, 0], // Vertical orientation
  scale: 0.1,
  opacity: 60,
})

Creating Multiple Floor Plan Guides

const groundFloorGuide = GuideNode.parse({
  name: 'Ground Floor Reference',
  parentId: 'level_ground',
  url: '/plans/ground.png',
  position: [0, 0, 0],
  rotation: [-Math.PI / 2, 0, 0],
  scale: 0.05,
  opacity: 40,
})

const firstFloorGuide = GuideNode.parse({
  name: 'First Floor Reference',
  parentId: 'level_first',
  url: '/plans/first.png',
  position: [0, 3, 0], // 3m above ground
  rotation: [-Math.PI / 2, 0, 0],
  scale: 0.05,
  opacity: 40,
})

Creating a Rotated Site Plan Guide

const sitePlan = GuideNode.parse({
  name: 'Site Plan',
  parentId: 'site_main',
  url: '/plans/site_plan.png',
  position: [0, 0, 0],
  rotation: [-Math.PI / 2, Math.PI / 4, 0], // Flat + 45° rotation
  scale: 0.2,
  opacity: 30, // Very faint for context
})

Creating a High-Opacity Guide for Tracing

const tracingGuide = GuideNode.parse({
  name: 'Tracing Reference',
  url: '/images/detailed_plan.png',
  position: [0, 0.01, 0], // Slightly above ground to avoid z-fighting
  rotation: [-Math.PI / 2, 0, 0],
  scale: 0.05,
  opacity: 70, // More opaque for detailed tracing
})

Creating a Scaled Architectural Drawing

const architecturalDrawing = GuideNode.parse({
  name: 'Architectural Plan 1:50',
  url: '/drawings/plan_1_50.pdf',
  position: [0, 0, 0],
  rotation: [-Math.PI / 2, 0, 0],
  scale: 0.02, // Adjust based on drawing scale
  opacity: 50,
  metadata: {
    drawingScale: '1:50',
    units: 'meters',
  },
})

Common Use Cases

Floor Plan Tracing

Load floor plan images to trace walls and rooms:

const floorPlanGuide = GuideNode.parse({
  name: 'Floor Plan for Tracing',
  url: '/plans/layout.png',
  position: [0, 0, 0],
  rotation: [-Math.PI / 2, 0, 0], // Horizontal
  scale: 0.05,
  opacity: 50,
  metadata: {
    purpose: 'wall tracing reference',
  },
})

Elevation Reference

Use elevation drawings to model facade details:

const elevationRef = GuideNode.parse({
  name: 'South Elevation',
  url: '/elevations/south.jpg',
  position: [5, 1.5, 15],
  rotation: [0, Math.PI, 0], // Facing building
  scale: 0.08,
  opacity: 60,
  metadata: {
    purpose: 'facade modeling',
  },
})

Site Context

Overlay site survey or aerial imagery:

const aerialImage = GuideNode.parse({
  name: 'Aerial Photo',
  parentId: 'site_main',
  url: '/site/aerial.jpg',
  position: [0, -0.1, 0], // Slightly below ground
  rotation: [-Math.PI / 2, 0, 0],
  scale: 1.0,
  opacity: 25, // Very transparent background
  metadata: {
    purpose: 'site context',
  },
})

Positioning Floor Plans

For floor plan guides, use these common settings:

// Standard horizontal floor plan
const standardFloorPlan = {
  position: [0, 0, 0],           // At ground level
  rotation: [-Math.PI / 2, 0, 0], // Rotate to horizontal plane
  opacity: 50,                    // Semi-transparent
}

// Elevated floor plan (for upper levels)
const upperFloorPlan = {
  position: [0, 3, 0],            // 3m elevation
  rotation: [-Math.PI / 2, 0, 0],
  opacity: 50,
}

Coordinate System

Guides use 3D world coordinates:

X axis: horizontal (left-right)
Y axis: vertical (up-down)
Z axis: horizontal (front-back)
Rotation: Euler angles [rx, ry, rz] in radians
Scale: Uniform scaling factor

Supported Formats

While the schema accepts any URL string, common image formats include:

PNG (recommended for transparency)
JPG/JPEG (for photographs)
SVG (for vector drawings)
GIF
WebP

Check your viewer’s documentation for supported formats.

Tips for Using Guides

Scaling: Measure a known dimension in the image and adjust the scale to match scene units
Opacity: Start with 50% opacity and adjust based on visibility needs
Position: For floor plans, set Y=0 or to the level elevation; for elevations, position away from the building
Rotation: Floor plans typically need -90° X rotation to lie flat
Layers: Use multiple guides with different opacities for different reference layers

BaseNode - Inherited base fields
ScanNode - 3D point cloud references (similar concept)
LevelNode - Typical parent for floor plan guides
BuildingNode - Typical parent for elevation guides

Core Package

Node Schemas

Systems

Viewer Package

Overview

Type Signature

Fields

Inherited from BaseNode

Guide-Specific Fields

Example

Usage

Creating a Floor Plan Guide

Creating an Elevation Guide

Creating Multiple Floor Plan Guides

Creating a Rotated Site Plan Guide

Creating a High-Opacity Guide for Tracing

Creating a Scaled Architectural Drawing

Common Use Cases

Floor Plan Tracing

Elevation Reference

Site Context

Positioning Floor Plans

Coordinate System

Supported Formats

Tips for Using Guides

Build docs developers (and LLMs) love

Core Package

Node Schemas

Systems

Viewer Package

​Overview

​Type Signature

​Fields

​Inherited from BaseNode

​Guide-Specific Fields

​Example

​Usage

​Creating a Floor Plan Guide

​Creating an Elevation Guide

​Creating Multiple Floor Plan Guides

​Creating a Rotated Site Plan Guide

​Creating a High-Opacity Guide for Tracing

​Creating a Scaled Architectural Drawing

​Common Use Cases

​Floor Plan Tracing

​Elevation Reference

​Site Context

​Positioning Floor Plans

​Coordinate System

​Supported Formats

​Tips for Using Guides

​Related

Build docs developers (and LLMs) love

Overview

Type Signature

Fields

Inherited from BaseNode

Guide-Specific Fields

Example

Usage

Creating a Floor Plan Guide

Creating an Elevation Guide

Creating Multiple Floor Plan Guides

Creating a Rotated Site Plan Guide

Creating a High-Opacity Guide for Tracing

Creating a Scaled Architectural Drawing

Common Use Cases

Floor Plan Tracing

Elevation Reference

Site Context

Positioning Floor Plans

Coordinate System

Supported Formats

Tips for Using Guides

Related