# thomthom/bitmap-2-mesh architecture

> Architecture diagram of the GitHub repository thomthom/bitmap-2-mesh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thomthom/bitmap-2-mesh
- Repository: https://github.com/thomthom/bitmap-2-mesh

## Overview

##### Project type and purpose
- This is a Ruby-based SketchUp extension (“Bitmap to Mesh”) that reads bitmap (or heightmap) images and generates 2D/3D triangle meshes inside the SketchUp environment.
- Its primary use case is converting pixel data to geometry for terrains or pixel-based models.

##### File structure
Top‐level files:
– Gemfile, .rubocop.yml: Ruby gem and style config
– README.md, LICENSE.md: documentation and licensing
Folders of interest:
– docs/ (images used in the README)
– resources/ (sample heightmaps and SketchUp models for demos)
– src/tt_bitmap2mesh/ (the heart of the plugin)
- image processing (image/, helpers/)
- heightmap sampling and core mesh logic (heightmap.rb, sampler.rb, core.rb)
- UI tools and SketchUp integration (bootstrap.rb, place_mesh_tool.rb, cursor.rb, draggable.rb, leader.rb, text.rb)
- error handling (error_reporter/)
- debug & profiling (debug.rb, debug_tools.rb, profiling/)
– tests/ (unit‐test helpers)

##### README for additional insights
- Describes two main features: “Mesh from Heightmap” and “Mesh from Bitmap.”
- Lists SketchUp menu/toolbar integration points.
- Notes performance considerations (large images → many faces → slow generation).

