capturegraph.procedures.nodes.action.user_input

User Input Procedures

Procedures that present user interface elements to collect data directly from users. All user input procedures require user interaction and pause workflow execution until the user provides the requested input.

Example

from capturegraph.procedures.nodes.action import UserInputString, UserInputBool
from capturegraph.procedures.nodes.automatic import ProcedureSequence
from capturegraph.procedures.nodes.filesystem import GetRootDirectory

def survey_procedure():
    target = GetRootDirectory()
    session = target.new_session("survey")

    return ProcedureSequence(
        label="Daily Survey",
        procedures=[
            session.new_file("notes").save(
                UserInputString(label="How are you feeling today?")
            ),
            session.new_file("satisfied").save(
                UserInputBool(
                    label="Are you satisfied?",
                    true_text="Yes",
                    false_text="No"
                )
            ),
        ]
    )

UserInputBool

Bases: Procedure[PBool]

Prompts the user to select between true/false options.

Displays a boolean choice interface with customizable text for the true and false options. Useful for yes/no questions, feature toggles, or binary decisions in data collection workflows.

Attributes:

Name	Type	Description
true_text	str	Text to display for the true option (default: "True").
false_text	str	Text to display for the false option (default: "False").

Example

# Cache a user preference
use_raw = target.new_file("raw_setting").cache(
    UserInputBool(
        label="Capture in RAW format?",
        true_text="Yes - RAW",
        false_text="No - HEIC"
    ),
    skip_if_exists=True
)

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

@make_procedure
class UserInputBool(Procedure[PBool]):
    """
    Prompts the user to select between true/false options.

    Displays a boolean choice interface with customizable text for
    the true and false options. Useful for yes/no questions, feature
    toggles, or binary decisions in data collection workflows.

    Attributes:
        true_text: Text to display for the true option (default: "True").
        false_text: Text to display for the false option (default: "False").

    Example:
        ```python
        # Cache a user preference
        use_raw = target.new_file("raw_setting").cache(
            UserInputBool(
                label="Capture in RAW format?",
                true_text="Yes - RAW",
                false_text="No - HEIC"
            ),
            skip_if_exists=True
        )
        ```
    """

    true_text: str = "True"
    false_text: str = "False"

UserInputNumber

Bases: Procedure[PNumber]

Prompts the user to enter a numeric value.

Displays a number input interface with optional constraints for minimum/maximum values and step increments.

Attributes:

Name	Type	Description
min_value	Optional[int | float]	Minimum allowed value (optional).
max_value	Optional[int | float]	Maximum allowed value (optional).
step	Optional[int | float]	Increment step for number picker (optional).

Example

# Collect a temperature reading with constraints
session.new_file("temperature").save(
    UserInputNumber(
        label="Temperature (°F)",
        min_value=32.0,
        max_value=120.0,
        step=0.5
    )
)

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

@make_procedure
class UserInputNumber(Procedure[PNumber]):
    """
    Prompts the user to enter a numeric value.

    Displays a number input interface with optional constraints for
    minimum/maximum values and step increments.

    Attributes:
        min_value: Minimum allowed value (optional).
        max_value: Maximum allowed value (optional).
        step: Increment step for number picker (optional).

    Example:
        ```python
        # Collect a temperature reading with constraints
        session.new_file("temperature").save(
            UserInputNumber(
                label="Temperature (°F)",
                min_value=32.0,
                max_value=120.0,
                step=0.5
            )
        )
        ```
    """

    min_value: Optional[int | float] = None
    max_value: Optional[int | float] = None
    step: Optional[int | float] = None

UserInputString

Bases: Procedure[PString]

Prompts the user to enter text input.

Displays a text input field where users can type free-form text. Useful for collecting names, descriptions, notes, or any other textual data during the procedure execution.

Example

session.new_file("notes").save(
    UserInputString(label="Observations")
)

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

@make_procedure
class UserInputString(Procedure[PString]):
    """
    Prompts the user to enter text input.

    Displays a text input field where users can type free-form text.
    Useful for collecting names, descriptions, notes, or any other
    textual data during the procedure execution.

    Example:
        ```python
        session.new_file("notes").save(
            UserInputString(label="Observations")
        )
        ```
    """

UserInputSelectString

Bases: Procedure[PString]

Prompts the user to select from a list of predefined text options.

Displays a dropdown or selection interface with customizable options. Useful for collecting specific values like categories, tags, or other predefined text inputs.

Attributes:

Name	Type	Description
options	list[str]	List of string options for the user to choose from

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

@make_procedure
class UserInputSelectString(Procedure[PString]):
    """
    Prompts the user to select from a list of predefined text options.

    Displays a dropdown or selection interface with customizable options.
    Useful for collecting specific values like categories, tags, or
    other predefined text inputs.

    Attributes:
        options (list[str]): List of string options for the user to choose from
    """

    options: list[str]

UserInputLocation

Bases: Procedure[PLocation]

Prompts the user to select or input a location.

