Text-Texture-Generator-for-Blender/README.md

# Text Texture Generator - Blender Addon

A modern Blender addon that generates image textures from text with extensive customization options and advanced features.

## Features

- **Text Input & Processing**:

  - Enter any text to convert into a texture (up to 1024 characters)
  - Prepend and append text support with customizable margins
  - Horizontal and vertical text layout options
  - Text fitting system with automatic font size adjustment

- **Advanced Positioning System**:

  - 9-point anchor positioning system (top-left, center, bottom-right, etc.)
  - Manual coordinate positioning with percentage or pixel units
  - Fine-tuning offsets for precise placement
  - Canvas constraint options

- **Font System**:

  - System font detection and selection
  - Custom font file support (.ttf, .otf)
  - Font validation with mixed-case support testing
  - Adjustable font size (8-500px)
  - Text alignment (left, center, right)

- **Image Overlay System**:

  - Multiple image overlays with individual controls
  - Three positioning modes: Absolute, Prepend, Append
  - Per-overlay scaling, rotation, and z-index control
  - Image spacing and sequencing for complex layouts
  - Enable/disable individual overlays

- **Color & Transparency**:

  - RGBA text color picker with full alpha support
  - RGBA background color picker
  - Transparent background option
  - Preview background options (transparent, solid color, gradient)

- **Normal Map Generation**:

  - Automatic normal map creation from text alpha channel
  - Adjustable strength, blur radius, and invert options
  - Proper colorspace handling for normal maps

- **Advanced Shader Generation**:

  - Complete material shader creation
  - Multiple shader types: Principled BSDF, Emission, Transparent
  - Light path control: disable shadows, reflections, backfacing
  - Auto-assignment to selected objects
  - Normal map integration in shaders

- **Preset Management System**:

  - Three-tier storage: Blend File, Persistent, Local presets
  - All preset types now display properly in the interface
  - Presets travel with .blend files (Blend File type)
  - Import/export functionality for backup and sharing
  - Automatic migration system for addon updates
  - Conflict resolution for preset imports

- **Preview System**:

  - Full-resolution live preview generation
  - Zoomable preview window with Image Editor integration
  - Multiple preview background options
  - Real-time updates on property changes

- **Blender Integration**:
  - Works in Shader Editor, 3D Viewport, and Properties panel
  - Automatic texture node creation with proper connections
  - Generated textures are packed into the .blend file
  - Menu integration across multiple editors

## Installation

### Method 1: Modern Blender 4.0+ (Recommended)

1. Download the addon files (`blender_manifest.toml` and `__init__.py`)
2. Create a folder named `text_texture_generator`
3. Place both files in this folder
4. In Blender, go to `Edit > Preferences > Add-ons`
5. Click `Install from Disk` and select the folder
6. Enable the "Text Texture Generator" addon

### Method 2: Traditional Installation

1. Download the `__init__.py` file
2. In Blender, go to `Edit > Preferences > Add-ons`
3. Click `Install from Disk` and select the `__init__.py` file
4. Enable the "Text Texture Generator" addon

## Usage

### In Shader Editor:

1. Select a material with nodes enabled
2. Open the Shader Editor
3. Press `N` to open the side panel
4. Navigate to the "Text Texture" tab
5. Configure your text and settings
6. Click "Generate Texture"
7. The texture node will be automatically added to your material

### In 3D Viewport:

1. Press `N` to open the side panel
2. Navigate to the "Text Texture" tab
3. Configure your text and settings
4. Click "Generate Texture"
5. Find your texture in the Image Editor or use it in materials

## Settings Reference

### Text Settings

- **Main Text**: Primary text to render (up to 1024 characters)
- **Prepend Text**: Text to add before main text (up to 512 characters)
- **Append Text**: Text to add after main text (up to 512 characters)
- **Layout**: Horizontal or vertical arrangement of text elements
- **Margins**: Percentage-based spacing between text elements

### Font Settings

- **System Fonts**: Auto-detected system fonts with validation
- **Custom Font**: Load external .ttf/.otf font files
- **Font Size**: Size in pixels (8-500px)
- **Text Alignment**: Left, center, right alignment options

### Positioning & Layout

- **Position Mode**: Preset anchor points or manual coordinates
- **Anchor Points**: 9-point positioning grid (top-left to bottom-right)
- **Margins**: Percentage-based margins from canvas edges (0-50%)
- **Offsets**: Pixel-perfect fine-tuning (-200 to +200px)
- **Manual Positioning**: Direct X,Y coordinates in percentage or pixels
- **Canvas Constraints**: Keep text within canvas bounds

### Text Fitting

- **Auto-Sizing**: Automatically adjust font size to fit canvas
- **Fitting Modes**: Fit width, height, both, or contain within bounds
- **Size Limits**: Minimum and maximum font size constraints
- **Fitting Margin**: Percentage margin for auto-fitting calculations

### Texture Settings

- **Dimensions**: Canvas size in pixels (64x64 to 4096x4096)
- **Text Color**: RGBA color picker with full alpha support
- **Background**: Transparent or solid color with RGBA control

### Image Overlays

- **Multiple Images**: Add unlimited image overlays
- **Positioning Modes**: Absolute coordinates, prepend, or append to text
- **Transform Controls**: Scale (0.1-5.0x), rotation (360°), z-index layering
- **Spacing Controls**: Configurable spacing between images and text
- **Sequence Control**: Order overlays in prepend/append modes

### Normal Maps

