^Status|Final Draft|
^Todo|Proofread|

====== Image Library ======

Provides methods for the dynamic manipulation of images. Various image formats such as JPEG, PNG, and GIF can be resized, cropped, rotated and sharpened.

All image manipulations are applied to a **temporary** image. Only the ''save()'' method is permanent, the temporary image being written to a specified image file.

<box blue>
Image manipulation methods can be chained efficiently. Recommended order: ''resize'', ''crop'', ''sharpen'', ''quality'' and ''rotate'' or ''flip'' 
</box>

===== Loading the Image library =====

Uses a driver, configured in ''config/image.php''. The default driver uses the GD2 library, bundled with PHP. ImageMagick may be used if available.

When loading the library, a path to the image file, (relative or absolute) must be passed as a parameter.

Load the Image Library in your controller using the **new** keyword:
<code php>
$this->image = new Image('./photo.jpg');
</code>

Access to the library is available through ''$this->image'' Some methods are chainable.

===== Configuring the library =====

To change default settings, edit ''application/config/image.php''

Drivers available:

  * **GD** - The default driver, requires GD2 version >= 2.0.34 (Debian / Ubuntu users note: Some functions, eg. ''sharpen'' may not be available)
  * **ImageMagick** - Windows users **must** specify a path to the binary. Unix versions will attempt to auto-locate.
  * **GraphicsMagick** - Windows users **must** specify a path to the binary. Unix versions will attempt to auto-locate.

<code php>
$config['driver'] = 'GD';
// For Windows
$config['params'] = array('directory' => 'C:/ImageMagick');
// For Un*x assuming the binary is in usr/local/bin
$config['params'] = array('directory' => '/usr/local/bin');
</code>


===== Methods =====


==== resize() ====

''resize()'' is used to resize an image. This method is chainable. By default, the aspect ratio will be maintained automatically. 

  *[integer] Width in pixels of the resized image.
  *[integer] Height in pixels of the resized image.
  *[integer] Master dimension, default is Auto.  Options : Image::NONE, Image::AUTO, Image::HEIGHT, Image::WIDTH

**Example:**
<code php>
// Resize original image to width of 400 and height of 200 pixels without maintaining the aspect ratio.
$this->image->resize(400, 200, Image::NONE)
//Note: The output image is resized to width of 400 and height of 200, without maintaining the aspect ratio

// Resize original image to Height of 200 pixels, using height to maintain aspect ratio.
$this->image->resize(400, 200, Image::HEIGHT)
// Note: Passing width = 400 has no effect on the resized width, which is controlled by the 3rd argument, maintain aspect ratio on height

// Resize original image (800x600) using automatic aspect ratio calculation 
$this->image->resize(740,400,Image::AUTO)
// the resulting resized image is 533x400 because Kohana determines the master dimension to be height 800/740 < 600/400


</code>


==== crop() ====

''crop()'' is used to crop an image to a specific width and height. This method is chainable. 

The **top** and **left** offsets may be specified. By default 'top' and 'left' use the 'center' offset. 

  *[integer] Width in pixels of the cropped image.
  *[integer] Height in pixels of the cropped image.
  *[integer] Top offset of input image, pixel value or one of 'top', 'center', 'bottom'.
  *[integer] Left offset of input image, pixel value or one of 'left', 'center', 'right'.

**Example:**
<code php>
// Crop from the original image, starting from the 'center' of the image from the 'top' and the 'center' of the image from the 'left' 
// to a width of 400 and height of 350. 
$this->image->crop(400, 350) 
</code>


==== rotate() ====

''rotate()'' is used to rotate an image by a specified number of degrees. This method is chainable. The image may be rotated clockwise or anti-clockwise, by a maximum of 180 degrees.

  *[integer] Degrees to rotate. (negative rotates anti-clockwise) There is no default.

**Example:**
<code php>
// Rotate the image by 45 degrees to the 'left' or anti-clockwise.
$this->image->rotate(-45) 
</code>


==== flip() ====

''flip()'' is used to rotate an image along the horizontal or vertical axis. The method is chainable.

  *[integer] Direction. Horizontal = 5, Vertical = 6


**Example:**
<code php>
// Rotate the image along the vertical access. 
$this->image->flip(6);
</code>


==== sharpen() ====

''sharpen()'' Is used to sharpen an image by a specified amount. This method is chainable. 

  *[integer] Sharpen amount to apply to image. Range is between 1 and 100. Optimal amount is about 20. There is no default.

**Example:**
<code php>
// Sharpen the image by an amount of 15. 
$this->image->sharpen(15);
</code>


==== quality() ====

''quality()'' Is used to adjust the image quality by a specified percentage.  This method is chainable. 

Note: The method is for reducing the quality of an image, in order to reduce the file size of the image, saving bandwidth and load time. It cannot be used to actually improve the quality of an input image. 

  *[integer] Percentage amount to adjust quality. Range is between 1 and 100. Optimal percentage is from 75 to 85. There is no default.

**Example:**
<code php>
// Reduce image quality to 75 percent of original
$this->image->quality(75);
</code>


==== save() ====

''save($new_image = FALSE, $chmod = 0644, $keep_actions = FALSE)'' Is used to save the image to a file on disk.  This method is NOT chainable. The default is to overwrite the input image file. Accepts a relative or absolute file path. 


  ***[string]** //$new_image// The file path and output image file name. Default is to overwrite input file. 
  ***[integer]** //$chmod// permissions for new image (default 0644)
  ***[bool]** //$keep_actions// keep or discard image process actions (default FALSE).

**Example:**
<code php>
// Save image and overwrite the input image file
$this->image->save();
//
$this->image->save('./new-image.jpg'); // Save image to a new file.
</code>

==== render() ====

''render($keep_actions = FALSE) '' is used to output the image to the browser. This method is NOT chainable. It means that the headers corresponding to the image format are sent and the raw image stream with manipulation applied will be outputted directly to the browser. Returns TRUE on success or FALSE on failure. 

  ***[bool]** //$keep_actions// keep or discard image process actions (default FALSE)

**Example:**
<code php>
$image = new Image($dir.'moo.jpg'); // Instantiate the library
$image->resize(400, NULL)->crop(400, 350, 'top')->sharpen(20)->quality(75); // apply image manipulations

// Output the image directly to the browser
$this->image->render();
</code>

==== __get() ====

''%%__get()%%'' is used to handle retrieval of pre-save image properties. Properties available are:

  * 'file'
  * 'width'
  * 'height'
  * 'type'
  * 'ext'
  * 'mime'

===== Full Example =====

Place this code into a controller:

<code php>
// The original image is located in folder /application/upload.
$dir = str_replace('\\', '/', realpath(dirname(__FILE__).'/../upload')).'/';

$image = new Image($dir.'moo.jpg'); // Instantiate the library

$image->resize(400, NULL)->crop(400, 350, 'top')->sharpen(20)->quality(75); // apply image manipulations

$image->save($dir.'super-cow-crop.jpg'); // Write the changed image to a new file in the original input folder. Manipulations are discarded after the save call ($keep_action default TRUE).

echo Kohana::debug($image); // Display some useful info about the operation **for debugging only**.

$image->resize(300, NULL); // Resize the original image

$image->save($dir.'super-cow-resize.jpg', TRUE); // Write the changed image to a new file in the original input folder

$image->crop(300, 250, 'top'); // Resize and crop the original image ($keep_action set to TRUE means that resize manipulation has been kept after the save method call).

</code>