Go Captcha

http://gocaptcha.wencodes.com/docs
Admin
Go Captcha is a behavior verification code system that implements text/graphic click, slide/drag,...
Tokens:5,812
Snippets:13
Trust Score:0.6
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install GoCaptcha v2

Installs the latest version of the GoCaptcha v2 library using go get. This is the primary command for integrating GoCaptcha into your Golang projects.

```shell
go get github.com/wenlng/go-captcha/v2@latest
```

--------------------------------

### Install GoCaptcha Assets

Installs the pre-built embedded asset resources for GoCaptcha using the go get command.

```shell
$goget-ugithub.com/wenlng/go-captcha-assets@latest
```

--------------------------------

### Install GoCaptcha Library

Installs the latest version of the GoCaptcha library for Go projects using the go get command.

```shell
$goget-ugithub.com/wenlng/go-captcha/v2@latest
```

--------------------------------

### Install GoCaptcha Assets

Installs the pre-built embedded asset resources for GoCaptcha. These assets are often required for the captcha generation process.

```shell
go get github.com/wenlng/go-captcha-assets@latest
```

--------------------------------

### Generate Slide Captcha Instance and Data

This Go code demonstrates how to initialize the slide captcha builder, set background and tile resources, generate captcha data, and retrieve image data as base64 strings.

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"github.com/golang/freetype/truetype"
	"github.com/wenlng/go-captcha-assets/resources/imagesv2"
	"github.com/wenlng/go-captcha-assets/resources/tiles"
	"github.com/wenlng/go-captcha/v2/base/option"
	"github.com/wenlng/go-captcha/v2/slide"
)

var slideCapt slide.Captcha

func init() {
	builder := slide.NewBuilder(
		// slide.WithGenGraphNumber(2),
		// slide.WithEnableGraphVerticalRandom(true),
	)
	// background images
	imgs, err := imagesv2.GetImages()
	if err != nil {
		log.Fatalln(err)
	}
	graphs, err := tiles.GetTiles()
	if err != nil {
		log.Fatalln(err)
	}

	var newGraphs = make([]*slide.GraphImage, 0, len(graphs))
	for i := 0; i < len(graphs); i++ {
		graph := graphs[i]
		newGraphs = append(newGraphs, &slide.GraphImage{
			OverlayImage: graph.OverlayImage,
			MaskImage:    graph.MaskImage,
			ShadowImage:  graph.ShadowImage,
		})
	}

	// set resources
	builder.SetResources(
		slide.WithGraphImages(newGraphs),
		slide.WithBackgrounds(imgs),
	)

	sslideCapt = builder.Make()
}

func main() {
	captData, err := slideCapt.Generate()
	if err != nil {
		log.Fatalln(err)
	}

	dotData := captData.GetData()
	if dotData == nil {
		log.Fatalln(">>>>> generate err")
	}
	dots, _ := json.Marshal(dotData)
	fmt.Println(">>>>> ", string(dots))

	var mBase64, tBase64 string
	mBase64, err = captData.GetMasterImage().ToBase64()
	if err != nil {
		fmt.Println(err)
	}
	tBase64, err = captData.GetTileImage().ToBase64()
	if err != nil {
		fmt.Println(err)
	}

	fmt.Println(">>>>> ", mBase64)
	fmt.Println(">>>>> ", tBase64)

	// err = captData.GetMasterImage().SaveToFile("./.caches/master.jpg", option.QualityNone)
	// if err != nil {
	// 	fmt.Println(err)
	// }

	// err = captData.GetTileImage().SaveToFile("./.caches/thumb.png")
	// if err != nil {
	// 	fmt.Println(err)
	// }
}

