pexels_aesth_bucketed_1024.staging

Edit this section before uploading:

• Title: pexels_aesth_bucketed_1024.staging
• Description: (add a short description / intended use)

---

Technical details

This repository contains a bucketed-shards export (uncompressed TAR shards).

Format

• Format: bucketed_shards_v1
• Created: 2026-04-23T21:28:33.102206+00:00
• Export ID: export-2026-04-23T21:28:33.102206+00:00
• Manifest: manifest.json
• Image mode: reencode_jpeg

Directory layout:

• manifest.json (global metadata + per-bucket shard listing)
• buckets/<bucket_id>/shard-*.tar

Each TAR shard contains 3 files per sample:

• <key>.jpg (JPEG bytes; either re-encoded RGB JPEG or source JPEG passthrough depending on image_mode)
• <key>.txt (caption text, UTF-8, newline-terminated)
• <key>.json (per-sample metadata: w, h, jpeg, image_mode, caption_variant, caption_selector_index, caption_source_id)

Image preprocessing

If image_mode=reencode_jpeg, images are processed deterministically per-sample:

• EXIF transpose, convert to RGB
• Cover-resize using torch CPU bicubic interpolation with antialiasing (mode=bicubic, antialias=True)
• Never upsample: samples that would require upscaling are skipped (too_small_policy=drop)
• Crop to the bucket target size (crop_strategy=corner, allowed corners [2, 3])

Resize/crop details:

• Cover scale is scale = max(target_w / src_w, target_h / src_h); if scale > 1, the sample is skipped.
• After resize, a crop box is chosen deterministically from the sample key (sha256 of image_id).
  • Corner strategy chooses a corner from allowed_corners where 0=TL, 1=TR, 2=BL, 3=BR (optional small jitter for corner_jitter).

JPEG encoding:

• quality 95
• subsampling policy adaptive_scale (adaptive threshold 0.85)

If image_mode=passthrough_jpeg, the exporter stores the source file bytes as-is (no EXIF transpose / resize / crop / re-encode). Buckets and w/h metadata still refer to the planned target size for that bucket (not necessarily the encoded JPEG dimensions). Loaders should decode the JPEG bytes, apply EXIF orientation if desired, then do resize/crop at load time.

Buckets / resolutions

• Buckets follow SDXL-style proto buckets defined at a 1024×1024 base.
• Base resolution(s): [1024]
• In single-res exports, bucket_id is the proto (1024-base) bucket, e.g. p1024x1024.
• In multi-res exports, buckets are namespaced by base resolution: r<base>_<proto>, e.g. r512_p1024x1024.
• The actual target resolution for each bucket (scaled by the per-bucket base resolution and divisible=32) is stored in:
  • manifest.json → buckets[<bucket_id>].scaled.w/h (and base_resolution)
  • each sample’s <key>.json → w/h

Bucket IDs (preview): p1024x1024, p1024x960, p1088x896, p1088x960, p1152x832, p1152x896, p1216x832, p1280x768, p1344x704, p1344x768, p1408x704, p1472x704, p1536x640, p1600x640, p1664x576, p1728x576, p1792x576, p1856x512, p1984x512, p2048x512, … (+13 more)

Bucket distribution:

bucket_id	target_w×h	aspect	count
p832x1216	832×1216	0.684	105,330
p1216x832	1216×832	1.462	87,993
p832x1152	832×1152	0.722	19,817
p1152x832	1152×832	1.385	8,947
p896x1088	896×1088	0.824	8,916
p1344x768	1344×768	1.750	6,840
p768x1344	768×1344	0.571	6,492
p1280x768	1280×768	1.667	3,003
p896x1152	896×1152	0.778	2,973
p1024x1024	1024×1024	1.000	2,329
p768x1280	768×1280	0.600	1,590
p1152x896	1152×896	1.286	1,351
p1088x896	1088×896	1.214	1,202
p1344x704	1344×704	1.909	477
p960x1088	960×1088	0.882	445
p960x1024	960×1024	0.938	370
p1024x960	1024×960	1.067	292
p1088x960	1088×960	1.133	288
p1408x704	1408×704	2.000	172
p1472x704	1472×704	2.091	142
p704x1408	704×1408	0.500	93
p1536x640	1536×640	2.400	76
p704x1472	704×1472	0.478	48
p1600x640	1600×640	2.500	38
p1664x576	1664×576	2.889	26
p1728x576	1728×576	3.000	19
p1792x576	1792×576	3.111	15
p640x1536	640×1536	0.417	8
p1856x512	1856×512	3.625	8
p2048x512	2048×512	4.000	6
p640x1600	640×1600	0.400	3
p1984x512	1984×512	3.875	1
p512x2048	512×2048	0.250	1

