Skip to content

Defining Procedures#

A procedure describes a capture session: what to photograph, measure, and ask, and where each result is stored. You declare the target's data layout as a typed schema, then write the procedure with the recorder — ordinary Python whose assignments record nodes.

import capturegraph as cg


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


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


@cg.procedure(Survey)
def survey(root: cg.Procedure[cg.Path[Survey]]):
    session = root.sessions[cg.CaptureTime()]          # a new session
    session.photo &= cg.CaptureImage(label="Photo")    # capture and store
    session.notes &= cg.UserInputString(label="Notes")


json_str = survey.to_json()

The decorated function never runs your capture logic — it records a graph. survey.to_json() (or survey.to_dict()) serializes it to the {schema, root, nodes} wire form the iOS app executes.

How it fits together#

Concept What it is
Type A value form — cg.Image, cg.Struct, cg.Map, … — that says how data is stored.
Schema The target's type tree, fixed before the first capture.
Procedure A DAG of nodes recorded with @cg.procedure.
Node One step: capture, compute, or cache.
Path A cg.Path[T] cursor into the schema; where a value is written.

Because the schema is fixed a priori, the dataset's shape is known before anyone captures anything — so analysis is one call and a server knows every file that can exist.

How procedures execute#

Python only declares the graph; the iOS app executes it:

  1. Topologically sort nodes from inputs and substeps edges.
  2. Auto-run process nodes (computations, constants, path navigation).
  3. Block on collection nodes until the user acts.
  4. Write cached values to the schema positions the recorder named.

The recorder type-checks the DAG as it builds, so most mistakes fail on your laptop, not on the device.

Section Contents#

The four type forms, the on-disk layout, and the node set

Schema shapes for targets, sessions, and per-entry data

Path navigation and the |= / &= caching operators

cg.do, cg.while_repeat, cg.when, cg.optional, and operators

Adding a node to the catalog

The {schema, root, nodes} interoperability standard

The file-transport wire contract — how a client syncs captured leaves