Location: PHPKode > scripts > Plogger > plog-includes/lib/phpthumb/phpthumb.readme.txt
//////////////////////////////////////////////////////////////
///  phpThumb() by James Heinrich <hide@address.com>   //
//        available at http://phpthumb.sourceforge.net      ///
//////////////////////////////////////////////////////////////
///                                                         //
//       This code is released under the GNU GPL:           //
//         http://www.gnu.org/copyleft/gpl.html             //
//                                                          //
//    +-----------------------------------------------+     //
//    | phpThumb() is free to use according to the    |     //
//    | terms of the GPL. Donations also gratefully   |     //
//    | accepted from happy users :)                  |     //
//    | Please see http://phpthumb.sourceforge.net    |     //
//    |                                               |     //
//    | If you like phpThumb(), please consider       |     //
//    | writing a review at HotScripts.com:           |     //
//    | http://www.hotscripts.com/Detailed/25654.html |     //
//    |                                               |     //
//    | If you do use this code somewhere, send me    |     //
//    | an email and tell me how/where you used it.   |     //
//    +-----------------------------------------------+     //
//                                                         ///
//////////////////////////////////////////////////////////////

Description:

phpThumb() uses the GD library to create thumbnails from
images (GIF, PNG or JPEG) on the fly. The output size is
configurable (can be larger or smaller than the source),
and the source may be the entire image or only a portion
of the original image. True color and resampling is used
if GD v2.0+ is available, otherwise low-color and simple
resizing is used. Source image can be a physical file on
the server or can be retrieved from a database. GIFs are
supported on all versions of GD even if GD does not have
native GIF support thanks to the GIFutil class by Fabien
Ezber. AntiHotlinking feature prevents other people from
using your server to resize their thumbnails.  The cache
feature reduces server load.


Usage:

Call phpThumb() just like you would a normal image.
Examples:
 <IMG SRC="phpThumb.php?src=/image.jpg&w=100">
 <IMG SRC="phpThumb.php?src=http://example.com/foo.jpg">
See the "demo" link on http://phpthumb.sourceforge.net
for more usage examples). Parameters that can be passed
are listed below under "URL Parameters".

NOTE: It's recommended you use the local image filename
wherever possible (rather than http://) because performance
is much better, less (or no) use of temp files, and the
last-modified check for cached files doesn't work for
remote files.

To access files over a LAN with Windows share names you
must use the network name (or IP) and not a mapped drive
name, for example:
  //othercomputer/file.jpg - good
  //192.168.2.1/file.jpg - good
  z:/file.jpg - won't work
This is a PHP limitation (see www.php.net/file-exists)
Note: you may want to use "/" slashes instead of "\" if
you have magic_quotes_gpc enabled to avoid stripslashes
problems, although either slash should work if
magic_quotes_gpc is disabled


Configuration:

There are some configuration options you may (but are
not required to) change. Most configuration options can
be set when you call phpThumb() - see list below), but
default configuration options (such as cache directory)
are in phpThumb.config.php - this is the only file you
should ever modify.

The amount of memory required for phpThumb depends on
several factors: the dimensions of the source image,
the dimensions of the output image, whether unsharp
masking is applied, whether watermarks are applied, etc.
The auto-detection of memory limits works as a general
"safe" value. You may be able to exceed the auto value
by a small or large amount, depending on whether you
apply watermarks and/or sharpening, and the output size
of your thumbnails. I do not currently have a reliable
formula for calculating such things, but I will attempt
to craft one for future versions of phpThumb(). Until
then, set "max_source_pixels" in phpThumb.config.php to a
value that works well for you (or leave it alone if the
defaults give you no problems).

The configuration options you should maybe modify are:
* cache_directory - thumbnailing is slow and processor-
    intensive. Enabling caching will dramatically speed
    up future thumbnail serving
* max_source_pixels - This should be auto-detected, but
    if auto-detection fails and you get an invalid image
    from large source images, set this to about 20% of
    your available PHP memory limit.
