Thumbscanner

Overview

The Turbo Cropper (thumbscan.php) is a comprehensive gallery thumbnail scanning and cropping utility. It fetches remote gallery pages, extracts images using advanced hybrid detection (regex + DOM), downloads them for preview, and provides an interactive cropping interface with star rating and text overlay capabilities. This tool is essential for creating high-quality thumbnails for imported gallery content.

[Screenshot: thumbscan-overview]

System Requirements

PHP Requirements

Required PHP Extensions

Required PHP Functions

External Tools

Folder Permissions

Server Requirements

Installation Requirements

Fonts Directory

For enhanced text overlays, place TrueType fonts in:

• ct/admin/fonts/ (primary)
• ct/fonts/ (fallback)

Supported font files:

Features & UI Elements

Entry Page (No Gallery Selected)

[Screenshot: thumbscan-entry]

When accessed without a gallery ID:

Enhanced Features Listed:

• Real-time Progress Updates
• Flexible Image Detection (regex + DOM hybrid)
• Enhanced XPath Queries
• Video Content Detection
• Smart Error Handling
• Debug Mode

Live Progress Page

[Screenshot: thumbscan-progress]

During scanning, shows:

Cropping Interface

[Screenshot: thumbscan-cropping]

The main thumbnail creation interface:

Thumbnail Strip

[Screenshot: thumbscan-strip]

• Horizontal scrollable grid of downloaded images
• Maximum 40 images displayed (20 per row)
• Size indicator below each thumbnail
• Click to select as main image
• Green border indicates selected image
• Scroll buttons for navigation

Main Cropping Area

[Screenshot: thumbscan-main-crop]

Live Preview Panel

[Screenshot: thumbscan-preview]

Real-time preview at exact thumbnail dimensions:

• Shows current crop selection
• Displays overlay effects (stars, text)
• Updates instantly as you adjust

Star Rating Overlay

[Screenshot: thumbscan-stars]

Position Options:

• Top Left, Top Right
• Bottom Left, Bottom Right
• Center

Text Overlay

[Screenshot: thumbscan-text]

Quick Text Buttons:

• Up to 15 most frequently used text overlays
• Category names as quick options
• Click to instantly apply

Text Controls:

Text Effects:

Text Position Options:

• Top Left, Top Center, Top Right
• Center Left, Center, Center Right
• Bottom Left, Bottom Center, Bottom Right

Action Buttons

[Screenshot: thumbscan-actions]

User Instructions Panel

[Screenshot: thumbscan-instructions]

Collapsible panel showing:

• Cropping instructions
• Keyboard shortcuts
• Overlay configuration tips

Keyboard Shortcuts:

Font Test Utility

[Screenshot: thumbscan-fonttest]

Accessed via ?action=fonttest:

• Shows font directory status
• Lists available TTF fonts
• Displays font mapping status
• Live font test generator
• Test rotation, shadows, outlines

Step-by-Step Usage

Starting a Scan from Gallery List

1. Navigate to Admin Panel → Database → Galleries → Review
2. Find a gallery without a thumbnail
3. Click the Create Thumbnail button or icon
4. System redirects to thumbscan with gallery info

Using the Progress Page

1. Scan begins automatically upon page load
2. Watch the progress bar fill
3. Monitor log entries for any issues
4. Wait for "Scan Complete" status
5. Click Continue to Cropping button

Creating a Thumbnail

1. Select Source Image: Click thumbnail in strip to use different image
2. Position Crop Box: Drag the green selection to desired position
3. Resize if Needed: Drag edges/corners to adjust aspect ratio
4. Add Star Rating (optional):

• Check "Enable star overlay"
• Click desired star count (1-5)
• Choose color and position

1. Add Text Overlay (optional):

• Check "Enable text overlay"
• Enter text or click quick button
• Configure font, size, color
• Add shadow/outline effects

1. Preview: Check the live preview panel
2. Save: Click Capture or Capture and NEXT

Batch Processing Galleries

Using "Capture and NEXT" workflow:

1. Process first gallery's thumbnail
2. Click Capture and NEXT
3. System automatically finds next gallery without thumbnail
4. Page redirects to scan that gallery
5. Repeat until all galleries have thumbnails
6. "All Galleries Complete" message shows when done

Disapproving a Gallery

If gallery images are unsuitable:

1. Review the available images
2. Click Disapprove button
3. Gallery marked with accept='disapproved'
4. System moves to next gallery automatically

Technical Details

Image Detection Pipeline

1. Fetch Page → cURL with retry logic (max 3 attempts)

1. Parse HTML → Check for <base href> override
2. Find Images:

   a. Regex extraction (href, src, srcset, data-src, etc.)
   b. Filter unwanted patterns (logos, icons, pixels)
   c. Priority scoring (prefer "full", "large" over "thumb")

1. Resolve URLs:

   a. Protocol-relative (//example.com)
   b. Root-relative (/path/image.jpg)
   c. Page-relative (./image.jpg)
   d. Dual-domain resolution when base href differs

Download Images → Fast parallel downloadsValidate → Check size, content-type, GD compatibilityCreate Thumbnails → Generate preview versions

1. Store Metadata → Save original URL and dimensions

Video Detection

The scanner automatically detects video galleries and sets hasvideo=1:

Detection Methods:

1. <video> tags in DOM
2. Video platform iframes (YouTube, Vimeo, PornHub, etc.)
3. Video file extensions (.mp4, .webm, .m4v, etc.)
4. <source> tags with video MIME types
5. Video player JavaScript references (jwplayer, videojs, etc.)
6. HLS/DASH streaming manifests (.m3u8, .mpd)

URL Resolution Logic

function resolveUrl($relativeUrl, $baseUrl) {
    // Already absolute → return as-is
    // Protocol-relative (//example.com) → add scheme
    // Root-relative (/path) → add domain
    // Page-relative (./path or path) → add base path
    // Handle ../ navigation
}

Progress Tracking

Progress stored in JSON files:

ct/admin/temp/scanprogress{galleryid}.json

Content:

{

  "status": "scanning",

  "totaltarget": 25,

  "currentimages": 15,

  "pagesscanned": 1,

  "imagesfound": 30,

  "imagesdownloaded": 15,

  "logs": ["12:34:56 - Starting scan..."],

  "timestamp": 1704067200

}

Thumbnail Generation

// Create destination canvas
$desim = imagecreatetruecolor($thumbwidth, $thumbheight);

// Extract crop region
$tmpim = imagecreatetruecolor($capturewidth, $captureheight);
imagecopy($tmpim, $srcim, 0, 0, $captureX, $captureY, $capturewidth, $captureheight);

// Resample to final size
imagecopyresampled($desim, $tmpim, 0, 0, 0, 0, $thumbwidth, $thumbheight, $capturewidth, $captureheight);

// Apply overlays
addStarsOverlay($desim, ...);
addTextOverlay($desim, ...);

// Save files
imagejpeg($desim, $thumbfile, $quality); // Display version
imagejpeg($desim, $thumbmasterfile, 100); // Master copy

File Naming

Troubleshooting

Scan Fails to Start

No Images Found

Image Download Fails

Cropping Interface Not Loading

Text Overlay Not Appearing

Stars Not Displaying

Thumbnail Not Saving

mkdir -p ct/thumbs

chmod 775 ct/thumbs

chown www-data:www-data ct/thumbs

Database Update Failed

Scan Takes Too Long

AJAX Endpoints

progress

Gets current scan progress:

• Method: GET
• Parameters: action=progress, pageindex={galleryid}
• Returns: Progress JSON object

startscan

Initiates background scanning:

• Method: GET
• Parameters: startscan=1, pageindex={galleryid}, url={galleryurl}
• Returns: Completion JSON when done

capture / captureandnext

Saves thumbnail and updates database:

• Method: POST
• Parameters: Form data including crop coordinates, overlay settings
• Returns: Success page with thumbnail preview

disapprove

Marks gallery as disapproved:

Method: POST

• Parameters: action=disapprove, pageindex={galleryid}
• Returns: Redirect to next gallery

keepthumb

Uses existing thumbnail with overlays:

• Method: POST
• Parameters: Form data with overlay settings
• Returns: Success page with updated thumbnail

fonttest

Font detection utility:

• Method: GET
• Parameters: action=fonttest
• Returns: Font test HTML page

Related Pages

Translatable Strings

The following text strings appear in this page and should be added to backendtranslations.md:

Page Titles

• "Enhanced Thumbscan with Real-time Progress"
• "Enhanced Comus Thumbnail Cropper"
• "Thumbnail Saved Successfully!"
• "All Galleries Complete!"
• "Scan Error"

Progress Page

• "Initializing..."
• "Scanning..."
• "Scan Complete"
• "Scan Error"
• "Images Found"
• "Pages Scanned"
• "Target Images"
• "Downloaded"
• "Scan Log"
• "Continue to Cropping"
• "Return to Admin"

Cropping Interface

• "PLEASE WAIT FOR SCAN TO 100% COMPLETE"
• "Visit Url"
• "Select thumbnail to crop"

Overlay Controls

• "Star Rating Overlay"
• "Enable star overlay"
• "Color:"
• "Position:"
• "Top Left"
• "Top Right"
• "Bottom Left"
• "Bottom Right"
• "Center"

Text Overlay

• "Text Overlay"
• "Enable text overlay"
• "Quick Text:"
• "Enter text..."
• "Font Family:"
• "Font Size:"
• "Font Weight:"
• "Rotation (°):"
• "Normal"
• "Bold"

Text Effects

• "Text Effects"
• "Drop Shadow"
• "Shadow X:"
• "Shadow Y:"
• "Blur:"
• "Outline:"

Font Families

• "Arial"
• "Helvetica"
• "Times New Roman"
• "Courier"
• "Georgia"
• "Verdana"
• "Trebuchet MS"
• "Comic Sans"

Action Buttons

• "Capture"
• "Capture and NEXT"
• "Disapprove"
• "Return to Review Editor"
• "Close Window"

Status Messages

• "Moving to next gallery that needs a thumbnail..."
• "Next Gallery ID:"
• "URL:"
• "Please wait, we are scanning the next gallery URL..."
• "Wrapping Around to Beginning"
• "No more galleries found after current ID."
• "Database Statistics:"
• "Total Galleries:"
• "With Thumbnails:"
• "Without Thumbnails:"
• "No URL:"

Error Messages

• "ERR: Bad pageindex value"
• "ERR: Bad record"
• "ERROR! Invalid page index!"
• "ERROR! GD library is not available."
• "ERROR! Source image not found."
• "ERROR! Failed to create thumbs directory."
• "ERROR! Thumbs directory is not writable."
• "ERROR! GD processing failed:"
• "ERROR! Database update failed:"
• "Failed to fetch URL:"
• "No valid thumbnail images were found"
• "No images found on"

Font Test Utility

• "Enhanced Font Detection Utility"
• "Font Directory Information"
• "Fonts Directory:"
• "Directory Exists:"
• "Directory Readable:"
• "Font Mapping Status"
• "Live Font Test"
• "Generate Test Image"

User Instructions

• "How to Use the Cropper"
• "Click and drag the green box to position your crop"
• "Drag corners or edges to resize"
• "Click a thumbnail below to switch images"
• "Use overlays for star ratings and text"
• "Click Capture to save or Capture and NEXT to continue"

Keyboard Shortcuts

• "Arrow Keys - Move selection"
• "+/- - Resize"
• "Enter - Submit"
• "Esc - Cancel"

Version History