Displays a location picker interface that may use maps, GPS, or manual coordinate entry. Users can specify geographic locations for data collection or analysis.

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

@make_procedure
class UserInputLocation(Procedure[PLocation]):
    """
    Prompts the user to select or input a location.

    Displays a location picker interface that may use maps, GPS,
    or manual coordinate entry. Users can specify geographic
    locations for data collection or analysis.
    """

UserInputTime

Bases: Procedure[PTime]

Prompts the user to select a specific date and time.

Displays date/time picker interface for selecting timestamps. Can be configured to round selections to day boundaries for simplified date-only input.

Attributes:

Name	Type	Description
round_to_days	bool	Whether to round time selection to day boundaries (default: False)

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

@make_procedure
class UserInputTime(Procedure[PTime]):
    """
    Prompts the user to select a specific date and time.

    Displays date/time picker interface for selecting timestamps.
    Can be configured to round selections to day boundaries for
    simplified date-only input.

    Attributes:
        round_to_days (bool): Whether to round time selection to day boundaries (default: False)
    """

    round_to_days: bool = False

UserInputTimeInterval

Bases: Procedure[PNumber]

Prompts the user to enter a time duration or interval.

Displays an interface for selecting time durations (e.g., "2 hours", "30 minutes"). Returns the interval as a numeric value in seconds.

Attributes:

Name	Type	Description
round_to_days	bool	Whether to round interval to day boundaries (default: False)

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

@make_procedure
class UserInputTimeInterval(Procedure[PNumber]):
    """
    Prompts the user to enter a time duration or interval.

    Displays an interface for selecting time durations (e.g., "2 hours",
    "30 minutes"). Returns the interval as a numeric value in seconds.

    Attributes:
        round_to_days (bool): Whether to round interval to day boundaries (default: False)
    """

    round_to_days: bool = False

UserInputTimeOfDay

Bases: Procedure[PNumber]

Prompts the user to select a time of day (hours and minutes only).

Displays a time picker for selecting the time portion only, without date information. Returns the time as seconds since midnight (0-86399).

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

@make_procedure
class UserInputTimeOfDay(Procedure[PNumber]):
    """
    Prompts the user to select a time of day (hours and minutes only).

    Displays a time picker for selecting the time portion only,
    without date information. Returns the time as seconds since
    midnight (0-86399).
    """

UserInputRating

Bases: Procedure[PNumber]

Prompts the user to select a star rating from 1-5.

Displays an interactive 5-star rating interface. Returns the selected rating as a number (1-5). Useful for quality assessments, ratings, or any scale-based input.

Attributes:

Name	Type	Description
max_stars	int	Maximum number of stars (default: 5)
bad_adjective	Optional[str]	Label to show on the left side (low rating), e.g., "Bad"
good_adjective	Optional[str]	Label to show on the right side (high rating), e.g., "Good"

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

@make_procedure
class UserInputRating(Procedure[PNumber]):
    """
    Prompts the user to select a star rating from 1-5.

    Displays an interactive 5-star rating interface. Returns the
    selected rating as a number (1-5). Useful for quality assessments,
    ratings, or any scale-based input.

    Attributes:
        max_stars (int): Maximum number of stars (default: 5)
        bad_adjective (Optional[str]): Label to show on the left side (low rating), e.g., "Bad"
        good_adjective (Optional[str]): Label to show on the right side (high rating), e.g., "Good"
    """

    max_stars: int = 5
    bad_adjective: Optional[str] = None
    good_adjective: Optional[str] = None

ShowInstructions

Bases: Procedure[PBool]

Displays instructions to the user and waits for acknowledgement.

Shows instruction text with an optional image to guide the user through a capture workflow. Returns True when the user acknowledges they have read and understood the instructions. Useful for collaborative capture scenarios where users need clear guidance before proceeding.

Attributes:

Name	Type	Description
text	str	The instruction text to display to the user
image	Procedure[PImage]	Optional image procedure to display alongside the instructions

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

@make_procedure
class ShowInstructions(Procedure[PBool]):
    """
    Displays instructions to the user and waits for acknowledgement.

    Shows instruction text with an optional image to guide the user through
    a capture workflow. Returns True when the user acknowledges they have
    read and understood the instructions. Useful for collaborative capture
    scenarios where users need clear guidance before proceeding.

    Attributes:
        text: The instruction text to display to the user
        image: Optional image procedure to display alongside the instructions
    """

    text: str
    image: Procedure[PImage] = NullProcedure(return_type=PImage)

GuideToLocation

Bases: Procedure[PVoid]

Guides the user to a target location before proceeding.

Displays a map showing the user's current location and the target location. Completes when the user is within the specified threshold distance and confirms arrival. Unlike ShowInstructions, this does not save acknowledgement state - arrival is always determined by the current location.

Attributes:

Name	Type	Description
target	Procedure[PLocation]	The target location to guide the user to
threshold_meters	float	Distance in meters at which the user is considered "arrived" (default: 25)

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