* imagemagick_path - If the source image is larger than
    max_source_pixels allows, but ImageMagick is available
    phpThumb() will use it to generate the thumbnail.


Calling as an object (not using phpThumb.php):

To use a database rather than physical files, or to
render output to a file instead of the browser, you
should skip phpThumb.php and instantiate your own
phpThumb() object as follows:

  // create new phpThumb() object
  require_once('phpthumb.class.php');
  $phpThumb = new phpThumb();

  // set data
  $phpThumb->rawImageData = $binary_image_data;
  // or $phpThumb->src = $sourceFilename;

  // set parameters (see "URL Parameters" below)
  $phpThumb->w = 100;

  // set options (see phpThumb.config.php)
  // here you must preface each option with "config_"
  $phpThumb->config_output_format = 'jpeg';

  // Set error handling (optional)
  $phpThumb->config_error_die_on_error = false;

  // generate & output thumbnail
  if ($phpThumb->GenerateThumbnail()) {
    $phpThumb->RenderToFile($filename);
    // or $phpThumb->OutputThumbnail();
  } else {
    // do something with debug/error messages
    echo 'Failed: '.implode("\n", $phpThumb->debugmessages);
  }


If you want to change any of the configuration parameters
(see phpThumb.config.php) you can change them like this:
    $phpThumb->config_<variable_name> = <value>
for example:
    $phpThumb->config_output_format = 'jpeg';

Note: If you want to loop through and create multiple
  thumbnails from different image sources, you should
  create and dispose an instance of phpThumb() each time
  through the loop and not reuse the object.




URL Parameters:
   w = max width of output thumbnail in pixels
   h = max height of output thumbnail in pixels
   f = output image format ('jpeg', 'png', or 'gif')
   q = JPEG compression (1=worst, 95=best, 75=default)
  sx = left side of source rectangle (default = 0)
       (values 0 < sx < 1 represent percentage)
  sy = top side of source rectangle (default = 0)
       (values 0 < sy < 1 represent percentage)
  sw = width of source rectangle (default = fullwidth)
       (values 0 < sw < 1 represent percentage)
  sh = height of source rectangle (default = fullheight)
       (values 0 < sh < 1 represent percentage)
  bw = border width in pixels (set to enable fixed-size
       thumbnails with background filled with 'bg' color
  bg = background hex color (default = FFFFFF)
 bgt = background color is transparent (default = 0)
       use with brx/bry, set to 1 for transparency,
       set to 256 for IE-compatible 256-color mode
  bc = border hex color (default = 000000)
 usr = unsharp mask radius (default = 0.5, range 0.5-1)
 usa = unsharp mask amount (default = 80, range 50-200)
 ust = unsharp mask threshold (default = 3, range 0-10)
 wmf = filename of watermark image (default = none)
 wmp = % opacity of watermark image (default = 50)
 wmm = % margin to watermark image (default = 5)
 wma = watermark alignment (default = BR = bottom-right)
       one of: BR, BL, TR, TL, C, R, L, T, B, *
       B=bottom,T=top,L=left,R=right,C=centre,*=tile
file = if set then thumbnail will be rendered to this
       filename, not output and not cached. (Deprecated,
       recommended you instantiate your own object instead)
goto = URL to redirect to after rendering image to file
       * Must begin with 'http://'
       * Requires file parameter set
       (Deprecated, recommended you instantiate your own
       object instead)
 err = custom error image filename instead of showing
       error messages (for use on production sites)
 xto = EXIF Thumbnail Only - set to only extract EXIF
       thumbnail and not do any additional processing
  ra = Rotate Angle: angle of rotation in degrees
       positive = counterclockwise, negative = clockwise
  ar = Auto Rotate: can be 'l' or 'L' for landscape, or
       'p' or 'P' for portrait. 'l' and 'P' rotate the
       image clockwise, 'L' and 'p' rotate the image
       counter-clockwise. If your images get rotated
       upside-down, email me a suggestion for how to do
       it better :)
 aoe = Output Allow Enlarging - override the setting for
       $CONFIG['output_allow_enlarging'] (1=on, 0=off)
 iar = Ignore Aspect Ratio - disable proportional resizing
       and stretch image to fit 'h' & 'w' (which must both
       be specified).  (1=on, 0=off)
 brx,
 bry = border radius in pixels (radius of curved corners)
       You must specify  both 'brx' (horizontal radius)
       and 'bry' (vertical radius) as well as 'bw'
       (border width). If 'bw' is greater than zero, the
       image will be shrunk to fit inside the border with
       a margin of background color. If 'bw' is zero, the
       corners of the image will be cut off and filled
       with background color.
