complexcaptcha

span.code { display: inline; padding: 0; width: 100%; font-size: 13px; font-family: monospace; background-color: rgba(0,0,0,0.08); color: rgba(0,0,0,0.8); } table.optstable { font-size: 14px; } table.optstable tr:nth-child(1) td { background-color: rgba(0,0,0,0.1); }

ComplexCaptcha

Project that aims for generating captcha image with various customization options - for Node.JS

Quick look

For simply generating and saving one captcha image:

import * as fs from "fs";

import ComplexCaptcha from "complexcaptcha";

//

// generating captcha
const data = ComplexCaptcha.Generate({
    mimeType:   "image/jpeg"
});

// saving to file
fs.writeFileSync(`./captcha__${data.solution}.jpeg`), data.buffer);

Current features

• Custom characters list (string)
• Custom font or fonts selected randomly for each character.
• Custom colors by creating palette of 3 colors (background, foreground, details) or providing array of palettes (random picking)
• Displacement of individual characters on y-axis
• Deformation of individual characters (scaling/skewing)
• Rotation of individual characters
• Pairing individual characters for overlaping
• Randomly picking characters for being impostors (characters that doesn't matter in answer/solution)
• Randomly picking font for each character.
• Ability to disable features for individual provided fonts
• Ability to disable characters for individual provided fonts
• Drawing fake captcha text in background with smaller font size (dummies)
• Drawing dirt on top of captcha (lines, xor linex/box/islands)

How to build

To build from typescript to javascript CommonJS module, just run command npm run build. You will find built code in dist directory. This command build whole module along with examples.

Examples

To run any of the examples located in examples folder:

• Run command npm run build for building whole module along with examples.
• Run command npm run example1 for running example1 program.
• Look at the output in output/example1 directory.

API

Registering custom font

If You want to use custom font/s, just call ComplexCaptcha.CanvasRegisterFont function with same arguments as in registerFont function in canvas module for Node.js. Read more details here: https://github.com/Automattic/node-canvas#registerfont

ComplexCaptcha.Generate

Static function ComplexCaptcha.Generate generates captcha and returns object of GeneratedCaptcha type. It takes one argument, object of GenerateOptions type.

GeneratedCaptcha

Object of GeneratedCaptcha type contains fields:

name	type	description
text	string	Contains text that is displayed on generated image. Including impostors, excluding background text/dummies.
solution	string	Contains text that is answer to generated image. Against that string You want to test answer of user.
buffer	Buffer	Contains buffer that holds image data in jpeg or png format.
instructions	Instructions	Contains few informations about generated captcha - useful for composing question that will be presented to user.

GeneratedCaptcha.Instructions

name	type	description
maxLength	number	Max length of solution can be.
omitMarked	boolean	Says that impostors/fake characters are on image among real ones and are marked in some way. (currently colored circle)
omitBackgroundText	boolean	Says that background text units are on image that aren't part of solution/answer.

GenerateOptions

Object of GenerateOptions type may contains fields:

table#generate-options tr:not(:nth-child(1)) td:nth-child(2) { text-align: center; font-weight: bold; } table#generate-options tr:not(:nth-child(1)) td:nth-child(4) { max-width: 250px; }

name	optional	type	default	description
mimeType		"image/png" | "image/jpeg"	N/A	Decides about mime type of image in resulted buffer.
quality	✔️	number	0.75	Decides about quality of image - works only with mimeType of "image/jpeg"
padding	✔️	number	10	Sets padding around captcha for readability.
characters	✔️	string	"abcdefghijklmonpqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456790"	List of characters that captcha is built from.
palette	✔️	Palette | Palette[]	{ background: [255, 255, 255], foreground: [0, 0, 0], details: [255, 0, 0], }	Holds colors information, it can be one or array of palettes. With array, generating function will pick one randomly.
fontSize	✔️	number	60	Size of front characters that build captcha code.
fontInfo	✔️	null | FrontFontInfo | FrontFontInfo[]	null	Details that describe font usage, or array of them for random picking. See below. Value of null means defaults of Konva library will be used, probably it's about default OS font. Tip: ComplexCaptcha has few fonts preinstalled, free for comercial use.
length	✔️	number | [number, number]	6	Length of captcha code. It can be number or number range if You want it random.
charDisplacementV	✔️	boolean | CharDisplacementVOptions	true	Value of true means default inner options will be applied, false means feature is disabled for all fonts and characters. Value of CharDisplacementVOptions type means custom options will be applied - described below.
charRotation	✔️	boolean | CharRotationOptions	true	Value of true means default inner options will be applied, false means feature is disabled for all fonts and characters. Value of CharRotationOptions type means custom options will be applied - described below.
charDeformation	✔️	boolean | CharDeformationOptions	true	Value of true means default inner options will be applied, false means feature is disabled for all fonts and characters. Value of CharDeformationOptions type means custom options will be applied - described below.
pairing	✔️	boolean | PairingOptions	true	Value of true means default inner options will be applied, false means feature is disabled for all fonts and characters. Value of PairingOptions type means custom options will be applied - described below.
impostors	✔️	boolean | ImpostorsOptions	true	Value of true means default inner options will be applied, false means feature is disabled for all fonts and characters. Value of ImpostorsOptions type means custom options will be applied - described below.
dirt	✔️	boolean | DirtOptions	true	Value of true means default inner options will be applied, false means feature is disabled for all fonts and characters. Value of DirtOptions type means custom options will be applied - described below.
dummies	✔️	boolean | DummiesOptions	true	Value of true means default inner options will be applied, false means feature is disabled for all fonts and characters. Value of DummiesOptions type means custom options will be applied - described below.

GenerateOptions, Palette

name	type	description
background	Color	Color of background. Color type is equivalent to Array of 3 or 4 numbers (rgb or rgba)
foreground	Color	Color of foreground elements like for example text. Color type is equivalent to Array of 3 or 4 numbers (rgb or rgba)
details	Color	Color of details, for example impostors marks. Color type is equivalent to Array of 3 or 4 numbers (rgb or rgba)

GenerateOptions, FontInfo/FrontFontInfo

Object of FontInfo/FrontFontInfo type contains information about font used to render text:

name	optional	type	default	description
family		string	N/A	Holds font family name, for example: "arial". Tip: ComplexCaptcha has few preinstalled fonts that are free for commercial use. You can find theirs family names looking to assets/fonts/ directory, each folder name is family name as well.
allowRotation	✔️	boolean	true	Only FrontFontInfo. If false then characters with that font can't be rotated.
allowDeformation	✔️	boolean	true	Only FrontFontInfo. If false then characters with that font can't be deformated.
allowForPairs	✔️	boolean	true	Only FrontFontInfo. If false then that font can't be used for pairs - two characters joined and overlapped into one unit.
disallowCharacters	✔️	string	""	Only FrontFontInfo. String that contains characters that font is not allowed to be used for.

GenerateOptions.CharDisplacementVOptions

Object of CharDisplacementVOptions type contains information about how generator will displace vertically characters on image.

name	optional	type	default	description
chance	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of that feature will be applied to character/pair.
range	✔️	[number, number]	[20, 30]	Range of displacement. Displacement value on y-axis will be random in that range, direction also will be random with 50:50 chance.

GenerateOptions.CharRotationOptions

Object of CharRotationOptions type contains information about how generator will rotate characters on image.

name	optional	type	default	description
chance	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of that feature will be applied to character/pair.
range	✔️	[number, number]	[-35, 35]	Range of rotation. Character will be rotated by random value in that range.
excludeChars	✔️	false | string	false	If You want some characters to not be rotated at all, put them in a string of that field, or set to false if You don't want to.

GenerateOptions.CharDeformationOptions

Object of CharDeformationOptions type contains information about how generator will deformate characters on image. First, a chance test will be performed, then the deformation type will be selected randomly (scaling on x or y axis, or skewing on x or y axis)

name	optional	type	default	description
chance	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of that feature will be applied to character/pair.
scxRange	✔️	[number, number]	[0.75, 3]	Range of scaling on x-axis. Character will be scaled by random value in that range.
scyRange	✔️	[number, number]	[0.75, 2]	Range of scaling on y-axis. Character will be scaled by random value in that range.
skxRange	✔️	[number, number]	[0.1, 0.5]	Range of skewing on x-axis. Character will be skewed by random value in that range.
skyRange	✔️	[number, number]	[0.1, 0.5]	Range of skewing on y-axis. Character will be skewed by random value in that range.

GenerateOptions.PairingOptions

Object of PairingOptions type contains information about how generator will pair characters rendered on image. Pairing is feature that randomly pair two characters into one unit, that will be rotated/deformated together and also both characters in pair will slightly overlapped for less readability and greater challange (can be customized).

name	optional	type	default	description
chance	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of that feature will be applied to whole captcha code.
disallowed	✔️	false | string[]	false	Pairs that aren't allowed for occuring. For example ["ab", "oq"] means if that characters will be generated side by side, it isn't possible for algorithm to make them as a pair in random decision.
defaultSqueezing	✔️	number	3	Value of overlapping that works by decreasing space between characters in pair.
squeezingPairs	✔️	null | Record<string, number>	null	Squeezing value for individual pairs. For example: {"oq": 5} means that all pairs will be squeezed by defaultSqueezing value except oq that will be squeezed by 5. Value of null means that there is no individual configs.

GenerateOptions.ImpostorsOptions

Object of ImpostorsOptions type contains information about fake characters will be placed among real ones. User is challanged to skip fake characters when rewriting captcha. Fake characters are marked by circle colored by palette.details, but modified to be semi-transparent.

name	optional	type	default	description
chance	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of that feature will be applied to whole captcha code.
count	✔️	number | [number, number]	[1, 2]	Count of fake characters to be placed among real characters. Range can be provided for random count.
convert	✔️	boolean	true	Value of true means that existed characters will be transformed into impostors (solution text/final real text will be shirnked then). Value of false means that fake characters will be added to existed characters and placed randomly among them.
hintRadius	✔️	number	20	Radius of the circle that marks fake character.

GenerateOptions.DirtOptions

Object of DirtOptions type contains information about drawings that will be put on top of whole image to make it less readable for cpu. Currently only xor box and line are avaliable and are selected randomly.

name	optional	type	default	description
chance	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of that feature will be applied to image.
chanceForLine	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of "line" dirt will be applied.
chanceForXorLine	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of "xorLine" dirt will be applied.
chanceForXorBox	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of "xorBox" dirt will be applied.
chanceForXorIsland	✔️	number	0.5	Value from 0 (never) to 1 (always) that describes chance of "xorIsland" dirt will be applied.
count	✔️	number | [number, number]	[1, 3]	Count of dirt units to be drawn.
lineOpacity	✔️	number	1	Opacity of line, use values from 0 to 1.
lineWidth	✔️	number | [number, number]	3	Width of line. Thick lines can make image unreadable for humans.
lineTension	✔️	number	0	Tension of line. Value of 0 means it is disabled.
lineBezier	✔️	boolean	true	Draw line as bezier, works only if lineTension is disabled.
xorLineWidth	✔️	number | [number, number]	3	Width of xorLine..
xorIslandArmCount	✔️	number | [number, number]	30	Vertex count of polygon, the more You will set, the more island will be rounded, 30 is fine.
xorIslandArmRadius	✔️	number | [number, number]	40	Radius/distance of vertexes from the center point of polygon. It can be multiplied by accents (randomly choosen angles where distance is higher.
xorIslandAccentCount	✔️	number | [number, number]	[1-2]	Accents count. Accents are angles where radius is multiplied for making shape looking less like circle.
xorIslandAccentStrength	✔️	number | [number, number]	1.5	Accent strength. Radius = radius * xorIslandAccentStrength
xorIslandAccentSensitivity	✔️	number | [number, number]	35	Accent sensitivity. That value determines how close to accent (radius/distance of vertex from center) starts to be multiplied.

GenerateOptions.DummiesOptions

Object of DummiesOptions type contains information about smaller text units that will be put behind real text to make whole captcha less readable for cpu.

name	optional	type	default	description
chance	✔️	number	0.75	Value from 0 (never) to 1 (always) that describes chance of that feature will be applied to image.
count	✔️	number | [number, number]	[4, 8]	Count of background text units to be drawn.
length	✔️	number | [number, number]	[2, 4]	Length of each background text unit.
fontPercentageSize	✔️	number	0.4	Font size for background text units. Its relative to real text font size. Keep it lower than around 0.75 for readability.
fontInfo	✔️	null | FontInfo | FontInfo[]	null	Font information that describes what font will be used, set to array for randomness. Value of null means it will use FontInfo from real text config.
opacity	✔️	number	0.65	Opacity of background text, use values from 0 to 1.
rotation	✔️	false | [number, number]	[-15, 15]	Rotation of each background text unit in degrees. Use false value for disabling.