capturegraph.procedures.nodes.action.capture

Hardware Capture Procedures

Procedures that interact with device hardware to capture data from cameras, sensors, and other device capabilities. All capture procedures require user interaction and pause workflow execution until the user completes the action.

Example

from capturegraph.procedures.nodes.action import CaptureImage, CaptureLocation
from capturegraph.procedures.nodes.automatic import ProcedureSequence
from capturegraph.procedures.nodes.filesystem import GetRootDirectory

def field_capture():
    target = GetRootDirectory()
    session = target.new_session("field_data")

    return ProcedureSequence(
        label="Field Data Collection",
        procedures=[
            session.new_file("photo").save(CaptureImage(label="Site Photo")),
            session.new_file("location").save(CaptureLocation()),
        ]
    )

CaptureAlignedImage

Bases: Procedure[PImage]

Captures an image aligned to a reference image for consistent positioning.

Used for timelapse photography or when you need multiple images taken from the same perspective. The app guides the user to align their camera with the reference image before allowing capture.

Attributes:

Name	Type	Description
reference_image	Procedure[PImage]	The image to align against.
raw_photo	Procedure[PBool]	Whether to capture in RAW format (default: False).
requires_reference	bool	Whether alignment to reference is mandatory (default: True).

Example

# First session: capture the reference
reference = target.new_file("reference").cache(
    CaptureImage(label="Reference Photo"),
    skip_if_exists=True
)

