Skip to content

Toolkits#

Toolkits are pre-built modules that add common features to your procedures. They encapsulate complex functionality so you don't have to build it from scratch. See the Toolkits API for full reference.

Location Manager#

Manage GPS locations for field data collection. See location_manager API.

Setting Target Location#

Define where data should be captured:

import capturegraph.procedures as cgp

# Set from user's current GPS
cgp.set_target_location(cgp.CaptureLocation(), skip_if_exists=True)

# Or set a specific location
cgp.set_target_location(
    cgp.ConstantLocation(
        latitude=37.7749,
        longitude=-122.4194,
        altitude=0.0
    ),
    skip_if_exists=False
)

Location Validation#

Ensure users are at the correct location:

import capturegraph.procedures as cgp

# Check if user is within range; prompt to update if not
cgp.update_target_location(max_distance_meters=100)

This encapsulates:

  1. Getting current location
  2. Calculating distance to target
  3. Prompting user if too far away
  4. Updating the saved location if confirmed

Use Cases#

  • Field research: Consistent sampling locations
  • Clinical studies: Verify correct facility
  • Environmental monitoring: Reproducible measurements

Notification Manager#

Schedule reminders for data collection. See notification_manager API.

Basic Configuration#

Let users configure their preferred reminder schedule:

import capturegraph.procedures as cgp

# Runs once per target, remembers settings
cgp.configure_notifications()

This single function:

  1. Asks if notifications should be enabled
  2. Asks for scheduling preference (time-of-day or interval)
  3. Collects specific timing
  4. Sets up the notification schedule

Notification Modes#

Time-of-Day: Fire at specific times

  • "Remind me every day at 8:00 AM"
  • Good for daily routines

Interval: Fire after a fixed period

  • "Remind me 6 hours after each capture"
  • Good for event-driven collection

Thumbnail Manager#

Create preview images for the app UI. See thumbnail_manager API.

Setting Thumbnails#

import capturegraph.procedures as cgp

# Capture and create thumbnail
photo = cgp.CaptureImage(label="Primary Photo")
thumbnail = cgp.ConvertImageToThumbnail(image=photo)

# Set for both target and session
cgp.set_thumbnail(target, thumbnail, skip_if_exists=True)
cgp.set_thumbnail(session, thumbnail, skip_if_exists=True)

Non-Blocking Thumbnail Generation#

Thumbnail conversion can take a second or two. Use .make_optional() to start conversion in the background without blocking the user:

import capturegraph.procedures as cgp

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

    photo = cgp.CaptureImage(label="Photo")
    thumbnail = cgp.ConvertImageToThumbnail(image=photo)

    save_thumbnails = cgp.ProcedureSet(
        procedures=[
            cgp.set_thumbnail(target, thumbnail, skip_if_exists=True),
            cgp.set_thumbnail(session, thumbnail, skip_if_exists=True),
        ]
    )

    return cgp.ProcedureSequence(
        procedures=[
            session.new_file("photo").save(photo),

            # Start thumbnail conversion in background (non-blocking)
            save_thumbnails.make_optional(),

            # User continues with other captures while thumbnail processes...
            session.new_file("notes").save(cgp.UserInputString(label="Notes")),

            # By now thumbnail is likely ready; require completion
            save_thumbnails,
        ]
    )

The pattern: start optional early → do other work → require at end. By the time the user finishes other steps, the thumbnail is ready.

Combining Toolkits#

Real procedures often use multiple toolkits:

import capturegraph.procedures as cgp

def field_study_procedure():
    target = cgp.GetRootDirectory()
    session = target.new_session("observation")

    photo = cgp.CaptureImage(label="Specimen Photo")
    thumbnail = cgp.ConvertImageToThumbnail(image=photo)

    return cgp.ProcedureSequence(
        procedures=[
            # One-time setup
            cgp.configure_notifications(),

            # Validate location
            cgp.update_target_location(max_distance_meters=25),

            # Collect data
            session.new_file("photo").save(photo),
            session.new_file("notes").save(
                cgp.UserInputString(label="Observations")
            ),
            session.new_file("temperature").save(
                cgp.UserInputNumber(label="Temperature (°C)")
            ),

            # Set thumbnails
            cgp.ProcedureSet(
                procedures=[
                    cgp.set_thumbnail(target, thumbnail, skip_if_exists=True),
                    cgp.set_thumbnail(session, thumbnail, skip_if_exists=True),
                ]
            ),
        ]
    )

See Also#