##### Main components & their relationships
a. UI & Bootstrap Layer
- bootstrap.rb registers menu items and context‐menu commands in SketchUp
- When the user invokes “Mesh From Heightmap/Bitmap,” SketchUp hands control to a Tool object (place_mesh_tool.rb)
b. Configuration & Error Reporting
- settings.rb reads default and user preferences
- error_reporter/* captures uncaught exceptions and renders an HTML/JS/CSS report in the user’s browser for easy debugging
c. Image‐to‐Data Conversion
- helpers/image* and image_rep handle pixel‐level data extraction
d. Mesh Generation Core
- core.rb orchestrates creation of vertices and faces (two triangles per pixel)
e. SketchUp API Integration
- place_mesh_tool.rb, cursor.rb, draggable.rb implement interactive placement of the generated mesh in the SketchUp scene
f. Debug & Profiling
- debug.rb, debug_tools.rb provide instrumentation hooks; profiling/ scripts to measure performance

##### Architectural patterns & principles
- Layered approach:
– Presentation/UI layer (SketchUp menu & Tool classes)
– Application layer (bootstrap, command dispatch)
– Domain layer (image processing, sampling, mesh‐builder)
– Infrastructure (SketchUp API, file system for resources)
- Modularity: each responsibility lives in its own Ruby module/class
- Separation of concerns: error handling, config, and debugging are isolated from core logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI & Registration Layer
    subgraph "UI & Registration" 
        direction TB
        Boot["bootstrap.rb"]:::ui
        Settings["settings.rb"]:::ui
        PlaceTool["place_mesh_tool.rb"]:::ui
        Cursor["cursor.rb"]:::ui
        Draggable["draggable.rb"]:::ui
    end

    %% Domain Layer
    subgraph "Domain Core" 
        direction TB
        subgraph "Image Processing Module"
            direction TB
            Bitmap["bitmap.rb"]:::domain
            BMP["bmp.rb"]:::domain
            DIB["dib.rb"]:::domain
            Color["color.rb"]:::domain
            ImageRep["image_rep.rb"]:::domain
            ImgHelper["helpers/image.rb"]:::domain
            ImgRepHelper["helpers/image_rep.rb"]:::domain
        end
        subgraph "Sampling & Heightmap Module"
            direction TB
            Heightmap["heightmap.rb"]:::domain
            Sampler["sampler.rb"]:::domain
        end
        subgraph "Mesh Generation Core"
            direction TB
            Core["core.rb"]:::domain
            BoundingBox["bounding_box.rb"]:::domain
            Leader["leader.rb"]:::domain
            Text["text.rb"]:::domain
        end
    end

    %% Error Reporting & Debugging
    subgraph "Error Reporting & Debugging"
        direction TB
        ErrReporter["error_reporter.rb"]:::error
        ErrHTML["error_reporter.html"]:::error
        ErrCSS["error_reporter.css"]:::error
        ErrJS["error_reporter.js"]:::error
        JQuery["jquery.js"]:::error
        Debug["debug.rb"]:::error
        DebugTools["debug_tools.rb"]:::error
        Profiling["PR_HeightMap_generate.rb"]:::error
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        SUAPI["SketchUp Ruby API"]:::infra
        Resources["resources (heightmaps/models)"]:::infra
    end

    %% Data Flows and Dependencies
    User["SketchUp User"]:::external
    User -->|"invoke Mesh From Heightmap/Bitmap"| Boot
    Boot -->|"read settings"| Settings
    Boot -->|"register Tool"| PlaceTool
    PlaceTool -->|"cursor & draggable"| Cursor
    PlaceTool -->|"cursor & draggable"| Draggable
    PlaceTool -->|"load image"| Bitmap
    Bitmap --> BMP
    Bitmap --> DIB
    Bitmap --> Color
    Bitmap --> ImageRep
    Bitmap --> ImgHelper
    Bitmap --> ImgRepHelper
    ImageRep --> Heightmap
    Heightmap --> Sampler
    Sampler --> Core
    Core --> BoundingBox
    Core --> Leader
    Core --> Text
    Core -->|"generate entities"| SUAPI
    SUAPI -->|"insert into scene"| Resources

    %% Error Flow
    Bitmap -.->|exception| ErrReporter
    Heightmap -.->|exception| ErrReporter
    Core -.->|exception| ErrReporter
    ErrReporter -->|"render report"| ErrHTML
    ErrHTML --> ErrCSS
    ErrHTML --> ErrJS
    ErrHTML --> JQuery

    %% Click Events
    click Boot "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/bootstrap.rb"
    click PlaceTool "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/place_mesh_tool.rb"
    click Cursor "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/cursor.rb"
    click Draggable "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/draggable.rb"
    click Settings "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/settings.rb"
    click ErrReporter "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/error_reporter/error_reporter.rb"
    click ErrHTML "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/error_reporter/error_reporter.html"
    click ErrCSS "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/error_reporter/error_reporter.css"
    click ErrJS "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/error_reporter/error_reporter.js"
    click JQuery "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/error_reporter/jquery.js"
    click Bitmap "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/bitmap.rb"
    click BMP "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/image/bmp.rb"
    click DIB "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/image/dib.rb"
    click Color "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/image/color.rb"
    click ImageRep "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/image/image_rep.rb"
    click ImgHelper "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/helpers/image.rb"
    click ImgRepHelper "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/helpers/image_rep.rb"
    click Heightmap "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/heightmap.rb"
    click Sampler "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/sampler.rb"
    click Core "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/core.rb"
    click BoundingBox "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/bounding_box.rb"
    click Leader "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/leader.rb"
    click Text "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/text.rb"
    click Debug "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/debug.rb"
    click DebugTools "https://github.com/thomthom/bitmap-2-mesh/blob/master/src/tt_bitmap2mesh/debug_tools.rb"
    click Profiling "https://github.com/thomthom/bitmap-2-mesh/blob/master/profiling/PR_HeightMap_generate.rb"

    %% Styles
    classDef ui fill:#cfe2f3,stroke:#06529c,color:#06529c;
    classDef domain fill:#d9ead3,stroke:#274e13,color:#274e13;
    classDef infra fill:#fce5cd,stroke:#a64d14,color:#a64d14;
    classDef error fill:#f4cccc,stroke:#990000,color:#990000;
    classDef external fill:#ffffff,stroke:#666666,color:#666666,stroke-dasharray: 5 5;
    class User external
```
