From 5956f6b118c085f823ee159939af3bb022e43ad8 Mon Sep 17 00:00:00 2001 From: "Sebastian G. Marinescu" Date: Mon, 19 Aug 2024 17:43:06 +0200 Subject: [PATCH 1/3] Create PARAMS.md --- PARAMS.md | 303 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 PARAMS.md diff --git a/PARAMS.md b/PARAMS.md new file mode 100644 index 0000000..73bcff2 --- /dev/null +++ b/PARAMS.md @@ -0,0 +1,303 @@ +# Parameters + + +| Parameter | Description | +|-----------|:------------| +| src | filename of source image | +| new | create new image, not thumbnail of existing image.
Requires "w" and "h" parameters set.
[ex: &new=FF0000\|75] - red background, 75% opacity
Set to hex color string of background. Opacity is
optional (defaults to 100% opaque). | +| w | max width of output thumbnail in pixels | +| h | max height of output thumbnail in pixels | +| wp | max width for portrait images | +| hp | max height for portrait images | +| wl | max width for landscape images | +| hl | max height for landscape images | +| ws | max width for square images | +| hs | max height for square images | +| 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) | +| zc | zoom-crop. Will auto-crop off the larger dimension
so that the image will fill the smaller dimension
(requires both "w" and "h", overrides "iar", "far")
Set to "1" or "C" to zoom-crop towards the center,
or set to "T", "B", "L", "R", "TL", "TR", "BL", "BR"
to gravitate towards top/left/bottom/right directions
(requies ImageMagick for values other than "C" or "1") | +| ica | ImageCropAuto, requires (PHP 5 >= 5.5.0, PHP 7)
https://www.php.net/manual/en/function.imagecropauto.php
value can be 0-4 (IMG_CROP_DEFAULT, IMG_CROP_TRANSPARENT,
IMG_CROP_BLACK, IMG_CROP_WHITE, IMG_CROP_SIDES) or can be
"5|\|" where is between 0
and 1, and is the hex background color | +| bg | background hex color (default=FFFFFF) | +| bc | border hex color (default=000000) | +| fltr | filter system. Call as an array as follows: [Filters](#filters) | +| md5s | MD5 hash of the source image -- if this parameter is
passed with the hash of the source image then the
source image is not checked for existence or
modification and the cached file is used (if
available). If 'md5s' is passed an empty string then
phpThumb.php dies and outputs the correct MD5 hash
value. This parameter is the single-file equivalent
of 'cache_source_filemtime_ignore_*' configuration
parameters | +| xto | EXIF Thumbnail Only - set to only extract EXIF
thumbnail and not do any additional processing | +| ra | Rotate by Angle: angle of rotation in degrees
positive=counterclockwise, negative=clockwise | +| ar | Auto Rotate: set to "x" to use EXIF orientation
stored by camera. Can also be set to "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. | +| sfn | Source Frame Number - use this frame/page number for
multi-frame/multi-page source images (GIF, TIFF, etc) | +| aoe | Output Allow Enlarging - override the setting for
$CONFIG['output_allow_enlarging'] (1=on, 0=off)
("far" and "iar" both override this and allow output
larger than input) | +| iar | Ignore Aspect Ratio - disable proportional resizing
and stretch image to fit "h" & "w" (which must both
be set). (1=on, 0=off) (overrides "far") | +| far | Force Aspect Ratio - image will be created at size
specified by "w" and "h" (which must both be set).
Alignment: L=left,R=right,T=top,B=bottom,C=center
BL,BR,TL,TR use the appropriate direction if the
image is landscape or portrait. | +| dpi | Dots Per Inch - input DPI setting when importing from
vector image format such as PDF, WMF, etc | +| sia | Save Image As - default filename to save generated
image as. Specify the base filename, the extension
(eg: ".png") will be automatically added | +| maxb | MAXimum Byte size - output quality is auto-set to
fit thumbnail into "maxb" bytes (compression
quality is adjusted for JPEG, bit depth is adjusted
for PNG and GIF) | +| down | filename to save image to. If this is set the
browser will prompt to save to this filename rather
than display the image | + + + +## Filters + +
    + 
  • "brit" (Brightness) [ex: &fltr[]=brit|<value>]
+         where <value> is the amount +/- to adjust brightness
+         (range -255 to 255)
+         Available in PHP5 with bundled GD only.
    • + 
  • "cont" (Constrast) [ex: &fltr[]=cont|<value>]
+         where <value> is the amount +/- to adjust contrast
+         (range -255 to 255)
+         Available in PHP5 with bundled GD only.
    • + 
  • "gam" (Gamma Correction) [ex: &fltr[]=gam|<value>]
+         where <value> can be a number 0.01 to 10 (default 1.0)
+         Must be >0 (zero gives no effect). There is no max,
+         although beyond 10 is pretty useless. Negative
+         numbers actually do something, maybe not quite the
+         desired effect, but interesting nonetheless.
    • + 
  • "sat" (SATuration) [ex: &fltr[]=sat|<value>]
+         where <value> is a number between zero (no change)
+         and -100 (complete desaturation=grayscale), or it
+         can be any positive number for increased saturation.
    • + 
  • "ds" (DeSaturate) [ex: &fltr[]=ds|<value>]
+         is an alias for "sat" except values are inverted
+         (positive values remove color, negative values boost
+         saturation)
    • + 
  • "gray" (Grayscale) [ex: &fltr[]=gray]
+         remove all color from image, make it grayscale
    • + 
  • "th" (Threshold) [ex: &fltr[]=th|<value>]
+         makes image greyscale, then sets all pixels brighter
+         than <value> (range 0-255) to white, and all pixels
+         darker than <value> to black
    • + 
  • "rcd" (Reduce Color Depth) [ex: &fltr[]=rcd|<c>|<d>]
+         where <c> is the number of colors (2-256) you want
+         in the output image, and <d> is "1" for dithering
+         (deault) or "0" for no dithering
    • + 
  • "clr" (Colorize) [ex: &fltr[]=clr|<value>|]
+         where <value> is a number between 0 and 100 for the
+         amount of colorization, and  is the hex color
+         to colorize to.
    • + 
  • "sep" (Sepia) [ex: &fltr[]=sep|<value>|]
+         where <value> is a number between 0 and 100 for the
+         amount of colorization (default=50), and  is
+         the hex color to colorize to (default=A28065).
+         Note: this behaves differently when applied by
+         ImageMagick, in which case 80 is default, and lower
+         values give brighter/yellower images and higher
+         values give darker/bluer images
    • + 
  • "usm" (UnSharpMask) [ex: &fltr[]=usm|<a>|<r>|<t>]
+         where <a> is the amount (default=80, range 0-255),
+         <r> is the radius (default=0.5, range 0.0-10.0),
+         <t> is the threshold (default=3, range 0-50).
    • + 
  • "blur" (Blur) [ex: &fltr[]=blur|]
+         where (0 <  < 25) (default=1)
    • + 
  • "gblr" (Gaussian Blur) [ex: &fltr[]=gblr]
+         Available in PHP5 with bundled GD only.
    • + 
  • "sblr" (Selective Blur) [ex: &fltr[]=gblr]
+         Available in PHP5 with bundled GD only.
    • + 
  • "smth" (Smooth) [ex: &fltr[]=smth|<value>]
+         where <value> is the weighting value for the matrix
+         (range -10 to 10, default 6)
+         Available in PHP5 with bundled GD only.
    • + 
  • "lvl" (Levels)
+         [ex: &fltr[]=lvl|||
+         where  can be one of 'r', 'g', 'b', 'a' (for
+         Red, Green, Blue, Alpha respectively), or '*' for all
+         RGB channels (default) based on grayscale average.
+         ImageMagick methods can support multiple channels
+         (eg "lvl|rg|3") but internal methods cannot (they will
+         use first character of channel string as channel)
+          can be one of:
+         0=Internal RGB;
+         1=Internal Grayscale;
+         2=ImageMagick Contrast-Stretch (default)
+         3=ImageMagick Normalize (may appear over-saturated)
+          is how much of brightest/darkest pixels
+         will be clipped in percent (default=0.1%)
+         Using default parameters (&fltr[]=lvl) is similar to
+         Auto Contrast in Adobe Photoshop.
    • + 
  • "wb" (White Balance) [ex: &fltr[]=wb|<c>]
+         where <c> is the target hex color to white balance
+         on, this color is what "should be" white, or light
+         gray. The filter attempts to maintain brightness so
+         any gray color can theoretically be used. If <c> is
+         omitted the filter guesses based on brightest pixels
+         in each of RGB
+         OR <c> can be the percent of white clipping used
+         to calculate auto-white-balance (default=0.1%)
+         NOTE: "wb" in default settings already gives an effect
+         similar to "lvl", there is usually no need to use "lvl"
+         if "wb" is already used.
    • + 
  • "hist" (Histogram)
+         [ex: &fltr[]=hist|<b>|<c>|<w>|<h>|<a>|<o>|<x>|<y>]
+         Where <b> is the color band(s) to display, from back
+         to front (one or more of "rgba*" for Red Green Blue
+         Alpha and Grayscale respectively);
+         <c> is a semicolon-separated list of hex colors to
+         use for each graph band (defaults to FF0000, 00FF00,
+         0000FF, 999999, FFFFFF respectively);
+         <w> and <h> are the width and height of the overlaid
+         histogram in pixels, or if <= 1 then percentage of
+         source image width/height;
+         <a> is the alignment (same as for "wmi" and "wmt");
+         <o> is opacity from 0 (transparent) to 100 (opaque)
+             (requires PHP v4.3.2, otherwise 100% opaque);
+         <x> and <y> are the edge margin in pixels (or percent
+             if 0 < (x|y) < 1) 
+
    • + 
  • "over" (OVERlay/underlay image) overlays an image on
+         the thumbnail, or overlays the thumbnail on another
+         image (to create a picture frame for example)
+         [ex: &fltr[]=over|<i>|<u>|<m>|<o>]
+         where <i> is the image filename; <u> is "0" (default)
+         for overlay the image on top of the thumbnail or "1"
+         for overlay the thumbnail on top of the image; <m> is
+         the margin - can be absolute pixels, or if < 1 is a
+         percentage of the thumbnail size [must be < 0.5]
+         (default is 0 for overlay and 10% for underlay);
+         <o> is opacity (0=transparent, 100=opaque)
+             (requires PHP v4.3.2, otherwise 100% opaque);
+         (thanks raynerapeØgmail*com, shabazz3Ømsu*edu)
    • + 
  • "wmi" (WaterMarkImage)
+         [ex: &fltr[]=wmi|<f>|<a>|<o>|<x>|<y>|<r>] where
+         <f> is the filename of the image to overlay;
+         <a> is the alignment (one of BR, BL, TR, TL, C,
+             R, L, T, B, *) where B=bottom, T=top, L=left,
+             R=right, C=centre, *=tile)
+             *or*
+             an absolute position in pixels (from top-left
+             corner of canvas to top-left corner of overlay)
+             in format {xoffset}x{yoffset} (eg: "10x20")
+             note: this is center position of image if <x>
+             and <y> are set
+         <o> is opacity from 0 (transparent) to 100 (opaque)
+             (requires PHP v4.3.2, otherwise 100% opaque);
+         <x> and <y> are the edge (and inter-tile) margin in
+             pixels (or percent if 0 < (x|y) < 1)
+             *or*
+             if <a> is absolute-position format then <x> and
+             <y> represent maximum width and height that the
+             watermark image will be scaled to fit inside
+         <r> is rotation angle of overlaid watermark
    • + 
  • "wmt" (WaterMarkText)
+         [ex: &fltr[]=wmt|<t>|<s>|<a>|<c>|<f>|<o>|<m>|<n>|<b>|<O>|<x>|<h>]
+         where:
+         <t> is the text to use as a watermark;
+             URLencoded Unicode HTMLentities must be used for
+               characters beyond chr(127). For example, the
+               "eighth note" character (U+266A) is represented
+               as "♪" and then urlencoded to "%26%239834%3B"
+             Any instance of metacharacters will be replaced
+             with their calculated value. Currently supported:
+              - ^Fb: source image filesize in bytes
+              - ^Fk: source image filesize in kilobytes
+              - ^Fm: source image filesize in megabytes
+              - ^X : source image width in pixels
+              - ^Y : source image height in pixels
+              - ^x : thumbnail width in pixels
+              - ^y : thumbnail height in pixels
+              - ^^ : the character ^
+         <s> is the font size (1-5 for built-in font, or point
+             size for TrueType fonts);
+         <a> is the alignment (one of BR, BL, TR, TL, C, R, L,
+             T, B, * where B=bottom, T=top, L=left, R=right,
+             C=centre, *=tile);
+             note: * does not work for built-in font "wmt"
+             *or*
+             an absolute position in pixels (from top-left
+             corner of canvas to top-left corner of overlay)
+             in format {xoffset}x{yoffset} (eg: "10x20")
+         <c> is the hex color of the text;
+         <f> is the filename of the TTF file (optional, if
+             omitted a built-in font will be used);
+         <o> is opacity from 0 (transparent) to 100 (opaque)
+             (requires PHP v4.3.2, otherwise 100% opaque);
+         <m> is the edge (and inter-tile) margin in percent;
+         <n> is the angle
+         <b> is the hex color of the background;
+         <O> is background opacity from 0 (transparent) to
+             100 (opaque)
+             (requires PHP v4.3.2, otherwise 100% opaque);
+         <x> is the direction(s) in which the background is
+             extended (either 'x' or 'y' (or both, but both
+             will obscure entire image))
+             Note: works with TTF fonts only, not built-in
+         <h> is the scale multiplier for line height/spacing
+             default is 1.0 
+
    • + 
  • "flip" [ex: &fltr[]=flip|x   or   &fltr[]=flip|y]
+         flip image on X or Y axis
    • + 
  • "ric" [ex: &fltr[]=ric|<x>|<y>]
+         rounds off the corners of the image (to transparent
+         for PNG output), where <x> is the horizontal radius
+         of the curve and <y> is the vertical radius
    • + 
  • "elip" [ex: &fltr[]=elip]
+         similar to rounded corners but more extreme
    • + 
  • "mask" [ex: &fltr[]=mask|filename.png|<i>]
+         greyscale values of mask are applied as the alpha
+         channel to the main image. White is opaque, black
+         is transparent, unless the <i> (invert) parameter is
+         set to 1 in which case black is opaque and white is
+         transparent
    • + 
  • "bvl" (BeVeL) [ex: &fltr[]=bvl|<w>||]
+         where <w> is the bevel width,  is the hex color
+         for the top and left shading,  is the hex color
+         for the bottom and right shading
    • + 
  • "bord" (BORDer) [ex: &fltr[]=bord|<w>|||<c>
+         where <w> is the width in pixels,  and  are
+         horizontal and vertical radii for rounded corners,
+         and <c> is the hex color of the border
    • + 
  • "fram" (FRAMe) draws a frame, similar to "bord" but
+         more configurable
+         [ex: &fltr[]=fram|||||]
+         where  is the width of the main border,  is
+         the width of each side of the bevel part,  is the
+         hex color of the main border,  is the highlight
+         bevel color,  is the shadow bevel color
    • + 
  • "drop" (DROP shadow)
+         [ex: &fltr[]=drop|<d>|<w>||<a>|<o>]
+         where <d> is distance from image to shadow, <w> is
+         width of shadow fade (not yet implemented),  is
+         the hex color of the shadow, <a> is the angle of the
+         shadow (default=225), <o> is opacity (0=transparent,
+         100=opaque, default=100) (not yet implemented)
    • + 
  • "crop" (CROP image)
+         [ex: &fltr[]=crop|<l>|<r>|<t>|<b>]
+         where <l> is the number of pixels to crop from the left
+         side of the resized image; <r>, <t>, <b> are for right,
+         top and bottom respectively. Where (0 < x < 1) the
+         value will be used as a percentage of width/height.
+         Left and top crops take precedence over right and
+         bottom values. Cropping will be limited such that at
+         least 1 pixel of width and height always remains.
    • + 
  • "rot" (ROTate)
+         [ex: &fltr[]=rot|<a>|<b>]
+         where <a> is the rotation angle in degrees; <b> is the
+         background hex color. Similar to regular "ra" parameter
+         but is applied in filter order after regular processing
+         so you can rotate output of other filters.
    • + 
  • "size" (reSIZE)
+         [ex: &fltr[]=size|<x>|<y>|<s>]
+         where <x> is the horizontal dimension in pixels, <y> is
+         the vertical dimension in pixels, <s> is boolean whether
+         to stretch (if 1) or resize proportionately (0, default)
+         <x> and <y> will be interpreted as percentage of current
+         output image size if values are (0 < X < 1)
+         NOTE: do NOT use this filter unless absolutely necessary.
+         It is only provided for cases where other filters need to
+         have absolute positioning based on source image and the
+         resultant image should be resized after other filters are
+         applied. This filter is less efficient than the standard
+         resizing procedures.
    • + 
  • "stc" (Source Transparent Color)
+         [ex: &fltr[]=stc|<c>|<n>|<x>]
+         where <c> is the hex color of the target color to be made
+         transparent; <n> is the minimum threshold in percent (all
+         pixels within <n>% of the target color will be 100%
+         transparent, default <n>=5); <x> is the maximum threshold
+         in percent (all pixels more than <x>% from the target
+         color will be 100% opaque, default <x>=10); pixels between
+         the two thresholds will be partially transparent.
    • +
+ From 81a73195dd445b90dcad1cb23dd87c77fe269561 Mon Sep 17 00:00:00 2001 From: "Sebastian G. Marinescu" Date: Mon, 19 Aug 2024 17:44:58 +0200 Subject: [PATCH 2/3] Update README.md --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5df5cfc..7748b5f 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,8 @@ Documentation pThumb includes two snippets: phpthumbof and pthumb. They're exactly the same; use whichever snippet name you like best. phpthumbof is handy for an existing site that was already using phpthumbof; pthumb better for future compatibility and shorter too :-) -Official documentation for [phpThumbOf](http://rtfm.modx.com/display/addon/phpthumbof/) and [phpThumb](http://phpthumb.sourceforge.net/demo/docs/phpthumb.readme.txt). +Official documentation for [phpThumbOf](http://rtfm.modx.com/display/addon/phpthumbof/) and [phpThumb](https://web.archive.org/web/20220323050907/https://phpthumb.sourceforge.net/demo/docs/phpthumb.readme.txt) (Archived version). +Only interested in parameters? Check out the [PARAMS.md](PARAMS.md). pThumb adds the following system settings: @@ -130,4 +131,4 @@ In addition to that it: * Improves performance, especially on sites and pages which use phpThumbOf extensively. In some cases the difference can be very significant. * Adds better debugging output, like the page's resource ID to make finding broken images easy, or simple access to phpThumb's debug messages. -* Improves phpThumbOfCacheManager behavior so that the cache isn't wiped out by default. The cache manager provides three different levels of cleaning and does better reporting on the number of files and the size of a cache. \ No newline at end of file +* Improves phpThumbOfCacheManager behavior so that the cache isn't wiped out by default. The cache manager provides three different levels of cleaning and does better reporting on the number of files and the size of a cache. From 40fe1e98c4b93f39e197a9774042d6c6cbd92abb Mon Sep 17 00:00:00 2001 From: "Sebastian G. Marinescu" Date: Mon, 19 Aug 2024 17:47:47 +0200 Subject: [PATCH 3/3] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7748b5f..4d0d7a2 100644 --- a/README.md +++ b/README.md @@ -27,10 +27,10 @@ Documentation pThumb includes two snippets: phpthumbof and pthumb. They're exactly the same; use whichever snippet name you like best. phpthumbof is handy for an existing site that was already using phpthumbof; pthumb better for future compatibility and shorter too :-) -Official documentation for [phpThumbOf](http://rtfm.modx.com/display/addon/phpthumbof/) and [phpThumb](https://web.archive.org/web/20220323050907/https://phpthumb.sourceforge.net/demo/docs/phpthumb.readme.txt) (Archived version). +Official documentation for [phpThumbOf](http://rtfm.modx.com/display/addon/phpthumbof/) and [phpThumb](https://web.archive.org/web/20220323050907/https://phpthumb.sourceforge.net/demo/docs/phpthumb.readme.txt) (Archived version).
Only interested in parameters? Check out the [PARAMS.md](PARAMS.md). -pThumb adds the following system settings: +pThumb adds the following system settings: * __Check File Modification Time__: Checks the original image's file modification time and updates the cached version if necessary. Changing this setting's value will cause all currently cached images to become stale. **Default**: No