capturegraph.procedures.toolkits.metadata.location_manager

Location Management Toolkit

This module provides utilities for managing target locations for data collection. Location managers handle setting, retrieving, and updating geographic coordinates where data should be captured, with built-in logic for location validation and user-friendly distance checking.

The toolkit enables location-aware data collection workflows where users can:

• Set target capture locations

• Check distance from current location to target

• Ask user if they want to update target location when far from the original location

All location data is persisted across procedure executions for consistency.

set_target_location(location, skip_if_exists)

Sets the target capture location for the current capture target.

Establishes the geographic location where data should be captured for this target. The location is persisted and used for distance calculations and location-based workflow decisions.

Parameters:

Name	Type	Description	Default
location	Procedure[PLocation]	The procedure that provides the target location coordinates	required
skip_if_exists	bool	Whether to skip setting if a target location already exists	required

Returns:

Type	Description
Procedure[PVoid]	A procedure that saves the location to the target's location file

Example

import capturegraph.procedures as cgp

# Set a fixed target location
target_coords = cgp.ConstantLocation(latitude=37.7749, longitude=-122.4194)
cgp.set_target_location(target_coords, skip_if_exists=False)

# Set target to current location
cgp.set_target_location(cgp.CaptureLocation(), skip_if_exists=True)

Source code in capturegraph-lib/capturegraph/procedures/toolkits/metadata/location_manager.py

def set_target_location(
    location: Procedure[PLocation], skip_if_exists: bool
) -> Procedure[PVoid]:
    """
    Sets the target capture location for the current capture target.

    Establishes the geographic location where data should be captured for this
    target. The location is persisted and used for distance calculations and
    location-based workflow decisions.

    Args:
        location: The procedure that provides the target location coordinates
        skip_if_exists: Whether to skip setting if a target location already exists

    Returns:
        A procedure that saves the location to the target's location file

    Example:
        ```python
        import capturegraph.procedures as cgp

        # Set a fixed target location
        target_coords = cgp.ConstantLocation(latitude=37.7749, longitude=-122.4194)
        cgp.set_target_location(target_coords, skip_if_exists=False)

        # Set target to current location
        cgp.set_target_location(cgp.CaptureLocation(), skip_if_exists=True)
        ```
    """
    return (
        _target.get_location_file()
        .save(procedure=location, skip_if_exists=skip_if_exists)
        .set_label("Set Target Location")
    )

get_target_location(default_location=CaptureLocation())

Retrieves the target capture location for the current capture target.

Returns the previously saved target location, or the default location if no target has been set. Used to check distances and validate capture locations.

Parameters:

Name	Type	Description	Default
default_location	Procedure[PLocation]	The location to use if no target location is saved (defaults to current GPS location)	CaptureLocation()

Returns:

Type	Description
Procedure[PLocation]	A procedure that retrieves the target location from persistent storage

Example

import capturegraph.procedures as cgp

# Get target location, defaulting to current location
target = cgp.get_target_location()

# Get target location with custom default
fallback = cgp.ConstantLocation(latitude=0, longitude=0)
target = cgp.get_target_location(fallback)

Source code in capturegraph-lib/capturegraph/procedures/toolkits/metadata/location_manager.py

def get_target_location(
    default_location: Procedure[PLocation] = CaptureLocation(),
) -> Procedure[PLocation]:
    """
    Retrieves the target capture location for the current capture target.

    Returns the previously saved target location, or the default location if
    no target has been set. Used to check distances and validate capture locations.

    Args:
        default_location: The location to use if no target location is saved
                         (defaults to current GPS location)

    Returns:
        A procedure that retrieves the target location from persistent storage

    Example:
        ```python
        import capturegraph.procedures as cgp

        # Get target location, defaulting to current location
        target = cgp.get_target_location()

        # Get target location with custom default
        fallback = cgp.ConstantLocation(latitude=0, longitude=0)
        target = cgp.get_target_location(fallback)
        ```
    """
    return (
        _target.get_location_file()
        .cache(default_location, skip_if_exists=True)
        .set_label("Get Target Location")
    )

update_target_location(max_distance_meters=100, current_location=CaptureLocation())

Conditionally updates the target location when the user is far from the current target.

Calculates the distance between the user's current location and the saved target location. If the distance exceeds the threshold, prompts the user to update the target location to their current position. This enables flexible data collection where the target location can adapt to the user's movements.

Parameters:

Name	Type	Description	Default
max_distance_meters	float | int	Maximum allowed distance in meters before prompting for location update (default: 100 meters)	100
current_location	Procedure[PLocation]	Procedure to get the user's current GPS location (defaults to CaptureLocation())	CaptureLocation()

Returns:

Type	Description
Procedure[PVoid]	A procedure that conditionally updates the target location based on distance
Procedure[PVoid]	and user choice. Does nothing if the user is within the allowed distance.

Example

import capturegraph.procedures as cgp

# Check if user is more than 50 meters from target, prompt to update
cgp.update_target_location(max_distance_meters=50)

# Use a custom location source with default 100m threshold
custom_location = cgp.UserInputLocation(label="Where are you now?")
cgp.update_target_location(current_location=custom_location)

Source code in capturegraph-lib/capturegraph/procedures/toolkits/metadata/location_manager.py

def update_target_location(
    max_distance_meters: float | int = 100,
    current_location: Procedure[PLocation] = CaptureLocation(),
) -> Procedure[PVoid]:
    """
    Conditionally updates the target location when the user is far from the current target.

    Calculates the distance between the user's current location and the saved target
    location. If the distance exceeds the threshold, prompts the user to update the
    target location to their current position. This enables flexible data collection
    where the target location can adapt to the user's movements.

    Args:
        max_distance_meters: Maximum allowed distance in meters before prompting
                           for location update (default: 100 meters)
        current_location: Procedure to get the user's current GPS location
                         (defaults to CaptureLocation())

    Returns:
        A procedure that conditionally updates the target location based on distance
        and user choice. Does nothing if the user is within the allowed distance.

    Example:
        ```python
        import capturegraph.procedures as cgp

        # Check if user is more than 50 meters from target, prompt to update
        cgp.update_target_location(max_distance_meters=50)

        # Use a custom location source with default 100m threshold
        custom_location = cgp.UserInputLocation(label="Where are you now?")
        cgp.update_target_location(current_location=custom_location)
        ```
    """

    target_location = get_target_location(current_location)

    distance_to_target = LocationDistanceMeters(
        left=current_location, right=target_location
    ).set_label("Distance to Target Location")

    threshold_distance = ConstantNumber(value=max_distance_meters).set_label(
        "Threshold Distance"
    )

    too_far = (distance_to_target > threshold_distance).set_label("Is User Too Far?")

    reset_needed = (
        too_far
        & UserInputBool(
            label="You are far from the target location. Update it?",
            true_text="Yes — Update Location",
            false_text="No — Keep Existing",
        )
    ).set_label("Should Update Target Location?")

    return IfThenElse(
        condition=reset_needed,
        true_branch=(
            set_target_location(current_location, skip_if_exists=False).set_label(
                "Update Target Location"
            )
        ),
        false_branch=(DoNothing()),
    ).set_label("Conditional Target Location Update")