wulu-geetest-bypass-icon

Offline icon-type solver for Geetest v4 CAPTCHAs. Locates the background collage icon that matches each question and returns normalized click coordinates.

How it works

The icon CAPTCHA shows a collage background built from the same icons that appear as questions, which makes it a matching problem rather than a recognition one:

1. The background collage goes through a YOLO model, which returns one box per direction icon (u, d, l, r, lu, ld, ru, rd).
2. Each question thumbnail is MD5-hashed. That digest is the CDN filename of the asset, so it maps straight to a direction via DIR_HASHES — no image comparison involved.
3. The question is answered with the center of the first still-unused detection facing that direction.

A question with an unknown MD5, or whose direction has no detection, raises UnsupportedQuestionError instead of guessing.

Model

The default model is a YOLOv8n ONNX export: input 640x640, output [1, 12, 8400], 8 direction classes. It is not trained here — both the ONNX file and the DIR_HASHES table come from gaogzhen/GeekedTest under the MIT License. See THIRD_PARTY_NOTICES.md.

Lookup order

1. $WULU_ICON_MODEL, if it points at an existing file
2. <CACHE_DIR>/<FILENAME>
3. download model_url() into CACHE_DIR

The model also downloads on first use. To prefetch it, run the main package's CLI:

wulu-geetest download icon

If huggingface.co is unreachable, point HF_ENDPOINT at a mirror — the same variable huggingface_hub reads, so anything already configured for it works here too:

export HF_ENDPOINT=https://hf-mirror.com
wulu-geetest download icon

--endpoint is shorthand for setting that variable for the one command:

wulu-geetest download icon --endpoint https://hf-mirror.com

download_model(progress=None, *, force=False) is registered under the wulu_geetest_bypass.downloads entry point group, which is how that command finds it; call it directly to download without the framework.

Environment variables

Source constants (_config.py)

For downstream forks that ship their own model:

Class order

Read from the model's names metadata when present, so a retrained model with a different class order works with no configuration. Otherwise WULU_ICON_DIRECTIONS (or its default) is used.

Either way the result must be a permutation of the eight known directions, or the first detection raises UnsupportedModelError — as does a model exported with end2end=True (built-in NMS). The output channel count must equal 4 + len(classes); anything else raises too.

Usage

uv add wulu-geetest-bypass[icon]

The solver registers as an entry point of the wulu_geetest_bypass.solvers group under the icon captcha type, and is discovered automatically by wulu_geetest_bypass.

from wulu_geetest_bypass import Geetest

solver = Geetest(captcha_id='your_captcha_id', risk_type='icon')
seccode = await solver.resolve()