# tabithabragg/groundcontrol architecture

> Architecture diagram of the GitHub repository tabithabragg/groundcontrol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tabithabragg/groundcontrol
- Repository: https://github.com/tabithabragg/groundcontrol

## Overview

1. This repository is a suite of native DCC plug-ins, not a single application. The code is split primarily by host platform: `CarraraExtensions` for Carrara, and `LightwavePlugins` for Lightwave. Each plug-in lives in its own folder and is built as a separate binary/module that the host application loads.

2. The architecture is “plugin-per-feature.” Most folders map to one installable plug-in package with its own entrypoint file (`*DLL.cpp`, `gcMain.c`, etc.), public headers, and host-specific resource files (`.def`, `.r`, `.rsr`, `.plist`, Visual Studio/Xcode projects). The host app is the runtime container; this repo provides modules that extend import, geometry generation, shading, deformation, and rendering behavior.

3. The largest functional area is terrain and geodata. `GroundControl` is the main terrain/geodata subsystem in Carrara, with supporting types for elevation meshes, shapefiles, DEMs, water, bump/shader filters, and generators. The Lightwave side also has a `GroundControl` plug-in with file loading and mesh-building code (`gcImageLoad.c`, `gcMeshload.c`, `gcMain.c`). This area is backed by a shared C library under `Library/GroundControl`, which contains low-level mesh, binary tree, math, and data helpers used by the plug-in layer.

4. Geometry generation is another major subsystem. `AnythingGrooves` contains primitive generators such as cone, cube, cylinder, plane, and sphere, plus conversion-to-mesh logic. `AnythingGrows` adds procedural growth/hair-style generation with a primitive, deformer, billboard support, strand generator interface, and hair generator. These modules typically transform parametric inputs into mesh or strand data before handing it back to the host.

5. Shader and material extensions form a separate family. `ShaderOps`, `ShaderOps2`, `ShadersPlus`, `Shoestring_Shaders`, and `ShaderGel` are all collections of shader nodes/ops. They include color/math operators, UV transforms, mixing/compositing, gradients, lighting controls, and procedural effects. Architecturally, these modules sit inside the host’s shading pipeline and operate on material inputs/outputs rather than geometry.

6. Renderer-adjacent plug-ins are separated from pure shader nodes. `WireframePro`, `ToonPro`, `Noir`, `Parchment`, `StarBright`, and `Gemini` focus on non-photoreal or stylized rendering, selection/override behavior, wireframe display, toon/cell shading, and related rendering controls. The shared `WirerendererCommon` folder contains common data and state helpers for wire/toon rendering behavior across those plug-ins.

7. There is a smaller set of scene/utility plug-ins that manipulate existing assets rather than generate new ones. `DCGImporter` handles sequenced OBJ import. `TerrainTools` contains operators for terrain editing and conversion tasks such as normal/terrain transforms, intersection, surf, cutout, and beach-related operations. `ShaderGel` and `Cognito` appear to be additional host extensions with their own module boundaries, likely using the same overall plug-in pattern.

8. Shared code is intentionally separated from plug-in wrappers. `CarraraExtensions/Common` holds reusable infrastructure: scene utilities, shader helpers, mesh accumulators, cache helpers, tree structures, debug/util macros, and generic math/random utilities. This is the “library layer” beneath several Carrara plug-ins, keeping mesh traversal, shader plumbing, and collection logic out of feature-specific modules.

9. The main data flow across the repo is: host application loads a plug-in module → plug-in presents UI or hooks into host events → plug-in reads scene/file/terrain/shader inputs → shared helpers build or transform mesh/shader/state data → results are returned to the host as geometry, shading results, or importer output. For ground/terrain features, the flow often starts from external data files and ends as terrain meshes, elevation maps, or water/bump/shader effects in the scene.

10. Build and packaging are host-specific and legacy-toolchain oriented. Many folders contain both Visual Studio and Xcode projects, indicating cross-platform builds for older plugin SDKs. The presence of `.def`, `.r`, and `.rsr` files suggests exported symbols plus host-specific resources/localization/UI assets are bundled per plug-in.

11. The repository structure also shows an active fork/maintenance story. The README explains that the Lightwave `GroundControl` plug-in is a development/testing build intended to load a `groundcontrol.p` plugin file into both Layout and Modeler, with compatibility work for Lightwave 2018–2020. So the repo is not only source code but also a distribution tree for multiple historical host integrations.

