Architecture Documentation - Layout Generator for SketchUp

Overview

The Layout Generator is a Ruby extension for SketchUp that automates the creation of residential floor plan layouts from JSON files. The extension automatically generates walls, doors, and windows in SketchUp 3D models.

Objective

Simplify the process of creating architectural floor plans in SketchUp, allowing architects and designers to import structured data and automatically generate 3D models.

Technologies

Ruby (version compatible with SketchUp)
SketchUp Ruby API
JSON for data input

System Architecture

Architecture Diagram

graph TB
    subgraph "SketchUp Environment"
        A[Menu Plugins] --> B[LayoutGenerator Module]
        B --> C[import_json_layout]
    end
    
    subgraph "Input Layer"
        C --> D[UI.openpanel]
        D --> E[JSON File]
    end
    
    subgraph "Processing Layer"
        E --> F[JSONParser]
        F --> G[Validation]
        G --> H[Room Objects]
    end
    
    subgraph "Generation Layer"
        H --> I[WallGenerator]
        H --> J[DoorGenerator]
        H --> K[WindowGenerator]
        I --> L[SketchUp Model]
        J --> L
        K --> L
    end
    
    subgraph "Configuration"
        M[Config Module] --> I
        M --> J
        M --> K
    end
    
    L --> N[3D Visualization]

Diagram Organization Explanation

The architecture diagram is organized into 5 distinct layers that represent the flow of data and responsibilities in the system:

1. SketchUp Environment (Top Layer - Entry Point)

Represents the user interaction within SketchUp
A → B → C: User clicks menu item → Loads LayoutGenerator module → Calls import_json_layout method
This is the entry point where the process begins

2. Input Layer (Data Acquisition)

Handles user input and file selection
C → D → E: Method calls file dialog → User selects file → JSON file is loaded
This layer is responsible for obtaining the input data

3. Processing Layer (Data Transformation)

Transforms raw JSON into structured Ruby objects
E → F → G → H: JSON file → Parser reads it → Validates structure → Creates Room objects
This layer validates and structures the input data

4. Generation Layer (3D Creation)

Creates the actual 3D geometry in SketchUp
H → I, J, K: Room objects feed into three parallel generators (Walls, Doors, Windows)
I, J, K → L: All generators output to the SketchUp Model
This layer generates the 3D geometry based on processed data

5. Configuration Layer (Cross-Cutting Concern)

Provides constants and settings to all generators
M → I, J, K: Config module supplies default values to all three generators
This is a shared resource used by all generation components

Final Output: L → N: The SketchUp Model is rendered as 3D Visualization

Key Design Principles:

Top-to-bottom flow: Data flows from user interaction down to 3D visualization
Separation of concerns: Each layer has a specific responsibility
Parallel processing: Wall, Door, and Window generators work independently
Shared configuration: Config module is used by all generators without direct data flow dependency

Architectural Pattern

The project follows a modular pattern with separation of concerns:

Interface Layer: SketchUp menus and dialogs
Processing Layer: Parser and data validation
Generation Layer: 3D geometry creation
Configuration Layer: Constants and standards

File Structure

ruby-sketchup/
├── layout_generator/
│   ├── layout_generator.rb    # Main file and entry point
│   ├── config.rb               # Configuration and constants
│   ├── json_parser.rb          # JSON parser and validation
│   ├── wall_generator.rb       # Wall generation
│   ├── door_generator.rb       # Door generation
│   └── window_generator.rb     # Window generation
└── examples/
    └── example_layout.json     # Example JSON file

Module Hierarchy

LayoutGenerator (main module)
├── Config (configuration module)
├── JSONParser (class)
│   ├── Room (data class)
│   ├── Door (data class)
│   └── Window (data class)
├── WallGenerator (class)
├── DoorGenerator (class)
└── WindowGenerator (class)

Main Components

1. LayoutGenerator (layout_generator.rb)

Responsibility: Entry point of the extension, process coordination, and user interface.

Main Features:

Plugin registration in SketchUp
Adding item to "Plugins" menu
Import flow coordination
Error handling and user feedback

Main Methods:

import_json_layout: Main method that orchestrates the entire process

2. Config (config.rb)

Responsibility: Centralize all system configurations and constants.

Defined Constants:

Default dimensions (wall thickness, height, etc.)
Door and window dimensions
Default colors (RGB)
Wall directions (north, south, east, west)
Geometric tolerances

Usage Example:

Config::WALL_THICKNESS  # 0.15m
Config::DOOR_WIDTH      # 0.90m
Config::WALL_COLOR      # [200, 200, 200]

3. JSONParser (json_parser.rb)

Responsibility: Parse, validate, and structure JSON data into Ruby objects.

Data Classes:

Room: Represents a room with dimensions, position, doors, and windows
Door: Represents a door with position and dimensions
Window: Represents a window with position and dimensions

Implemented Validations:

JSON structure (must be object with 'rooms' key)
Valid dimensions (greater than zero)
Valid wall directions (north, south, east, west)
Required fields present