- **Auto-Generation**: Create normal maps from text alpha channel
- **Strength Control**: Adjust normal map intensity (0.1-5.0)
- **Blur Radius**: Smooth normal map edges (0-10px)
- **Invert Option**: Switch between emboss and deboss effects

### Shader Generation

- **Shader Types**: Principled BSDF, Emission, Transparent materials
- **Texture Connections**: Base color, emission, or alpha channels
- **Light Path Controls**: Disable shadows, reflections, or backfacing
- **Auto-Assignment**: Automatically apply materials to selected objects
- **Normal Map Integration**: Automatic normal map nodes and connections

### Preview Options

- **Live Preview**: Real-time texture generation and display
- **Preview Size**: Adjustable preview resolution (128-2048px)
- **Background Display**: Transparent, solid color, or gradient options
- **Zoom Controls**: Open preview in zoomable Image Editor window

## System Requirements

- Blender 4.0.0 or newer
- Python 3.10+ (included with Blender)
- Pillow library (>=10.0.0, automatically installed via pip)

## Font Support

The addon features intelligent font detection and validation:

### System Font Detection

- Automatically scans system font directories
- Supports .ttf, .ttc, .otf, and .dfont files
- Mixed-case rendering validation for quality assurance
- Platform-specific fallback fonts with guaranteed compatibility

### Windows Fallback Fonts

- Arial, Calibri, Segoe UI, Verdana, Tahoma, Times, Trebuchet MS

### macOS Fallback Fonts

- Helvetica, Arial, Times, Avenir, Geneva, Palatino

### Linux Fallback Fonts

- Liberation Sans, DejaVu Sans, Ubuntu, Noto Sans, Lato, Open Sans

### Custom Fonts

- Load any .ttf or .otf font file
- Automatic validation for mixed-case support
- Error handling and fallback for unsupported fonts

## Dependencies

The addon automatically installs required dependencies:

- **Pillow** (>=10.0.0): For image generation and text rendering

## Troubleshooting

### Common Issues

1. **"Failed to generate texture" error**:

   - Ensure Pillow is installed (addon does this automatically)
   - Check that your text isn't empty
   - Verify texture dimensions are within limits

2. **Font not displaying correctly**:

   - Try using "Default" font option
   - Some system fonts may not be available
   - Custom font paths vary by system

3. **Texture appears in wrong location**:
   - In Shader Editor: Ensure you have a material selected
   - Check the generated image in the Image Editor
   - Look for the texture in `bpy.data.images`

### Performance Notes

- Large textures (2048x2048+) may take longer to generate
- Very long text strings may affect performance
- Generated textures are stored in memory and packed with the .blend file

## Preset System

The addon features a sophisticated three-tier preset system:

### Storage Locations (Priority Order)

1. **Blend File Storage** (Highest Priority)

   - Presets stored in scene custom properties
   - Travel with your .blend file
   - Perfect for project-specific presets

2. **Persistent File Storage** (Medium Priority)

   - Survives addon updates and Blender upgrades
   - Stored in Blender's user config directory
   - Shared across all blend files

3. **Local File Storage** (Lowest Priority)
   - Local addon-specific presets
   - Automatically migrated to persistent storage when needed

### Preset Features

- **Improved UI Display**: Recent bug fix ensures all three preset types (Blend File, Persistent, Local) display properly in the interface
- **Auto-Migration**: Seamlessly upgrades presets during addon updates
- **Import/Export**: Backup and share presets across installations
- **Conflict Resolution**: Smart handling of duplicate preset names
- **Migration Reports**: Detailed logs of preset migration operations

## Development

### File Structure

```
text_texture_generator/
├── blender_manifest.toml  # Modern addon manifest (Blender 4.0+)
├── __init__.py           # Main addon code (~5000 lines)
└── README.md            # Documentation
```

### Code Organization

- **Utility Functions**: Font detection, validation, system compatibility
- **Preview Generation**: Real-time texture creation and display
- **Normal Map Generation**: Height-based normal map algorithms
- **Positioning System**: 9-point anchors, manual coordinates, constraints
- **Preset Management**: Three-tier storage with migration system
- **UI Components**: Collapsible sections, shared drawing functions
- **Operators**: 20+ operators for all addon functionality
- **Property Groups**: Comprehensive property system with validation

### Contributing

The addon is designed with modularity and extensibility in mind. Key areas for contribution:

- Additional shader types and material presets
- Extended image overlay positioning modes
- Font rendering improvements and compatibility
- UI/UX enhancements and workflow optimization
- Platform-specific font detection improvements

## License

GPL-3.0-or-later

## Author

Marc Mintel <marc@mintel.me>

## Changelog

### Version 2.3.2 (Current Code Version)

- Advanced positioning system with 9-point anchors and manual coordinates
- Text fitting with automatic font size adjustment and multiple modes
- Comprehensive image overlay system with absolute, prepend, and append positioning
- Normal map generation from text alpha channels with strength/blur controls
- Advanced shader generation with Principled BSDF, Emission, and Transparent types
- Light path controls for shadows, reflections, and backfacing geometry
- Three-tier preset system (blend file → persistent → legacy) with auto-migration
- Live preview with zoomable Image Editor integration and multiple backgrounds
- Prepend/append text support with horizontal/vertical layouts
- Custom font support with mixed-case validation and fallback systems
- Import/export functionality for preset backup and cross-installation sharing
- Enhanced error handling and user feedback throughout the interface

### Version 1.0.0 (Manifest Version)

- Note: The blender_manifest.toml shows version 1.0.0 but the code implements v2.3.2 features
- Recommendation: Update manifest version to match actual code capabilities