EricRollei-PDF-Tools/CODE_OVERVIEW.md

# PDF Tools - Code Structure Summary

## Overview
This is a ComfyUI custom node package containing **downloader nodes** and **PDF/image processing nodes**. Despite the "PDF_tools" name, it's evolved into a comprehensive media download and processing toolkit.

## Directory Structure

```
PDF_tools/
├── __init__.py                    # Main entry point - loads all nodes
├── requirements.txt               # Python dependencies
├── INSTALLATION_GUIDE.md          # Setup instructions (NEW)
│
├── nodes/                         # ComfyUI node implementations
│   ├── gallery_dl_downloader.py   # Download from 100+ websites (Instagram, Reddit, etc.)
│   ├── yt_dlp_downloader.py       # Video/audio downloader (YouTube, TikTok, etc.)
│   ├── pdf_extractor_v08.py       # Latest PDF extraction node (MAIN VERSION)
│   ├── pdf_extractor_v07.py       # Previous version
│   ├── enhanced_layout_parser_v06.py  # Layout analysis node (MAIN VERSION)
│   ├── eric_rectangle_detector_node.py  # Rectangle detection node
│   └── [older versions]           # v01-v06 versions for reference
│
├── florence2_scripts/             # Florence2 AI vision model integration
│   ├── florence2_detector.py      # Main detector (based on kijai's implementation)
│   ├── modeling_florence2.py      # Florence2 model definition
│   ├── modern_image_enhancer.py   # Image enhancement utilities
│   └── [test/demo scripts]        # Various test and demo files
│
├── sam2_scripts/                  # SAM2 (Segment Anything 2) integration
│   ├── sam2_florence_segmentation.py  # Combined SAM2+Florence2
│   ├── sam2_integration.py        # SAM2 wrapper
│   └── [other scripts]
│
├── configs/                       # Configuration files
│   ├── auth_config.json           # Authentication for various sites
│   ├── instagram_cookies.json     # Cookie storage
│   ├── gallery-dl*.conf           # Gallery-dl configurations
│   └── yt-dlp*.conf              # Yt-dlp configurations
│
├── Docs/                          # Documentation and guides
│   ├── gallery_dl_node_complete_guide.md    # Gallery-dl setup guide
│   ├── yt_dlp_node_complete_guide.md        # Yt-dlp setup guide
│   ├── SETUP_COMPLETE.md          # Authentication setup
│   ├── test_*.py                  # Test scripts for various features
│   └── [various guides]           # Implementation guides
│
├── oldfiles/                      # Deprecated/backup files
├── test-*/                        # Test output directories
└── [other directories]            # History, cache, etc.
```

## Main Components

### 1. Gallery-dl Downloader (`nodes/gallery_dl_downloader.py`)
**Purpose:** Download media from 100+ websites  
**Key Features:**
- URL list or URL file input
- Browser cookie support (Chrome, Firefox, etc.)
- Exported cookie file support
- Download archive (SQLite) to avoid duplicates
- Automatic file organization (images/videos/audio/other)
- Video filtering
- Metadata extraction
- Rate limiting and retry logic
- Instagram-specific optimizations

**Main Class:** `GalleryDLDownloader`
**Key Methods:**
- `_build_command()` - Constructs gallery-dl command
- `_convert_cookie_file()` - Converts cookie formats
- `_organize_downloaded_files()` - Sorts files by type
- `download()` - Main download execution

**External Dependencies:**
- `gallery-dl` command-line tool
- `browser-cookie3` for browser cookie extraction

### 2. Yt-dlp Downloader (`nodes/yt_dlp_downloader.py`)
**Purpose:** Download videos and audio from 1000+ sites  
**Key Features:**
- URL list or batch file input
- Format selection (quality presets)
- Audio extraction (MP3, FLAC, etc.)
- Subtitle download and embedding
- Playlist support
- Rate limiting
- Cookie support
- File organization

**Main Class:** `YtDlpDownloader`
**Key Methods:**
- `_build_command()` - Constructs yt-dlp command
- `_organize_downloaded_files()` - Sorts files by type
- `download()` - Main download execution

**External Dependencies:**
- `yt-dlp` command-line tool
- `ffmpeg` for audio/video processing

### 3. PDF Extractor v08 (`nodes/pdf_extractor_v08.py`)
**Purpose:** Extract images and text from PDFs  
**Key Features:**
- Page extraction as images
- Quality assessment
- Spread detection (book scanning)
- OCR integration
- Metadata preservation
- Multiple output formats

