From 6449bc0e8703161d4a8fd060dbc0be3ef75065d9 Mon Sep 17 00:00:00 2001 From: zihluwang Date: Sat, 23 May 2026 08:48:42 +0800 Subject: [PATCH] docs: add captcha project documentation Add English and Chinese documentation for onixbyte/captcha library, including overview (index.mdx) and full API reference (api.md). --- docs/en-gb/projects/captcha/api.md | 248 ++++++++++++++++++++++++ docs/en-gb/projects/captcha/index.mdx | 89 +++++++++ docs/zh-hans/projects/captcha/api.md | 248 ++++++++++++++++++++++++ docs/zh-hans/projects/captcha/index.mdx | 89 +++++++++ 4 files changed, 674 insertions(+) create mode 100644 docs/en-gb/projects/captcha/api.md create mode 100644 docs/en-gb/projects/captcha/index.mdx create mode 100644 docs/zh-hans/projects/captcha/api.md create mode 100644 docs/zh-hans/projects/captcha/index.mdx diff --git a/docs/en-gb/projects/captcha/api.md b/docs/en-gb/projects/captcha/api.md new file mode 100644 index 0000000..40498f5 --- /dev/null +++ b/docs/en-gb/projects/captcha/api.md @@ -0,0 +1,248 @@ +--- +title: Captcha API +--- + +## Package Overview + +The library is organised under the base package `com.onixbyte.captcha` with the following structure: + +| Package | Description | +|---------------------------------------------|---------------------------------------| +| `com.onixbyte.captcha` | Core interfaces | +| `com.onixbyte.captcha.impl` | Default implementations | +| `com.onixbyte.captcha.text` | Text producer and renderer interfaces | +| `com.onixbyte.captcha.text.impl` | Text producer and renderer impls | +| `com.onixbyte.captcha.text.enums` | Text-related enums | +| `com.onixbyte.captcha.background` | Background producer interface | +| `com.onixbyte.captcha.background.impl` | Background producer implementations | +| `com.onixbyte.captcha.noise` | Noise producer interface | +| `com.onixbyte.captcha.noise.impl` | Noise producer implementations | +| `com.onixbyte.captcha.gimpy` | Distortion engine interface | +| `com.onixbyte.captcha.gimpy.impl` | Distortion engine implementations | + +--- + +## Producer + +The top-level interface responsible for creating CAPTCHA images with text drawn on them. + +```java +Producer captcha = DefaultCaptchaProducer.builder() + .textProducer(textProducer) + .wordRenderer(wordRenderer) + .gimpyEngine(gimpyEngine) + .backgroundProducer(backgroundProducer) + .width(200) + .height(50) + .borderDrawn(true) + .borderColour(Color.BLACK) + .borderThickness(1) + .build(); + +String text = captcha.createText(); +BufferedImage image = captcha.createImage(text); +``` + +### DefaultCaptchaProducer Builder + +| Method | Default Value | Description | +|---------------------|---------------------------------------------|---------------------------------------| +| `textProducer` | `DefaultTextProducer.builder().build()` | The text producer to use | +| `wordRenderer` | `DefaultWordRenderer.builder().build()` | The word renderer to use | +| `gimpyEngine` | `WaterRipple.builder().build()` | The distortion engine to use | +| `backgroundProducer`| `DefaultBackgroundProducer.builder().build()`| The background producer to use | +| `width` | `200` | Width of the CAPTCHA image | +| `height` | `50` | Height of the CAPTCHA image | +| `borderDrawn` | `true` | Whether a border is drawn | +| `borderColour` | `Color.BLACK` | The colour of the border | +| `borderThickness` | `1` | The thickness of the border | + +--- + +## Text + +### TextProducer + +Interface for creating CAPTCHA text strings. + +```java +public interface TextProducer { + String getText(); +} +``` + +#### DefaultTextProducer + +Generates random text with configurable length and character set. + +```java +DefaultTextProducer textProducer = DefaultTextProducer.builder() + .length(6) // default: 6 + .chars("ABCDEFGHIJKLMNOPQRSTUVWXYZ".toCharArray()) // default: a-z, A-Z, 0-9 + .build(); +``` + +| Method | Default Value | Description | +|----------|-----------------------------------------------------------|--------------------------------| +| `length` | `6` | Length of generated text | +| `chars` | `a-z`, `A-Z`, `0-9` (62 characters) | Characters used for generation | + +### WordRenderer + +Interface for rendering text onto an image. + +```java +public interface WordRenderer { + BufferedImage renderWord(String word, int width, int height); +} +``` + +#### DefaultWordRenderer + +Renders text with configurable font, colour, and spacing. + +```java +DefaultWordRenderer wordRenderer = DefaultWordRenderer.builder() + .fontSize(40) // default: 40 + .fonts("Arial", "Courier") // default: Arial, Courier + .fontColour(Color.BLACK) // default: Color.BLACK + .charSpace(2) // default: 2 + .fontStyle(FontStyle.BOLD) // default: FontStyle.BOLD + .build(); +``` + +| Method | Default Value | Description | +|-------------|-----------------------------------|-----------------------------------------| +| `fontSize` | `40` | Font size in pixels | +| `fonts` | `["Arial", "Courier"]` | Font families to use (randomly chosen) | +| `fontColour`| `Color.BLACK` | Font colour | +| `charSpace` | `2` | Space between characters in pixels | +| `fontStyle` | `FontStyle.BOLD` | Font style to apply | + +### FontStyle + +Defines the supported font styles for rendering CAPTCHA text. + +| Value | Corresponding AWT Constant | Description | +|---------------|-------------------------------------|------------------------------| +| `PLAIN` | `java.awt.Font.PLAIN` | Plain style | +| `BOLD` | `java.awt.Font.BOLD` | Bold style | +| `ITALIC` | `java.awt.Font.ITALIC` | Italic style | +| `BOLD_ITALIC` | `java.awt.Font.BOLD | Font.ITALIC` | Bold and italic combined | + +--- + +## GimpyEngine + +Interface for applying image distortion effects. + +```java +public interface GimpyEngine { + BufferedImage getDistortedImage(BufferedImage baseImage); +} +``` + +### WaterRipple + +Applies a water ripple distortion effect. Extends `AbstractGimpyEngine` and adds noise automatically. + +```java +WaterRipple gimpy = WaterRipple.builder() + .noiseProducer(DefaultNoiseProducer.builder().build()) // default: DefaultNoiseProducer + .build(); +``` + +| Method | Default Value | Description | +|-----------------|---------------------------------------------|------------------------------| +| `noiseProducer` | `DefaultNoiseProducer.builder().build()` | The noise producer to use | + +### FishEyeGimpy + +Applies a fish-eye distortion effect with horizontal and vertical lines over the image. + +```java +FishEyeGimpy gimpy = FishEyeGimpy.builder() + .build(); +``` + +### ShadowGimpy + +Applies a shadow and ripple effect. Extends `AbstractGimpyEngine` and adds noise automatically. + +```java +ShadowGimpy gimpy = ShadowGimpy.builder() + .noiseProducer(DefaultNoiseProducer.builder().build()) // default: DefaultNoiseProducer + .build(); +``` + +| Method | Default Value | Description | +|-----------------|---------------------------------------------|------------------------------| +| `noiseProducer` | `DefaultNoiseProducer.builder().build()` | The noise producer to use | + +--- + +## Noise + +### NoiseProducer + +Interface for adding noise to an image. + +```java +public interface NoiseProducer { + void makeNoise(BufferedImage image, float factorOne, float factorTwo, + float factorThree, float factorFour); +} +``` + +#### DefaultNoiseProducer + +Adds noise curves with configurable colour. + +```java +DefaultNoiseProducer noise = DefaultNoiseProducer.builder() + .noiseColour(Color.BLACK) // default: Color.BLACK + .build(); +``` + +| Method | Default Value | Description | +|---------------|---------------|---------------------| +| `noiseColour` | `Color.BLACK` | The noise colour | + +#### NoNoiseProducer + +A no-op implementation that does not add any noise to the image. + +```java +NoiseProducer noise = NoNoiseProducer.builder() + .build(); +``` + +--- + +## Background + +### BackgroundProducer + +Interface for adding background to an image. + +```java +public interface BackgroundProducer { + BufferedImage addBackground(BufferedImage image); +} +``` + +#### DefaultBackgroundProducer + +Creates a gradient background with configurable start and end colours. + +```java +DefaultBackgroundProducer background = DefaultBackgroundProducer.builder() + .colourFrom(Color.WHITE) // default: Color.LIGHT_GRAY + .colourTo(Color.LIGHT_GRAY) // default: Color.WHITE + .build(); +``` + +| Method | Default Value | Description | +|--------------|--------------------|---------------------------------| +| `colourFrom` | `Color.LIGHT_GRAY` | The starting colour of gradient | +| `colourTo` | `Color.WHITE` | The ending colour of gradient | diff --git a/docs/en-gb/projects/captcha/index.mdx b/docs/en-gb/projects/captcha/index.mdx new file mode 100644 index 0000000..b2d29b0 --- /dev/null +++ b/docs/en-gb/projects/captcha/index.mdx @@ -0,0 +1,89 @@ +--- +title: Captcha +--- + +import { Tabs, Tab } from "@rspress/core/theme" + +## Introduction + +Captcha is a Java library for generating CAPTCHA images. This project is a spiritual successor to Google's Kaptcha, modernised for contemporary development practices. + +With Captcha, you can easily generate customisable CAPTCHA images with various distortion effects, noise, and background options to integrate into your Java applications. + +## Features + +- **Easy Integration** — Simple builder-based API for quick setup and configuration. +- **Customisable CAPTCHA Generation** — Configure text length, character sets, font styles, and colours. +- **Multiple Distortion Effects** — Choose from Water Ripple, Fish Eye, and Shadow effects. +- **Configurable Noise** — Add noise lines with custom colours, or disable noise entirely. +- **Gradient Backgrounds** — Customisable gradient background colours. +- **Clean, Modern Codebase** — Well-documented, type-safe, and easy to extend. + +## Installation + + + + ```kotlin title="build.gradle.kts" + dependencies { + implementation("com.onixbyte:captcha:1.0.0") + } + ``` + + + ```xml title="pom.xml" + + + com.onixbyte + captcha + 1.0.0 + + + ``` + + + +## Quick Start + +```java +import com.onixbyte.captcha.Producer; +import com.onixbyte.captcha.background.BackgroundProducer; +import com.onixbyte.captcha.background.impl.DefaultBackgroundProducer; +import com.onixbyte.captcha.gimpy.GimpyEngine; +import com.onixbyte.captcha.gimpy.impl.WaterRipple; +import com.onixbyte.captcha.impl.DefaultCaptchaProducer; +import com.onixbyte.captcha.noise.NoiseProducer; +import com.onixbyte.captcha.noise.impl.DefaultNoiseProducer; +import com.onixbyte.captcha.text.TextProducer; +import com.onixbyte.captcha.text.WordRenderer; +import com.onixbyte.captcha.text.impl.DefaultTextProducer; +import com.onixbyte.captcha.text.impl.DefaultWordRenderer; + +import javax.imageio.ImageIO; +import java.awt.*; +import java.awt.image.BufferedImage; +import java.io.File; +import java.io.IOException; + +public class CaptchaExample { + + public static void main(String[] args) throws IOException { + // Create a CAPTCHA producer with default configurations + Producer captcha = DefaultCaptchaProducer.builder().build(); + + // Generate text and create the image + String captchaText = captcha.createText(); + BufferedImage captchaImage = captcha.createImage(captchaText); + + // Save the image to a file + ImageIO.write(captchaImage, "png", new File("captcha.png")); + + System.out.println("CAPTCHA text: " + captchaText); + } +} +``` + +This generates a CAPTCHA image with a 6-character random text and saves it as a PNG file. + +## License + +Captcha is open-source software released under the MIT License. diff --git a/docs/zh-hans/projects/captcha/api.md b/docs/zh-hans/projects/captcha/api.md new file mode 100644 index 0000000..60370ad --- /dev/null +++ b/docs/zh-hans/projects/captcha/api.md @@ -0,0 +1,248 @@ +--- +title: Captcha API +--- + +## 包结构概览 + +库的代码组织在基础包 `com.onixbyte.captcha` 下，结构如下： + +| 包 | 描述 | +|---|---| +| `com.onixbyte.captcha` | 核心接口 | +| `com.onixbyte.captcha.impl` | 默认实现 | +| `com.onixbyte.captcha.text` | 文本生成器和渲染器接口 | +| `com.onixbyte.captcha.text.impl` | 文本生成器和渲染器实现 | +| `com.onixbyte.captcha.text.enums` | 文本相关枚举 | +| `com.onixbyte.captcha.background` | 背景生成器接口 | +| `com.onixbyte.captcha.background.impl` | 背景生成器实现 | +| `com.onixbyte.captcha.noise` | 噪点生成器接口 | +| `com.onixbyte.captcha.noise.impl` | 噪点生成器实现 | +| `com.onixbyte.captcha.gimpy` | 扭曲引擎接口 | +| `com.onixbyte.captcha.gimpy.impl` | 扭曲引擎实现 | + +--- + +## Producer + +负责创建 CAPTCHA 图片并在其上绘制文字的顶层接口。 + +```java +Producer captcha = DefaultCaptchaProducer.builder() + .textProducer(textProducer) + .wordRenderer(wordRenderer) + .gimpyEngine(gimpyEngine) + .backgroundProducer(backgroundProducer) + .width(200) + .height(50) + .borderDrawn(true) + .borderColour(Color.BLACK) + .borderThickness(1) + .build(); + +String text = captcha.createText(); +BufferedImage image = captcha.createImage(text); +``` + +### DefaultCaptchaProducer Builder + +| 方法 | 默认值 | 描述 | +|---|---|---| +| `textProducer` | `DefaultTextProducer.builder().build()` | 文本生成器 | +| `wordRenderer` | `DefaultWordRenderer.builder().build()` | 文字渲染器 | +| `gimpyEngine` | `WaterRipple.builder().build()` | 扭曲引擎 | +| `backgroundProducer` | `DefaultBackgroundProducer.builder().build()` | 背景生成器 | +| `width` | `200` | 验证码图片宽度 | +| `height` | `50` | 验证码图片高度 | +| `borderDrawn` | `true` | 是否绘制边框 | +| `borderColour` | `Color.BLACK` | 边框颜色 | +| `borderThickness` | `1` | 边框厚度 | + +--- + +## Text + +### TextProducer + +用于创建 CAPTCHA 文本字符串的接口。 + +```java +public interface TextProducer { + String getText(); +} +``` + +#### DefaultTextProducer + +生成可配置长度和字符集的随机文本。 + +```java +DefaultTextProducer textProducer = DefaultTextProducer.builder() + .length(6) // 默认: 6 + .chars("ABCDEFGHIJKLMNOPQRSTUVWXYZ".toCharArray()) // 默认: a-z, A-Z, 0-9 + .build(); +``` + +| 方法 | 默认值 | 描述 | +|---|---|---| +| `length` | `6` | 生成文本的长度 | +| `chars` | `a-z`、`A-Z`、`0-9`（共 62 个字符） | 生成文本使用的字符集 | + +### WordRenderer + +将文字渲染到图片上的接口。 + +```java +public interface WordRenderer { + BufferedImage renderWord(String word, int width, int height); +} +``` + +#### DefaultWordRenderer + +使用可配置的字体、颜色和间距渲染文字。 + +```java +DefaultWordRenderer wordRenderer = DefaultWordRenderer.builder() + .fontSize(40) // 默认: 40 + .fonts("Arial", "Courier") // 默认: Arial, Courier + .fontColour(Color.BLACK) // 默认: Color.BLACK + .charSpace(2) // 默认: 2 + .fontStyle(FontStyle.BOLD) // 默认: FontStyle.BOLD + .build(); +``` + +| 方法 | 默认值 | 描述 | +|---|---|---| +| `fontSize` | `40` | 字号（像素） | +| `fonts` | `["Arial", "Courier"]` | 字体族（随机选择） | +| `fontColour` | `Color.BLACK` | 字体颜色 | +| `charSpace` | `2` | 字符间距（像素） | +| `fontStyle` | `FontStyle.BOLD` | 字体样式 | + +### FontStyle + +定义 CAPTCHA 文字渲染支持的字体样式。 + +| 值 | 对应的 AWT 常量 | 描述 | +|---|---|---| +| `PLAIN` | `java.awt.Font.PLAIN` | 普通样式 | +| `BOLD` | `java.awt.Font.BOLD` | 粗体 | +| `ITALIC` | `java.awt.Font.ITALIC` | 斜体 | +| `BOLD_ITALIC` | `java.awt.Font.BOLD | Font.ITALIC` | 粗斜体 | + +--- + +## GimpyEngine + +用于对图片应用扭曲效果的接口。 + +```java +public interface GimpyEngine { + BufferedImage getDistortedImage(BufferedImage baseImage); +} +``` + +### WaterRipple + +应用水波纹扭曲效果。继承 `AbstractGimpyEngine`，自动添加噪点。 + +```java +WaterRipple gimpy = WaterRipple.builder() + .noiseProducer(DefaultNoiseProducer.builder().build()) // 默认: DefaultNoiseProducer + .build(); +``` + +| 方法 | 默认值 | 描述 | +|---|---|---| +| `noiseProducer` | `DefaultNoiseProducer.builder().build()` | 噪点生成器 | + +### FishEyeGimpy + +应用鱼眼扭曲效果，在图片上绘制水平和垂直线条。 + +```java +FishEyeGimpy gimpy = FishEyeGimpy.builder() + .build(); +``` + +### ShadowGimpy + +应用阴影和波纹效果。继承 `AbstractGimpyEngine`，自动添加噪点。 + +```java +ShadowGimpy gimpy = ShadowGimpy.builder() + .noiseProducer(DefaultNoiseProducer.builder().build()) // 默认: DefaultNoiseProducer + .build(); +``` + +| 方法 | 默认值 | 描述 | +|---|---|---| +| `noiseProducer` | `DefaultNoiseProducer.builder().build()` | 噪点生成器 | + +--- + +## Noise + +### NoiseProducer + +向图片添加噪点的接口。 + +```java +public interface NoiseProducer { + void makeNoise(BufferedImage image, float factorOne, float factorTwo, + float factorThree, float factorFour); +} +``` + +#### DefaultNoiseProducer + +使用可配置的颜色添加噪点曲线。 + +```java +DefaultNoiseProducer noise = DefaultNoiseProducer.builder() + .noiseColour(Color.BLACK) // 默认: Color.BLACK + .build(); +``` + +| 方法 | 默认值 | 描述 | +|---|---|---| +| `noiseColour` | `Color.BLACK` | 噪点颜色 | + +#### NoNoiseProducer + +不向图片添加任何噪点的空实现。 + +```java +NoiseProducer noise = NoNoiseProducer.builder() + .build(); +``` + +--- + +## Background + +### BackgroundProducer + +向图片添加背景的接口。 + +```java +public interface BackgroundProducer { + BufferedImage addBackground(BufferedImage image); +} +``` + +#### DefaultBackgroundProducer + +创建具有可配置起始和结束颜色的渐变背景。 + +```java +DefaultBackgroundProducer background = DefaultBackgroundProducer.builder() + .colourFrom(Color.WHITE) // 默认: Color.LIGHT_GRAY + .colourTo(Color.LIGHT_GRAY) // 默认: Color.WHITE + .build(); +``` + +| 方法 | 默认值 | 描述 | +|---|---|---| +| `colourFrom` | `Color.LIGHT_GRAY` | 渐变起始颜色 | +| `colourTo` | `Color.WHITE` | 渐变结束颜色 | diff --git a/docs/zh-hans/projects/captcha/index.mdx b/docs/zh-hans/projects/captcha/index.mdx new file mode 100644 index 0000000..68dd663 --- /dev/null +++ b/docs/zh-hans/projects/captcha/index.mdx @@ -0,0 +1,89 @@ +--- +title: Captcha +--- + +import { Tabs, Tab } from "@rspress/core/theme" + +## 介绍 + +Captcha 是一个用于生成 CAPTCHA 验证码图片的 Java 库。本项目是 Google Kaptcha 的精神继承者，按照现代开发实践进行了现代化改造。 + +通过 Captcha，您可以轻松生成可定制的 CAPTCHA 图片，支持多种扭曲效果、噪点和背景选项，轻松集成到您的 Java 应用中。 + +## 特性 + +- **易于集成** — 基于 Builder 的简洁 API，快速完成配置和集成。 +- **可定制的验证码生成** — 配置文本长度、字符集、字体样式和颜色。 +- **多种扭曲效果** — 支持水波纹、鱼眼和阴影效果。 +- **可配置噪点** — 使用自定义颜色添加噪点线条，或完全禁用噪点。 +- **渐变背景** — 可自定义的渐变背景颜色。 +- **简洁现代的代码** — 文档完善、类型安全且易于扩展。 + +## 安装 + + + + ```kotlin title="build.gradle.kts" + dependencies { + implementation("com.onixbyte:captcha:1.0.0") + } + ``` + + + ```xml title="pom.xml" + + + com.onixbyte + captcha + 1.0.0 + + + ``` + + + +## 快速开始 + +```java +import com.onixbyte.captcha.Producer; +import com.onixbyte.captcha.background.BackgroundProducer; +import com.onixbyte.captcha.background.impl.DefaultBackgroundProducer; +import com.onixbyte.captcha.gimpy.GimpyEngine; +import com.onixbyte.captcha.gimpy.impl.WaterRipple; +import com.onixbyte.captcha.impl.DefaultCaptchaProducer; +import com.onixbyte.captcha.noise.NoiseProducer; +import com.onixbyte.captcha.noise.impl.DefaultNoiseProducer; +import com.onixbyte.captcha.text.TextProducer; +import com.onixbyte.captcha.text.WordRenderer; +import com.onixbyte.captcha.text.impl.DefaultTextProducer; +import com.onixbyte.captcha.text.impl.DefaultWordRenderer; + +import javax.imageio.ImageIO; +import java.awt.*; +import java.awt.image.BufferedImage; +import java.io.File; +import java.io.IOException; + +public class CaptchaExample { + + public static void main(String[] args) throws IOException { + // 使用默认配置创建 CAPTCHA 生产者 + Producer captcha = DefaultCaptchaProducer.builder().build(); + + // 生成文本并创建图片 + String captchaText = captcha.createText(); + BufferedImage captchaImage = captcha.createImage(captchaText); + + // 保存图片到文件 + ImageIO.write(captchaImage, "png", new File("captcha.png")); + + System.out.println("CAPTCHA 文本: " + captchaText); + } +} +``` + +以上代码生成一张包含 6 位随机字符的 CAPTCHA 图片，并将其保存为 PNG 文件。 + +## 许可证 + +Captcha 是采用 MIT 许可证发布的开源软件。