```

--------------------------------

### GoCaptcha Click Captcha Initialization and Generation

Demonstrates how to initialize the GoCaptcha click captcha with custom resources (fonts, background images) and generate captcha data, including master and thumbnail images. It shows error handling and printing base64 encoded image data.

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"github.com/golang/freetype/truetype"
	"github.com/wenlng/go-captcha-assets/bindata/chars"
	"github.com/wenlng/go-captcha-assets/resources/fonts/fzshengsksjw"
	"github.com/wenlng/go-captcha-assets/resources/imagesv2"
	"github.com/wenlng/go-captcha/v2/base/option"
	"github.com/wenlng/go-captcha/v2/click"
)

var textCapt click.Captcha

func init() {
	builder := click.NewBuilder()
	// fonts
	fonts, err := fzshengsksjw.GetFont()
	if err != nil {
		log.Fatalln(err)
	}
	// background images
	imgs, err := imagesv2.GetImages()
	if err != nil {
		log.Fatalln(err)
	}
	builder.SetResources(
		click.WithChars(chars.GetChineseChars()),
		click.WithFonts([]*truetype.Font{fonts}),
		click.WithBackgrounds(imgs),
	)
	textCapt = builder.Make()
}

func main() {
	captData, err := textCapt.Generate()
	if err != nil {
		log.Fatalln(err)
	}
	dotData := captData.GetData()
	if dotData == nil {
		log.Fatalln(">>>>> generate err")
	}
	dots, _ := json.Marshal(dotData)
	fmt.Println(">>>>> ", string(dots))

	var mBase64, tBase64 string
	mBase64, err = captData.GetMasterImage().ToBase64()
	if err != nil {
		fmt.Println(err)
	}
	tBase64, err = captData.GetThumbImage().ToBase64()
	if err != nil {
		fmt.Println(err)
	}

	fmt.Println(">>>>> ", mBase64)
	fmt.Println(">>>>> ", tBase64)

	// err = captData.GetMasterImage().SaveToFile("./.caches/master.jpg", option.QualityNone)
	// if err != nil {
	// 	fmt.Println(err)
	// }
	// err = captData.GetThumbImage().SaveToFile("./.caches/thumb.png")
	// if err != nil {
	// 	fmt.Println(err)
	// }
}
```

--------------------------------

### GoCaptcha Click Captcha Resource Configuration

Configures the resources used by the click captcha. This includes setting character sets, shape images, fonts, and background images. These options are passed as variadic arguments to the SetResources function.

```go
builder.SetResources(click.WithChars([]string), click.WithShapes(map[string]image.Image), click.WithFonts([]*truetype.Font), click.WithBackgrounds([]image.Image), click.WithThumbBackgrounds([]image.Image))
```

```APIDOC
SetResources(options ...interface{})
  - Configures resources for click captcha generation.
  - Options:
    - click.WithChars([]string): Sets the character seed. The length of the character set must be greater than rangeLen.Max to avoid CharRangeLenErr.
    - click.WithShapes(map[string]image.Image): Sets the shape seed. Requires valid image resources for shape mode, otherwise ShapesTypeErr is triggered.
    - click.WithFonts([]*truetype.Font): Sets the fonts to be used.
    - click.WithBackgrounds([]image.Image): Sets the main background images. Must not be empty, otherwise EmptyBackgroundImageErr is triggered.
    - click.WithThumbBackgrounds([]image.Image): Sets the thumbnail background images.
```

--------------------------------

### GoCaptcha Click Captcha Configuration Options

Details the various configuration options available for customizing the GoCaptcha click captcha builder. These options control image dimensions, character sets, fonts, colors, image effects, and thumbnail properties.

