Image CAPTCHAs

Image CAPTCHAs

The examples below are complete server-side generation examples. Keep answers and private metadata on the server.

ImageRandomCaptcha

Selects one image and creates answer choices from filenames.

from pathlib import Path

from CaptchaGenerator import ImageRandomCaptcha

image_folder = Path("./images")

filename, correct_name, extension, choices = ImageRandomCaptcha().generate(
    path_folder=str(image_folder),
    number_random_select=4,
)

public_image = image_folder / filename
print("Show this image:", public_image)
print("Choice buttons:", choices)

# Run this comparison on the server.
user_choice = "Tree"
solved = user_choice.casefold() == correct_name.casefold()
print("Solved:", solved)

Image names should be meaningful, for example Tree.png, Car.png and Apple.png.

ImageDirectionCaptcha

Reads the expected direction from an image filename.

from pathlib import Path

from CaptchaGenerator import ImageDirectionCaptcha

image_folder = Path("./direction_images")
filename, expected_direction = ImageDirectionCaptcha().generate(
    folder_path=str(image_folder)
)

print("Show:", image_folder / filename)
print(
    "Buttons:",
    ("Up", "Down", "Left", "Right", "UpLeft", "UpRight",
     "DownLeft", "DownRight"),
)

user_direction = "Up"
solved = user_direction.casefold() == expected_direction.casefold()
print("Solved:", solved)

Use filenames such as arrow_Up.png or icon_DownLeft.jpg.

ImageGridCaptcha

Builds a selectable image grid. The answer contains every matching zero-based cell index.

from CaptchaGenerator import CaptchaConfig, ImageGridCaptcha

config = CaptchaConfig(width=720, height=720, random_seed=42)
result = ImageGridCaptcha(config).generate(
    path_folder="./images",
    target_name="Tree",
    name_export="image_grid",
    path_export="./output",
    grid_size=3,
)

print("Show image:", result.path)
print("Instruction:", result.prompt)
print("Grid size:", result.metadata["grid_size"])

# Example response received from a multi-select grid UI.
selected_cells = [1, 5]
solved = set(selected_cells) == set(result.answer)
print("Solved:", solved)

Do not send result.answer to the browser. Send only the image, prompt and grid size.

RotateImageCaptcha

Rotates an upright source image and asks which operation restores it.

from CaptchaGenerator import CaptchaConfig, RotateImageCaptcha

result = RotateImageCaptcha(
    CaptchaConfig(width=720, height=420, random_seed=42)
).generate(
    image_path="./images/upright_arrow.png",
    name_export="rotate",
    path_export="./output",
)

print("Show image:", result.path)
print("Instruction:", result.prompt)
print("Buttons:", ("clockwise", "counterclockwise", "180"))

user_rotation = "clockwise"
solved = user_rotation == result.answer
print("Solved:", solved)

The source image must have an obvious upright orientation.

UpsideDownObjectCaptcha

Shows repeated objects with one rotated object.

from CaptchaGenerator import CaptchaConfig, UpsideDownObjectCaptcha

config = CaptchaConfig(width=800, height=480, random_seed=42)
result = UpsideDownObjectCaptcha(config).generate(
    name_export="upside_down",
    path_export="./output",
    image_path=None,  # Uses the built-in arrow icon.
    item_count=12,
    rotation=180,
)

print("Show image:", result.path)
print("Instruction:", result.prompt)
print("Numbered options:", range(1, result.metadata["item_count"] + 1))

# UI labels are one-based; the internal answer is zero-based.
user_number = 4
user_index = user_number - 1
solved = user_index == result.answer
print("Solved:", solved)

Pass image_path="./images/object.png" to use your own transparent object.