maxb = MAXimum Byte size - auto-set compression (JPEG) or
       bit depth (GIF & PNG) to fit thumbnail into 'maxb'
       bytes of output image.
down = filename to save image to. If this is set the
       browser will prompt to save to this filename rather
       than display the image


Additional Object-only configuration variables:
  rawImageData = binary data of source image, for example
                 if the source data is from a database. Set
                 this value instead of setting 'src'.



General Notes:

* Always use the local image filename wherever possible
  rather than a full http:// URL because performance is
  much better, less (or no) use of temp files, and the
  last-modified check for cached files doesn't work for
  remote files.

* Thumbnails will be scaled proportionately to fit in a
  box of at most (width * height) pixels
  (unless 'iar' is set)

* Thumbnail caching for URL or database sources requires
  an absolute directory name for $config_cache_directory
  Physical file cached thumbnails will be recreated if
  the source file changes, but remote/database files
  cannot (modification time isn't readily available)

* If you need a GUI interface for a user to specify crop
  settings you can investigate 12cropimage:
  http://one-two.net/12cropimage

* Cropping images can be specified with either exact pixel
  values for sx/sy/sw/sh parameters, or if those are set
  to a value >0 and <1 then these are interpreted as a
  percentage of the source image width/height. For example,
  to crop 25% off all sides, you would specify parameters:
  phpThumb.php?src=pic.jpg&sx=.25&sy=.25&sw=.5&sh=.5

* phpThumb() may have tempfile access issues on servers
  where Safe Mode is enabled, specificly when accessing
  a file over HTTP, or when a non-bundled version of GD
  is in use. Specifying 'config_temp_directory' may help

* Transparent PNG output is buggy with true-color images
  and some software (Internet Explorer, Photoshop). Output
  can be forced to 256-color mode for compatability by
  setting the 'bgt' parameter to '256'

* Properly resolving /~user/ style filenames requires
  apache_lookup_uri(), which is missing or broken in
  Apache2, or if PHP is not installed as an Apache module.
  phpThumb() does try and work around this if it is
  unavailble, but you may have to specify a full filename
  for "src" if you encounter problems.

* phpThumb() should work with PHP v4.0.6+, but seems to
   have a few quirks before v4.1.0
  EXIF thumbnail extraction requires PHP v4.2.0+
  Image rotation requires PHP v4.3.0+. There have been
    reports of problems with PHP older than v4.3.3

* phpThumb() works fine with GD v1.x, but works better
   with GD v2.0+ because of the true-color image support
   and ImageCopyResampled(). Also, there appears to be a
   bug in ImageCopyResized() which is used with GD v1.x
   where the bottom and/or right line of pixels is set
   to the background color (due to a rounding error?)
  NOTE: Please use the bundled version of GD if at all
   possible (with PHP v4.3.0+) because the non-bundled
   version has bugs which may cause PHP to crash:
   * http://bugs.php.net/bug.php?id=21518
   * http://bugs.php.net/bug.php?id=24174
   phpThumb() has a workaround for the above bug but
   there may be other bugs, and the workaround is slow.
  Watermarks work MUCH better with GD v2 than GD v1!
  Unsharp masking requires GD v2.x
  Rounded Image Corners requires GD v2.x
Return current item: Plogger