ChannelSmith

Texture Channel Packing/Unpacking Tool for Game Development

📖 What is ChannelSmith?

ChannelSmith is a desktop application that allows game developers and technical artists to efficiently manage texture channel packing. It reduces texture memory usage by combining multiple grayscale maps (Roughness, Metallic, Ambient Occlusion, etc.) into a single RGBA image.

Key Features

✅ Pack multiple grayscale textures into one RGBA image
✅ Unpack existing packed textures to extract individual channels
✅ Repack textures with different template formats (e.g., ORM → ORD)
✅ Replace individual channels without recreating entire textures
✅ Smart defaults for missing texture channels
✅ Template system with predefined and custom packing configurations

Benefits

📉 Reduce memory usage by ~75% (4 textures → 1)
⚡ Faster loading times in game engines
🔄 Flexible workflows for different engine requirements
🎯 Industry-standard templates (ORM, ORD)

📥 Download & Run

Standalone Executable (Easiest)

No Python required! Download the latest release:

Platform	Download
Windows 10+	ChannelSmith-Windows.zip
macOS 12+	ChannelSmith-macOS.zip
Linux	ChannelSmith-Linux.tar.gz

Extract and double-click to run. Browser opens automatically.

See full installation guide →

🚀 Quick Start

Prerequisites

Python 3.8 or higher
pip (Python package manager)

Installation

Clone or download the project:

git clone <repository-url>
cd ChannelSmith

