# Standalone macOS App Distribution

## Overview

The Handwriting Recognition app is now available as a **fully standalone macOS application** that requires **NO Python installation** from users. All dependencies are bundled inside the app.

### Quick Facts

- **File**: `Handwriting Recognition-1.0.0-standalone.dmg` (357 MB)
- **App Size**: 928 MB (includes complete Python + all dependencies)
- **System Requirements**: macOS 10.13 or later
- **User Setup**: Download → Drag to Applications → Run
- **Python Needed**: ❌ NO

## Distribution Process

### Step 1: Share the DMG

- **File**: `Handwriting Recognition-1.0.0-standalone.dmg`
- **Size**: 357 MB (compressed with zlib level 9)
- **Share via**: Email, cloud storage, website, etc.

### Step 2: User Installation

1. Download `Handwriting Recognition-1.0.0-standalone.dmg`
2. Double-click to mount the DMG
3. Drag **Handwriting Recognition.app** to Applications folder
4. Eject the DMG

### Step 3: Running the App

- Double-click **Handwriting Recognition.app** in Applications
- App launches immediately - no terminal, no Python setup needed
- First launch may take a few seconds while system recognizes the app

## Technical Details

### What's Bundled

The app contains a complete isolated Python environment with all dependencies:

```
Handwriting Recognition.app/Contents/
├── MacOS/
│   └── Handwriting Recognition (launcher script)
├── Resources/
│   ├── app.py (GUI entry point)
│   ├── models/ (CRNN neural network)
│   ├── inference/ (transcription engine)
│   ├── gui/ (PyQt6 interface)
│   ├── preprocessing/ (image processing)
│   ├── training/ (training pipeline)
│   ├── cli/ (command-line interface)
│   ├── utils/ (utilities)
│   ├── config.py (configuration)
│   └── data/ (sample images)
└── Frameworks/
    └── venv/ (Python 3.10 + all packages)
        ├── bin/python (Python interpreter)
        ├── lib/python3.10/site-packages/ (all dependencies)
        └── [complete virtual environment]
```

### Included Dependencies

- **Python**: 3.10.15 (arm64 optimized for Apple Silicon)
- **PyTorch**: 2.12.0 (deep learning framework)
- **PyQt6**: 6.11.0 (GUI toolkit)
- **OpenCV**: 4.13.0.92 (image processing)
- **NumPy**: 2.2.6 (numerical computing)
- **Pillow**: 12.2.0 (image manipulation)
- **tqdm**: 4.66.5 (progress bars)
- **Plus all transitive dependencies**

### How It Works

1. User double-clicks the app
2. macOS launches the shell script at `Contents/MacOS/Handwriting Recognition`
3. The launcher script:
   - Sources the bundled Python environment at `Contents/Frameworks/venv/`
   - Sets up the environment variables
   - Executes the app using the bundled Python
   - User never sees or needs system Python
4. PyQt6 GUI appears with full functionality

## Build System

### Creating New Standalone Builds

If you modify the app and need to rebuild:

```bash
# Make the scripts executable (one-time setup)
chmod +x build_standalone.sh build_dmg_standalone.sh

# Build the standalone app bundle
./build_standalone.sh
# Output: dist/Handwriting Recognition.app (928 MB)

# Create the distributable DMG
./build_dmg_standalone.sh
# Output: Handwriting Recognition-1.0.0-standalone.dmg (357 MB)
```

### Build Scripts

**`build_standalone.sh`**

- Creates complete app bundle with bundled Python environment
- Installs all dependencies from `requirements-gui.txt`
- Generates launcher script and Info.plist
- Handles directory structure and file copying
- Total time: ~5 minutes on Apple Silicon

**`build_dmg_standalone.sh`**

- Packages the app bundle into a distributable DMG
- Includes README.txt with installation instructions
- Compresses with zlib level 9 for smallest size
- Creates drag-to-install experience

### Updating Dependencies

To update Python packages in standalone builds:

1. Edit `requirements-gui.txt` with new package versions
2. Run `./build_standalone.sh` (will reinstall all packages)
3. Run `./build_dmg_standalone.sh` (creates new DMG)

## Advantages vs. System Python

| Aspect | Standalone App | System Python Required |
|--------|---|---|
| **User Setup** | Download + drag | Download + install Python + install app |
| **Multiple Versions** | Can coexist | Conflicts with system/other apps |
| **Dependency Conflicts** | Isolated | Can break other Python apps |
| **Python Knowledge** | Zero required | User must understand Python |
| **Distribution** | Single file | Complex setup instructions |
| **Updates** | Replace app file | Update Python + app separately |

## Support & Troubleshooting

### App Won't Launch

1. Right-click app → **Open** (bypass Gatekeeper for first launch)
2. If "damaged" warning appears: `xattr -d com.apple.quarantine "/Applications/Handwriting Recognition.app"`
3. Check macOS version is 10.13+

### Performance Issues

- First launch may take a few seconds (normal)
- Model inference takes 1-2 seconds per image (GPU accelerated where available)
- Large batch processing is normal

### File Locations

- App configuration: `~/.config/handwriting-recognition/`
- Model cache: `~/.cache/handwriting-recognition/`
- Training outputs: Check Training tab in app

## Version Information

- **App Version**: 1.0.0
- **Build Date**: May 14, 2024
- **Python Version**: 3.10.15
- **PyTorch Version**: 2.12.0
- **macOS Minimum**: 10.13 (High Sierra)

## Future Updates

To distribute app updates:

1. Modify source code as needed
2. Run `./build_standalone.sh` to rebuild
3. Run `./build_dmg_standalone.sh` to create new DMG
4. Distribute the new DMG file
5. Users download and replace old app with new version

No version management complications - each DMG is self-contained.