Main Methods:

parse: Parses and validates JSON
validate_structure: Validates general structure
parse_room: Parses an individual room
parse_door: Parses a door
parse_window: Parses a window

4. WallGenerator (wall_generator.rb)

Responsibility: Create 3D wall geometry based on room data.

Generation Process:

For each room, calculates the 4 corners
Creates 4 walls (north, south, east, west)
Calculates direction and perpendicular vectors
Creates groups in SketchUp for each wall
Extrudes faces to create 3D volume
Applies materials and colors
Stores metadata (attributes) in walls

Features:

Walls created as groups (facilitates modifications)
Metadata stored for later reference
Undo/redo support through SketchUp operations

5. DoorGenerator (door_generator.rb)

Responsibility: Create doors and openings in walls.

Generation Process:

Locates the wall corresponding to the room and direction
Calculates door position on the wall
Creates opening in the wall (cut)
Creates door geometry
Applies material and color

Opening Technique:

Creates cutting face on the wall surface
Uses pushpull to create the hole
Ensures the opening goes through the entire wall thickness

6. WindowGenerator (window_generator.rb)

Responsibility: Create windows and openings in walls.

Similar Process to DoorGenerator:

Locates wall
Calculates position (considers sill height)
Creates opening
Creates window frame
Applies material

Differences:

Considers sill height (WINDOW_SILL_HEIGHT)
Creates frame with defined thickness

Data Flow

Sequence Diagram

sequenceDiagram
    participant U as User
    participant S as SketchUp
    participant LG as LayoutGenerator
    participant JP as JSONParser
    participant WG as WallGenerator
    participant DG as DoorGenerator
    participant WG2 as WindowGenerator
    participant M as Model

    U->>S: Clicks "Import Layout JSON..."
    S->>LG: import_json_layout()
    LG->>U: Opens file selection dialog
    U->>LG: Selects JSON file
    LG->>JP: new(json_data)
    LG->>JP: parse()
    JP->>JP: validate_structure()
    JP->>JP: extract_rooms()
    JP-->>LG: Returns rooms[]
    
    alt Invalid JSON
        LG->>U: Displays errors
    else Valid JSON
        LG->>M: start_operation()
        LG->>WG: new(model, rooms)
        LG->>WG: generate()
        WG->>M: Creates walls (groups)
        WG-->>LG: Returns walls[]
        
        LG->>DG: new(model, rooms, walls)
        LG->>DG: generate()
        DG->>M: Creates doors and openings
        DG-->>LG: Complete
        
        LG->>WG2: new(model, rooms, walls)
        LG->>WG2: generate()
        WG2->>M: Creates windows and openings
        WG2-->>LG: Complete
        
        LG->>M: commit_operation()
        LG->>U: Displays success message
    end

Processing Flow

1. INPUT
   └─> JSON file selected by user

2. PARSE AND VALIDATION
   └─> JSONParser validates structure
   └─> Extracts data into Room, Door, Window objects
   └─> Returns error list if any

3. GEOMETRY GENERATION
   ├─> WallGenerator: Creates 3D walls
   │   └─> For each room: 4 walls (N, S, E, W)
   │   └─> Stores metadata in walls
   │
   ├─> DoorGenerator: Creates doors
   │   └─> Locates corresponding wall
   │   └─> Creates opening in wall
   │   └─> Creates door geometry
   │
   └─> WindowGenerator: Creates windows
       └─> Locates corresponding wall
       └─> Creates opening in wall
       └─> Creates window frame

4. OUTPUT
   └─> 3D model in SketchUp
   └─> Visual feedback to user

User Interface

Visual Interface Structure

1. SketchUp Menu

┌─────────────────────────────────────┐
│  SketchUp Menu Bar                  │
├─────────────────────────────────────┤
│  File  Edit  View  Camera  Draw    │
│  Tools  Window  Plugins  Help       │
│              ┌──────────────────┐  │
│              │ Import Layout     │  │
│              │ JSON...           │  │
│              └──────────────────┘  │
└─────────────────────────────────────┘

2. File Selection Dialog

┌─────────────────────────────────────────────┐
│  Import Layout JSON                         │
├─────────────────────────────────────────────┤
│                                             │
│  Navigate to locate .json file              │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │  📁 Documents                       │   │
│  │  📁 Desktop                          │   │
│  │  📄 example_layout.json              │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  [Cancel]              [Open]               │
└─────────────────────────────────────────────┘

3. Success Message

┌─────────────────────────────────────────────┐
│  Layout imported successfully!              │
│                                             │
│  Rooms: 3                                   │
│                                             │
│                    [OK]                     │
└─────────────────────────────────────────────┘

4. Error Message

┌─────────────────────────────────────────────┐
│  Errors found:                              │
│                                             │
│  • Room 'Living Room': 'width' is required │
│  • Door in room 'Bedroom': 'wall' must be  │
│    'north', 'south', 'east' or 'west'      │
│                                             │
│                    [OK]                     │
└─────────────────────────────────────────────┘

SketchUp Viewport (Result)

