Skip to content

capturegraph.procedures.toolkits.instructions #

Instructions Toolkit#

This module provides utilities for managing per-user acknowledgements in collaborative capture workflows. Users must acknowledge instructions before proceeding, and these acknowledgements are cached per-user so they only see each instruction once.

The toolkit enables collaborative capture scenarios where:

  • Multiple users share a capture target
  • Each user needs their own acknowledgement state
  • Instructions with optional images guide users through the capture process

show_instructions(title, text, image=NullProcedure(return_type=PImage)) #

Shows instructions and saves acknowledgement to a user-specific folder.

Displays instruction text with an optional image and waits for user acknowledgement. The acknowledgement is cached so the user only sees the instructions once. Uses user-specific storage for collaborative capture scenarios.

Parameters:

Name Type Description Default
text str

The instruction text to display

 required
image Procedure[PImage]

Optional image procedure to display alongside instructions

 NullProcedure(return_type=PImage)

Returns:

Type Description
Procedure[PBool]

A procedure that returns True when the user has acknowledged
Example 
import capturegraph.procedures as cgp

target = cgp.GetRootDirectory()

cgp.show_instructions(
    title="Eye Level Instructions",
    text="Please capture the photo from eye level",
    image=reference_image
)
Source code in capturegraph-lib/capturegraph/procedures/toolkits/instructions.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def show_instructions(
    title: str,
    text: str,
    image: Procedure[PImage] = NullProcedure(return_type=PImage),
) -> Procedure[PBool]:
    """
    Shows instructions and saves acknowledgement to a user-specific folder.

    Displays instruction text with an optional image and waits for user
    acknowledgement. The acknowledgement is cached so the user only sees
    the instructions once. Uses user-specific storage for collaborative
    capture scenarios.

    Args:
        text: The instruction text to display
        image: Optional image procedure to display alongside instructions

    Returns:
        A procedure that returns True when the user has acknowledged

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

        target = cgp.GetRootDirectory()

        cgp.show_instructions(
            title="Eye Level Instructions",
            text="Please capture the photo from eye level",
            image=reference_image
        )
        ```
    """
    instruction = ShowInstructions(text=text, image=image).set_label(title)

    target = GetRootDirectory()
    folder = target.get_user_directory(".acknowledgements")

    return (
        folder.new_file("acknowledged")
        .save(procedure=instruction, skip_if_exists=False)
        .set_label("Acknowledge Instructions")
    )