photo3d — iCloud Photos → 3D Reconstruction

Find photos from iCloud Photos that are suitable for 3D reconstruction (SfM / photogrammetry) and download them to a local directory for processing with the video2mesh pipeline.

Structure

privat/photo3d/
├── application/
│   ├── Photos3DSelector.swift          # Swift tool: query + analyze + download
│   ├── run_photos3d_selector.sh         # Wrapper script
│   └── Photos3DSelector.app/           # Compiled app bundle (for TCC permissions)
├── photos_for_3d/                       # Downloaded photos (output, created on first run)
└── README.md                            # This file

Prerequisites

1. A local Photos Library with iCloud Photos sync

This Mac mini has iCloud signed in (gerd.grasshoff@gmail.com) with the iCloud Photos service active, but no local Photos Library exists (~/Pictures/ is empty).

To set up the Photos Library:

1. Open Photos.app from Launchpad or Applications
2. If Photos.app shows a "Choose Library" dialog, click "Create New..."
3. Save it to ~/Pictures/Photos Library.photoslibrary (default location)
4. Go to Photos → Settings → iCloud
5. Enable "Sync this Mac"
6. Optionally enable "Download Originals to this Mac" (recommended for 3D — you need full-resolution images)
7. Wait for iCloud Photos to sync — this may take a while depending on your library size

2. Photos access permission

On first run, the system will show a permission dialog asking for Photos access. Click "Allow" to grant the Photos3DSelector access to your photo library.

If the permission is denied, you can reset it:

tccutil reset Photos

Then re-run the selector.

Usage

Always go through run_photos3d_selector.sh. It compiles the selector into the Photos3DSelector.app bundle and runs that binary. Running the source directly with swift Photos3DSelector.swift does not work: the interpreter does not link Photos.framework and aborts with Symbols not found. And even once compiled, macOS grants photo access to the app bundle, not to a loose binary.

Quick start (dry run — analyze only, no download)

cd privat/photo3d/application
./run_photos3d_selector.sh --dry-run --verbose

Download photos from yesterday

cd privat/photo3d/application
./run_photos3d_selector.sh

Options

Examples

Find photos from 3 days ago, include videos:

./run_photos3d_selector.sh --days-back 3 --include-videos --verbose

Lower the cluster threshold to 2 photos:

./run_photos3d_selector.sh --min-cluster 2 --cluster-interval 600

Dry run to see what would be selected:

./run_photos3d_selector.sh --dry-run --verbose

How it works

3D Reconstruction Suitability Criteria

A photo is considered suitable for 3D reconstruction if:

1. High resolution — long edge ≥ 1500px (configurable via --min-resolution)
2. Not a screenshot — screenshots are flat images, not real-world captures
3. Not audio — audio files are irrelevant
4. Video duration ≥ 1s (if --include-videos is set) — enough frames for extraction
5. Has GPS location (warning, not a hard disqualifier) — indicates real-world scenes

Time Clustering

Photos are grouped into time clusters — sequences of photos taken within 5 minutes (default) of each other. A cluster of ≥ 3 photos from different angles is ideal for 3D reconstruction (photogrammetry needs overlapping views).

Photos from clusters with fewer than the minimum cluster size are still downloaded individually if they pass the suitability filter.

Output Structure

photos_for_3d/
├── cluster_00/              # First photo-walk session
│   ├── IMG_20260730_143022_000.jpg
│   ├── IMG_20260730_143055_001.jpg
│   └── ...
├── cluster_01/              # Second photo-walk session
│   ├── IMG_20260730_161200_010.jpg
│   └── ...
└── photos3d_metadata.json    # Full metadata: dates, GPS, resolution, clusters

Next Step: 3D Reconstruction

After downloading photos, use the video2mesh pipeline:

cd apps/ai-applevoicerecorder/video2mesh
python video2mesh.py --frames /path/to/privat/photo3d/photos_for_3d/cluster_00/

The video2mesh pipeline runs COLMAP for Structure-from-Motion (SfM) and can produce sparse point clouds on macOS (dense MVS requires CUDA/Linux). See SFM_REFERENCE.md in the video2mesh directory for details.

Troubleshooting

"Photos access denied (status=2)"

This means no Photos Library exists or permission was denied:

1. Open Photos.app and create a library (see Prerequisites above)
2. Reset TCC: tccutil reset Photos
3. Re-run the selector

"No photos found"

• iCloud Photos may not have synced yet — wait longer
• Check Photos.app Settings → iCloud → ensure sync is enabled
• Try --days-back 2 or --days-back 7 for a wider date range

App bundle permission issues

If the swift command-line tool can't get Photos permission (auto-denies), use the compiled app bundle:

cd privat/photo3d/application
# The app bundle is pre-built. If you modified the Swift source, rebuild it:
# swiftc -o Photos3DSelector.app/Contents/MacOS/Photos3DSelector \
#   Photos3DSelector.swift -framework Photos -framework Foundation \
#   -framework UniformTypeIdentifiers
# Then run via open:
open Photos3DSelector.app --args --dry-run --verbose
# Check output in Console.app or system logs:
# log show --predicate 'process == "Photos3DSelector"' --last 5m

Build from source

cd privat/photo3d/application
swiftc -typecheck Photos3DSelector.swift -framework Photos -framework Foundation \
  -framework UniformTypeIdentifiers