# Subsequent sessions: align to reference
session.new_file("aligned").save(
    CaptureAlignedImage(
        label="Aligned Photo",
        reference_image=reference,
        raw_photo=ConstantBool(value=True)
    )
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/action/capture.py

@make_procedure
class CaptureAlignedImage(Procedure[PImage]):
    """
    Captures an image aligned to a reference image for consistent positioning.

    Used for timelapse photography or when you need multiple images taken from
    the same perspective. The app guides the user to align their camera with
    the reference image before allowing capture.

    Attributes:
        reference_image: The image to align against.
        raw_photo: Whether to capture in RAW format (default: False).
        requires_reference: Whether alignment to reference is mandatory (default: True).

    Example:
        ```python
        # First session: capture the reference
        reference = target.new_file("reference").cache(
            CaptureImage(label="Reference Photo"),
            skip_if_exists=True
        )

        # Subsequent sessions: align to reference
        session.new_file("aligned").save(
            CaptureAlignedImage(
                label="Aligned Photo",
                reference_image=reference,
                raw_photo=ConstantBool(value=True)
            )
        )
        ```
    """

    reference_image: Procedure[PImage]
    raw_photo: Procedure[PBool] = ConstantBool(value=False)
    requires_reference: bool = True

CaptureImage

Bases: Procedure[PImage]

Captures a single image using the device camera.

The most basic image capture procedure that prompts the user to take a photo. The captured image can then be saved, processed, or used as input to other procedures.

Attributes:

Name	Type	Description
raw_photo	Procedure[PBool]	Whether to capture in RAW format for higher quality (default: False).

Example

# Simple photo capture
session.new_file("photo").save(
    CaptureImage(label="Take Photo")
)

# RAW capture with user preference
use_raw = target.new_file("raw_setting").cache(
    UserInputBool(label="Capture RAW?"),
    skip_if_exists=True
)
session.new_file("photo").save(
    CaptureImage(label="Photo", raw_photo=use_raw)
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/action/capture.py

@make_procedure
class CaptureImage(Procedure[PImage]):
    """
    Captures a single image using the device camera.

    The most basic image capture procedure that prompts the user to take a photo.
    The captured image can then be saved, processed, or used as input to other procedures.

    Attributes:
        raw_photo: Whether to capture in RAW format for higher quality (default: False).

    Example:
        ```python
        # Simple photo capture
        session.new_file("photo").save(
            CaptureImage(label="Take Photo")
        )

        # RAW capture with user preference
        use_raw = target.new_file("raw_setting").cache(
            UserInputBool(label="Capture RAW?"),
            skip_if_exists=True
        )
        session.new_file("photo").save(
            CaptureImage(label="Photo", raw_photo=use_raw)
        )
        ```
    """

    raw_photo: Procedure[PBool] = ConstantBool(value=False)

CaptureImageSequence

Bases: Procedure[PImageSequence]

Captures multiple images in sequence as a bundle.

Prompts the user to capture several related images that will be grouped together. Useful for creating image series, documenting multiple angles, or collecting related visual data.

Attributes:

Name	Type	Description
raw_photo	Procedure[PBool]	Whether to capture images in RAW format (default: False).

Example

# Capture multiple angles of a specimen
session.new_directory("specimen_photos").save_bundle(
    CaptureImageSequence(
        label="All Angles",
        raw_photo=ConstantBool(value=False)
    )
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/action/capture.py

@make_procedure
class CaptureImageSequence(Procedure[PImageSequence]):
    """
    Captures multiple images in sequence as a bundle.

    Prompts the user to capture several related images that will be grouped
    together. Useful for creating image series, documenting multiple angles,
    or collecting related visual data.

    Attributes:
        raw_photo: Whether to capture images in RAW format (default: False).

    Example:
        ```python
        # Capture multiple angles of a specimen
        session.new_directory("specimen_photos").save_bundle(
            CaptureImageSequence(
                label="All Angles",
                raw_photo=ConstantBool(value=False)
            )
        )
        ```
    """

    raw_photo: Procedure[PBool] = ConstantBool(value=False)

CaptureFlashNoFlash

Bases: Procedure[PImageFlashPair]

Captures a pair of images: one with flash and one without.

This capture mode is useful for computational photography applications that need to separate flash illumination from ambient lighting. The result is a bundle containing two named images: 'flash' and 'no_flash'.

Attributes:

Name	Type	Description
raw_photo	Procedure[PBool]	Whether to capture images in RAW format (default: False).

Example

# Capture flash/no-flash pair for material analysis
session.new_directory("flash_pair").save_bundle(
    CaptureFlashNoFlash(label="Flash Pair Capture")
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/action/capture.py

@make_procedure
class CaptureFlashNoFlash(Procedure[PImageFlashPair]):
    """
    Captures a pair of images: one with flash and one without.

    This capture mode is useful for computational photography applications that
    need to separate flash illumination from ambient lighting. The result is a
    bundle containing two named images: 'flash' and 'no_flash'.

    Attributes:
        raw_photo: Whether to capture images in RAW format (default: False).

    Example:
        ```python
        # Capture flash/no-flash pair for material analysis
        session.new_directory("flash_pair").save_bundle(
            CaptureFlashNoFlash(label="Flash Pair Capture")
        )
        ```
    """

    raw_photo: Procedure[PBool] = ConstantBool(value=False)

CaptureConstantColorImage

Bases: Procedure[PImage]

Captures an image using Apple's iOS 18 Constant Color API.

Uses flash with constant color correction to capture an image with consistent color temperature, removing the influence of ambient lighting. Useful for material scanning, product photography, and situations requiring accurate color.

Note: Requires iOS 18+ and a device with flash support.

Attributes:

Name	Type	Description
raw_photo	Procedure[PBool]	Whether to capture in RAW format (default: False).

Example

session.new_file("constant_color").save(
    CaptureConstantColorImage(label="Constant Color Capture")
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/action/capture.py

@make_procedure
class CaptureConstantColorImage(Procedure[PImage]):
    """
    Captures an image using Apple's iOS 18 Constant Color API.

    Uses flash with constant color correction to capture an image with consistent
    color temperature, removing the influence of ambient lighting. Useful for
    material scanning, product photography, and situations requiring accurate color.

    Note: Requires iOS 18+ and a device with flash support.

    Attributes:
        raw_photo: Whether to capture in RAW format (default: False).

    Example:
        ```python
        session.new_file("constant_color").save(
            CaptureConstantColorImage(label="Constant Color Capture")
        )
        ```
    """

    raw_photo: Procedure[PBool] = ConstantBool(value=False)

CaptureTime

Bases: Procedure[PTime]

Captures the current timestamp when the procedure executes.

Records the exact date and time when this procedure is executed, which can be useful for timestamping data collection or measuring time intervals between procedures.

Source code in capturegraph-lib/capturegraph/procedures/nodes/action/capture.py

@make_procedure
class CaptureTime(Procedure[PTime]):
    """
    Captures the current timestamp when the procedure executes.

    Records the exact date and time when this procedure is executed,
    which can be useful for timestamping data collection or measuring
    time intervals between procedures.
    """

CaptureLocation

Bases: Procedure[PLocation]

Captures the current GPS location of the device.

Records the device's current latitude, longitude, altitude, and other location metadata. Useful for geotagging data collection or tracking where measurements were taken.

Source code in capturegraph-lib/capturegraph/procedures/nodes/action/capture.py

@make_procedure
class CaptureLocation(Procedure[PLocation]):
    """
    Captures the current GPS location of the device.

    Records the device's current latitude, longitude, altitude, and other
    location metadata. Useful for geotagging data collection or tracking
    where measurements were taken.
    """

CaptureWeather

Bases: Procedure[PWeather]

Captures current weather conditions at the device location.

Retrieves weather information such as temperature, humidity, atmospheric pressure, and conditions for the current location. Useful for environmental data collection and context.

Attributes:

Name	Type	Description
location	Procedure[PLocation] | None	Optional location to fetch weather for. If not provided, uses the device's current location.

Source code in capturegraph-lib/capturegraph/procedures/nodes/action/capture.py

@make_procedure
class CaptureWeather(Procedure[PWeather]):
    """
    Captures current weather conditions at the device location.

    Retrieves weather information such as temperature, humidity,
    atmospheric pressure, and conditions for the current location.
    Useful for environmental data collection and context.

    Attributes:
        location (Procedure[PLocation] | None): Optional location to fetch weather for.
            If not provided, uses the device's current location.
    """

    location: Procedure[PLocation] | None = None

CaptureVideo

Bases: Procedure[PVideo]

Captures a video using the device camera.

Prompts the user to record a video. The recorded video can then be saved or used as input to other procedures.

Attributes:

Name	Type	Description
hdr_video	Procedure[PBool]	Whether to capture in HDR format (default: False).

Example

# Simple video capture
session.new_file("video").save(
    CaptureVideo(label="Record Video")
)

# HDR video capture
session.new_file("video").save(
    CaptureVideo(label="HDR Video", hdr_video=ConstantBool(value=True))
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/action/capture.py

@make_procedure
class CaptureVideo(Procedure[PVideo]):
    """
    Captures a video using the device camera.

    Prompts the user to record a video. The recorded video can then be saved
    or used as input to other procedures.

    Attributes:
        hdr_video: Whether to capture in HDR format (default: False).

    Example:
        ```python
        # Simple video capture
        session.new_file("video").save(
            CaptureVideo(label="Record Video")
        )

        # HDR video capture
        session.new_file("video").save(
            CaptureVideo(label="HDR Video", hdr_video=ConstantBool(value=True))
        )
        ```
    """

    hdr_video: Procedure[PBool] = ConstantBool(value=False)