PictCaptcha Programmer Manual


May 2013


Patricio Cardó




Table of contents

PictCaptcha Conceptual basis

Functioning of PictCaptcha


1.Install PictCaptcha

2.Include PictCaptcha in the php page

3.Configure PictCaptcha styles

4.Configure session starting in linker file

5.Change language of text.

6.Insert images and drawings

7.Change advanced options


To Do list for current version

Research, questions and suggestions


PictCaptcha Conceptual basis

As any programmer knows, CAPTCHA concept relies on the fact that computers are Turing machines, and Humans not. In that context, humans could deduce individual entities in a confusing image. In fact, most people like to see things where there are just clouds or rocks. Furthermore, it is difficult to make a machine to have illusions.

Using this criterion, most CAPTCHAS show distorted alphanumeric entities, which are abstract entities by themselves and are language-dependant. PictCaptcha aims to be more universal and give other level of humanity to the system, using real solid elements and their presentation.

PictCaptcha is not only easy (my three years old daughter likes to play with it), it can be adapted to restrict access to people outside certain community. For example, programmer can use pictures of electrical elements and drawing of their symbols, so people not familiar with electricity knowledge will find it difficult to pass.


Functioning of PictCaptcha

Basically, the server selects a random group of entities, read their representations, distort them and send as table to the client together with images. Client see it inside a web form, and select images that fit the drawing. Once the form is submitted, the server compares the code of selected images with the code of the random selection.

In order to difficult hacking, all web links are not exposed to client, instead, it displays the linker file who knows where to search required files. Furthermore, it has some sophistication to avoid some known hacking techniques.

Between page and page, server remember variables with $_SESSIONS, so programmer must be care about session handling because linker file execute inside an iframe. See instructions for more details.

PictCaptcha does not require GD library or other image manipulation since it uses a table to display drawings.





3.1.Install PictCaptcha

Compressed files pack must be downloaded
  1. 1.Expand files to a directory where server can run php files 

  2. 2.Create folder named imgs inside the directory where files were expanded 

  3. 3.Move all images to imgs folder 

  4. 4.Copy pictcaptcha_link.php to a directory more related to website 

  5. 5.Run test_pictcapt.php from browser. Drawing and images should display properly. 

3.2.Include PictCaptcha in the php page

Sessions must be started before PictCaptcha object is created
  1. 1.Open php file with the preferred php editor 

  2. 2.Set a variable for the pictcaptcha directory (e.g. $dir = “var/www/others/pictcaptcha/”) 

  3. 3.Include pictcaptcha.php file (require_once $dir.“pictcaptcha.php”) 

  4. 4.Set a configuration variable with quantities and routes ( 

    1. $capt_conf = array(

          1. "quantity"=>3,

                    "linker"=>"pictcaptcha_link.php" , 

                    “dir” => $dir 


    1. $capt = new pict_captcha($capt_conf);


  5. 5.Create pictcaptcha object ($capt = new pict_captcha($capt_conf);) 

  6. 6.Create a condition for verification ( 

    1. if(!empty($_POST["pictcapt_id"])){

            if($capt->verify()){        // any task to continue 

      1. }else{ // any task to stop}



  7. 7.Set a variable for html to put inside the form (e.g.: $ifr = $capt->gethtml();) 

  8. 8.Include the variable in the HTML to display 



3.3.Configure PictCaptcha styles

  1. 1.Open pictcaptcha.css in the preferred CSS editor 

  2. 2.Use the following table to recognise rules 




The question character (“?”) displayed at right of drawing


The help text displayed when user clicks “?”


The foreground pixel. Note that background-color is used to set color


The background pixel


  2. 3.Change classes values until appearance is as expected 

3.4.Configure session starting in linker file

Do it only if website have a special session handler

It could be difficult if website is running over a php platform that has its own way to handle sessions.

  1. 1.Open pictcaptcha_link.php file used in the site 

  2. 2.Replace session_start() with special session handler lines to call/create and start 


3.5.Change language of text.

  1. 1 Change base phrases 

    1. 1.1 Open pictcaptcha_conf.php 

    2. 1.2 Change values in “phrases” array, starting at line 3. 

  2. 2 Change page phrases 

    1. 2.1 Add “phrases” key in the configuration variable (see Include PictCaptcha in the php page, step 4 ) 

    2. 2.2 Set an array for that key, with or more of the following keys: 




title of ? character


title of image


div element displayed on help click


div element displayed on help click


3.6.Insert images and drawings

Bad writing inside the code could lead in operating failures
Use images with the proper permission
  1. 1.Select an image of the desired entity 

  2. 2.Resize the image to 60px × 60px 

  3. 3.Save the image in the /imgs folder of pictcaptcha folder 

  4. 4.Open pictcaptcha_conf.php file with the preferred php editor 

  5. 5.Create a key in the “objects” array, with an array value containing the keys “pic” and “img” 

  6. 6.Set the image file name as a string value of the “img” key  

  7. 7.Open the Drawing panel at http://decumano.com.ar/codes/drawer/, and play with it until drawing is complete 

  8. 8.Select the code displayed in the textarea, and copy it. 

  9. 9.Paste code as the string value of “pic” key. 

3.7.Change advanced options

  1. 1.Open pictcaptcha_conf.php file with the preferred php editor 

  2. 2.Change “pixel” value if it is required a different table size 

  3. 3.Change “onlyfromallowed” value to false, if “framing” hacking technique is not a problem. E.g. analysis purposes. 

  4. 4.Add IP numbers as string values to “referers” array, if it is required to open element from outside server. 


To Do list for current version

Research, questions and suggestions

If you have any questions or suggestions regarding PictCaptcha usage, please use phpclasses.org platform where the class is published

If you want to take a Research around PictCaptcha concept, please contact me to patricio.cardo at decumano.com.ar