aboutsummaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authormistic100 <mistic@piwigo.org>2013-11-29 13:48:55 +0000
committermistic100 <mistic@piwigo.org>2013-11-29 13:48:55 +0000
commit7297e1cfae7ffe7cbf62d047fc3b16e2757df09d (patch)
tree916f8a127083a04f317a0cf7b7569209fe047af3 /include
parent91b6a0137dc6b703604f9c2720ee887b13b08020 (diff)
feature 2999 : Documentation of multisize classes
git-svn-id: http://piwigo.org/svn/trunk@25754 68402e56-0260-453c-a942-63ccdbb3a9ee
Diffstat (limited to '')
-rw-r--r--include/derivative.inc.php138
-rw-r--r--include/derivative_params.inc.php179
-rw-r--r--include/derivative_std_params.inc.php83
3 files changed, 348 insertions, 52 deletions
diff --git a/include/derivative.inc.php b/include/derivative.inc.php
index 6821817fe..cb368ac69 100644
--- a/include/derivative.inc.php
+++ b/include/derivative.inc.php
@@ -19,22 +19,36 @@
// | USA. |
// +-----------------------------------------------------------------------+
-/*A source image is used to get a derivative image. A source image is either the original file for a jpg or a
-'representative' image of a non image file or a standard icon for the non-image file.*/
+/**
+ * @package Derivatives
+ */
+
+
+/**
+ * A source image is used to get a derivative image. It is either
+ * the original file for a jpg/png/... or a 'representative' image
+ * of a non image file or a standard icon for the non-image file.
+ */
final class SrcImage
{
const IS_ORIGINAL = 0x01;
const IS_MIMETYPE = 0x02;
const DIM_NOT_GIVEN = 0x04;
+ /** @var int */
public $id;
+ /** @var string */
public $rel_path;
+ /** @var int */
public $rotation = 0;
-
+ /** @var int[] */
private $size=null;
+ /** @var int */
private $flags=0;
- /*@param infos assoc array of data from images table*/
+ /**
+ * @param array $infos assoc array of data from images table
+ */
function __construct($infos)
{
global $conf;
@@ -88,21 +102,33 @@ final class SrcImage
}
}
+ /**
+ * @return bool
+ */
function is_original()
{
return $this->flags & self::IS_ORIGINAL;
}
+ /**
+ * @return bool
+ */
function is_mimetype()
{
return $this->flags & self::IS_MIMETYPE;
}
+ /**
+ * @return string
+ */
function get_path()
{
return PHPWG_ROOT_PATH.$this->rel_path;
}
+ /**
+ * @return string
+ */
function get_url()
{
$url = get_root_url().$this->rel_path;
@@ -113,12 +139,17 @@ final class SrcImage
return embellish_url($url);
}
+ /**
+ * @return bool
+ */
function has_size()
{
return $this->size != null;
}
- /* @return a 2-element array containing width/height or null if dimensions are not available*/
+ /**
+ * @return int[]|null 0=width, 1=height or null if fail to compute size
+ */
function get_size()
{
if ($this->size == null)
@@ -137,19 +168,29 @@ final class SrcImage
}
-/*Holds information (path, url, dimensions) about a derivative image. A derivative image is constructed from a source
-image (SrcImage class) and derivative parameters (DerivativeParams class).
-*/
+/**
+ * Holds information (path, url, dimensions) about a derivative image.
+ * A derivative image is constructed from a source image (SrcImage class)
+ * and derivative parameters (DerivativeParams class).
+ */
final class DerivativeImage
{
+ /** @var SrcImage */
public $src_image;
-
+ /** @var array */
private $params;
- private $rel_path, $rel_url, $is_cached=true;
+ /** @var string */
+ private $rel_path;
+ /** @var string */
+ private $rel_url;
+ /** @var bool */
+ private $is_cached=true;
- /*
- @param type string of standard derivative param type (e.g. IMG_???) or a DerivativeParams object
- @param src_image the source image of this derivative*/
+ /**
+ * @param string|DerivativeParams $type standard derivative param type (e.g. IMG_*)
+ * or a DerivativeParams object
+ * @param SrcImage $src_image the source image of this derivative
+ */
function __construct($type, SrcImage $src_image)
{
$this->src_image = $src_image;
@@ -165,16 +206,25 @@ final class DerivativeImage
self::build($src_image, $this->params, $this->rel_path, $this->rel_url, $this->is_cached);
}
+ /**
+ * Generates the url of a thumbnail.
+ *
+ * @param array|SrcImage $infos array of info from db or SrcImage
+ * @return string
+ */
static function thumb_url($infos)
{
return self::url(IMG_THUMB, $infos);
}
/**
- @return derivative image url
- @param type string of standard derivative param type (e.g. IMG_???) or a DerivativeParams object
- @param infos assoc array of data from images table or a SrcImage object
- */
+ * Generates the url for a particular photo size.
+ *
+ * @param string|DerivativeParams $type standard derivative param type (e.g. IMG_*)
+ * or a DerivativeParams object
+ * @param array|SrcImage $infos array of info from db or SrcImage
+ * @return string
+ */
static function url($type, $infos)
{
$src_image = is_object($infos) ? $infos : new SrcImage($infos);
@@ -193,7 +243,7 @@ final class DerivativeImage
/**
* Return associative an array of all DerivativeImage for a specific image.
- * Disabled derivative types can be still found in the return mapped to an
+ * Disabled derivative types can be still found in the return, mapped to an
* enabled derivative (e.g. the values are not unique in the return array).
* This is useful for any plugin/theme to just use $deriv[IMG_XLARGE] even if
* the XLARGE is disabled.
@@ -228,7 +278,7 @@ final class DerivativeImage
* Returns an instance of DerivativeImage for a specific image and size.
* Disabled derivatives fallback to an enabled derivative.
*
- * @param string $type
+ * @param string $type standard derivative param type (e.g. IMG_*)
* @param array|SrcImage $src_image array of info from db or SrcImage
* @return DerivativeImage|null null if $type not found
*/
@@ -254,6 +304,9 @@ final class DerivativeImage
return null;
}
+ /**
+ * @todo : documentation of DerivativeImage::build
+ */
private static function build($src, &$params, &$rel_path, &$rel_url, &$is_cached=null)
{
if ( $src->has_size() && $params->is_identity( $src->get_size() ) )
@@ -334,11 +387,17 @@ final class DerivativeImage
}
}
+ /**
+ * @return string
+ */
function get_path()
{
return PHPWG_ROOT_PATH.$this->rel_path;
}
+ /**
+ * @return string
+ */
function get_url()
{
if ($this->params == null)
@@ -352,12 +411,17 @@ final class DerivativeImage
) );
}
+ /**
+ * @return bool
+ */
function same_as_source()
{
return $this->params == null;
}
-
+ /**
+ * @return string one if IMG_* or 'Original'
+ */
function get_type()
{
if ($this->params == null)
@@ -365,7 +429,9 @@ final class DerivativeImage
return $this->params->type;
}
- /* returns the size of the derivative image*/
+ /**
+ * @return int[]
+ */
function get_size()
{
if ($this->params == null)
@@ -375,6 +441,11 @@ final class DerivativeImage
return $this->params->compute_final_size($this->src_image->get_size());
}
+ /**
+ * Returns the size as CSS rule.
+ *
+ * @return string
+ */
function get_size_css()
{
$size = $this->get_size();
@@ -384,6 +455,11 @@ final class DerivativeImage
}
}
+ /**
+ * Returns the size as HTML attributes.
+ *
+ * @return string
+ */
function get_size_htm()
{
$size = $this->get_size();
@@ -393,6 +469,11 @@ final class DerivativeImage
}
}
+ /**
+ * Returns literal size: $widthx$height.
+ *
+ * @return string
+ */
function get_size_hr()
{
$size = $this->get_size();
@@ -402,6 +483,11 @@ final class DerivativeImage
}
}
+ /**
+ * @param int $maxw
+ * @param int $mawh
+ * @return int[]
+ */
function get_scaled_size($maxw, $maxh)
{
$size = $this->get_size();
@@ -426,6 +512,13 @@ final class DerivativeImage
return $size;
}
+ /**
+ * Returns the scaled size as HTML attributes.
+ *
+ * @param int $maxw
+ * @param int $mawh
+ * @return string
+ */
function get_scaled_size_htm($maxw=9999, $maxh=9999)
{
$size = $this->get_scaled_size($maxw, $maxh);
@@ -435,6 +528,9 @@ final class DerivativeImage
}
}
+ /**
+ * @return bool
+ */
function is_cached()
{
return $this->is_cached;
diff --git a/include/derivative_params.inc.php b/include/derivative_params.inc.php
index 31c76bed7..b0b9d67e3 100644
--- a/include/derivative_params.inc.php
+++ b/include/derivative_params.inc.php
@@ -19,11 +19,28 @@
// | USA. |
// +-----------------------------------------------------------------------+
+/**
+ * @package Derivatives
+ */
+
+
+/**
+ * Formats a size name into a 2 chars identifier usable in filename.
+ *
+ * @param string $t one of IMG_*
+ * @return string
+ */
function derivative_to_url($t)
{
return substr($t, 0, 2);
}
+/**
+ * Formats a size array into a identifier usable in filename.
+ *
+ * @param int[] $s
+ * @return string
+ */
function size_to_url($s)
{
if ($s[0]==$s[1])
@@ -33,26 +50,55 @@ function size_to_url($s)
return $s[0].'x'.$s[1];
}
+/**
+ * @param int[] $s1
+ * @param int[] $s2
+ * @return bool
+ */
function size_equals($s1, $s2)
{
return ($s1[0]==$s2[0] && $s1[1]==$s2[1]);
}
+/**
+ * Converts a char a-z into a float.
+ *
+ * @param string
+ * @return float
+ */
function char_to_fraction($c)
{
return (ord($c) - ord('a'))/25;
}
+/**
+ * Converts a float into a char a-z.
+ *
+ * @param float
+ * @return string
+ */
function fraction_to_char($f)
{
return chr(ord('a') + round($f*25));
}
-/** small utility to manipulate a 'rectangle'*/
+
+/**
+ * Small utility to manipulate a 'rectangle'.
+ */
final class ImageRect
{
+ /**
+ * @var int $l
+ * @var int $t
+ * @var int $r
+ * @var int $b
+ */
public $l,$t,$r,$b;
+ /**
+ * @param int[] $l width and height
+ */
function __construct($l)
{
$this->l = $this->t = 0;
@@ -60,19 +106,28 @@ final class ImageRect
$this->b = $l[1];
}
+ /**
+ * @return int
+ */
function width()
{
return $this->r - $this->l;
}
+ /**
+ * @return int
+ */
function height()
{
return $this->b - $this->t;
}
- /** crops horizontally this rectangle by increasing left side and/or reducing the right side.
- @param pixels the amount to substract from the width
- @param coi a 4 character string (or null) containing the center of interest*/
+ /**
+ * Crops horizontally this rectangle by increasing left side and/or reducing the right side.
+ *
+ * @param int $pixels - the amount to substract from the width
+ * @param stirng $coi - a 4 character string (or null) containing the center of interest
+ */
function crop_h($pixels, $coi)
{
if ($this->width() <= $pixels)
@@ -101,9 +156,12 @@ final class ImageRect
$this->r -= $pixels - $tlcrop;
}
- /** crops vertically this rectangle by increasing top side and/or reducing the bottom side.
- @param pixels the amount to substract from the height
- @param coi a 4 character string (or null) containing the center of interest*/
+ /**
+ * Crops vertically this rectangle by increasing top side and/or reducing the bottom side.
+ *
+ * @param int $pixels - the amount to substract from the height
+ * @param string $coi - a 4 character string (or null) containing the center of interest
+ */
function crop_v($pixels, $coi)
{
if ($this->height() <= $pixels)
@@ -131,35 +189,63 @@ final class ImageRect
$this->t += $tlcrop;
$this->b -= $pixels - $tlcrop;
}
-
}
-/** Paramaters for derivative scaling and cropping. Instance of this class contained by DerivativeParams class.*/
+/**
+ * Paramaters for derivative scaling and cropping.
+ * Instance of this class contained by DerivativeParams class.
+ */
final class SizingParams
{
+ /** @var int[] */
+ var $ideal_size;
+ /** @var float */
+ var $max_crop;
+ /** @var int[] */
+ var $min_size;
+
/**
- @param ideal_size two element array of maximum output dimensions (width, height)
- @param max_crop range 0=no cropping ... 1= max cropping (100% of width/height); expressed as a factor of the input width/height
- @param min_size used only if max_crop != 0 - two element array of output dimensions (width, height)
- */
- function __construct($ideal_size, $max_crop = 0, $min_size = null)
+ * @param int[] $ideal_size - two element array of maximum output dimensions (width, height)
+ * @param float $max_crop - from 0=no cropping to 1= max cropping (100% of width/height);
+ * expressed as a factor of the input width/height
+ * @param int[] $min_size - (used only if _$max_crop_ !=0) two element array of output dimensions (width, height)
+ */
+ function __construct($ideal_size, $max_crop=0, $min_size=null)
{
$this->ideal_size = $ideal_size;
- $this->max_crop = $max_crop; // range 0=no cropping ... 1= max cropping (100% of width/height)
+ $this->max_crop = $max_crop;
$this->min_size = $min_size;
}
+ /**
+ * Returns a simple SizingParams object.
+ *
+ * @param int $w
+ * @param int $h
+ * @return SizingParams
+ */
static function classic($w, $h)
{
return new SizingParams( array($w,$h) );
}
+ /**
+ * Returns a square SizingParams object.
+ *
+ * @param int $x
+ * @return SizingParams
+ */
static function square($w)
{
return new SizingParams( array($w,$w), 1, array($w,$w) );
}
+ /**
+ * Adds tokens depending on sizing configuration.
+ *
+ * @param array &$tokens
+ */
function add_url_tokens(&$tokens)
{
if ($this->max_crop == 0)
@@ -178,12 +264,14 @@ final class SizingParams
}
}
- /* calculate the cropping rectangle and the scaled size for an input image size
- @param in_size two element array of input dimensions (width, height)
- @param coi empty or a four character encoded string containing the center of interest (unused if max_crop=0)
- @param crop_rect output ImageRect containing the cropping rectangle or null if cropping is not required
- @param scale_size output two element array containing width and height of the scaled image
- */
+ /**
+ * Calculates the cropping rectangle and the scaled size for an input image size.
+ *
+ * @param int[] $in_size - two element array of input dimensions (width, height)
+ * @param string $coi - four character encoded string containing the center of interest (unused if max_crop=0)
+ * @param ImageRect &$crop_rect - ImageRect containing the cropping rectangle or null if cropping is not required
+ * @param int[] &$scale_size - two element array containing width and height of the scaled image
+ */
function compute($in_size, $coi, &$crop_rect, &$scale_size)
{
$destCrop = new ImageRect($in_size);
@@ -245,50 +333,81 @@ final class SizingParams
$crop_rect = $destCrop;
}
}
-
}
-/** All needed parameters to generate a derivative image.*/
+/**
+ * All needed parameters to generate a derivative image.
+ */
final class DerivativeParams
{
- public $type = IMG_CUSTOM; // string IMG_xxx
- public $last_mod_time = 0; // used for non-custom images to regenerate the cached files
+ /** @var SizingParams */
+ public $sizing;
+ /** @var string among IMG_* */
+ public $type = IMG_CUSTOM;
+ /** @var int used for non-custom images to regenerate the cached files */
+ public $last_mod_time = 0;
+ /** @var bool */
public $use_watermark = false;
- public $sizing; // of type SizingParams
- public $sharpen = 0; // range 0= no sharpening ... 1= max sharpening
+ /** @var float from 0=no sharpening to 1=max sharpening */
+ public $sharpen = 0;
+ /**
+ * @param SizingParams $sizing
+ */
function __construct($sizing)
{
$this->sizing = $sizing;
}
+ /**
+ * @return array
+ */
public function __sleep()
{
- return array('last_mod_time', 'sizing', 'sharpen');
+ return array('last_mod_time', 'sizing', 'sharpen');
}
+ /**
+ * Adds tokens depending on sizing configuration.
+ *
+ * @param array &$tokens
+ */
function add_url_tokens(&$tokens)
{
$this->sizing->add_url_tokens($tokens);
}
+ /**
+ * @return int[]
+ */
function compute_final_size($in_size)
{
$this->sizing->compute( $in_size, null, $crop_rect, $scale_size );
return $scale_size != null ? $scale_size : $in_size;
}
+ /**
+ * @return int
+ */
function max_width()
{
return $this->sizing->ideal_size[0];
}
+ /**
+ * @return int
+ */
function max_height()
{
return $this->sizing->ideal_size[1];
}
+ /**
+ * @todo : description of DerivativeParams::is_identity
+ *
+ * @return bool
+ */
function is_identity($in_size)
{
if ($in_size[0] > $this->sizing->ideal_size[0] or
@@ -299,6 +418,9 @@ final class DerivativeParams
return true;
}
+ /**
+ * @return bool
+ */
function will_watermark($out_size)
{
if ($this->use_watermark)
@@ -310,4 +432,5 @@ final class DerivativeParams
return false;
}
}
+
?> \ No newline at end of file
diff --git a/include/derivative_std_params.inc.php b/include/derivative_std_params.inc.php
index 649120033..e015a7c51 100644
--- a/include/derivative_std_params.inc.php
+++ b/include/derivative_std_params.inc.php
@@ -19,6 +19,11 @@
// | USA. |
// +-----------------------------------------------------------------------+
+/**
+ * @package Derivatives
+ */
+
+
define('IMG_SQUARE', 'square');
define('IMG_THUMB', 'thumb');
define('IMG_XXSMALL', '2small');
@@ -30,54 +35,98 @@ define('IMG_XLARGE', 'xlarge');
define('IMG_XXLARGE', 'xxlarge');
define('IMG_CUSTOM', 'custom');
+
+/**
+ * Container for watermark configuration.
+ */
final class WatermarkParams
{
+ /** @var string */
public $file = '';
+ /** @var int[] */
public $min_size = array(500,500);
+ /** @var int */
public $xpos = 50;
+ /** @var int */
public $ypos = 50;
+ /** @var int */
public $xrepeat = 0;
+ /** @var int */
public $opacity = 100;
}
+/**
+ * Container for standard derivatives parameters.
+ */
final class ImageStdParams
{
+ /** @var string[] */
private static $all_types = array(
- IMG_SQUARE,IMG_THUMB,IMG_XXSMALL,IMG_XSMALL,IMG_SMALL,IMG_MEDIUM,IMG_LARGE,IMG_XLARGE,IMG_XXLARGE
+ IMG_SQUARE, IMG_THUMB, IMG_XXSMALL, IMG_XSMALL, IMG_SMALL,
+ IMG_MEDIUM, IMG_LARGE, IMG_XLARGE, IMG_XXLARGE
);
+ /** @var DerivativeParams[] */
private static $all_type_map = array();
+ /** @var DerivativeParams[] */
private static $type_map = array();
+ /** @var DerivativeParams[] */
private static $undefined_type_map = array();
+ /** @var WatermarkParams */
private static $watermark;
+ /** @var array */
public static $custom = array();
+ /** @var int */
public static $quality=95;
+ /**
+ * @return string[]
+ */
static function get_all_types()
{
return self::$all_types;
}
+ /**
+ * @return DerivativeParams[]
+ */
static function get_all_type_map()
{
return self::$all_type_map;
}
+ /**
+ * @return DerivativeParams[]
+ */
static function get_defined_type_map()
{
return self::$type_map;
}
+ /**
+ * @return DerivativeParams[]
+ */
static function get_undefined_type_map()
{
return self::$undefined_type_map;
}
+ /**
+ * @return DerivativeParams
+ */
static function get_by_type($type)
{
return self::$all_type_map[$type];
}
+ /**
+ * @param int $w
+ * @param int $h
+ * @param float $crop
+ * @param int $minw
+ * @param int $minh
+ * @return DerivativeParams
+ */
static function get_custom($w, $h, $crop=0, $minw=null, $minh=null)
{
$params = new DerivativeParams( new SizingParams( array($w,$h), $crop, array($minw,$minh)) );
@@ -94,11 +143,17 @@ final class ImageStdParams
return $params;
}
+ /**
+ * @return WatermarkParams
+ */
static function get_watermark()
{
return self::$watermark;
}
+ /**
+ * Loads derivative configuration from database or initializes it.
+ */
static function load_from_db()
{
global $conf;
@@ -121,11 +176,19 @@ final class ImageStdParams
self::build_maps();
}
+ /**
+ * @param WatermarkParams $watermark
+ */
static function set_watermark($watermark)
{
self::$watermark = $watermark;
}
+ /**
+ * @see ImageStdParams::save()
+ *
+ * @param DerivativeParams[] $map
+ */
static function set_and_save($map)
{
self::$type_map = $map;
@@ -133,6 +196,9 @@ final class ImageStdParams
self::build_maps();
}
+ /**
+ * Saves the configuration in database.
+ */
static function save()
{
global $conf;
@@ -146,6 +212,9 @@ final class ImageStdParams
conf_update_param('derivatives', addslashes($ser) );
}
+ /**
+ * @return DerivativeParams[]
+ */
static function get_default_sizes()
{
$arr = array(
@@ -159,13 +228,19 @@ final class ImageStdParams
IMG_XLARGE => new DerivativeParams( SizingParams::classic(1224,918) ),
IMG_XXLARGE => new DerivativeParams( SizingParams::classic(1656,1242) ),
);
+ $now = time();
foreach($arr as $params)
{
- $params->last_mod_time = time();
+ $params->last_mod_time = $now;
}
return $arr;
}
+ /**
+ * Compute 'apply_watermark'
+ *
+ * @param DerivativeParams $params
+ */
static function apply_global($params)
{
$params->use_watermark = !empty(self::$watermark->file) &&
@@ -173,6 +248,9 @@ final class ImageStdParams
or self::$watermark->min_size[1]<=$params->sizing->ideal_size[1] );
}
+ /**
+ * Build 'type_map', 'all_type_map' and 'undefined_type_map'.
+ */
private static function build_maps()
{
foreach (self::$type_map as $type=>$params)
@@ -200,7 +278,6 @@ final class ImageStdParams
}
}
}
-
}
?> \ No newline at end of file