ctgui - Graphical User Interface Library for Pure Data

ctgui is a collection of graphical user interfaces (GUIs) written in Pure Data Lua (pd_lua), specially designed to complement the Pure Data version of conTorchionist. While originally developed for conTorchionist's machine learning audio processing workflows, ctgui also provides general-purpose GUI objects that can be used in any Pure Data patch.

Overview

ctgui bridges the gap between complex audio processing functionality and intuitive visual control. It provides both specialized interfaces for conTorchionist's audio analysis tools and general-purpose widgets that enhance the Pure Data patching experience.

Features

Specialized conTorchionist Interfaces

• ctgui.amb.directivity: Visual control for ambisonic directivity patterns
• ctgui.specradar: Spectral radar visualization and control
• ctgui.vu: VU meter with visual feedback
• ctgui.vulabel: Labeled VU meter
• ctgui.vuscale: Scalable VU meter display

General-Purpose GUI Objects

• ctgui.slider: Vertical or horizontal slider for continuous parameter control
• ctgui.rslider: Range slider for controlling minimum and maximum values simultaneously
• ctgui.play: Play/pause button with visual state indication
• ctgui.record: Record button with visual state indication
• ctgui.clock: Clock display for timing information
• ctgui.numbox: Number box for numerical input/output

Project Structure

ctgui/
├── doc/                    # Documentation files
│   ├── ctgui.slider.md
│   ├── easings.md
│   └── pd_arg_parser_README.md
├── help/                   # Help patches for each GUI object
│   ├── ctgui-help.pd
│   ├── ctgui.amb.directivity-help.pd
│   ├── ctgui.play-help.pd
│   ├── ctgui.rslider-help.pd
│   ├── ctgui.slider-help.pd
│   ├── ctgui.specradar-help.pd
│   └── ctgui.vu-help.pd
└── src/                    # Source code
    ├── colors.lua          # Color definitions
    ├── pd_arg_parser.lua   # Argument parsing utility
    └── *.pd_lua            # GUI object implementations

Requirements

• Pure Data 0.54 or later, OR
• PlugData (any recent version)
• pd-lua external (usually bundled with Pure Data/PlugData)

Installation

Building from Source

ctgui uses CMake for building and installation:

# Configure the project
cmake -B build

# Build (copies files to distribution directory)
cmake --build build

Installing to Pure Data

To install ctgui to your Pure Data externals directory (~/Documents/Pd/externals/):

cmake --build build --target install-puredata

The ctgui objects will be installed to:

~/Documents/Pd/externals/ctgui/

Installing to PlugData

To install ctgui to your PlugData externals directory (~/Documents/plugdata/Externals/):

cmake --build build --target install-plugdata

The ctgui objects will be installed to:

~/Documents/plugdata/Externals/ctgui/

Installing to Both

To install to both Pure Data and PlugData simultaneously:

cmake --install build

Usage

After installation, you can use ctgui objects in your patches:

1. Create a new Pure Data patch

2. Add the ctgui directory to your search path (if not automatically detected):

   • In Pure Data: Preferences → Path → Add... → Select the ctgui directory
   • In PlugData: Usually automatic if installed in the Externals directory

3. Create objects by typing their names in object boxes:

   [ctgui.slider]
   [ctgui.rslider]
   [ctgui.vu]
   [ctgui.play]
   

4. Right-click on any ctgui object and select Help to open its help patch with usage examples

Integration with conTorchionist

ctgui was specifically designed to work seamlessly with conTorchionist's Pure Data externals:

• ctgui.specradar provides visual control for spectral trail analysis
• ctgui.amb.directivity controls ambisonics spatial directivity patterns
• ctgui.vu displays audio level meters for monitoring conTorchionist's audio processing

Example patch using ctgui with conTorchionist:

[adc~]
|
[torch.amb.spectrails~]
|
[ctgui.specradar]

Documentation

Detailed documentation for each object can be found in:

• Help patches: help/*.pd - Interactive examples for each GUI object
• Documentation files: doc/*.md - Technical documentation and implementation details

Color Customization

All ctgui objects use the shared colors.lua module, which defines a consistent color palette. You can customize the appearance by editing the color definitions in src/colors.lua.

Development

ctgui is written in Lua using the pd-lua framework, which allows for rapid prototyping and easy customization. Each GUI object is a standalone .pd_lua file that can be modified independently.

Utilities

• pd_arg_parser.lua: A helper module for parsing Pure Data object arguments consistently across all ctgui objects

Acknowledgments

• Pure Data by Miller Puckette
• pd-lua by Claude Heiland-Allen and contributors
• conTorchionist audio processing framework

---

Note: ctgui objects require pd-lua to be installed and working in your Pure Data or PlugData environment. If objects don't load, ensure pd-lua is properly installed.