Create virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```

Usage - Web UI (Recommended) 🌐

ChannelSmith features a modern web-based interface with Flask backend and Tailwind CSS styling!

Windows

Double-click launch_web_ui.bat or run:

python -m channelsmith

macOS / Linux

Make scripts executable (first time only):

chmod +x launch_web_ui.sh launch_simple.sh install.sh

Then run the launcher:

./launch_web_ui.sh

Or for setup first time:

./install.sh

The browser opens automatically at http://localhost:5000

Web UI Features

🎨 Modern Dark Theme - Professional Tailwind CSS design
🖱️ Drag-and-Drop - Upload images by dragging to zones
👁️ Live Preview - See channels in real-time as you upload
📥 Download Results - Get packed or unpacked images instantly
🚀 No External Tools - Everything in your browser

Web UI Workflow

Pack Textures:

Open http://localhost:5000 (auto-opens in browser)
Stay on "Pack Channels" tab
Select template (ORM, ORD, etc.)
Drag or click to upload Red, Green, Blue channels
(Alpha channel optional)
Click "Pack Texture"
Download packed PNG immediately

Unpack Textures:

Switch to "Unpack Texture" tab
Upload your packed texture
Select correct template
Click "Unpack Texture"
Download extracted channels as individual PNG files

Complete Testing Guide

See WEB_UI_TESTING.md for:

Automated API tests (22 tests, all passing)
Manual testing workflows
Edge case testing
Browser compatibility
Performance benchmarks

Programmatic API (Python)

For automation or scripting:

from channelsmith.core.packing_engine import pack_texture_from_template
from channelsmith.templates.template_loader import load_template
from channelsmith.utils.image_utils import load_image, save_image

# Load template
template = load_template("channelsmith/templates/orm.json")

# Load individual texture maps
ao_map = load_image("textures/ao.png")
roughness_map = load_image("textures/roughness.png")
metallic_map = load_image("textures/metallic.png")

# Pack into single texture
textures = {
    'ambient_occlusion': ao_map,
    'roughness': roughness_map,
    'metallic': metallic_map
}

packed = pack_texture_from_template(textures, template)

# Save result
save_image(packed, "output/material_orm.png")

📚 Documentation

Installation & Getting Started

INSTALL.md ⭐ START HERE - Complete installation guide (3 methods)
SETUP.md - Environment setup for developers
cs_wiki.md - User guide with workflows and FAQs (also in-app)

Testing & Development

WEB_UI_TESTING.md - Web UI testing guide
CONTRIBUTING.md - How to contribute and code standards
CLAUDE.md - Architecture and development guidelines

Release Information

CHANGELOG.md - Version history and release notes
docs/RELEASE_PROCESS.md - Release workflow (maintainers)

🏗️ Project Structure

ChannelSmith/
├── channelsmith/               # Main package
│   ├── core/                  # Packing/unpacking engine
│   ├── api/                   # Flask REST API (NEW)
│   │   ├── app.py            # Flask app factory
│   │   ├── routes.py         # API endpoints (pack, unpack, templates)
│   │   └── utils.py          # Image utilities & validation
│   ├── frontend/              # Web UI
│   │   ├── index.html        # Single-page app
│   │   ├── styles.css        # Tailwind CSS styling
│   │   └── app.js            # Vanilla JavaScript logic
│   ├── templates/             # Template JSON files & loader
│   └── utils/                 # Utilities
├── tests/
│   ├── test_api/             # API endpoint tests
│   ├── test_core/            # Core engine tests
│   └── ...
├── docs/                      # Documentation
├── WEB_UI_TESTING.md          # Web UI testing guide (NEW)
├── SETUP.md                   # Installation guide
├── requirements.txt           # Python dependencies
└── README.md                  # This file

🛠️ Development Status

Current Phase: Post-Beta with Web MVP ✨

Goal: Deliver production-ready web UI with full pack/unpack workflows

Progress:

✅ Core packing/unpacking engine (Alpha - Complete)
✅ Template system with ORM/ORD templates
✅ Web UI MVP - Flask REST API + Tailwind CSS frontend (NEW)
✅ Full pack/unpack workflows
✅ Drag-and-drop support
✅ Live preview with Base64 encoding
✅ Browser auto-launch
✅ API tests (22 comprehensive tests, all passing)
✅ Core tests (207 tests, all passing, no regressions)
🔄 Advanced features (batch processing, custom templates UI)

Test Coverage:

Core Engine: 207 tests ✓
REST API: 22 tests ✓
Total: 229 tests passing

Roadmap

Alpha: Core engine ✅
Beta: Web MVP with Flask + Tailwind ✅
RC: Bug fixes, performance optimization, advanced features
v1.0: Production release

🧪 Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=channelsmith --cov-report=html

# Run specific test file
pytest tests/test_core/test_packing_engine.py

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for:

Code of conduct Development setup Coding standards Pull request process Testing requirements

This project is licensed under the MIT License - see LICENSE for details.

🎓 For Developers

First Time Setup

Read SETUP.md for environment setup
Read CLAUDE.md for architecture overview
Check ALPHA_TASKS.md for current tasks
Review docs/MVP_Documentation.md for full specs

Development Workflow

Activate virtual environment: source venv/bin/activate
Create feature: Work on dev branch
Write tests first (TDD approach)
- Core logic: tests/test_core/
- API endpoints: tests/test_api/
Format code: black channelsmith/
Run tests: pytest tests/ (expect 229+ passing)
Run API tests specifically: pytest tests/test_api/ -v
Commit: git commit -m "feat(scope): description"

Testing the Web UI

See WEB_UI_TESTING.md for complete guide including:

Quick start (2 minutes)
Automated API tests
Manual testing workflows
Edge case testing
Browser compatibility

Code Standards

File naming: snake_case
Type hints: Required on all functions
Docstrings: Google style, required on all public APIs
Testing: pytest, >80% coverage target
Formatting: black
Linting: pylint

📄 License

📞 Contact

GitHub Issues: Report bugs or request features
Email: For commercial inquiries or private discussions reach out to giuseppe.alfano.3d@gmail.com

Status: WebUI - Beta

Version: 0.3.0 Last Updated: February 9, 2026

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
channelsmith		channelsmith
docs		docs
imgs		imgs
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README.md		README.md
build_exe.bat		build_exe.bat
build_exe.sh		build_exe.sh
channelsmith.spec		channelsmith.spec
cs_wiki.md		cs_wiki.md
install.sh		install.sh
launch_simple.bat		launch_simple.bat
launch_simple.sh		launch_simple.sh
launch_web_ui.bat		launch_web_ui.bat
launch_web_ui.sh		launch_web_ui.sh
requirements.txt		requirements.txt
run_tests.bat		run_tests.bat

Latest commit

History

Folders and files

Repository files navigation