<?php
$q = $_SERVER['QUERY_STRING'];
if (!empty($q) && file_exists('examples/' . basename($q) . '.php'))
{
highlight_file('examples/' . basename($q) . '.php');
exit;
} elseif (!empty($q) && file_exists('examples/mods/' . basename($q) . '.php')) {
highlight_file('examples/mods/' . basename($q) . '.php');
exit;
}
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<title>PIMG Documentation</title>
<style type="text/css">
body { font: 9pt / 13pt verdana; }
pre { background-color: #eeeeee; padding: 5px; }
a { text-decoration: none; }
a:visited { color: blue; }
</style>
</head>
<body>
<center>
<h1>PIMG 1.1 Documentation</h1>
(full documentation for each function is available in the classes themselfs)
</center>
<h3>Basic modules</h3>
<ol>
<li><a href="#basicusage">Basic usage</a></li>
<li><a href="#submodules">Loading sub modules</a></li>
<li><a href="#createimg">Creating an image</a></li>
<li><a href="#debug">Debugging</a></li>
<li><a href="#render">Rendering</a></li>
<li><a href="#color">Creating a color</a></li>
<li><a href="#colormix">Mixing colors</a></li>
<li><a href="#fill">Fill</a></li>
<li><a href="#pixels">Pixels</a></li>
<li><a href="#stretch">Stretching an image</a></li>
<li><a href="#fit">Fitting an image</a></li>
<li><a href="#scan">Scanning pixels</a></li>
<li><a href="#merge">Merging images</a></li>
<li><a href="#crop">Cropping images</a></li>
</ol>
<h3>User modules</h3>
<ol>
<li><a href="#uloading">Loading user modules</a></li>
<li><a href="#uwriting">Writing user modules</a></li>
<li><a href="#u1">Watermark Remover · by · ton4y@abv.bg</a></li>
<li><a href="#u2">Filters · by · ton4y@abv.bg</a></li>
<li><a href="#u3"><font style="color: orange;">[ EXPERIMENT ]</font> THE MATRIX · by · ton4y@abv.bg</a></li>
</ol>
<br />
<hr />
<br />
<h2>Basic modules</h2>
<ol>
<li>
<h3>[ <a href="#">top</a> ] <a name="basicusage">Basic usage</a></h3>
To use the PIMG library just upload it to your web server somewhere (best in e separate folder), include the core <b>pimg.php</b> file in your project and you are done.<br />
Now read on to learn how to use it.
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="submodules">Loading sub modules</a></h3>
PIMG uses a file yerarchy for loading sub modules by the magic php method __call().
All pimg modules are stored in the same directory as the core pimg.php, and they must be named: [module].pimg.php:
<pre>color.pimg.php</pre>
Inside there must be declared a pimg module class like this:
<pre>class pimg_color { // class body }</pre>
Whenever the user wants to use that module he/she just needs to call a method of the pimg class with the name of the module:
<pre>$pimg -> color();</pre>
[ <a href="_example.php?f=submodule" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=submodule" target="_blank">SOURCE</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="createimg">Creating an image</a></h3>
Images are created by instatiating a pimg image class:
<pre>$pimg = new pimg_image([$img_resource, [$width, [$height]]]);</pre>
[ <a href="_example.php?f=createimg" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=createimg" target="_blank">SOURCE</a> ]<br /><br />
<ul>
<li>The image resource can be several types:</li><br />
<ul>
<li>Path to local image:<br />
<pre>'path/to/image.jpg'</pre>
</li>
<li>.. or URL of an image:<br />
<pre>'http://domain.com/path/to/image.jpg'</pre>
</li>
<li>An image file passed as a string</li>
<li>An image file passed as a base64 encoded string</li>
<li>A scan matrix return by pimg_scan</li>
<li>If the image resource is empty, a blank image is created</li>
</ul>
<br />
<li>The image width can be an integer or empty (null), in this case the default is used (100px)</li><br />
<li>Same goes for the height</li><br />
</ul>
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="debug">Debugging</a></h3>
Everytime something goes wrong a debug log is saved in the core class:
<pre>$pimg -> setDebug($msg, [$type, [__CLASS__]]);</pre>
If the debug message's status is error, the script will break and the message will be shown.<br /><br />
You can clear the debug by calling:
<pre>$pimg -> clearDebug();</pre>
Everytime you want to view the debug log, you can simply call:
<pre>$pimg -> showDebug();</pre>
[ <a href="_example.php?f=debug" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=debug" target="_blank">SOURCE</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="render">Rendering</a></h3>
You can render your final image using this method:
<pre>$pimg -> render([$format, [$location, [$quality]]]);</pre>
<ul>
<li>The format is any supported GD format. For example if GD supports these functions: <u>imagejpeg</u>, <u>imagegif</u>, <u>imagepng</u>, then the valid formats will be: <u>jpeg</u>, <u>gif</u> and <u>png</u>. JPEG is by default.</li>
<li>You can specify location for the image to be stored if you want. The location is any valid path to jpg, png, gif etc. file:
<pre>$pimg -> render('jpeg', 'path/to/file.jpg');</pre></li>
<li>You can specify the quality for the image from 0 to 100 (if supported, for example PNG has no quality parameter, but JPEG does), 75 is by default:
<pre>$pimg -> render('jpeg', 'path/to/file.jpg', 25);</pre></li>
</ul>
<b>STRONGLY RECOMMENDED</b><br />You can choose to render the image only if the debug log is empty, if it's not the method will display it:
<pre>$pimg -> renderDebug( <i>same params as render()</i> );</pre>
[ <a href="_example.php?f=render" target="_blank">DEMO</a> ] · [ <a href="_example.php?f=renderDebug" target="_blank">DEMO2</a> ] · [ <a href="_example.php?p=source&f=render" target="_blank">SOURCE</a> ] · [ <a href="_example.php?p=source&f=renderDebug" target="_blank">SOURCE2</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="color">Creating a color</a></h3>
All PIMG classes and modules must use the pimg_color class for handling color values. You can create a color by passing RGBA values in two ways:
<br /><br />
<ul>
<li>By passing the values to the color pimg function as shown (All values are 0 by default, all values are 0-255, except the alpha channel: 0-127):
<pre>$color = $pimg -> color([$red, [$green, [$blue, [$alpha]]]]);</pre></li>
<li>Another way is by creating a color and then updating the separate values:
<pre>$color = $pimg -> color();
$color -> red(255);
$color -> green(24);</pre>
<a name="usersconvenience"><b><i>USER'S CONVENIENCE CLAUSE</i></b></a><br />
<blockquote>
For user's convenience the color() method returns an instance of the pimg_color class, which means you can simply call red(), green() etc. methods as submethods of the color() method. The above example will be:
<pre>$color = $pimg -> color() -> red(255) -> green(24);</pre>
If you want to view (for debugging reasons) the color you can always echo one of the methods that return an instance of the color class:
<pre>$pimg -> color() -> red(255) -> green(24);</pre>
If you want to get the red or green etc. value you must call the red() or green() etc. method without a value:
<pre>echo $color -> red();</pre>
</blockquote>
</li>
</ul>
[ <a href="_example.php?f=color" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=color" target="_blank">SOURCE</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="colormix">Mixing colors</a></h3>
You can mix two or more colors by the mix() method of the pimg_color class:
<pre>echo $color -> mix(
array(
$color1,
50
),
array(
$color2,
50
));</pre>
mix() uses an array of arrays representing each color. Each color array then takes a pimg_color instance as the first parameter and a mix amount between 0 and 100 as second argument.
The amount represents a percentage of how much of that color must be mixed. In the above example we have mixed color1 and color2 with 50% of each one. If for example you set the first color amount to 0 and the second to 100, then you will get only the second color.<br />
The sum of all amounts must be exactly 100, or the class will trigger a debug error.<br /><br />
When you mix colors you must note that the result will overwrite any existing color values on the variable:
<pre>$mix = $pimg -> color(0, 0, 0);</pre>
will be overwritten by the result of mixing $color1 and $color2:
<pre>$mix -> mix($color1, $color2);</pre>
<a href="#usersconvenience"><b><i>USER'S CONVENIENCE CLAUSE APPLIES</i></b></a><br /><br />
[ <a href="_example.php?f=colormix" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=colormix" target="_blank">SOURCE</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="fill">Fill</a></h3>
You can fill the whole image with a specified color:
<pre>$pimg -> fill($color);</pre>
<ul>
<li>The color must be a valid pimg_color resource</li>
</ul><br />
<a name="callbackconvenience"><i><b>CALLBACK CONVENIENCE CLAUSE:</i></b></a><br />
<blockquote>
The callback convenience clause states that every method that works as an action method and has no return value, must return an instance of the caller pimg class, which allows the user to furthur refer to the method result as the pimg handle itself:
<pre>$pimg -> fill($color);
$pimg -> randomMethod();</pre>
will be:
<pre>$pimg -> fill($color) -> randomMethod();</pre>
</blockquote>
[ <a href="_example.php?f=fill" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=fill" target="_blank">SOURCE</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="pixels">Pixels</a></h3>
There has been added a pixel() method which represents a single pixel of the image.<br />
The pixel class contains 3 parameters: the x position in the image, the y position and a pimg_color instance for it's color info.<br />
You can create a pixel like this:
<pre>$color = $pimg -> color(0, 0, 0);
$pixel = $pimg -> pixel(0, 2, $color);</pre>
or you can retrieve a pixel's info like this:
<pre>$x = $pixel -> x();
$y = $pixel -> y();
$color = $pixel -> color();</pre>
X and Y will return an integer value and color() will return a pimg_color instance.<br /><br />
You can use the method draw() to draw any pixel to the parent image or you can pass a pimg_image handle to draw to:
<pre>$pixel -> draw($pimg);</pre>
<a href="#usersconvenience"><b><i>USER'S CONVENIENCE CLAUSE APPLIES</i></b></a><br /><br />
[ <a href="_example.php?f=pixel" target="_blank">DEMO</a> ] · [ <a href="_example.php?f=pixel2" target="_blank">DEMO2</a> ] · [ <a href="_example.php?p=source&f=pixel" target="_blank">SOURCE</a> ] · [ <a href="_example.php?p=source&f=pixel2" target="_blank">SOURCE2</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="stretch">Stretching an image</a></h3>
You can resize an image by stretching it to any width and height:
<pre>$pimg -> stretch($width, $height);</pre>
<a href="#callbackconvenience"><b><i>CALLBACK CONVENIENCE CLAUSE APPLIES</i></b></a><br /><br />
[ <a href="_example.php?f=stretch" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=stretch" target="_blank">SOURCE</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="fit">Fitting an image</a></h3>
You can resize an image keeping it's aspect ratio to fit in / out an user defined rectangle.<br /><br />
<ul>
<li>Fitting in an image means that neither the width nor the height of the resized image can be larger than the given width or height:
<pre>$pimg -> fitin(100, 50);</pre>
For example, if the original size is 200x150, then it will be scaled to 66x50. In another case if the original size is 200x20, then it will be scaled to 100x10.
</li>
<br />
<li>Fitting out an image means that both the width and height must be as small as possible and still larger or equal to the given width and height:
<pre>$pimg -> fitout(100, 50);</pre>
In this case 200x150 will be scaled to 100x75, and 200x20 to 500x50.
</ul><br />
<a href="#callbackconvenience"><b><i>CALLBACK CONVENIENCE CLAUSE APPLIES</i></b></a><br /><br />
[ <a href="_example.php?f=fitin" target="_blank">DEMO</a> ] · [ <a href="_example.php?f=fitout" target="_blank">DEMO2</a> ] · [ <a href="_example.php?p=source&f=fitin" target="_blank">SOURCE</a> ] · [ <a href="_example.php?p=source&f=fitout" target="_blank">SOURCE2</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="scan">Scanning pixels</a></h3>
You can scan a rectangle area from the image and retrieve it's pixels' information by setting the bounds of the rectangle as follows: x, y (start points), width, height:
<pre>$scan = $pimg -> scan(0, 0, 50, 50);</pre>
The result will be a double array with pimg_pixel instances with info about each pixel, later you can debug convert it to an image for viewing by simply passing it to a new pimg_image class:
<pre>$new = new pimg_image($scan);</pre>
[ <a href="_example.php?f=scan" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=scan" target="_blank">SOURCE</a> ]<br /><br />
</li>
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="merge">Merging images</a></h3>
You can easily merge two images offseting the secong at a desired X and Y by calling for example (offset and pct are not obligatory):
<pre>$pimg -> merge($pimg2, 20, 30, $pct);</pre>
The <b>$pimg2</b> variable must be a valid pimg_image resource.<br />
You can pass an additional argument <b>$pct</b> from 0 to 100 according to which the images will be merged.
If it is 0 (by default) no action is taken (no merging), if it's 100 the <b>imagecopyresampled</b> method is used as being faster
than the <b>imagecopymerge</b> - used in the other case.<br /><br />
You can merge more than two images by layering them on top of each other:
<pre>$pimg -> layer($pimg2, array($pimg2, 10, 10), array($pimg2, 20, 20, 50));</pre>
You can pass as many arguments as you wish as long as they are valid pimg_image resources or arrays containing a valid pimg_image resource and integer X & Y offsets as well as a PCT value (again, not obligatory).<br /><br />
<a href="#callbackconvenience"><b><i>CALLBACK CONVENIENCE CLAUSE APPLIES</i></b></a><br /><br />
[ <a href="_example.php?f=merge" target="_blank">DEMO</a> ] · [ <a href="_example.php?f=layer" target="_blank">DEMO2</a> ] · [ <a href="_example.php?p=source&f=merge" target="_blank">SOURCE</a> ] · [ <a href="_example.php?p=source&f=layer" target="_blank">SOURCE2</a> ]<br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="crop">Cropping images</a></h3>
You can crop an area of an image by specifying the x and y of the start point and the width and height of the selection:
<pre>$pimg -> crop(20, 20, 80, 80);</pre>
<a href="#callbackconvenience"><b><i>CALLBACK CONVENIENCE CLAUSE APPLIES</i></b></a><br /><br />
[ <a href="_example.php?f=crop" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=crop" target="_blank">SOURCE</a> ]
</li>
</ol>
<br />
<hr />
<br />
<h2>User modules</h2>
<ol>
<li>
<h3>[ <a href="#">top</a> ] <a name="uloading">Loading user modules</a></h3>
You can load any user written module by calling it as a normal basic module, except you must refer to pimg's method mod() rather than the pimg instance.<br />
For example, loading a basic mod is done like this:
<pre>$pimg -> basicMod($args);</pre>
Loading a user mod is done like this:
<pre>$pimg -> mod() -> userMod($args);</pre>
All other properties, functions, characteristics etc. of working with basic modules apply here too.
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="uwriting">Writing user modules</a></h3>
You can freely write any user module, but please be kind to use the same fashion in writing as the already written modules.<br />
Put many comments, see how other modules are written and try to keep it the same. Write inteligent, fast and simple scripts. Use the basic methods and the core functions as much as you can and avoid using third party scripts or libraries.
Name your classes inteligently and don't let their names interfiere with core modules.
Each module must be packed in one class and one file only, you can of course make your script to work with other user modules, but please put that information in the head comment section of your module together with your name or email (for copyright purposes).
Please note that writing a mod and releasing it with this library automatically makes it free to the public, therefore don't use any encrypters (ionCube, Zend etc.).
By publishing your script you must agree / or disagree (in the copyright comment) for other people to be able to fix, update and upgrade your mod.
All user modules will be released after examination from the PIMG creator (ton4y@abv.bg).<br />
So, now is the time to say that if you write a module and want to publish it together with newer versions, please contact me at ton4y@abv.bg and send me the module (and an appropriate documentation), I'll check it out and publish it in the next PIMG release.
All credits for creating the PIMG core and the basic modules goes to.. me - <b>ton4y@abv.bg</b> :)<br />
All credits for creating the custom user modules goes to the people who created them and who are listed in the module's head comment section.
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="u1">Watermark Remover · by · ton4y@abv.bg</a></h3>
<font color="green">/* This module is relatively slow couse of the need to re-process individual pixels */</font><br /><br />
This module allows you to remove a watermark or any other rectangular part of an image by stretching it's corners together.
You must specify the x and y start points and the width, and height of the selection to be removed.<br />
By default the rectangle will be removed and the left and right as well as the top and the bottom sides (1px thick, inline) will be stretched and fused together.<br /><br />
<b>Sample usage:</b>
<pre>$pimg -> mod() -> removewatermark($x, $y, $width, $height);</pre>
<a href="#callbackconvenience"><b><i>CALLBACK CONVENIENCE CLAUSE APPLIES</i></b></a><br /><br />
[ <a href="_example.php?f=mods/removewatermark" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=mods/removewatermark" target="_blank">SOURCE</a> ]
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="u2">Filters · by · ton4y@abv.bg</a></h3>
We've added a new experimental user module called 'filter', representing a pack of different filtering methods.
<ul>
<li>
<h4>Pixelize</h4>
Groups pixels into squares (cells) creating a pixelization effect<br /><br />
<b>Sample usage:</b>
<pre>$pimg -> mod() -> filter() -> pixelize([$size, [$method]]);</pre>
<i>Refer to <b>mods/filter.pimg.php</b> for complete documentation</i><br /><br />
<a href="#callbackconvenience"><b><i>CALLBACK CONVENIENCE CLAUSE APPLIES</i></b></a><br /><br />
[ <a href="_example.php?f=mods/filter.pixelize1" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=mods/filter.pixelize1" target="_blank">SOURCE</a> ] · [ <a href="_example.php?f=mods/filter.pixelize2" target="_blank">DEMO2</a> ] · [ <a href="_example.php?p=source&f=mods/filter.pixelize2" target="_blank">SOURCE2</a> ] · [ <a href="_example.php?f=mods/filter.pixelize3" target="_blank">DEMO3</a> ] · [ <a href="_example.php?p=source&f=mods/filter.pixelize3" target="_blank">SOURCE3</a> ]
</li>
</ul>
<br /><br />
<a href="#usersconvenience"><b><i>USER'S CONVENIENCE CLAUSE APPLIES</i></b></a><br /><br />
</li>
<li>
<h3>[ <a href="#">top</a> ] <a name="u3"><font style="color: orange;">[ EXPERIMENT ]</font> THE MATRIX · by · ton4y@abv.bg</a></h3>
Just an interesting experiment to create THE MATRIX kind of effect (I used it for a wallpaper for about 2 weeks :) the generation is quite heavy though).<br /><br />
[ <a href="_example.php?f=mods/THEMATRIX" target="_blank">DEMO</a> ] · [ <a href="_example.php?p=source&f=mods/THEMATRIX" target="_blank">SOURCE</a> ]
</li>
</ol>
</body>
</html> |
Stumble It!
Bookmark in del.icio.us
Download