Caption selection (waterfall)

Captions are selected from dataset.sqlite using the first matching selector (highest priority wins). Within the same selector, the newest caption source is preferred.

Caption provenance:

• Per-sample <key>.json includes caption_source_id (int, from dataset.sqlite).
• manifest.json includes a caption_sources table mapping caption_source_id → backend/model/created_at plus prompt hashes (not prompt text).

Caption sources used:

caption_source_id	backend	model	created_at	system_prompt_sha256	user_prompt_sha256
1	legacy	legacy_parquet	1767803344	e3b0c44298fc…	e3b0c44298fc…
2	openrouter	mistralai/ministral-14b-2512	1767804077	1c4cdeb48b59…	ebd6df172530…
4	openrouter	google/gemini-2.5-flash	1776962090	0bce4c4bd870…	d434dcc1ad47…
5	openrouter	google/gemini-2.5-flash	1776962237	6a2bc7e74b4b…	adc11c2c1758…
6	openrouter	google/gemini-2.5-flash	1776963677	256027f6c923…	6ed671b1ecec…
7	openrouter	google/gemini-2.5-flash-lite	1776965309	256027f6c923…	6ed671b1ecec…
9	openrouter	mistralai/mistral-medium-3.1	1776974446	256027f6c923…	6ed671b1ecec…
10	openrouter	google/gemini-3.1-flash-lite-preview	1778363543	b02ea5de41b3…	75e9d130e3b1…
11	openrouter	mistralai/mistral-medium-3.1	1778365496	b02ea5de41b3…	75e9d130e3b1…

Caption priority (waterfall) + planned usage:

selector_index	variant	backend	model	planned_images
0	caption_gemini			34,897
1	caption_ministral_14b_2512			182,050
2	caption_gemini_2_5_flash			10,553
3	caption_gemini_2_5_flash_lite			24,496
4	caption_mistral_medium_3_1			217
5	caption_gemini_3_1_flash_lite_preview			7,098

Available caption variants (top 30):

selected	variant	images_with_ok_caption
✓	caption_gemini	34,897
✓	caption_ministral_14b_2512	182,050
✓	caption_gemini_2_5_flash	10,553
✓	caption_gemini_2_5_flash_lite	24,496
✓	caption_mistral_medium_3_1	217
✓	caption_gemini_3_1_flash_lite_preview	7,098

Missing caption policy: error

Export summary

• images_seen: 259,325
• images_exported: 259,311
• skipped_no_caption: 0
• skipped_too_small: 14
• decode_errors: 0
• encode_errors: 0

Efficient loading

Recommended

Treat this as a webdataset-style collection of tar shards:

• Prefer sequential reads of tar files for throughput.
• Shuffle at the shard level (and optionally within-shard) for good randomness without expensive random I/O.
• Use manifest.json to list buckets and shards.

Python (webdataset)

import webdataset as wds

urls = "buckets/*/shard-*.tar"  # glob; adjust if you want a single bucket only
ds = (
    wds.WebDataset(urls)
    .decode("pil")            # decodes .jpg to PIL.Image
    .to_tuple("jpg", "txt", "json")
)
for jpg, caption, meta in ds:
    ...

Python (tarfile, no extra deps)

import io, json, tarfile
from pathlib import Path

tar_path = next(Path("buckets").rglob("shard-*.tar"))
with tarfile.open(tar_path, "r") as tf:
    members = tf.getmembers()
    for m in members:
        if not m.name.endswith(".txt"):
            continue
        key = m.name[:-4]
        caption = tf.extractfile(m).read().decode("utf-8").strip()
        meta = json.loads(tf.extractfile(tf.getmember(key + ".json")).read().decode("utf-8"))
        jpg_bytes = tf.extractfile(tf.getmember(key + ".jpg")).read()
        ...