More about setting

Settings array specifications

That document is a reference for creating the setting array to be passed to the constructor of ucaptcha class

All setting are passed to the constructor through an array structured like the following:

<?php
$setting = array(
    'dimensions' =>array(/* image dimensions here         */),    
    'string'     =>array(/* string settings go here       */),    
    'operations' =>array(/* containing noises and effects */),
    'colors'     =>array(/* color settings go here        */),
    'nums'       =>array(/* cardinality settings go here  */)
);

NOTE: In the setting array NO element is mandatory, you can even omit the setting array but the result will be a clean white default sized image.

 
dimensions
These parameters go into $setting['dimensions'] array
paramtypedescription
width integer Default value = 300

the width of the image; upper limited by class constant MAX_WIDTH = 400
height integer Default value = 100

the height of the image; upper limited by class constant MAX_HEIGHT = 300
 
string
These parameters go into $setting['string'] array
paramtypedescription
lenght integer Default value = 5

the lenght of the string; upper limited by class constant MAX_STRING_LENGHT = 8
char_set integer Default value = 5 (lowercase letters)

  • 2 for numbers
  • 3 for uppercase
  • 5 for lowercase
  • 7 for symbols
  • any product for a combination

sample: use 14 to see numbers and symbols
font string
OR
array(
string ttf_file1,
string ttf_file2
, [...])		 Default value = "arial.ttf"

ttf font filename , the font that will be used to write the string

NOTE: that file by default must be in a folder named `fonts` and that folder must be a sibling of ucaptcha.class.php

NOTE: You can use the array parameter only from v 1.1
fontsize integer
OR
array(
integer min_size,
integer max_size
)		 Default value = 30

the size used for the string; upper limited by class constant MAX_FONT_SIZE = 200

NOTE: You can use the array parameter only from v 1.1
spacing float Default value = 5

Use that to specify the distance in pixel between two letters.

NOTE: Available only from v 1.1
rotate integer
OR
array(
integer min_angle,
integer max_angle
)		 Default value = false

to specify angle bounds for a random rotation of the whole string
srotate array(
integer min_angle,
integer max_angle
)		 Default value = false

to specify angle bounds for a random rotation of every single element of the string
guess_set integer Default value = false

Give a value as You'd do with char_set

sample: use 2 to ask the user to input only numbers recognoised
guess_set_num integer Default value = false

Give a value as You'd do with char_set

sample: use 2 to ask the user to input only how many numbers recognoised
 
operations
These parameters go into $setting['operations'] array

As You`ll see, all elements that will be written in that array are label & params elements where
> label is a string that indicates which operation we want to add and
> value when requested is always an array that give to the operation some parameters needed


NOTE: All operations are applied in the exact order in which are inserted in this array. An exception is "logo", in fact `logo` if requested will be the last operation no matter where You write it.

To apply the same operation more than once use _ symbol after the operation name and a unique sequence (within that operation).
'operations' => ( 'wave_ssdf', 'wave_123' )
First of all let`s look at text operations
paramtypedescription
text no parameters Prints out a random text
dtext no parameters Prints out a random text picked up (each line a word) from a dictionary.txt file that must be located in the same place as the class
Now we get a look at some noises
paramtypedescription
dots array(integer max_radius ) Default value = array(1)

That noise will add point to the image, the number of dots drawn is ruled by $setting['num']['dots'] array param and upper limited by a class constant NUM_DOTS = 500; the color of dots is ruled by $setting['color']['dots'] array param.;

Parameters:
  • max_radius: maximum radius
lines no parameters Default value =

That noise will add lines to the image, the number of lines drawn is ruled by $setting['num']['lines'] array param and upper limited by a class constant NUM_LINES = 500; the color of lines is ruled by $setting['color']['lines'] array param.
circles array(integer how_many, boolean fill_em) Default value = array(3, false)

That noise will add circles to the image;

Parameters:
  • how_may: number of circles
  • fill_em: fill circles?
polygons array(integer how_many, boolean fill_em) Default value = array(2,true)

That noise will add polygons with random vertex to the image;

Parameters:
  • how_may: number of polygons
  • fill_em: fill polygons?
grind array(integer distance ) Default value = array(5)

Draw a grind with lines distanced by distance parameter

Parameters:
  • distance: the distance between two parallel lines contiguous
chessboard array(integer dimension ) Default value = array(7)

Draw a chessboard with squares dimensioned by dimension parameter

Parameters:
  • dimension: side dimension of each square
randchars array(integer maxsize, boolean noise) Default value = array(specified font_size, false)

That noise will add random chars to the image;

Parameters:
  • maxsize: maximum size for random noise chars
  • noise: if true use charset paramter otherwise uses symbols
func array(callback obj_method, array range) Default value = no defaults

Explicit function through callback

Please see the example
pfunc array(callback obj_method_R, callback obj_method_RHO, array rangeR, array rangeRHO, boolean join_points) Default value = no defaults

Polar function through callback

Please see the example
tfunc array(callback obj_method_X, callback obj_method_Y, array rangeX, array rangeY, boolean join_points) Default value = no defaults

Parametric function through callback

Please see the example
bgimage array(string img_relative_path, array 4 integers clipping array) Default value = no defaults

