Project that aims for generating captcha image with various customization options - for Node.JS
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);- 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)
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.
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.
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
Static function ComplexCaptcha.Generate generates captcha and returns object of GeneratedCaptcha type. It takes one argument, object of GenerateOptions type.
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. |
| 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. |
Object of GenerateOptions type may contains fields:
| 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. |
| 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) |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |