198 lines
6.3 KiB
Markdown
198 lines
6.3 KiB
Markdown
File: docs/GALLERIES.md
|
||
Version: v0.3.4
|
||
Last updated: November 2025
|
||
Maintainer: Leak Technologies
|
||
Project: Goondex
|
||
|
||
------------------------------------------------------------
|
||
Goondex Gallery Structure and Metadata Specification
|
||
------------------------------------------------------------
|
||
|
||
Purpose:
|
||
Define how galleries are stored, named, and structured within the Goondex system.
|
||
This document standardizes the folder layout, metadata schema, and indexing process to ensure all galleries are consistent and compatible with importer, tagger, and ML modules.
|
||
|
||
------------------------------------------------------------
|
||
1. Directory Structure
|
||
------------------------------------------------------------
|
||
|
||
All galleries are stored under:
|
||
~/Projects/PD/Goondex/Galleries/
|
||
|
||
Each imported gallery is placed in its own folder:
|
||
Galleries/<timestamp>_<model(s)>_<short_title>/
|
||
|
||
Example:
|
||
Galleries/20251106_1032_Mariella_Sun_Takes_A_Shower/
|
||
|
||
Inside each gallery folder:
|
||
metadata.json → Core metadata record
|
||
001.jpg, 002.jpg, ... → Sequentially numbered images
|
||
failed_downloads.json (opt.) → List of images that failed to download
|
||
thumbnail.jpg (future) → Designated cover image for previews
|
||
|
||
A global index is maintained at:
|
||
Galleries/index.json
|
||
|
||
------------------------------------------------------------
|
||
2. Naming Convention
|
||
------------------------------------------------------------
|
||
|
||
The importer automatically generates folder names using:
|
||
<timestamp>_<models>_<shortened_title>
|
||
|
||
Rules:
|
||
- Timestamp format: YYYYMMDD_HHMM (UTC local)
|
||
- Model names separated by underscores
|
||
- Title truncated to 40 characters max
|
||
- Illegal filesystem characters replaced with underscores
|
||
- Spaces are converted to underscores
|
||
|
||
This ensures folder names remain unique, sortable, and descriptive.
|
||
|
||
------------------------------------------------------------
|
||
3. Metadata Specification (metadata.json)
|
||
------------------------------------------------------------
|
||
|
||
Each gallery includes a metadata.json file containing descriptive fields.
|
||
|
||
Example:
|
||
{
|
||
"title": "Mariella Sun Takes A Shower",
|
||
"models": ["Mariella Sun"],
|
||
"categories": ["Amateur", "Shower", "Solo"],
|
||
"tags": ["Blonde", "Teen", "Wet", "Shower", "Outdoor"],
|
||
"inferred_tags": ["Amateur", "Solo", "Wet"],
|
||
"source_url": "https://www.pornpics.com/galleries/12345/",
|
||
"source": { "network": "PornPics", "channel": null },
|
||
"views": 5421,
|
||
"rating": 4.8,
|
||
"image_count": 52,
|
||
"image_urls": [
|
||
"https://cdn.pornpics.com/2025/11/12345_001.jpg",
|
||
"https://cdn.pornpics.com/2025/11/12345_002.jpg"
|
||
],
|
||
"import_path": "~/Projects/PD/Goondex/Galleries/20251106_1032_Mariella_Sun_Takes_A_Shower",
|
||
"last_refreshed": "2025-11-06T15:40:21Z"
|
||
}
|
||
|
||
------------------------------------------------------------
|
||
4. Field Definitions
|
||
------------------------------------------------------------
|
||
|
||
title
|
||
→ Human-readable title as extracted from the source site.
|
||
|
||
models
|
||
→ List of performer names detected or scraped from metadata.
|
||
|
||
categories
|
||
→ Source site’s categorical labels (if available).
|
||
|
||
tags
|
||
→ All user and inferred tags combined.
|
||
|
||
inferred_tags
|
||
→ Tags automatically added by the tag_gallery.py module.
|
||
|
||
source_url
|
||
→ The original URL used for import.
|
||
|
||
source
|
||
→ Object with optional "network" and "channel" fields.
|
||
Example: { "network": "PornPics", "channel": null }
|
||
|
||
views
|
||
→ Scraped view count from the source (if available).
|
||
|
||
rating
|
||
→ Normalized 0–5 rating (float).
|
||
|
||
image_count
|
||
→ Number of valid images downloaded.
|
||
|
||
image_urls
|
||
→ Full list of image URLs (for re-download or verification).
|
||
|
||
import_path
|
||
→ Absolute path where this gallery is stored locally.
|
||
|
||
last_refreshed
|
||
→ ISO 8601 timestamp marking last metadata update.
|
||
|
||
------------------------------------------------------------
|
||
5. Index File
|
||
------------------------------------------------------------
|
||
|
||
Galleries/index.json is rebuilt after each import or refresh operation.
|
||
It includes essential details for quick CLI lookups and searches.
|
||
|
||
Example structure:
|
||
{
|
||
"galleries": [
|
||
{
|
||
"folder": "20251106_1032_Mariella_Sun_Takes_A_Shower",
|
||
"title": "Mariella Sun Takes A Shower",
|
||
"models": ["Mariella Sun"],
|
||
"tags": ["Blonde", "Teen", "Shower"],
|
||
"source": "PornPics",
|
||
"image_count": 52,
|
||
"last_refreshed": "2025-11-06T15:40:21Z"
|
||
}
|
||
]
|
||
}
|
||
|
||
------------------------------------------------------------
|
||
6. Refresh and Rebuild Process
|
||
------------------------------------------------------------
|
||
|
||
When running:
|
||
goondex import <url>
|
||
→ Imports gallery, creates metadata.json, downloads images, auto-tags.
|
||
|
||
goondex refresh-one <folder>
|
||
→ Re-runs tag inference and updates metadata fields.
|
||
|
||
goondex refresh-all
|
||
→ Applies inference and updates to all galleries under Galleries/.
|
||
|
||
After any import or refresh, index_builder.py:
|
||
- Scans all folders for metadata.json
|
||
- Builds Galleries/index.json
|
||
- Removes stale entries
|
||
- Reports summary to console
|
||
|
||
------------------------------------------------------------
|
||
7. Cache and Error Handling
|
||
------------------------------------------------------------
|
||
|
||
failed_downloads.json
|
||
→ Written if any images fail to download.
|
||
→ Contains URL and error message for each failure.
|
||
|
||
Re-importing a gallery with the same title merges metadata:
|
||
- Local tags are preserved
|
||
- Missing fields (views, rating, etc.) are filled
|
||
- Downloaded images are skipped if already present
|
||
|
||
------------------------------------------------------------
|
||
8. Future Enhancements (planned for v0.4.x)
|
||
------------------------------------------------------------
|
||
|
||
- thumbnail.jpg generation from first image
|
||
- Gallery-level previews for upcoming Web UI
|
||
- Extended metadata (dominant colours, detected subjects)
|
||
- Support for multi-site import with normalized schema
|
||
|
||
------------------------------------------------------------
|
||
9. Developer Notes
|
||
------------------------------------------------------------
|
||
|
||
Do not manually rename or move gallery folders after import.
|
||
Always rebuild the index via CLI if metadata is manually edited.
|
||
Each metadata.json should remain human-readable and formatted with indent=4.
|
||
|
||
------------------------------------------------------------
|
||
End of File
|
||
------------------------------------------------------------
|