Methods
(bool) | annotate | Draws a text on a given location with a given style in the image. |
(bool) | border | Surrounds the image with a border of given width, height and color. This will enlarge the image. |
(string) | build | Generates a new image and returns it as a binary string. |
(void) | cleanup | Clears the image manipulation stack. |
(bool) | colorspace | Sets the colorspace for the generated image. |
(bool) | compose | Composes a new image out of the current image and the target image. |
(bool) | convert | Converts an image from one type to another. |
(bool) | crop | Crops the image to the given dimensions with the given offset. |
(bool) | cut | Removes a number of rows and columns on the top left of the image. |
(bool) | density | Sets the resolution of a vector image for rendering. |
(array) | getExif | Returns the exif information in the image, if any. |
(array) | getimageinfo | Returns the dimensions of the image, and optionally some extra embedded information. |
(array) | getThumbSettings | Retrieves the thumbnail settings, as defined in the photobook. |
(array) | identify | Returns a list of properties of the image, like width, height, type, etc. |
(bool) | interlace | Sets the image interlacing scheme. |
(bool) | rotate | Rotates an image clockwise. |
(array) | scale | Scales an image up or down. |
(array) | scaledown | Scales an image down only. |
(void) | selectFrames | Select the frame to operate on in a multi frame format like PDF or animated GIF. |
(void) | setComposeStyle | Creates a new style for use with compose(). |
(void) | setFontStyle | Creates a new named font style. |
(bool) | shadow | Adds a shadow to the image. |
(bool) | strip | Strips the image of any profiles or comments. |
annotate
(void) annotate( $text, $x, $y, $style )
| | The text to draw in the image. |
(int) | $x | The x location to start drawing the text. |
(int) | $y | The y location to start drawing the text. |
(string) | $style | The name of the fontstyle to use. |
Draws a text on a given location with a given style in the image.
border
(void) border($width, $height, $color=false)
| | The width of the border. |
(int) | $height | The height of the border. |
(string) | $color | The color of the border as a hex string, e.g. 'FFFFFF'. |
Surrounds the image with a border of given width, height and color. This will enlarge the image.
build
(string) build()
build() generates a new image string based on the instructions on the image manipulation command stack and returns it as a binary string. This stack is created by the image manipulation functions in pphoto, e.g. border(), convert(), etc.
Note: build() will automatically send a client-side cache header with a refresh time of 30 minutes.
Example: creating a thumbnail of at most 150x150 pixels.
<pinp>
ar('loader')->content( 'image/jpg' ); if ( !cached( 'mythumbnail' ) ) { convert( 'JPG' ); scaledown( 150, 150 ); echo build(); cleanup(); savecache( 999 ); } </pinp>
cleanup
(void) cleanup()
Clears the image manipulation command stack.
colorspace
(bool) colorspace($colorspace="RGB")
| | The colorspace to use for the generated image. |
Sets the colorspace to use in the generated image. See the ImageMagick documentation for a full list.
compose
(void) compose($target, $style="default", $blend=0, $params=false, $nls='' )
| $path | The path to the target pphoto. |
(string) | $style | The name of the compose style defined earlier with setComposeStyle(). |
(string) | $blend | The percentage of alpha blending for the source and target image, e.g. '30x70%' which is equal to '30%' - with a single value the target image alpha blending is calculated by subtracting the source percentage from 100%.. |
(array) | $params | A list of parameters that override the default settings from the compose style. |
(string) | $nls | The language to use when retrieving the target pphoto. |
compose() composes a new image out of the current image and the target image. It will overlay the current image with the target image, as specified in the compose style.
Example code to add a watermark in the lower right corner of an image:
<pinp>
ar('loader')->content('image/jpg');
if ( !cached( 'watermarked' ) ) {
convert( 'JPG' );
$watermark = ar('store')->currentSite()
. 'graphics/watermark.png';
setComposeStyle(
'imageWatermark',
'srcover',
null, null,
10, 10,
null,
'',
'SouthWest'
);
compose( $watermark, 'imageWatermark' );
scale( 500, 500 );
echo build();
cleanup();
savecache( 999 );
}
</pinp>
convert
(bool) convert($format="jpg", $quality=75, $background="white")
| | The target format of the new image. |
(int) | $quality | The JPG/MIFF/PNG compression level, from 0 (worst) to 100 (best). |
(string) | $background | The background color to use when converting transparent images to a format that doesn't support transparency. |
convert() converts an image from one type to another. Types supported depend on the version of ImageMagick installed. Please see the documentation of ImageMagick for a full list. Most common types are 'JPG', 'GIF', 'PNG' and 'BMP', but ImageMagick supports dozens of types.
crop
(bool) crop($width, $height, $x=0, $y=0)
| | The width of the crop region. |
(int) | $height | The height of the crop region. |
(int) | $x | The x offset of the crop region. |
(int) | $y | The y offset of the crop region. |
Crops the image to the given dimensions with the given offset, calculated from the top left of the source image.
Example: scaling and cropping an image to an exact size.
<pinp>
ar('loader')->content('image/jpg'); if ( !cached( "cropscaled" ) ) { $info = getimageinfo();
$x = $info[0];
$y = $info[1];
$ratio = $x / $y;
$cropx = 100;
$cropy = 80;
$newratio = $cropx/$cropy;
if ( $newratio > $ratio ) {
$scaley = ceil( $cropx / $ratio );
$scalex = $cropx;
$offsetx = 0;
$offsety = (int)( ( $scaley - $cropy ) / 2 );
} else {
$scalex = ceil( $cropy * $ratio );
$scaley = $cropy;
$offsety = 0;
$offsetx = (int)( ( $scalex - $cropx ) / 2 );
}
convert('JPG');
scale( $scalex, $scaley );
crop( $cropx, $cropy, $offsetx, $offsety );
echo build();
cleanup();
savecache(999);
}
</pinp>
cut
(bool) cut($x, $y)
| | The number of columns of pixels to remove. |
(int) | $y | The number of rows of pixels to remove. |
cut() removes a number of rows and columns from the top left of the image. The Image will become smaller as a result.
density
(bool) density($density=300)
| | The dpi (dots-per-inch) density to use when rendering vectore images. |
Sets the density to use when rendering vector images to a raster format.
getExif
(mixed) getExif($sections=false, $arrays=true, $thumbnail=false, $nls='')
| | A comma seperated list of sections that need to be present in the image to produce a result array.If none of these is present, getExif() will return FALSE. See the list in PHP's exif-read-data documentation. |
(bool) | $arrays | Whether or not each section becomes an array. |
(bool) | $thumbnail | If TRUE the thumbnail in the image itself is read, otherwise only the tagged data is read. |
(string) | $nls | Which language specific version of the current pphoto to use. |
Returns an array of EXIF data from the image, or false if no matching EXIF data was found. See PHP's exif_read_data method for more information.
getimageinfo
(mixed) getimageinfo(&$extrainfo=false, $nls='')
| | If set and not false, this variable will be filled with any extra information embedded in the image as JPG APP markers. |
(string) | $nls | Which language specific version of the current pphoto to use. |
Returns an array with the width, height and file type of this pphoto. The result format is:
$result[0] | The width of the image in pixels. |
$result[1] | The height of the image in pixels. |
$result[2] | The image type as one of PHP's IMAGETYPE_XXX constants, e.g IMAGETYPE_GIF, IMAGETYPE_JPG, IMAGETYPE_PNG, etc. |
$result['mime'] | The mime-type for this image. |
$result['channels'] | 3 for RGB images and 4 for CMYK images. |
$result['bits'] | The number of bits for each color. |
On failure, FALSE is returned.
getThumbSettings
(array) getThumbSettings()
getThumbSettings() retrieves the thumbnail settings, as defined in the photobook, from the parents of the current object. This can then be used to generate thumbnails according to the these settings.
The function returns an array with the following entries:
$width | The width of the thumbnail, in pixels. |
$height | The height of the thumbnail, in pixels. |
$color | The background color of the thumbnail as hexadecimal string. |
identify
(array) identify($nls='')
(string) | $nls | Which language specific version of the current pphoto to use. |
Returns a list of properties of the image, like width, height, type, etc. The getimageinfo() method returns less information but is significantly faster.
interlace
(bool) interlace($interlace = 'plane')
| | The type of interlacing scheme to use. |
Sets the type of interlacing scheme for the generated image. Choose from 'none', 'line', 'plane', 'partition', 'JPEG', 'GIF' or 'PNG'.
rotate
(bool) rotate($degrees)
| | The degrees by which to rotate the image, clockwise. |
Rotates an image clockwise.
scale
(array) scale($x, $y, $fillcolor=false, $keepaspect=true)
| | The maximum width of the new image in pixels. |
(int) | $y | The maximum height of the new image in pixels. |
(string) | $fillcolor | Deprecated - no longer used. |
(bool) | $keepaspect | If FALSE, the image will be scaled and deformed to fit the given dimensions. Otherwise the image will be scaled to fit inside the given dimensions while keeping its current aspect ratio. |
scale() scales an image up or down untill both width and height fit in the given dimensions.
Note: you should never use a url query parameter to set the height or width to scale an image to. This allows people to run a denial of service attack by simply specifying ever changing width and height parameters, defeating any server side caching. Instead you should define a fixed set of sizes that you use in a website and create seperate templates for those sizes.
scaledown
(array) scaledown($x, $y, $fillcolor=false)
| | The maximum width of the new image in pixels. |
(int) | $y | The maximum height of the new image in pixels. |
(string) | $fillcolor | Deprecated - no longer used. |
scaledown() scales an image down only, while keeping the width to height ratio intact. Unline scale() it will not scale up smaller images.
selectFrames
(void) selectFrames($frame,...)
| | The frame or frames to select, starting from 0. |
This method allows you to select a specific frame or set of frames from the source image to work on. It is implemented with ImageMagick's 'read modifiers' option. You can enter a page, a list of pages seperated by comma or each as a seperate argument. You can also specify a range, e.g. '0-3'.
If you want to generate a preview image of a PDF file, the PDF file needs to be stored as a pphoto object. This is generally not the case and could result in unwanted behaviour. There is a way to trick Ariadne to see a pfile as if it was a pphoto:
<pinp>
$fakeImg = newobject( $path, 'pphoto' );
$fakeImg->id = $id;
</pinp>
Now you can call the pphoto methods on the $fakeImg object and have them operate on the pfile. This is a bit of a dirty trick, but it is valid and supported. You can actually call templates on the $fakeImg object and Ariadne will run pphoto specific templates on it:
<pinp>
$fakeImg->call( 'frontpage.jpg', getvar('arCallArgs') );
</pinp>
A simple frontpage preview can be generated by this template:
<pinp>
ar('loader')->content('image/jpg');
if ( !cached( 'frontpage.jpg' ) ) {
selectFrames( 0 );
strip();
convert( 'jpg' );
scaledown( 150, 150 );
echo build();
cleanup();
savecache( 999 );
}
</pinp>
setComposeStyle
(void) setComposeStyle($name, $method, $width, $height, $xoffset, $yoffset, $percentage, $resize, $gravity=false)
(string) | $name | The name to assign to this style configuration. |
(string) | $method | The composition method. See the ImageMagick documentation for a full list. |
(int) | $width | The width of the image added to the generated image. |
(int) | $height | The height of the image added to the generated image. |
(int) | $xoffset | The x offset to place the image, may be negative. |
(int) | $yoffset | The y offset to place the image, may be negative. |
(int) | $percentage | Percentage between 0 and 100. |
(string) | $resize | Either '<' or '>'. |
(string) | $gravity | To which edge the composed image will 'fall'. Options are 'Center', 'NorthWest', 'North', 'NorthEast', etc. |
Creates a new composition style for use with compose().
setFontStyle
(void) setFontStyle($name, $font, $pointsize, $color, $gravity="northwest", $rotate=0)
(string) | $name | The name to assign to this font configuration. |
(string) | $font | The path to the font file in Ariadne. |
(int) | $pointsize | The point size of the font. |
(string) | $color | The draw color of the font. |
(string) | $gravity | To which edge the text will 'fall'. Options are 'Center', 'NorthWest', 'North', 'NorthEast', etc. |
(int) | $rotate | Rotation of the text in degrees, clockwise. |
setFontstyle() assigns a font configuration to $name. This font configuration can later be used by annotate().
Fonts must be Truetype fonts, and must be stored (and readable) in Ariadne somewhere.
shadow
(bool) shadow($shadowcolor="black", $background="white", $opacity=80, $size=3, $posx="+5", $posy="+5")
| | The color for the shadow. Can be a named color or a hexadecimal string, e.g. 'F0F0F0'. |
(string) | $background | The background color to blend the shadow with. |
(int) | $opacity | The starting opacity of the shadow. |
(int) | $size | The size of the shadow - or the spread - in pixels. |
(string) | $posx | The x offset of the shadow in pixels, either starting with a '+' or a '-'. |
(string) | $posy | The y offset of the shadow in pixels, either starting with a '+' or a '-'. |
Simulates an image shadow. Enlarges the generated image to draw the shadow.
strip
(bool) strip()
Removes all profiles and comments from the generated image.