```APIDOC
GoCaptcha Click Captcha Configuration Options:

**Instance Creation:**
- `click.NewBuilder()`: Creates a new builder for click captchas.
- `click.NewBuilder(options...)`: Creates a new builder with initial configuration options.
- `builder.Make()`: Builds the captcha instance for text-based click captchas.
- `builder.MakeWithShape()`: Builds the captcha instance for shape-based click captchas.

**Configuration Options (used with `click.NewBuilder` or `builder.SetOptions`):**

**Main Image Options:**
- `click.WithImageSize(option.Size)`: Sets the main image dimensions (width, height). Default: 300x220.
- `click.WithRangeLen(option.RangeVal)`: Sets the range for the length of random content. `option.RangeVal` is a struct with `Min` and `Max` fields.
- `click.WithRangeAnglePos([]option.RangeVal)`: Sets the range for random angle positions. Expects a slice of `option.RangeVal`.
- `click.WithRangeSize(option.RangeVal)`: Sets the range for random content size. `option.RangeVal` is a struct with `Min` and `Max` fields.
- `click.WithRangeColors([]string)`: Sets the allowed random colors for content. Expects a slice of color strings (e.g., `"#FF0000"`).
- `click.WithDisplayShadow(bool)`: Enables or disables the display of shadows for content.
- `click.WithShadowColor(string)`: Sets the color of the shadow. Expects a color string.
- `click.WithShadowPoint(option.Point)`: Sets the offset for the shadow. `option.Point` is a struct with `X` and `Y` fields.
- `click.WithImageAlpha(float32)`: Sets the transparency (alpha) of the main image. Value between 0.0 and 1.0.
- `click.WithUseShapeOriginalColor(bool)`: When true, uses the original colors of shapes in shape-based captchas. Only applicable to shape captchas.

**Thumbnail Image Options:**
- `click.WithThumbImageSize(option.Size)`: Sets the thumbnail image dimensions (width, height). Default: 150x40.
- `click.WithRangeVerifyLen(option.RangeVal)`: Sets the range for the length of verification content in the thumbnail. `option.RangeVal` is a struct with `Min` and `Max` fields.
- `click.WithDisabledRangeVerifyLen(bool)`: If true, disables random length for verification content, making it consistent with the main image content length.
- `click.WithRangeThumbSize(option.RangeVal)`: Sets the range for the random size of content within the thumbnail. `option.RangeVal` is a struct with `Min` and `Max` fields.
- `click.WithRangeThumbColors([]string)`: Sets the allowed random colors for content in the thumbnail. Expects a slice of color strings.
- `click.WithRangeThumbBgColors([]string)`: Sets the allowed random background colors for the thumbnail. Expects a slice of color strings.
- `click.WithIsThumbNonDeformAbility(bool)`: If true, ensures thumbnail content is not deformed and is unaffected by the background.
- `click.WithThumbBgDistort(int)`: Sets the level of background distortion for the thumbnail. Accepts values from `option.DistortLevel1` to `option.DistortLevel5`.
- `click.WithThumbBgCirclesNum(int)`: Sets the number of small circles to draw on the thumbnail background.
- `click.WithThumbBgSlimLineNum(int)`: Sets the number of slim lines to draw on the thumbnail background.
```

--------------------------------

### GoCaptcha Image Data Handling (JPEG and PNG)

Provides methods for converting image data into various formats like byte slices, base64 strings, and saving to files. JPEGImageData supports quality specification for byte and base64 conversions.

```go
// JPEGImageData methods
jpegData := captData.GetMasterImage()
img := jpegData.Get() // image.Image
bytes, err := jpegData.ToBytes() // []byte, error
base64Str, err := jpegData.ToBase64() // string, error
b64Data, err := jpegData.ToBase64Data() // string, error
bytesQ, err := jpegData.ToBytesWithQuality(80) // []byte, error (quality 0-100)
b64Q, err := jpegData.ToBase64WithQuality(80) // string, error (quality 0-100)
b64DataQ, err := jpegData.ToBase64DataWithQuality(80) // string, error (quality 0-100)
err = jpegData.SaveToFile("captcha.jpg", 90) // error (quality 0-100)

// PNGImageData methods
pngData := captData.GetThumbImage()
imgPng := pngData.Get() // image.Image
bytesPng, err := pngData.ToBytes() // []byte, error
base64StrPng, err := pngData.ToBase64() // string, error
b64DataPng, err := pngData.ToBase64Data() // string, error
err = pngData.SaveToFile("thumbnail.png") // error
```

```APIDOC
JPEGImageData Methods:
  - Get() image.Image: Retrieves the image as a standard Go image.Image.
  - ToBytes() ([]byte, error): Converts the image to a JPEG byte slice.
  - ToBytesWithQuality(imageQuality int) ([]byte, error): Converts to JPEG byte slice with specified quality (0-100).
  - ToBase64() (string, error): Converts to a base64 string with "data:image/jpeg;base64," prefix.
  - ToBase64Data() (string, error): Converts to a base64 string without the data URI prefix.
  - ToBase64WithQuality(imageQuality int) (string, error): Converts to base64 string with prefix and specified quality (0-100).
  - ToBase64DataWithQuality(imageQuality int) (string, error): Converts to base64 string without prefix and specified quality (0-100).
  - SaveToFile(filepath string, quality int) error: Saves the image to a file with specified quality (0-100).
```

