ddddocr

package module
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 28, 2026 License: MIT Imports: 17 Imported by: 0

README

ddddocr-go

Go SDK and CLI for OCR, target detection, click-captcha ordering, and simple slider matching.

Documentation: English | Chinese

Attribution

The original models and implementation references come from sml2h3/ddddocr, a MIT-licensed Python SDK for offline CAPTCHA OCR and related CAPTCHA recognition tasks.

This project packages the related capabilities as a Go SDK and CLI. See NOTICE for attribution details.

Documentation

Install

go get github.com/okatu-loli/ddddocr-go

CLI:

go install github.com/okatu-loli/ddddocr-go/cmd/ddddocr-go@latest

Assets

The SDK uses local ONNX models from assets/:

  • common_old.onnx
  • common.onnx
  • common_det.onnx
  • charsets.json
  • onnxruntime_arm64.dylib

By default, NewClient looks for assets/ in the current directory, then beside the installed module source. For another runtime or asset directory, pass ClientConfig.

client := ddddocr.NewClient(ddddocr.ClientConfig{
    AssetsDir:   "/path/to/assets",
    RuntimePath: "/path/to/onnxruntime.dylib",
})

The bundled runtime is macOS arm64. On other platforms, provide the matching ONNX Runtime shared library path.

SDK Usage

Click captcha:

package main

import (
    "fmt"

    ddddocr "github.com/okatu-loli/ddddocr-go"
)

func main() {
    client := ddddocr.NewClient(ddddocr.ClientConfig{})

    result, err := client.ClickFile("testdata/sample.jpg")
    if err != nil {
        panic(err)
    }

    fmt.Println(result.Target)
}

Output:

{"target":[[461,219],[216,298],[380,136]]}

OCR:

text, err := client.OCRFile("captcha.png", ddddocr.OCROptions{})

Detection:

boxes, err := client.DetectFile("captcha.png")

Slider:

result, err := client.SlideMatchFile("target.png", "background.png", false)

CLI Usage

ddddocr-go --mode click --image testdata/sample.jpg
ddddocr-go --mode detect --image testdata/sample.jpg
ddddocr-go --mode ocr --image captcha.png
ddddocr-go --mode slide-match --target target.png --background background.png

From the repo:

go run ./cmd/ddddocr-go --mode click --image testdata/sample.jpg

API

The primary SDK entry point is:

client := ddddocr.NewClient(ddddocr.ClientConfig{})

Main methods:

  • OCRFile, OCRImage
  • DetectFile, DetectImage
  • ClickFile, ClickImage
  • SlideMatchFile
  • SlideComparisonFile

Release Checklist

  1. Run go test ./....
  2. Commit all files.
  3. Push to GitHub. CI builds the project on each branch push. When the default branch build passes, CI automatically creates and pushes the next vX.Y.Z tag by incrementing the patch version.
git push origin main

Documentation

Overview

Package ddddocr provides local OCR, target detection, click-captcha ordering, and simple slider-captcha helpers backed by ONNX models.

The recommended entry point is Client: 

client := ddddocr.NewClient(ddddocr.ClientConfig{})
result, err := client.ClickFile("captcha.jpg")

Model files and the ONNX Runtime shared library are loaded from the assets directory. By default the package first checks ./assets, then the assets directory beside the module source. Set ClientConfig.AssetsDir or ClientConfig.RuntimePath when deploying with custom paths.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeImage 

func DecodeImage(data []byte) (image.Image, error)

DecodeImage decodes image bytes into an image.Image.

func DefaultAssetsDir 

func DefaultAssetsDir() string

DefaultAssetsDir returns the default assets directory used by NewClient.

func DetectionPreprocess 

func DetectionPreprocess(img image.Image) ([]float32, float64)

DetectionPreprocess converts an image into detection model input data.

func LoadImageFile 

func LoadImageFile(path string) (image.Image, error)

LoadImageFile reads and decodes an image file.

func OCRPreprocess 

func OCRPreprocess(img image.Image, pngFix bool) ([]float32, int, int)

OCRPreprocess converts an image into OCR model input data.

func ReadInputFile 

func ReadInputFile(path string) ([]byte, error)

ReadInputFile reads an image file into memory.

func RunOCRFile 

func RunOCRFile(cfg OCRConfig) (any, error)

RunOCRFile recognizes text from an image file using the provided config.

func RunOCRImage 

func RunOCRImage(img image.Image, cfg OCRConfig) (any, error)

RunOCRImage recognizes text from a decoded image using the provided config.

Types

type ClickCaptchaResult 

type ClickCaptchaResult struct {
	Target [][]int `json:"target"`
}

ClickCaptchaResult contains click points ordered by the prompt sequence.

func ResolveClickCaptcha 

func ResolveClickCaptcha(img image.Image, boxes []DetectionBox) (ClickCaptchaResult, error)

ResolveClickCaptcha resolves ordered click points from a decoded image and precomputed detection boxes.

func RunClickCaptchaFile 

func RunClickCaptchaFile(cfg DetectionConfig) (ClickCaptchaResult, error)

RunClickCaptchaFile resolves ordered click points from an image file.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the high-level SDK entry point.

func NewClient 

func NewClient(cfg ClientConfig) *Client

NewClient creates a reusable ddddocr client.

func (*Client) ClickFile 

func (c *Client) ClickFile(path string) (ClickCaptchaResult, error)

ClickFile returns click points ordered according to the prompt icons.

func (*Client) ClickImage 

func (c *Client) ClickImage(img image.Image) (ClickCaptchaResult, error)

ClickImage returns ordered click points from an already decoded image.

func (*Client) DetectFile 

func (c *Client) DetectFile(path string) ([]DetectionBox, error)

DetectFile returns detection boxes in [x1, y1, x2, y2] format.

func (*Client) DetectImage 

func (c *Client) DetectImage(img image.Image) ([]DetectionBox, error)

DetectImage returns detection boxes from an already decoded image.

func (*Client) OCRFile 

func (c *Client) OCRFile(path string, opts OCROptions) (any, error)

OCRFile recognizes text from an image file.

func (*Client) OCRImage 

func (c *Client) OCRImage(img image.Image, opts OCROptions) (any, error)

OCRImage recognizes text from an already decoded image.

func (*Client) SlideComparisonFile 

func (c *Client) SlideComparisonFile(targetPath, backgroundPath string) (SlideResult, error)

SlideComparisonFile locates a slider target by comparing two images.

func (*Client) SlideMatchFile 

func (c *Client) SlideMatchFile(targetPath, backgroundPath string, simple bool) (SlideResult, error)

SlideMatchFile locates a slider target by template matching.

type ClientConfig 

type ClientConfig struct {
	// AssetsDir contains ONNX models, charsets.json, and optional runtime files.
	// If empty, DefaultAssetsDir is used.
	AssetsDir string
	// RuntimePath points to the ONNX Runtime shared library. If empty, the
	// client uses onnxruntime_arm64.dylib inside AssetsDir.
	RuntimePath string
	// UseBetaModel switches OCR from common_old.onnx/old charset to
	// common.onnx/beta charset.
	UseBetaModel bool
}

type DetectionBox 

type DetectionBox []int

DetectionBox is a rectangle in [x1, y1, x2, y2] pixel coordinates.

func RunDetectionFile 

func RunDetectionFile(cfg DetectionConfig) ([]DetectionBox, error)

RunDetectionFile detects target boxes from an image file.

func RunDetectionImage 

func RunDetectionImage(img image.Image, cfg DetectionConfig) ([]DetectionBox, error)

RunDetectionImage detects target boxes from a decoded image.

type DetectionConfig 

type DetectionConfig struct {
	ImagePath   string
	ModelPath   string
	RuntimePath string
}

DetectionConfig configures the object detection model runtime.

type OCRConfig 

type OCRConfig struct {
	ImagePath   string
	ModelPath   string
	CharsetPath string
	CharsetName string
	RuntimePath string
	PNGFix      bool
	Probability bool
}

OCRConfig configures OCR model paths, runtime path, and preprocessing.

type OCROptions 

type OCROptions struct {
	// PNGFix composites transparent PNG pixels over white before OCR.
	PNGFix bool
	// Probability returns OCRProbability instead of a plain string.
	Probability bool
}

OCROptions controls OCR preprocessing and response shape.

type OCRProbability 

type OCRProbability struct {
	Text       string  `json:"text"`
	Confidence float64 `json:"confidence"`
}

OCRProbability is returned by OCR when probability output is enabled.

type SlideResult 

type SlideResult struct {
	Target     []int    `json:"target"`
	TargetX    int      `json:"target_x"`
	TargetY    int      `json:"target_y"`
	Confidence *float64 `json:"confidence,omitempty"`
}

SlideResult contains a slider target point.

func RunSlideComparisonFile 

func RunSlideComparisonFile(targetPath, backgroundPath string) (SlideResult, error)

RunSlideComparisonFile locates a slider target by comparing two image files.

func RunSlideMatchFile 

func RunSlideMatchFile(targetPath, backgroundPath string, simple bool) (SlideResult, error)

RunSlideMatchFile locates a slider target from target and background files.

func SlideComparison 

func SlideComparison(target, background image.Image) SlideResult

SlideComparison locates a slider target by image difference.

func SlideMatch 

func SlideMatch(target, background image.Image, simple bool) SlideResult

SlideMatch locates a slider target by template matching.

Source Files

View all Source files

Directories

Path Synopsis
cmd
ddddocr-go command
examples
click command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.