┌─────────────────────────────────────────────────────┐
│  SketchUp Viewport                                  │
├─────────────────────────────────────────────────────┤
│                                                     │
│         ┌─────────────┐                            │
│         │             │                            │
│         │  Bedroom 1  │                            │
│         │             │                            │
│         └──────┬──────┘                            │
│                │                                    │
│         ┌──────┴──────┐                            │
│         │             │                            │
│         │ Living Room │                            │
│         │             │                            │
│         └──────┬──────┘                            │
│                │                                    │
│         ┌──────┴──────┐                            │
│         │             │                            │
│         │  Kitchen    │                            │
│         │             │                            │
│         └─────────────┘                            │
│                                                     │
│  [Walls in gray]                                  │
│  [Doors in brown]                                 │
│  [Windows in light blue]                          │
└─────────────────────────────────────────────────────┘

JSON Format

Complete Structure

{
  "rooms": [
    {
      "name": "Room Name",
      "width": 4.0,
      "length": 5.0,
      "position": {
        "x": 0.0,
        "y": 0.0
      },
      "doors": [
        {
          "wall": "north",
          "position": 2.0,
          "width": 0.90
        }
      ],
      "windows": [
        {
          "wall": "south",
          "position": 2.5,
          "width": 1.5,
          "height": 1.2
        }
      ]
    }
  ]
}

Field Specification

Room

name (string, optional): Room name. Default: "Room N"
width (number, required): Width in meters
length (number, required): Length in meters
position (object, optional): Position of bottom-left corner
- x (number): X coordinate in meters. Default: 0.0
- y (number): Y coordinate in meters. Default: 0.0
doors (array, optional): List of doors
windows (array, optional): List of windows

Door

wall (string, required): Wall direction ("north", "south", "east", "west")
position (number, optional): Position along the wall in meters (from start). Default: center of wall
width (number, optional): Door width in meters. Default: 0.90m

Window

wall (string, required): Wall direction ("north", "south", "east", "west")
position (number, optional): Position along the wall in meters. Default: center of wall
width (number, optional): Window width in meters. Default: 1.20m
height (number, optional): Window height in meters. Default: 1.20m

Complete Example

See the examples/example_layout.json file for a complete example with multiple rooms.

Installation and Usage

Installation

Locate SketchUp plugins directory:
- Windows: C:\Users\[User]\AppData\Roaming\SketchUp\SketchUp [Version]\SketchUp\Plugins\
- macOS: ~/Library/Application Support/SketchUp [Version]/SketchUp/Plugins/
- Linux: ~/.config/SketchUp [Version]/SketchUp/Plugins/
Copy layout_generator folder to the plugins directory
Restart SketchUp

Usage

Open SketchUp
Access menu: Plugins > Import Layout JSON...
Select JSON file in the dialog
Wait for processing:
- If there are errors, a message will be displayed
- If everything is correct, the layout will be generated automatically
View result in SketchUp viewport

Supported Operations

Undo/Redo: All operations are grouped into a single SketchUp operation, allowing to undo everything at once
Modification: Generated elements can be edited normally in SketchUp
Materials: Colors and materials can be changed after generation

Technical Considerations

Coordinate System

Origin: (0, 0, 0) - bottom-left corner of the first room
X Axis: East (right)
Y Axis: North (up)
Z Axis: Height (upward)

Wall Directions

North: Top wall (positive Y)
South: Bottom wall (negative Y)
East: Right wall (positive X)
West: Left wall (negative X)

Units

All dimensions are in meters (metric system).

Tolerances

TOLERANCE: 0.001m (1mm) - used for geometric comparisons
Values smaller than tolerance are considered zero

Performance

Operations are grouped for efficiency
Use of SketchUp groups facilitates manipulation
Stored metadata allows quick reference

Extensibility

Adding New Elements

To add new elements (e.g., furniture, stairs), follow the pattern:

Create data class in JSONParser (if necessary)
Create specific generator (e.g., FurnitureGenerator)
Add call in layout_generator.rb
Add constants in config.rb (if necessary)

Modifying Standards

Edit the config.rb file to change:

Default dimensions
Colors
Tolerances
Directions

Troubleshooting

Common Issues

Plugin doesn't appear in menu:
- Check if folder was copied correctly
- Check if SketchUp was restarted
- Check Ruby console (Window > Ruby Console) for errors
Error importing JSON:
- Check JSON format (use online JSON validator)
- Check if all required fields are present
- Check if dimensions are valid numbers
Geometry doesn't appear:
- Check if viewport is in correct position (Zoom Extents)
- Check for errors in Ruby console
- Check if dimensions are reasonable (not too small)

Conclusion

The Layout Generator is a modular and extensible extension that simplifies the creation of architectural floor plans in SketchUp. Its architecture allows for easy maintenance and feature expansion.

For more information or support, consult the source code or contact the developer.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
examples		examples
layout_generator		layout_generator
README.md		README.md

agaragon/ruby-sketchup

Folders and files

Latest commit

History

Repository files navigation