Class Captcha

Core CAPTCHA class for low-level canvas operations and image generation.

This class provides direct access to the underlying canvas operations for creating CAPTCHA images. It offers more granular control compared to CaptchaGenerator but requires manual coordination of drawing operations. Use CaptchaGenerator for most use cases unless you need fine-grained control over the rendering process.

Example: Basic usage

const captcha = new Captcha(300, 100);
captcha.drawCaptcha({ text: 'HELLO', size: 40 });
captcha.drawTrace({ color: '#95a5a6' });

const buffer = await captcha.png;
console.log('Text:', captcha.text);

Example: Advanced multi-step generation

const captcha = new Captcha(400, 150, 6);

// Add background noise with decoys
captcha.addDecoy({ total: 30, opacity: 0.3 });

// Draw main captcha text
captcha.drawCaptcha({
  text: 'SECURE',
  size: 60,
  colors: ['#e74c3c', '#3498db']
});

// Add connecting trace lines
captcha.drawTrace({ size: 4, opacity: 0.8 });

// Add more decoys on top
captcha.addDecoy({ total: 20, opacity: 0.2 });

const buffer = await captcha.png;

Index

Constructors

constructor

new Captcha(width?: number, height?: number, characters?: number): Captcha
Creates a new Captcha instance with specified canvas dimensions.

Initializes the underlying HTML5 canvas and 2D rendering context with optimized settings for CAPTCHA generation. The canvas is configured for high-quality text rendering and precise drawing operations.
Parameters
- width: number = defaultDimension.width
  Canvas width in pixels (default: 300)
- height: number = defaultDimension.height
  Canvas height in pixels (default: 100)
- characters: number = ...
  Expected number of characters for coordinate calculation (default: 6)
Returns Captcha
Example: Standard CAPTCHA size
```
const captcha = new Captcha(300, 100);
```
Example: Large CAPTCHA for better accessibility
```
const captcha = new Captcha(500, 200, 8);
```
Example: Mobile-optimized size
```
const captcha = new Captcha(250, 80, 5);
```
- Defined in src/captcha.ts:89

Properties

`Protected`_height

_height: number

`Protected`_width

_width: number

`Protected`_captcha

_captcha: SetCaptchaOption

`Protected`_trace

_trace: SetTraceOption

`Protected`_decoy

_decoy: SetDecoyOption

`Protected`_canvas

_canvas: Canvas

`Protected`_ctx

_ctx: CanvasRenderingContext2D

`Protected`_coordinates

_coordinates: number[][]

async

async: boolean

Accessors

text

get text(): string
Gets the current CAPTCHA text that has been drawn on the canvas.

Returns the text content that users need to enter to solve the CAPTCHA. This value is set when drawCaptcha() is called and represents the solution to the generated CAPTCHA image.

Returns string
The CAPTCHA text string, or empty string if no text has been set
Example
```
const captcha = new Captcha(300, 100);
captcha.drawCaptcha({ text: 'HELLO' });
console.log(captcha.text); // Output: "HELLO"
```
- Defined in src/captcha.ts:122

png

get png(): Buffer | Promise<Buffer>
Gets the generated CAPTCHA image as a PNG buffer.

Returns either a Promise (async mode) or Buffer (sync mode) containing the PNG-encoded image data. The mode is determined by the async property.

Returns Buffer | Promise<Buffer>
PNG image buffer (Promise in async mode, Buffer in sync mode)
Example: Async mode (default)
```
const captcha = new Captcha(300, 100);
captcha.drawCaptcha({ text: 'HELLO' });

const buffer = await captcha.png;
fs.writeFileSync('captcha.png', buffer);
```
Example: Sync mode
```
const captcha = new Captcha(300, 100);
captcha.async = false;
captcha.drawCaptcha({ text: 'HELLO' });

const buffer = captcha.png as Buffer;
fs.writeFileSync('captcha.png', buffer);
```
- Defined in src/captcha.ts:152

Methods

drawImage

drawImage(image: Image): Captcha
Draws a background image on the CAPTCHA canvas.

The image is automatically scaled to fit the entire canvas dimensions, providing a background that increases visual complexity and security. This should typically be called before drawing text and other elements.
Parameters
- image: Image
  Pre-loaded image object (use resolveImage() to load from file/URL)
Returns Captcha
The Captcha instance for method chaining
Example: With background image
```
import { resolveImage } from 'captcha-canvas';

const backgroundImage = await resolveImage('./noise-pattern.jpg');
const captcha = new Captcha(300, 100);

captcha
  .drawImage(backgroundImage)
  .drawCaptcha({ text: 'HELLO', opacity: 0.9 });
```
Example: Texture background
```
const texture = await resolveImage('https://example.com/texture.png');
const captcha = new Captcha(400, 150);

captcha
  .drawImage(texture)
  .addDecoy({ opacity: 0.2 })
  .drawCaptcha({ text: 'SECURE' });
```
- Defined in src/captcha.ts:193

addDecoy

addDecoy(decoyOption?: SetDecoyOption): Captcha

Adds decoy characters to the CAPTCHA for enhanced security against OCR.

Decoy characters are randomly positioned fake characters that confuse automated solving attempts while remaining distinguishable from real text by humans through opacity, size, or positioning differences.

Parameters

decoyOption: SetDecoyOption = {}
Configuration for decoy character appearance

Returns Captcha

The Captcha instance for method chaining

Example: Basic decoy setup