**Main Classes:**
- `PDFExtractorV08Node` - Main ComfyUI node
- `PDFProcessor` - Core PDF processing logic

**Dependencies:**
- `PyMuPDF` (fitz) for PDF reading
- `PyPDF2` as fallback
- Florence2 for image analysis

### 4. Florence2 Detector (`florence2_scripts/florence2_detector.py`)
**Purpose:** AI-powered vision model for image analysis  
**Key Features:**
- Rectangle detection
- Object detection
- Caption generation
- Visual question answering

**Main Classes:**
- `Florence2RectangleDetector` - Main detector
- `BoundingBox` - Bounding box data structure

**Based on:** kijai's ComfyUI-Florence2 implementation

**Dependencies:**
- `transformers` library
- `safetensors`
- Florence2 models from Hugging Face

### 5. Enhanced Layout Parser v06 (`nodes/enhanced_layout_parser_v06.py`)
**Purpose:** Document layout analysis  
**Key Features:**
- Text block detection
- Figure/table detection
- Multi-engine OCR support
- Computer vision-based analysis

**Dependencies:**
- `opencv-python`
- Optional: Surya OCR, LayoutLMv3

## Architecture Patterns

### Node Loading System
The `__init__.py` dynamically loads all nodes from the `nodes/` directory:
1. Scans `nodes/` for `.py` files
2. Imports each module
3. Extracts `NODE_CLASS_MAPPINGS` and `NODE_DISPLAY_NAME_MAPPINGS`
4. Registers with ComfyUI

### Downloader Pattern
Both gallery-dl and yt-dlp nodes follow the same pattern:
1. **Command Building** - Construct CLI command with all options
2. **Subprocess Execution** - Run external tool via subprocess
3. **Output Parsing** - Parse stdout/stderr for status
4. **File Organization** - Move downloaded files into organized folders
5. **Status Reporting** - Return summary with file counts and errors

### Error Handling
All nodes use extensive try-except blocks with:
- Graceful fallbacks (e.g., PyMuPDF → PyPDF2)
- Detailed debug output
- Status reporting to user
- Optional strict error mode

### Memory Management
AI model nodes (Florence2, SAM2) include:
- GPU memory checking
- Model offloading to CPU
- Batch size management
- CUDA cache clearing

## Key Design Decisions

### 1. External Command-Line Tools
**Why:** Gallery-dl and yt-dlp are mature, well-maintained tools with extensive site support. Wrapping them provides instant access to 1000+ sites without reimplementing complex protocols.

**Trade-offs:**
- ✅ Comprehensive site support
- ✅ Active maintenance
- ❌ Subprocess overhead
- ❌ Error parsing complexity

### 2. File Organization Within Profile Directories
**Why:** Preserves gallery-dl's original directory structure while organizing by file type.

**Implementation:** Files are moved into subdirectories (images/, videos/, audio/, other/) within each profile/site directory.

### 3. Cookie Authentication
**Why:** Many sites (Instagram, Reddit) require authentication for full access.

**Implementation:**
- Browser cookie extraction via `browser-cookie3`
- Exported cookie file support (JSON/Netscape format)
- Automatic cookie format conversion

**Challenges:**
- Chrome requires admin privileges on Windows
- Cookie expiration handling
- Site-specific cookie formats

### 4. Modular AI Model Integration
**Why:** Allow optional AI features without forcing all dependencies.

**Implementation:**
- Try-except imports for optional models
- Graceful degradation when models unavailable
- Lazy loading of heavy models

## Configuration System

### Config Files (`configs/`)
- **auth_config.json** - Site credentials and API keys
- **instagram_cookies.json** - Cookie storage
- **gallery-dl.conf** - Gallery-dl options
- **yt-dlp.conf** - Yt-dlp options

### Runtime Configuration
Nodes accept configuration via:
1. Node parameters (primary)
2. Config files (secondary)
3. Environment variables (some cases)

Priority: Node params > Config file > Defaults

## Testing Strategy

### Test Scripts (`Docs/test_*.py`)
- **test_instagram_optimal_setup.py** - Instagram download test
- **test_file_sorting.py** - File organization test
- **test_gallery_dl_node.py** - Gallery-dl integration test
- **test_yt_dlp_node.py** - Yt-dlp integration test
- And many more...

### Test Pattern
```python
# 1. Setup test environment
# 2. Create node instance
# 3. Run with test data
# 4. Verify output
# 5. Cleanup
```

