CaptureGraph#

CaptureGraph is a system for distribution-aware data capture. You define a capture procedure — what to photograph, measure, and ask — over a typed schema in Python, and an iOS app executes it, guiding anyone with a phone through a perfectly structured capture session. A server can coordinate whole groups, scheduling captures so the dataset stays evenly distributed across the conditions you care about (sun angle, location, weather, time) instead of piling up at whatever moment was convenient. Because the shape of the data is fixed before the first capture, analysis is one line: load the target and get typed access to every session.

The Pipeline#

plan ──► schedule ──► capture ──► organize ──► analyze

The minimal pipeline is just plan → capture → analyze: a Python library and a phone. The server, scheduler, and sync tool join in when you scale from one person to a crowd.

Who Is It For?#

Environmental time-lapse groups. A lab time-lapses a riverbank across seasons with a rotating cast of volunteers. Instead of "photograph it every day at noon," the procedure captures an aligned photo, location, and weather; the server schedules each volunteer's notification for the solar angles and cloud conditions the dataset is still missing. Nobody is spammed, and golden-hour frames stop being a lucky accident.

Clinicians documenting change over time. A wound-care team needs the same photos, ratings, and notes at every visit, across many patients and many hands. The schema encodes the protocol — photo, pain rating, notes, branching follow-up questions — so every session is complete by construction. Sessions are timestamped folders that merge cleanly from multiple devices, and the analysis script can be written before the first patient is seen.

Graphics and vision researchers. Building a relighting or reconstruction dataset means covering viewpoint, weather, and illumination evenly, not just abundantly. Procedures attach typed metadata (location, solar position, weather, EXIF) to every frame, and the scheduler treats coverage as an importance-sampling problem — interrupting collectors only when a capture would fill a real gap in the distribution.

Quick Start#

Every procedure is two steps: first declare the shape of your data with cg.Struct classes, then record how to fill it in a small function. Here is both, plus serializing the result to JSON for the app:

import capturegraph as cg


class Session(cg.Struct):
    photo: cg.Image
    notes: cg.String


class DailyCapture(cg.Struct):
    sessions: cg.Map[cg.Date, Session]
    _metadata: cg.Metadata


@cg.procedure(DailyCapture)
def daily(root):
    session = root.sessions[cg.CaptureTime()]
    session.photo &= cg.CaptureImage(label="Today's photo")
    session.notes &= cg.UserInputString(label="Notes")


with open("DailyCapture.json", "w") as f:
    f.write(daily.to_json())

Drop DailyCapture.json into the iOS app and every run becomes a session keyed by its capture time, containing a photo and your notes. The full walkthrough — installing the library, building the app — starts at Getting Started.

Documentation Sections#