const captcha = new Captcha(300, 100);
captcha
  .addDecoy({ total: 25, opacity: 0.3 })
  .drawCaptcha({ text: 'HELLO' });

Example: Layered security with multiple decoy calls

const captcha = new Captcha(400, 150);
captcha
  .addDecoy({ total: 30, opacity: 0.2, size: 15 })  // Background noise
  .drawCaptcha({ text: 'SECURE' })
  .addDecoy({ total: 15, opacity: 0.1, size: 25 }); // Foreground confusion

Example: Custom decoy styling

const captcha = new Captcha(350, 120);
captcha
  .addDecoy({
    total: 40,
    color: '#95a5a6',
    font: 'Arial',
    size: 18,
    opacity: 0.25
  })
  .drawCaptcha({ text: 'VERIFY' });

drawTrace

drawTrace(traceOption?: SetTraceOption): Captcha
Draws connecting trace lines between CAPTCHA characters for enhanced security.

Trace lines connect the character positions, making character segmentation significantly more difficult for automated systems while maintaining human readability. The lines follow the character coordinates established by drawCaptcha().
Parameters
- traceOption: SetTraceOption = {}
  Configuration for trace line appearance
Returns Captcha
The Captcha instance for method chaining
Example: Basic trace line
```
const captcha = new Captcha(300, 100);
captcha
  .drawCaptcha({ text: 'HELLO' })
  .drawTrace({ color: '#95a5a6', size: 3 });
```
Example: Subtle trace for better readability
```
const captcha = new Captcha(350, 120);
captcha
  .drawCaptcha({ text: 'VERIFY', size: 45 })
  .drawTrace({
    color: '#bdc3c7',
    size: 2,
    opacity: 0.6
  });
```
Example: Security-focused thick trace
```
const captcha = new Captcha(400, 150);
captcha
  .addDecoy({ total: 20, opacity: 0.2 })
  .drawCaptcha({ text: 'SECURE', size: 50 })
  .drawTrace({
    color: '#e74c3c',
    size: 5,
    opacity: 0.8
  });
```
Note: Call drawCaptcha() before drawTrace() to ensure proper character coordinate calculation.
- Defined in src/captcha.ts:297

drawCaptcha

drawCaptcha(captchaOption?: DrawCaptchaOption | DrawCaptchaOption[]): Captcha

Draws the main CAPTCHA text on the canvas with specified styling options.

This is the core method for rendering the CAPTCHA text that users need to solve. Supports both single configuration objects and arrays for multi-styled text segments. Character positions are automatically calculated and stored for trace line generation.

Parameters

captchaOption: DrawCaptchaOption | DrawCaptchaOption[] = {}
Single text configuration or array of configurations for multi-styled segments

Returns Captcha

The Captcha instance for method chaining

Example: Basic text rendering

const captcha = new Captcha(300, 100);
captcha.drawCaptcha({
  text: 'HELLO',
  size: 40,
  color: '#2c3e50'
});

Example: Advanced styling with transformations

const captcha = new Captcha(350, 120);
captcha.drawCaptcha({
  text: 'SECURE',
  size: 50,
  font: 'Arial',
  rotate: 15,        // Random rotation up to ±15 degrees per character
  skew: true,        // Apply random skewing transformation
  opacity: 0.85
});

Example: Multi-color text using colors array

const captcha = new Captcha(400, 150);
captcha.drawCaptcha({
  text: 'RAINBOW',
  size: 45,
  colors: ['#e74c3c', '#f39c12', '#f1c40f', '#27ae60', '#3498db', '#9b59b6']
});

Example: Multi-styled text segments

const captcha = new Captcha(450, 150);
captcha.drawCaptcha([
  { text: 'SEC', size: 50, color: '#e74c3c', font: 'Arial', rotate: 10 },
  { text: 'URE', size: 45, color: '#27ae60', font: 'Times', skew: true }
]);

Example: Random text generation

const captcha = new Captcha(300, 100);
captcha.drawCaptcha({
  characters: 6,     // Generate 6 random characters
  size: 40,
  colors: ['#34495e', '#e67e22']
});
console.log('Generated text:', captcha.text);

Throws

When array mode is used but text property is missing from segments

Throws

When text length doesn't match specified character count

Class Captcha

Example: Basic usage

Example: Advanced multi-step generation

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Captcha

Example: Standard CAPTCHA size

Example: Large CAPTCHA for better accessibility

Example: Mobile-optimized size

Properties

Protected_height

Protected_width

Protected_captcha

Protected_trace

Protected_decoy

Protected_canvas

Protected_ctx

Protected_coordinates

async

Accessors

text

Returns string

Example

png

Returns Buffer | Promise<Buffer>

Example: Async mode (default)

Example: Sync mode

Methods

drawImage

Parameters

Returns Captcha

Example: With background image

Example: Texture background

addDecoy

Parameters

Returns Captcha

Example: Basic decoy setup

Example: Layered security with multiple decoy calls

Example: Custom decoy styling

drawTrace

Parameters

Returns Captcha

Example: Basic trace line

Example: Subtle trace for better readability

Example: Security-focused thick trace

drawCaptcha

Parameters

Returns Captcha

Example: Basic text rendering

Example: Advanced styling with transformations

Example: Multi-color text using colors array

Example: Multi-styled text segments

Example: Random text generation

Throws

Throws

Settings

On This Page

`Protected`_height

`Protected`_width

`Protected`_captcha

`Protected`_trace

`Protected`_decoy

`Protected`_canvas

`Protected`_ctx

`Protected`_coordinates