## Dependencies Summary

### Core (Required)
- `Pillow` - Image processing
- `numpy` - Array operations
- `PyMuPDF` - PDF reading
- `opencv-python` - Computer vision

### AI/ML (Optional)
- `torch` - Deep learning (from ComfyUI)
- `transformers` - Hugging Face models
- `safetensors` - Model format
- `timm` - Vision models

### Downloaders (Optional)
- `gallery-dl` - Web media downloader
- `yt-dlp` - Video downloader
- `browser-cookie3` - Cookie extraction

### Utilities
- `requests` - HTTP requests
- `tqdm` - Progress bars
- `colorama` - Terminal colors

## Performance Considerations

### Memory Usage
- **Florence2**: ~2-4GB VRAM
- **SAM2**: ~4-8GB VRAM
- **PDF Processing**: Depends on PDF size
- **Downloads**: Minimal (streaming)

### Optimization Strategies
1. **Model Offloading** - Move models to CPU when not in use
2. **Batch Processing** - Process multiple items together
3. **Caching** - Cache model outputs
4. **Streaming Downloads** - Don't load entire files in memory

## Known Issues & Limitations

### Reddit API
- May hang with old credentials
- 2FA complications
- **Solution:** Use browser cookies instead

### Chrome Cookie Access
- Requires admin privileges on Windows
- **Solution:** Use Firefox or export cookies

### Instagram Rate Limiting
- Too many requests can trigger rate limits
- **Solution:** Use `--sleep` parameter (implemented)

### Large PDF Files
- Memory intensive for large PDFs
- **Solution:** Process page by page

## Future Improvement Areas

1. **Async Downloads** - Parallel downloads for better performance
2. **Download Queue** - Queue system for batch downloads
3. **Better Error Recovery** - Automatic retry with backoff
4. **Model Caching** - Better model management
5. **UI Improvements** - Progress bars in ComfyUI
6. **Database Integration** - Track all downloads in database
7. **Webhook Support** - Notify on completion

## How to Extend

### Adding a New Downloader Node
1. Create new file in `nodes/`
2. Implement node class with required methods
3. Add `NODE_CLASS_MAPPINGS` and `NODE_DISPLAY_NAME_MAPPINGS`
4. Test with various URLs
5. Document in `Docs/`

### Adding a New PDF Feature
1. Extend `PDFProcessor` class
2. Add new parameters to node
3. Update `_build_command()` or processing logic
4. Test with various PDFs
5. Update documentation

### Adding a New AI Model
1. Create new script in `florence2_scripts/` or `sam2_scripts/`
2. Implement model loading and inference
3. Add memory management
4. Create node wrapper in `nodes/`
5. Test on GPU and CPU
6. Document model requirements

## Code Quality Notes

### Good Practices
- ✅ Extensive error handling
- ✅ Detailed documentation
- ✅ Debug output for troubleshooting
- ✅ Modular design
- ✅ Graceful degradation

### Areas for Improvement
- ⚠️ Some code duplication between versions
- ⚠️ Test coverage could be better
- ⚠️ Some large functions could be split
- ⚠️ More type hints would help
- ⚠️ Some hardcoded paths

## Security Considerations

### Cookie Handling
- Cookies stored in JSON files
- **Risk:** Plaintext cookie storage
- **Mitigation:** Document proper file permissions

### Subprocess Execution
- User input passed to subprocess
- **Risk:** Command injection
- **Mitigation:** Input validation and sanitization (implemented)

### External Commands
- Relies on external binaries
- **Risk:** Malicious binary execution
- **Mitigation:** Check binary availability, use known paths

## Version History

- **v08** - Current PDF extractor with enhanced features
- **v07** - Added spread detection
- **v06** - Enhanced layout parser
- Earlier versions in oldfiles/

## Contributing Guidelines

If extending this codebase:
1. Follow existing patterns
2. Add comprehensive error handling
3. Include debug output
4. Test with real data
5. Document in Docs/
6. Update requirements.txt if adding dependencies
7. Keep backward compatibility when possible

## Summary

This is a **well-structured, feature-rich** ComfyUI custom node package that combines:
- Mature external tools (gallery-dl, yt-dlp)
- Modern AI models (Florence2, SAM2)
- Robust error handling
- Comprehensive documentation

The codebase is **production-ready** for the download nodes and **functional but evolving** for the AI model integration. The modular design makes it easy to use only the features you need.