Skip to content

Creating Your First Procedure#

This tutorial walks you through building a simple data capture procedure using the Procedure DSL.

Prerequisites#

Install the CaptureGraph library:

pip install capturegraph

Step 1: Define the Procedure#

Create a Python file for your procedure:

# my_procedure.py
import capturegraph.procedures as cgp

def my_procedure():
    # Get the root directory (your "target")
    target = cgp.GetRootDirectory()

    # Create a timestamped session for each execution
    session = target.new_session("capture")

    # Define what to capture
    return cgp.ProcedureSequence(
        label="My First Procedure",
        procedures=[
            session.new_file("photo").save(
                cgp.CaptureImage(label="Take a photo")
            ),
            session.new_file("notes").save(
                cgp.UserInputString(label="Add some notes")
            ),
        ]
    )

# Create the procedure instance
procedure = my_procedure()

Step 2: Understand the Key Concepts#

Targets#

A target is the subject of your capture (a building, patient, specimen). It represents the root project folder. See Targets and Sessions for details.

target = cgp.GetRootDirectory()

Sessions#

A session is a timestamped subfolder for each execution of your procedure:

session = target.new_session("capture")
# Creates: sessions/capture/00063B40E29D696A/

Session names use hex-encoded microsecond timestamps, ensuring:

  • Automatic chronological sorting
  • Mergeability between devices
  • No overwrites on repeated runs

Saving Data#

Use .save() to persist captured data:

session.new_file("photo").save(cgp.CaptureImage(label="Photo"))

This creates a file reference and saves the captured image to it. See the Fluent API for .save() vs .cache() vs .load().

Step 3: Add Configuration#

Make your procedure smarter with cached settings:

import capturegraph.procedures as cgp

def smart_procedure():
    target = cgp.GetRootDirectory()
    session = target.new_session("capture")

    # Ask once, remember forever
    capture_raw = target.new_file("use_raw").cache(
        cgp.UserInputBool(
            label="Capture in RAW format?",
            true_text="Yes",
            false_text="No"
        ),
        skip_if_exists=True  # Don't ask again if already answered
    )

    return cgp.ProcedureSequence(
        label="Smart Capture",
        procedures=[
            session.new_file("photo").save(
                cgp.CaptureImage(
                    label="Today's Photo",
                    raw_photo=capture_raw
                )
            ),
        ]
    )

The key difference (see Fluent API):

  • .save() — Stores data, returns PVoid, used in sequences
  • .cache() — Stores data, returns the original type, can be reused

Step 4: Export to JSON#

Serialize your procedure for the iOS app:

import capturegraph.procedures as cgp

procedure = my_procedure()
json_string = cgp.procedure_to_json(procedure)

with open("MyProcedure.json", "w") as f:
    f.write(json_string)

Next Steps#