🐱 Gato

A neural network-powered ASCII/Braille cat animation with realistic eye movements, blinking, and mood-based expressions.

✨ Features

• Neural Network Control: All facial features (eyes, blinking, mouth, mood) are controlled by a custom neural network
• Stereo Audio Reactivity:
  • Distinguishes between left and right audio channels
  • Audio-Reactive Gaze: The cat looks towards the source of the sound
  • Enhanced Smoothing: Exponential smoothing for fluid, organic reactions
• Braille Canvas Rendering: High-resolution terminal graphics using Braille Unicode characters
• Rock-Solid Stability: Optimized for environmental reactivity (audio/time) with no input-related freezes
• Natural Animations:
  • Smooth eye tracking with attention system
  • Asymmetric blinking (fast close, smooth open)
  • Mood-driven expressions (ears, mouth, blush)
  • Breathing animations
• Multi-threaded Architecture: Separate render and logic loops with triple buffering for smooth 30 FPS animation
• Clean Codebase: Refactored with concise, essential comments

🎯 Neural Network Architecture

The brain uses a simple feedforward neural network:

• Input Layer: Time, attention coordinates, intensity
• Hidden Layer: 8 neurons with tanh activation
• Output Layer: 6 features
  • Pupil position (x, y)
  • Pupil size
  • Blink factor
  • Mouth expression
  • Mood (happiness level)

Each feature has independent random variation to create natural, organic movement.

🛠️ Building

Prerequisites

• CMake 3.10+
• C++17 compatible compiler
• Linux/Unix terminal with Braille Unicode support

With CMake

# Build both versions
./run.sh

# Or build manually
mkdir -p build
cd build
cmake ..
make

With Nix (if CMake not found)

The build script automatically uses nix-shell if CMake is not available:

./run.sh  # Automatically handles dependencies

🚀 Running

CuteCat (Recommended)

./run_cute.sh

Features:

• Full cat face with ears, nose, mouth
• Mood-based expressions
• Blush intensity varies with happiness
• Droopy ears when sad, perky when happy

Original Eyes

./run.sh

Classic eye-tracking animation with neural control.

🎮 Controls

Currently, the animations run autonomously without user input. The cat's behavior is driven entirely by its neural network and internal state.

To exit: Press Ctrl+C

📁 Project Structure

Gato/
├── include/
│   ├── brain/              # Neural network and state machine
│   ├── behavior/           # Awakeness, blinking, attention
│   └── rendering/          # Canvas and drawing utilities
├── src/
├── ├── audio/              # Audio input
│   ├── brain/              # Neural brain implementation
│   ├── behavior/           # Behavior controllers
│   ├── rendering/          # Braille canvas and renderers
│   ├── core/               # Utilities and terminal functions
│   ├── main.cpp            # Original eyes app
│   └── cute_main.cpp       # CuteCat app
├── run.sh                  # Build and run eyes
├── run_cute.sh             # Build and run CuteCat
└── CMakeLists.txt

🧠 How It Works

Triple Buffering

The application uses a lock-free triple buffering system:

1. Logic Thread: Renders to a private buffer
2. Render Thread: Displays from its own buffer
3. Shared Buffer: Swapped atomically between threads

This ensures smooth 30 FPS animation without freezing or tearing.

Mood System

The cat's mood slowly drifts using random noise:

• 0.0 (Sad): Droopy ears, frown, no blush
• 0.5 (Neutral): Normal expression
• 1.0 (Happy): Perky ears, smile, pink blush

Mood influences:

• Ear position
• Mouth curvature
• Blush visibility
• Overall facial expression

Randomness

Each feature uses independent pseudo-random noise:

• Pupil size: Changes ~3x per second
• Mood: Changes ~2x per second
• Mouth: Changes ~4x per second
• Blink interval: Randomly varies 1.5-4.5 seconds

This prevents the mechanical "everything moves together" effect.

🎨 Technical Details

• Resolution: Terminal width × height in Braille pixels (4× vertical resolution)
• Frame Rate: 30 FPS (33ms per frame)
• Color Support: ANSI colors (white, pink, gray, cyan, magenta)
• Threading: 2 threads (render + logic)
• Memory: ~2MB (two Braille canvases)

📸 Screenshots

happy cat.

not so-happy cat.

📝 Notes

• Requires a terminal with good Unicode support
• Best viewed in a dark terminal theme
• Larger terminal = bigger cat face
• Minimum terminal size: 50×20 characters

🐛 Troubleshooting

Animation freezes: Make sure your terminal supports Unicode Braille characters (U+2800-U+28FF)

Weird characters: Your terminal font may not support Braille. Try a different font (e.g., DejaVu Sans Mono, Fira Code)

Too slow: Reduce terminal size or close other applications

📜 Changelog

v2.0.0 (Stable Neural Cat)

• Stereo Audio: Added support for 2-channel audio input.
• Audio Pan Gaze: Cat now looks towards the direction of sound.
• Smoothing: Implemented exponential smoothing for audio volume and pitch.
• Stability: Removed keyboard/mouse input handling to resolve freezing issues.
• Refactoring: Entire codebase refactored for a cleaner style.
• Nix: Improved Nix integration for reproducible builds.
• Version: Bumped project version to 2.0.0.

v1.0.0

• Initial release with neural-controlled cat face and eye tracking.
• Braille canvas rendering engine.
• Triple buffering for smooth animations.

🤝 Contributing

This is a personal project exploring neural networks and terminal graphics. Feel free to fork and experiment!

📄 License

MIT License - feel free to use and modify as you wish.

---

Made with caffeine and 💕 for cats, sponsored by lack of sleep and exams pressure.