Add the specified image in background covering the whole image optionally using the clipped part decided with the second parameter
array('../ucaptcha/lion4.jpg', array(20,20,150,150) )

NOTE: the image file path must be relative to the file that renders the image
logo array(string img_relative_path, string position) Default value = no defaults

Add a logo in one of the 9 corner/centers of the image
array('../ucaptcha/mylogo.gif', 'd_r' )

Parameters:
  • img_relative_path: the image to be used (ONLY GIF)
  • position: a string within {'u_l','u_c','u_r','c_l','c_c','c_r','d_l','d_c','d_r'}
vertical_horizontal:(u,c,d)_(l,c,r)

NOTE: the image file path must be relative to the file that renders the image
Now let`s look at some effects
paramtypedescription
warp no parameters Warps randomly in the right places
wave no parameters Apply a wave effect
shear array(integer min, integer max, ) Default value = array(-20,20)

Shears the image along the horizontal direction; the parameter give are not linear with angle but with horizont, 10 stand exactly to 45° and ∞ to 90°
breeze array(integer displacement) Default value = array(1)

Apply to the image an horizontal displacement line per line. The parameter is a strenght factor.
rotate array(integer min, integer max, ) Default value = false

Rotates CCW the image around the center of a random angle between the specified bounds
convolve array(mixed) Default value = no defaults

Within the array You can write one or more of the following built-in filters

  • gauss
  • blur0
  • blur1
  • blur2
  • blur3
  • detect_hlines
  • detect_vlines
  • detect_45lines
  • detect_135lines
  • detect_edges
  • sobel_horiz
  • sobel_vert
  • sobel
  • detect_edges
  • edges
  • laplace
  • sharpen
  • laplace_emboss
  • sharp
  • mean_removal
  • emboss


OR

use Your own filters specifing one or more 3*3 matrix
array(
   array(float, float, float),
   array(float, float, float),
   array(float, float, float),
)
 
colors

These parameters go into $setting['colors'] array

Allowed formats: #012345 ; #012 ; 012345; 012

For every parameter but "bg" You can use two special color label:

  • > rand : the whole element will be randomly colorized
  • > srand : every single composing element will be randomly colorized

paramtypedescription
text string Default value = "#000000"

Color for text

using "rand" the whole string will have a random color
using "srand" every character will have a random color
bg string Default value = "#ffffff"

Color for background.

NOTE: For background You can even use "noise" and "cnoise" producing respectively a random grayscale noise and rgb noise
lines string Default value = "#888888"

Color for lines noise

using "rand" all lines will have the same random color
using "srand" every line will have his own random color
dots string Default value = "#555555"

Color for dots noise

using "rand" all dots will have the same random color
using "srand" every dot will have his own random color
circles string Default value = "#883333"

Color for circles noise

using "rand" all circles will have the same random color
using "srand" every circle will have his own random color
grind string Default value = "#338833"

Color for grind noise

using "rand" all lines of the grind will have the same random color
using "srand" every line will have his own random color
polygons string Default value = "#ffffff"

Color for polygons nooise

using "rand" all polygons sides will have the same random color
using "srand" every polygon will have his sides with one random color
functions string Default value = "#fede76"

Color for functions noise

using "rand" all lines approximating the function graph will have the same random color
using "srand" every line will have his own random color
chessboard_0 string Default value = "#fede76"

Color for chessbard tiles odd

using "rand" all squares will have the same random color
using "srand" every square will have his own random color
chessboard_1 string Default value = "#330000"

Color for chessboard tiles even... same as previous
randchars string Default value = "#333333"

Color for randc-hars

using "rand" all random chars will have the same random color
using "srand" every random char will have his own random color
 
nums
These parameters go into $setting['nums'] array
paramtypedescription
lines integer Default value = 50

Class constant upper limit MAX_NUM_LINES = 500.

Number of lines traced when a "lines" element is in $setting['operations']
dots integer Default value = 200

Class constant upper limit MAX_NUM_DOTS = 500.

Number of dots traced when a "dots" element is in $setting['operations']
circles integer Default value = 3

Class constant upper limit MAX_NUM_CIRCLES = 100

Number of circles traced when a "circles" element is in $setting['operations']
polygons integer Default value = 3

Class constant upper limit MAX_NUM_POLYGONS = 100

Number of polygons traced when a "polygons" element is in $setting['operations']
grind_px integer Default value = 10

Class constant upper limit MAX_NUM_GRINDPX = 100

Distance between grind lines when a "grind" element is in $setting['operations']
randchars integer Default value = 20

Class constant upper limit MAX_NUM_RANDCHARS = 100

Number of random chars drawn when a "randchars" element is in $setting['operations']

Sample list

  • basic
    • random text
    • dictionary text
    • rotate string
    • rotate letters
    • both previous
  • noises
    • dots
    • lines
    • circles
    • polygons
    • grind
    • chessboard
    • rand chars
    • back noise
    • your functions
    • background image
    • your logo
  • effects
    • warp
    • wave
    • shear
    • breeze
    • rotate
  • filters
    • gauss
    • blur
    • detect_hlines
    • detect_vlines
    • sobel
    • sobel_horiz
    • sobel_vert
    • edges
    • laplace
    • laplace_emboss
    • sharpen
    • mean_removal
    • your one
  • cognitive filters
    • subset based
    • subset count based