```APIDOC
PNGImageData Methods:
  - Get() image.Image: Retrieves the image as a standard Go image.Image.
  - ToBytes() ([]byte, error): Converts the image to a PNG byte slice.
  - ToBase64() (string, error): Converts to a base64 string with "data:image/png;base64," prefix.
  - ToBase64Data() (string, error): Converts to a base64 string without the data URI prefix.
  - SaveToFile(filepath string) error: Saves the image to a file.
```

--------------------------------

### GoCaptcha Click Captcha Data Generation and Retrieval

Generates captcha data and provides methods to retrieve the generated captcha's information, master image, and thumbnail image.

```go
captData, err := capt.Generate()

// Retrieve information about the current validation
info := captData.GetData() // Returns map[int]*Dot

// Retrieve the master image in JPEG format
masterImage := captData.GetMasterImage() // Returns imagedata.JPEGImageData

// Retrieve the thumbnail image in PNG format
thumbImage := captData.GetThumbImage() // Returns imagedata.PNGImageData
```

```APIDOC
capt.Generate() map[int]*Dot, error
  - Generates new captcha data.
  - Returns:
    - A map containing validation information (Dot objects).
    - An error if generation fails.
```

```APIDOC
GetData() map[int]*Dot
  - Retrieves the current validation information for the captcha.
  - Returns: A map where keys are integers and values are *Dot pointers.
```

```APIDOC
GetMasterImage() imagedata.JPEGImageData
  - Retrieves the main captcha image in JPEG format.
  - Returns: An imagedata.JPEGImageData object.
```

```APIDOC
GetThumbImage() imagedata.PNGImageData
  - Retrieves the thumbnail version of the captcha image in PNG format.
  - Returns: An imagedata.PNGImageData object.
```

--------------------------------

### PNGImageData Methods

Provides methods for handling PNG image data within the GoCaptcha rotate captcha module. These methods allow conversion to various formats and saving to files.

```go
type PNGImageData interface {
  Get() image.Image
  ToBytes() ([]byte, error)
  ToBase64() (string, error) // Includes "data:image/png;base64," prefix
  ToBase64Data() (string, error)
  SaveToFile(filepath string) error
}
```

--------------------------------

### Rotate Captcha Validation

API documentation for validating user interaction against the correct rotation angle for a captcha. It includes parameters for user input, correct angle, and error tolerance.

```APIDOC
Validate(srcAngle float64, angle float64, paddingValue float64) bool

  Description:
    Validates if the user-provided angle (srcAngle) is within an acceptable range of the correct captcha angle (angle), considering a padding value for tolerance.

  Parameters:
    srcAngle (float64): The angle provided by the user during interaction.
    angle (float64): The correct rotation angle for the captcha.
    paddingValue (float64): A value that controls the acceptable error margin or tolerance.

  Returns:
    bool: True if the validation passes (angles are within tolerance), false otherwise.

  Example:
    ok := rotate.Validate(userProvidedAngle, correctCaptchaAngle, 0.1)
```

--------------------------------

### GoCaptcha Click Captcha Validation

Validates user interaction against the generated captcha. It requires the user's input coordinates (srcX, srcY) and the captcha's target coordinates and dimensions (X, Y, width, height), along with a padding value for error tolerance.

```go
ok := click.Validate(srcX, srcY, X, Y, width, height, paddingValue)
```

```APIDOC
Validate(srcX, srcY, X, Y, width, height, paddingValue int) bool
  - Validates user's click coordinates against the captcha's target area.
  - Parameters:
    - srcX (int): The X coordinate of the user's click.
    - srcY (int): The Y coordinate of the user's click.
    - X (int): The X coordinate of the target area on the captcha.
    - Y (int): The Y coordinate of the target area on the captcha.
    - width (int): The width of the target area.
    - height (int): The height of the target area.
    - paddingValue (int): A value to allow for error tolerance in the click coordinates.
  - Returns: true if the validation passes, false otherwise.
```
Tokens:
Raw