12. For an architecture diagram, the most important boundaries are: host application boundary, plug-in module boundary, shared-library boundary, and external data boundary. The host loads modules; modules depend on shared helpers; terrain/import plug-ins ingest external geodata; shader/render plug-ins sit inside the rendering pipeline; and geometry plug-ins synthesize meshes or strands that are handed back into the scene.

Main entry points: [`CarraraExtensions`](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions) (Carrara suite), [`CarraraExtensions/Common`](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/Common) (Common library), [`CarraraExtensions/GroundControl`](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/GroundControl) (GroundControl), [`LightwavePlugins`](https://github.com/tabithabragg/groundcontrol/tree/master/LightwavePlugins) (Lightwave suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_carrara["Carrara extensions"]
  node_carrara_bundle["Carrara suite<br/>plugin family"]
  node_groundcontrol_carrara["GroundControl<br/>terrain plugin"]
  node_terrain_tools["TerrainTools<br/>terrain operators"]
  node_anything_grooves["AnythingGrooves<br/>geometry generators"]
  node_anything_grows["AnythingGrows<br/>growth generator"]
  node_shader_ops["ShaderOps<br/>shader nodes"]
  node_shader_ops2["ShaderOps2<br/>shader nodes"]
  node_shaders_plus["ShadersPlus<br/>shader nodes"]
  node_shoestring_shaders["Shoestring Shaders<br/>shader nodes"]
  node_renderer_plugins["Stylized renderers<br/>render plugins"]
  node_wirerenderer_common["Wire common<br/>render helpers"]
  node_dcg_importer["DCGImporter<br/>import plugin"]
  node_gemini["Gemini<br/>scene tool"]
  node_cognito["Cognito<br/>plugin module"]
end

subgraph group_lightwave["Lightwave plugins"]
  node_lightwave_bundle["Lightwave suite<br/>plugin family"]
  node_groundcontrol_lw["GroundControl<br/>terrain plugin"]
  node_anything_goos_lw["AnythingGoos<br/>geometry plugin"]
end

subgraph group_shared["Shared code"]
  node_shared_common["Common library<br/>shared helpers"]
  node_groundcontrol_lib["GroundControlLib<br/>c library"]
end

node_host["DCC host<br/>runtime"]
node_external_data["External data<br/>inputs"]

node_host -->|"loads"| node_carrara_bundle
node_host -->|"loads"| node_lightwave_bundle
node_carrara_bundle -->|"contains"| node_groundcontrol_carrara
node_carrara_bundle -->|"contains"| node_terrain_tools
node_carrara_bundle -->|"contains"| node_anything_grooves
node_carrara_bundle -->|"contains"| node_anything_grows
node_carrara_bundle -->|"contains"| node_shader_ops
node_carrara_bundle -->|"contains"| node_shader_ops2
node_carrara_bundle -->|"contains"| node_shaders_plus
node_carrara_bundle -->|"contains"| node_shoestring_shaders
node_carrara_bundle -->|"contains"| node_renderer_plugins
node_renderer_plugins -.->|"shares"| node_wirerenderer_common
node_carrara_bundle -.->|"uses"| node_shared_common
node_groundcontrol_carrara -.->|"uses"| node_groundcontrol_lib
node_groundcontrol_carrara -->|"reads"| node_external_data
node_terrain_tools -.->|"uses"| node_shared_common
node_anything_grooves -.->|"uses"| node_shared_common
node_anything_grows -.->|"uses"| node_shared_common
node_shader_ops -.->|"uses"| node_shared_common
node_shader_ops2 -.->|"uses"| node_shared_common
node_shaders_plus -.->|"uses"| node_shared_common
node_shoestring_shaders -.->|"uses"| node_shared_common
node_dcg_importer -->|"imports"| node_external_data
node_dcg_importer -.->|"uses"| node_shared_common
node_gemini -.->|"uses"| node_shared_common
node_cognito -.->|"uses"| node_shared_common
node_lightwave_bundle -->|"contains"| node_groundcontrol_lw
node_lightwave_bundle -->|"contains"| node_anything_goos_lw
node_groundcontrol_lw -->|"reads"| node_external_data
node_groundcontrol_lw -.->|"uses"| node_groundcontrol_lib
node_anything_goos_lw -.->|"uses"| node_shared_common

click node_carrara_bundle "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions"
click node_lightwave_bundle "https://github.com/tabithabragg/groundcontrol/tree/master/LightwavePlugins"
click node_groundcontrol_carrara "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/GroundControl"
click node_terrain_tools "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/TerrainTools"
click node_anything_grooves "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/AnythingGrooves"
click node_anything_grows "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/AnythingGrows"
click node_shader_ops "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/ShaderOps"
click node_shader_ops2 "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/ShaderOps2"
click node_shaders_plus "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/ShadersPlus"
click node_shoestring_shaders "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/Shoestring_Shaders"
click node_renderer_plugins "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions"
click node_wirerenderer_common "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/WirerendererCommon"
click node_shared_common "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/Common"
click node_groundcontrol_lib "https://github.com/tabithabragg/groundcontrol/tree/master/Library/GroundControl"
click node_dcg_importer "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/DCGImporter"
click node_gemini "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/Gemini"
click node_cognito "https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/Cognito"
click node_groundcontrol_lw "https://github.com/tabithabragg/groundcontrol/tree/master/LightwavePlugins/GroundControl"
click node_anything_goos_lw "https://github.com/tabithabragg/groundcontrol/tree/master/LightwavePlugins/AnythingGoos"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_carrara_bundle,node_groundcontrol_carrara,node_terrain_tools,node_anything_grooves,node_anything_grows,node_shader_ops,node_shader_ops2,node_shaders_plus,node_shoestring_shaders,node_renderer_plugins,node_wirerenderer_common,node_dcg_importer,node_gemini,node_cognito toneBlue
class node_lightwave_bundle,node_groundcontrol_lw,node_anything_goos_lw toneAmber
class node_shared_common,node_groundcontrol_lib toneMint
class node_host,node_external_data toneNeutral
```

## Components

### Carrara extensions

Host-specific plug-in modules for Carrara, organized by feature package.

- [Carrara suite](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions): plugin family · Main Carrara plug-in collection with geometry, terrain, shader, and renderer extensions. · `CarraraExtensions`
- [GroundControl](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/GroundControl): terrain plugin · Carrara terrain and geodata subsystem with DEM, shapefile, water, bump, and shader support. · `CarraraExtensions/GroundControl`
- [TerrainTools](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/TerrainTools): terrain operators · Carrara terrain editing and conversion operators such as normal, surf, cutout, beach, and intersection tools. · `CarraraExtensions/TerrainTools`
- [AnythingGrooves](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/AnythingGrooves): geometry generators · Carrara primitive generators and mesh conversion pipeline for parametric solids. · `CarraraExtensions/AnythingGrooves`
- [AnythingGrows](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/AnythingGrows): growth generator · Carrara procedural growth, hair, strand, billboard, and deformer module. · `CarraraExtensions/AnythingGrows`
- [ShaderOps](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/ShaderOps): shader nodes · Carrara shader operators for math, UV transforms, thresholds, scaling, and gradients. · `CarraraExtensions/ShaderOps`
- [ShaderOps2](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/ShaderOps2): shader nodes · Carrara multi-input shader operators and space/UV manglers. · `CarraraExtensions/ShaderOps2`
- [ShadersPlus](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/ShadersPlus): shader nodes · Carrara shading controls for anisotropy, GI, masks, lighting, and procedural effects. · `CarraraExtensions/ShadersPlus`
- [Shoestring Shaders](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/Shoestring_Shaders): shader nodes · Carrara shader collection including mix, fresnel, location, proximity, and multi-pass controls. · `CarraraExtensions/Shoestring_Shaders`
- [Stylized renderers](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions): render plugins · Carrara non-photoreal and wireframe rendering extensions. · `CarraraExtensions`
- [Wire common](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/WirerendererCommon): render helpers · Shared data and state helpers for wireframe and toon rendering behavior. · `CarraraExtensions/WirerendererCommon`
- [DCGImporter](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/DCGImporter): import plugin · Carrara sequenced OBJ importer built as a separate plug-in module. · `CarraraExtensions/DCGImporter`
- [Gemini](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/Gemini): scene tool · Carrara command/deformer plug-in for scene manipulation. · `CarraraExtensions/Gemini`
- [Cognito](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/Cognito): plugin module · Carrara host extension with its own plug-in boundary. · `CarraraExtensions/Cognito`

### Lightwave plugins

Host-specific plug-in modules for Lightwave, organized by feature package.

- [Lightwave suite](https://github.com/tabithabragg/groundcontrol/tree/master/LightwavePlugins): plugin family · Lightwave plug-in collection centered on GroundControl and geometry generation. · `LightwavePlugins`
- [GroundControl](https://github.com/tabithabragg/groundcontrol/tree/master/LightwavePlugins/GroundControl): terrain plugin · Lightwave GroundControl plug-in for loading terrain and building meshes. · `LightwavePlugins/GroundControl`
- [AnythingGoos](https://github.com/tabithabragg/groundcontrol/tree/master/LightwavePlugins/AnythingGoos): geometry plugin · Lightwave geometry plug-in counterpart for primitive generation. · `LightwavePlugins/AnythingGoos`

### Shared code

Reusable support libraries and common helpers shared by plug-in wrappers.

- [Common library](https://github.com/tabithabragg/groundcontrol/tree/master/CarraraExtensions/Common): shared helpers · Carrara reusable infrastructure for scene, shader, mesh, cache, tree, and utility code. · `CarraraExtensions/Common`
- [GroundControlLib](https://github.com/tabithabragg/groundcontrol/tree/master/Library/GroundControl): c library · Low-level shared C library for GroundControl mesh, binary tree, and math helpers. · `Library/GroundControl`

### Other components

- **DCC host**: runtime · Carrara or Lightwave loads these modules as native plug-ins.
- **External data**: inputs · Terrain, geodata, OBJ, and scene inputs consumed by import and terrain modules.

## Connections

- DCC host → Carrara suite: loads · Carrara hosts load the Carrara extension modules.
- DCC host → Lightwave suite: loads · Lightwave hosts load the Lightwave plug-ins.
- Carrara suite → GroundControl: contains · Carrara GroundControl package.
- Carrara suite → TerrainTools: contains · Carrara terrain operators.
- Carrara suite → AnythingGrooves: contains · Carrara primitive generators.
- Carrara suite → AnythingGrows: contains · Carrara growth and hair tools.
- Carrara suite → ShaderOps: contains · Carrara shader operator set.
- Carrara suite → ShaderOps2: contains · Carrara second shader operator set.
- Carrara suite → ShadersPlus: contains · Carrara shader and lighting controls.
- Carrara suite → Shoestring Shaders: contains · Carrara shader collection package.
- Carrara suite → Stylized renderers: contains · Carrara stylized rendering plug-ins.
- Stylized renderers → Wire common: shares · Wireframe and toon plug-ins reuse common rendering state and helpers.
- Carrara suite → Common library: uses · Many Carrara modules depend on shared helpers.
- GroundControl → GroundControlLib: uses · Carrara GroundControl depends on shared low-level terrain logic.
- GroundControl → External data: reads · Terrain and geodata inputs feed the plug-in.
- TerrainTools → Common library: uses · Terrain tools reuse shared mesh and scene utilities.
- AnythingGrooves → Common library: uses · Primitive generation and mesh conversion reuse common helpers.
- AnythingGrows → Common library: uses · Growth and strand generation reuse common helpers.
- ShaderOps → Common library: uses · Shader nodes rely on shared shader and utility helpers.
- ShaderOps2 → Common library: uses · Advanced shader nodes rely on shared helpers.
- ShadersPlus → Common library: uses · Shader extensions share infrastructure helpers.
- Shoestring Shaders → Common library: uses · Shader collection reuses shared Carrara infrastructure.
- DCGImporter → External data: imports · Sequenced OBJ content is brought into the host scene.
- DCGImporter → Common library: uses · Importer logic uses shared sequencing and mesh helpers.
- Gemini → Common library: uses · Scene tool relies on shared Carrara infrastructure.
- Cognito → Common library: uses · Plug-in boundary likely built atop shared Carrara utilities.
- Lightwave suite → GroundControl: contains · Lightwave GroundControl package.
- Lightwave suite → AnythingGoos: contains · Lightwave geometry package.
- GroundControl → External data: reads · GroundControl loads terrain data and builds meshes.
- GroundControl → GroundControlLib: uses · Lightwave GroundControl reuses the shared C terrain library.
- AnythingGoos → Common library: uses · Lightwave geometry code shares common math and mesh helpers.