@make_procedure
class GuideToLocation(Procedure[PVoid]):
    """
    Guides the user to a target location before proceeding.

    Displays a map showing the user's current location and the target location.
    Completes when the user is within the specified threshold distance and confirms arrival.
    Unlike ShowInstructions, this does not save acknowledgement state - arrival is always
    determined by the current location.

    Attributes:
        target: The target location to guide the user to
        threshold_meters: Distance in meters at which the user is considered "arrived" (default: 25)
    """

    target: Procedure[PLocation]
    threshold_meters: float = 25.0

UserInputOptimalSolarTime

Bases: Procedure[PTime]

Displays solar position plot with optimal capture times for user selection.

Shows a sun path plot with coverage analysis based on existing session data. Computes optimal capture times using the Void and Cluster algorithm and displays them as selectable bell markers. Returns the selected time when user confirms.

The plot shows: - Sun path over 24 hours centered on current position - Coverage shading (green = uncovered/good, red = covered/bad) - Bell markers at optimal capture times - Session markers showing existing captures

Attributes:

Name	Type	Description
target	Procedure[PDirectory]	The target root directory containing session data
session	str	Session name to compute coverage for
count	int	Number of optimal time choices to present (default: 5)
minimum_altitude	float	Minimum sun altitude in degrees to consider (default: 0 = horizon)

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

@make_procedure
class UserInputOptimalSolarTime(Procedure[PTime]):
    """
    Displays solar position plot with optimal capture times for user selection.

    Shows a sun path plot with coverage analysis based on existing session data.
    Computes optimal capture times using the Void and Cluster algorithm and displays
    them as selectable bell markers. Returns the selected time when user confirms.

    The plot shows:
    - Sun path over 24 hours centered on current position
    - Coverage shading (green = uncovered/good, red = covered/bad)
    - Bell markers at optimal capture times
    - Session markers showing existing captures

    Attributes:
        target: The target root directory containing session data
        session: Session name to compute coverage for
        count: Number of optimal time choices to present (default: 5)
        minimum_altitude: Minimum sun altitude in degrees to consider (default: 0 = horizon)
    """

    target: Procedure[PDirectory]
    session: str
    count: int = 5
    minimum_altitude: float = -18.0

PaceKeeper

Bases: Procedure[PVoid]

Displays a flashing visual metronome at a specified BPM.

Flashes the screen between white and black at the configured beats per minute. Returns PVoid immediately (fire-and-forget visual cue). Useful for timing actions like CPR compressions or other rhythmic activities.

The default BPM of 103 matches the tempo of "Staying Alive" by the Bee Gees, which is commonly used for CPR training.

Attributes:

Name	Type	Description
bpm	float	Beats per minute for the flashing rate (default: 103)

Example

# Use in a medical protocol to guide CPR compressions
cgp.PaceKeeper(label="CPR Pace", bpm=103)

# Slower pace for breathing exercises
cgp.PaceKeeper(label="Breathing Guide", bpm=12)

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

@make_procedure
class PaceKeeper(Procedure[PVoid]):
    """
    Displays a flashing visual metronome at a specified BPM.

    Flashes the screen between white and black at the configured beats per minute.
    Returns PVoid immediately (fire-and-forget visual cue). Useful for timing
    actions like CPR compressions or other rhythmic activities.

    The default BPM of 103 matches the tempo of "Staying Alive" by the Bee Gees,
    which is commonly used for CPR training.

    Attributes:
        bpm: Beats per minute for the flashing rate (default: 103)

    Example:
        ```python
        # Use in a medical protocol to guide CPR compressions
        cgp.PaceKeeper(label="CPR Pace", bpm=103)

        # Slower pace for breathing exercises
        cgp.PaceKeeper(label="Breathing Guide", bpm=12)
        ```
    """

    bpm: float = 103.0

Stopwatch

Bases: Procedure[PNumber]

Allows users to record how long something takes.

Displays a stopwatch interface with start/stop controls. The user can start timing, stop when the action is complete, and submit the recorded duration. Returns the elapsed time as a PNumber in seconds.

Useful for timing procedures, measuring reaction times, or recording the duration of observations in data collection workflows.

Example

# Record how long a task takes
session.new_file("task_duration").save(
    Stopwatch(label="Time the procedure")
)

# Measure reaction time
session.new_file("reaction_time").save(
    Stopwatch(label="Press stop when you see the signal")
)

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

@make_procedure
class Stopwatch(Procedure[PNumber]):
    """
    Allows users to record how long something takes.

    Displays a stopwatch interface with start/stop controls. The user can
    start timing, stop when the action is complete, and submit the recorded
    duration. Returns the elapsed time as a PNumber in seconds.

    Useful for timing procedures, measuring reaction times, or recording
    the duration of observations in data collection workflows.

    Example:
        ```python
        # Record how long a task takes
        session.new_file("task_duration").save(
            Stopwatch(label="Time the procedure")
        )

        # Measure reaction time
        session.new_file("reaction_time").save(
            Stopwatch(label="Press stop when you see the signal")
        )
        ```
    """