Monday, May 14, 2012

Understanding Image Channel Statistics in PHP with the ImageMagick Package

The ImageMagick function 'getImageChannelStatistics' returns an array of arrays.  The first array has keys with values set to 0, 1, 2, 4, 8, and 32.  Each of these arrays, in turn, has five values, mean, minima, maxima, standard deviation, and depth.  A sample print_r of the array produces...

Array
(
    [0] => Array
        (
            [mean] => 0
            [minima] => 1.0E+37
            [maxima] => -1.0E-37
            [standardDeviation] => 0
            [depth] => 1
        )

    [1] => Array
        (
            [mean] => 13215.2836185
            [minima] => 0
            [maxima] => 65535
            [standardDeviation] => 19099.2202751
            [depth] => 8
        )

[etc., etc..]
}

What does each 0, 1, 2, etc., value mean for the keys?  Those are shared, evaluated values of the ImageMagick Channel Constants.  You have the channel constant values that look like imagick::CHANNEL_UNDEFINED, with "_VALUE" values of: undefined, red, gray, cyan, green, magenta, blue, yellow, alpha, opacity, matte, black, index, all, and default.  If you actually print out these constants, you get '0' for undefined, '1' for red, gray, and cyan, '2' for green and magenta, '4' for blue and yellow, and '8' for alpha, opacity, and matte, or '32' for black and index.  Why do multiple channels share the same evaluated integer values?  That's because they're colors from different color spaces, with Red/Green/Blue being the RGB spectrum, Cyan/Magenta/Yellow/blacK being the CMYK spectrum, etc., etc..  If you want to get the statistical result values for Cyan or Red, you'll be accessing the same channel keys.

There are five values produced for each color channel.  The element values for the keys 'mean' and 'standardDeviation' are the results from the getImageChannelMean function.  The element values for the keys 'minima' and 'maxima' are the results from the getChannelRange function.  And the element values for the key 'depth' is the result from the getImageChannelDepth function.  All of these values can be useful in terms of measuring the Channel values of a particular image.

And now, some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Create Imagick Object
        // ---------------------------------------------
   
    $imagick_type = new Imagick();
   
        // Filename to Open
        // ---------------------------------------------

    $file_to_grab_with_location = "image_workshop_directory/test.bmp";
   
        // Open File
        // ---------------------------------------------
           
    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');

        // Read File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Statistics
        // ---------------------------------------------
               
    $imagick_type_channel_statistics = $imagick_type->getImageChannelStatistics();

        // Print Statistics
        // ---------------------------------------------

    print_r($imagick_type_channel_statistics);

?>

Official Function Page: http://www.php.net/manual/en/imagick.getimagechannelstatistics.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php

Tuesday, May 8, 2012

Understanding Image Colorspace within the ImageMagick Class of PHP

The getColorSpace function of the ImageMagick class returns an integer that is equal to one of the colorspace constants of the ImageMagick class.  That's going to look like "imagick::COLORSPACE_UNDEFINED", but the "_VALUE" could be anything among: undefined, rgb, gray, transparent, ohta, lab, xyz, ycbcr, ycc, yiq, ypbpr, yuv, cmyk, srgb, hsb, hsl, hwb, rec601luma, rec709luma, log, and cmy.  Of course, it actually returns an integer based on the order in which the value appears in this list.  Undefined returns '0', RGB returns '1', Gray returns '2', and so on.

While things like Undefined, Gray, and Transparent are obvious, the only two here I have heard of were RGB ("Red/Green/Blue") and CMYK ("Cyan/Magenta/Yellow/blacK").  The others may be of use, though.  The rec601luma and rec709luma are colorspaces used to define luminance within an image, so that could help you get a grasp of the brightness of an image.  According to Wikipedia, the rec601luma is nothing more than a specialized spectrum of the R/G/B values: "0.299 R' + 0.587 G' + 0.114 B'".  The rec709luma is: "0.2126 R' + 0.7152 G' + 0.0722 B'".

For every single image I have worked with, I have always received back a '0' from this function, indicating an Undefined colorspace.  So far, this function has simply returned whatever value was set using the setColorspace function of the ImageMagick class.

So, what's the difference between the functions getColorspace and getImageColorspace?  Not much, except the getColorspace default value is set to "_UNDEFINED", whereas the getImageColorspace functions default value is set to "_SRGB" ('13').

The total code looks like ...

<?php
   
        // Create Imagick Object
        // ---------------------------------------------
   
    $imagick_type = new Imagick();
   
        // Filename to Open
        // ---------------------------------------------

    $file_to_grab_with_location = "image_workshop_directory/test.bmp";
   
        // Open File
        // ---------------------------------------------
           
    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');

        // Read File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Colorspace
        // ---------------------------------------------

    $imagick_type_color_space = $imagick_type->getColorspace();

        // Print Colorspace
        // ---------------------------------------------

    print($imagick_type_color_space);

?>

Expected results?  So far, always: '0', representing the ImageMagick constant 'imagick::COLORSPACE_UNDEFINED'.

Official Function Page: http://www.php.net/manual/en/imagick.getcolorspace.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php

Monday, May 7, 2012

Understanding Channel Range within the ImageMagick Class of PHP

The getImageChannelRange returns an array with two values mapped to the keys 'minima' and 'maxima', which are simply the minimum and maximum values of that particular channel within the image that this function is performed upon.  For photographs and high-quality imagery, that means that you're almost always guaranteed to have the minima be at 0 and the maxima be at the maximum bit-value allowed.  For most images, that's 65,535, which is the value of 2^16 (if you start counting at 0), meaning 16-bits per Channel imagery.  This goes for all of the channels.

If an image is simple, though, you may be able to get a better variety of ranges.  An image that was simply a red square, the maxima and minima values for the Red Channel were both 65,535 (max), while the channels for the maxima and minima values for all other channels was 0 (min).  If you want to know the maximum values you might get back for any of the channels, feed this function the default channel.

For your normal channels, you'll have something that looks like "imagick::CHANNEL_RED", but you could have unusual channels like "imagick::CHANNEL_OPACITY".  For colors, you have the "_VALUE" options of: red, gray, cyan, green, magenta, blue, yellow, all, and default.  For unusual channels, you have the "_VALUE" options of: undefined, alpha, opacity, matte, black, and index.  With this function, the unusual channels always produce a minima of 1.0E+37 (10^37) and a maxima of -1.0E-37 (-10^-37), which makes no sense, so stick to the color values I pointed to above.

This function doesn't work for you?  No problem.  The function getImageChannelExtrema does the same *EXACT* thing.  The only difference is that the error you get on the unusual channels: their minima and maxima, instead of defaulting to crazy values, simply defaults to 0.

In general, this function seems to have the utility of telling you how simple an image might be -- if the difference between a channel maxima and minima is very small, that means there wasn't much expression of color for that given channel.  This will probably be able to tell you whether an image was drawn in some simple paint program or if it's an actual photograph, but beyond that, you'll have to do intensive programming to make it figure something out more complicated.

And now, an example of the results for some red-only image:

ImageMagick - Channel Range
Channel - 'Undefined' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Red' :     Minima: 65535     Maxima: 65535
Channel - 'Gray' :     Minima: 65535     Maxima: 65535
Channel - 'Cyan' :     Minima: 65535     Maxima: 65535
Channel - 'Green' :     Minima: 0     Maxima: 0
Channel - 'Magenta' :     Minima: 0     Maxima: 0
Channel - 'Blue' :     Minima: 0     Maxima: 0
Channel - 'Yellow' :     Minima: 0     Maxima: 0
Channel - 'Alpha' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Opacity' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Matte' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Black' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Index' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'All' :     Minima: 0     Maxima: 65535
Channel - 'Default' :     Minima: 0     Maxima: 65535

Official Function Page: http://www.php.net/manual/en/imagick.getimagechannelrange.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php

Sunday, May 6, 2012

Understanding Channel Depth within the ImageMagick Class of PHP

For undocumented functions, this is a particular oddity.  For me, this function has so far returned only two values for any particular image: 1 and 8.  And, after experimenting with it about forty or fifty times, I think I understand how it works, based simply on my experience.

The value returned is the number of bits used for the particular color channel within an image.  That means how variable a particular color is within an image.  While I received 1 and 8, it could theoretically be as much as 16 or 32, depending on how the technology evolves over, say, the next decade or so.

To best understand this function, you should probably also understand the ImageMagick function getColorValue.  In terms of the ImageMagick class, a color can be measured between 0 and 1, in terms in of a particular pixel.  Red, Green, Blue, or, any particular color of any color scheme, can be something like 0.501960784314.  But, since each pixel is a combination of the three colors, you can have 0.845 for red, 0.254 for green, and 0.11 for blue.

How does this all tie in with the getChannelDepth function?  Easy.  If all of the pixels in an image are either values 1 or values 0 for the particular Red/Green/Blue values, then this function will return a 1 for 1 bits per pixel for that color channel.  If, however, any single pixel in the image for the inputted channel parameter isn't exactly 1 or 0 for the particular color channel, then this function will return an 8 for 8-bit colors per pixel for that color channel.

If you receive back a 1 for every single color channel put in the parameter, that means you're dealing with an image that's 16-color (3-bit, one for Red/Green/Blue) -- you know, like those computer games published in 1982, or the Atari console games.  You won't ever forget a 16-bit color green, trust me.  If you get back an 8 for every single color channel put in the parameter, that means you're dealing with any standard, modern image.

You can input any color channel, based on the channel constants available within the ImageMagick class.  See them here: http://www.php.net/manual/en/imagick.constants.php#imagick.constants.channel .  That means a format like imagick::CHANNEL_UNDEFINED, but with the "_UNDEFINED" value being anything here: undefined, red, gray, cyan, green, magenta, blue, yellow, alpha, opacity, matte, black, index, all, and default.

For any image with one pixel color of RGB value 1 / 0.501960784314 / 0.501960784314 (#FF8080), you get this result:

Channel - 'Undefined' :        1
Channel - 'Red' :     1
Channel - 'Gray' :     1
Channel - 'Cyan' :     1
Channel - 'Green' :     8
Channel - 'Magenta' :     8
Channel - 'Blue' :     8
Channel - 'Yellow' :     8
Channel - 'Alpha' :     1
Channel - 'Opacity' :     1
Channel - 'Matte' :     1
Channel - 'Black' :     1
Channel - 'Index' :     1
Channel - 'All' :     8
Channel - 'Default' :     8

If all colors are between 0 and 1 with getColorValue function, each of these results with be 1.  If you're dealing with an image that has full color spectrum depth (almost any given photograph), you'll get 8 for red, gray, cyan, green, magenta, blue, yellow, all, and default, with a 1 for the other remaining channels.  Perhaps some use for automated image editing, like use with posterize or oilpaint functions.

Official Function Page: http://www.php.net/manual/en/imagick.getimagechanneldepth.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php

Wednesday, May 2, 2012

Perform Artistic SolarizeImage Effect on Image using ImageMagick in PHP

This is something neat that you can do to an image as part of making it artistic, probably in conjunction with other ImageMagick effects, like PosterizeImage and OilPaintImage.  SolarizeImage shifts the whole color spectrum toward red for an image -- white gets pushed directly into red, blues get pushed into greens, etc..  It is mostly a psychedelic effect.  You have the option of choosing one parameter for "Threshold", which is really simply how much of this effect you want to have in an image.  The minimum value is 0, and using a negative number defaults it to 0.  The maximum value is the Quantum Threshold.  You can get this value by the ImageMagick function getQuantumRange.  On my install of PHP, that value is set to 65535 (2^16).  Going higher than the Quantum Range defaults to the Quantum Range.  An image with this function performed on it at Threshold 0 has the maximum effect performed, and at Threshold maximum the image has no changes made to it at all.

And now a simple demonstration of the code :

<?php

        // Grab Image File Data
        // ---------------------------------------------
       
    $file_to_grab_with_location = "graphics_engine/image_workshop_directory/test.bmp";
   
    $imagick_type = new Imagick();
   
        // Open File
        // ---------------------------------------------
           
    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);
   
        // Perform Function
        // ---------------------------------------------
       
    $imagick_type->solarizeImage(30000);
   
        // Filename
        // ---------------------------------------------
       
    $file_to_save_with_location = "graphics_engine/image_workshop_directory/test_new.bmp";
   
        // Save File
        // ---------------------------------------------
           
    $file_handle_for_saving_image_file = fopen($file_to_save_with_location, 'a+');

    $imagick_type->writeImageFile($file_handle_for_saving_image_file);

?>



An example of this function performed on a Google Image Search result for "ocean":






Official Function Page: http://www.php.net/manual/en/imagick.solarizeimage.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php

Monday, April 30, 2012

Perform Artistic SketchImage Effect on Image using ImageMagick in PHP

This is a really neat function, definitely something for those into image manipulation in the style of Gimp/Photoshop effects.  The parameters are a bit unusual, though, and should be explained.

The "Radius of the Gaussian" (first parameter) is the width of the brush being used with the Sketch effect.  The "Standard Deviation of the Gaussian" (second parameter) is how often and to what extent there are "white space" areas between brush strokes.  If the Standard Deviation is big, the white areas are fewer but longer and deeper, but small, the white areas are many and tiny.  Too big, and it'll be too noticable an effect.  Do not that the higher the Standard Deviation goes, the significantly greater amount of time it takes to do the processing, compared to the other parameters.  The third parameter is the easiest: the angle.  That's just the angle that the brush strokes are drawn at uniformly throughout the image.  At 0, it's left-to-right, and at 90, it's up-and-down.  Don't forget you can use a negative degree to set the angle for this effect.  Ideally, you're probably going to want something between 30 and 60 degrees, if you're particularly aiming for an "artistic" effect.

And now, a sample demonstration on a 600 x 450 resolution image :

<?php

        // Grab Image File Data
        // ---------------------------------------------
       
    $file_to_grab_with_location = "image_workshop_directory/test.bmp";
   
    $imagick_type = new Imagick();
   
        // Open File
        // ---------------------------------------------
   
    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Perform Function
        // ---------------------------------------------

            // Gaussian Radius of 60 pixels,
            //   Gaussian Standard Deviation of 7 pixels,
            //   and Angle of -35 degrees.
   
    $imagick_type->sketchImage(60, 7, -35);
   
        // Filename
        // ---------------------------------------------
       
    $file_to_save_with_location = "image_workshop_directory/test_result.bmp";

        // Save File
        // ---------------------------------------------
   
    $file_handle_for_saving_image_file = fopen($file_to_save_with_location, 'a+');

    $imagick_type->writeImageFile($file_handle_for_saving_image_file);
       
?>

An example using the effect on an ocean picture from google image search...



Note:  This function is perfect for creating a "Rain Effect" to any picture.  Line it up to +/- 35 degrees or higher to get the optimal use out of it that way.

Note:  You'd think that this would make the drawing go into a black-gray-white scale, because it's a "sketch", but no, it actually retains the color.  That gives you the option to do more effects to it, like Posterize or OilImage.  Or, just convert it to a black and white scale to get a "true" Sketch effect.

Official Function Page: http://www.php.net/manual/en/imagick.sketchimage.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php

Sunday, April 29, 2012

Peform Polaroid-Image Effect on Image using ImageMagick in PHP

At first, the polaroidImage function looked amazingly simple.  "It must simply give a border of a specified color, and then rotate the given image by a certain number of degrees."  It actually turns out to be a really neat function.  Not only does it create an image that looks like a Polaroid of the targetted file, but it gives it a slight bend and curl that simulates a real, physical photograph.  On top of that, it gives a minor, fuzz shadow to some of the borders that accentuate the entire "effect" of looking at a real, 3d photograph.  There are some essentials to know, though!

The first parameter, $properties, has absolutely no effect upon the image that I can tell.  The official documentation, in this point, is absurdly incorrect.  Ignore the first parameter -- it's worthless.  I suspect that this is a miswrite, and what is implied is that you need to edit the properties of the Imagick class object that you're doing the PolaroidImage to.  There are two colors: the border of the image, and the color of shadow.  Both are set with the setImageBorderColor and setImageBackgroundColor functions, conveniently.  Unfortunately, this function still seems to demand a blank value for "properties", and NULL doesn't do it apparently.

One final note of precaution: the color of the surface that the photograph lies on defaults to black for BMP files, and then to white to PNG files. (Weird, huh?)  (Update:  This appears to be in how browsers decide to render opacity in the background of the image, which I have not figured out how to set in this function.)  Others have noticed this as well, on what appears to be the best source of info on this function: http://valokuva.org/?p=37 .

The angle rotates clockwise.  If you want to rotate counter-clockwise, it's easy: just use negative numbers, which this function accepts.

Now, for a brief demonstration of this function, with some fairly decent, standard parameters that should fit anyone's needs:

<?php

        // Grab Image File Data
        // ---------------------------------------------

    $file_to_grab_with_location = "image_workshop_directory/test.png"
   
        // Create ImageMagick Object Types
        // ---------------------------------------------

    $imagick_type = new Imagick();
    $draw_type = new ImagickDraw();
   
        // Open File
        // ---------------------------------------------
   
    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Perform Function: PolaroidImage
        // ---------------------------------------------

            // Polaroid Border Color:
            // ..............................................
   
    $imagick_type->setImageBorderColor( new ImagickPixel( "#CCCCCC" ) );

            // Polaroid Shadow Color:
            // ..............................................

    $imagick_type->setImageBackgroundColor( new ImagickPixel( "#000000" ) );

            // Call Function:
            // ..............................................

    $imagick_type->polaroidImage($draw_type, -10);
   
        // Save File
        // ---------------------------------------------
       
    $file_to_save_with_location = "image_workshop_directory/test_result.png"

    $file_handle_for_saving_image_file = fopen($file_to_save_with_location, 'a+');
    $imagick_type->writeImageFile($file_handle_for_saving_image_file);

?>

The following is an example using a GoogleImage search result for the word "Ocean":




Official Function Page: http://www.php.net/manual/en/imagick.polaroidimage.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php

Peform Artistic Dithering-Posterize Effect on Image using ImageMagick in PHP

Originally, I thought the OrderedPosterizeImage function would be similar to the PosterizeImage function, or at least, any one of the Imagick class functions that produces an artistic effect (like the oilPaintImage function).  This function can be used for those purposes, but it is mostly geared toward print production.  The OrderedPosterize is simply a highly flexible dithering tool.  The intention essentially is to produce high-resolution imagery by means of using constant dots across a medium that vary in size according to the detail of the imagery.  Everyone has seen a dithered photograph inside of a newspaper, but the wiki page provides better examples: http://en.wikipedia.org/wiki/Dither .

The two parameters are unusual to someone who simply wants to get the use of this function without fussing too much about the Imagick class.

First parameter: The threshold_map is a set of "brushes" predefined by a very simple xml file.  They are: threshold, checks, o2x2, o3x3, o4x4, o8x8, h4x4a, h6x6a, h8x8a, h4x4o, h6x6o, h8x8o, h16x16o, c5x5b, c5x5w, c6x6b, c6x6w, c7x7b, and c7x7w.  These are the values you are expected to input as parameters for the Thershold_Map value.  Much better descriptions of these brush shapes available at the Imagick site: http://www.imagemagick.org/Usage/quantize/tmaps_list.txt .

Second parameter: The channel is any of the constants as predefined by the Imagick class.  In the code, the value looks like "imagick::CHANNEL_RED", but you have the "_value" options of: red, undefined, gray, cyan, green, magenta, blue, yellow, alpha, opacity, matte, black, index, all, and default.  More info here: http://www.php.net/manual/en/imagick.constants.php#imagick.constants.channel .

Finally, don't forget you can use bitwise operators on the second parameter.  That means you can use & to AND them, | to OR them, & to XOR them, and ~ to NEGATE them.  A valid parameter for the second parameter would be: "(((~imagick::CHANNEL_GREEN) ^ imagick::CHANNEL_YELLOW) | imagick::CHANNEL_MAGENTA)".  You can get extremely creative in this particular parameter.  And if you want to define your own brushes using simple XML, then that's also true of the first parameter, too.

Note:  You can use this function artistically.  How?  Use the orderedPosterizeImage to give the image some texture (a photo of a vase, for instance), and then use your OilPoint, Sketch, or Standard Posterize to give the image a cool effect.  Alone, though, seems pretty boring.

And now, a very simple demonstration :

<?php
   
        // Filename
        // ---------------------------------------------

    $file_to_grab_with_location = "graphics_engine/image_workshop_directory/ordered_posterize_source.bmp"
   
    $imagick_type = new Imagick();
   
        // Open File
        // ---------------------------------------------
   
    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');
   
    $imagick_type->readImageFile($file_handle_for_viewing_image_file);
   
        // Perform Function
        // ---------------------------------------------
   
    $imagick_type->orderedPosterizeImage("o2x2", imagick::CHANNEL_GREEN);
   
        // Save File
        // ---------------------------------------------

    $file_to_save_with_location = "graphics_engine/image_workshop_directory/ordered_posterize_result.bmp"
   
    $file_handle_for_saving_image_file = fopen($file_to_save_with_location, 'a+');
   
    $imagick_type->writeImageFile($file_handle_for_saving_image_file);

?>

The following is an example using a GoogleImage search result for the word "Ocean":



Official Function Page: http://www.php.net/manual/en/imagick.orderedposterizeimage.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php

Giving a Charcoal Drawing Effect to an Image using ImageMagick in PHP

The PHP Function charcoalImage is really neat, but the parameters for this function are really scary.  Radius of the Gaussian and Standard Deviation of the Gaussian?  After playing with it for a little bit, I think I put it together.  The Gaussian is the "brush" (in Gimp/Photoshop jargin), the radius is simply the radius of the brush, and the standard deviation is the level of variation among the sizes of the brush imprints.  The $radius parameter can be anything from 0 to as high a number as you can think, but once you beyond 10, 20, or 30 pixels, depending on the image size, the whole image gets blurred beyond useful recognition.  The $sigma, being the standard deviation, should be smaller than your radius to get the desired effect.  Think of it as "Charcoal Brushes of $radius Pixels Size, with each brush being as much as $sigma Pixels bigger or smaller than that."

For an average 500 x 500 pixel image, you'll probably want a $radius of 3 to 5 and a $sigma of 1 to 3, but you can go as far as 10 pixels generally before the image is blurred beyond recognition.  (At the moment, $radius: 5 / $sigma: 2 is the perfect blend for this 400x400 image that I'm working on right now.)

There was not too help from the official documentation site for this project, either: http://www.imagemagick.org/RMagick/doc/image1.html .  The authors there note: "You can alter the intensity of the effect by changing the radius and sigma arguments."  So, my description here of the functioning is based mostly on experience rather than documentation, which is difficult to find.

The following is the entire code for applying the effect to an image.  This code will open the specified file, it will apply the charcoalImage effect to it, and then it will save it to another specified file.  The arguments are served up through POST data, and the only functions of the ImageMagick class that are used are the readImageFile, charcoalImage, and writeImageFile, as so :

<?php

        // Grab Inbound Data -- Function Parameters
        // --------------------------------------------------
       
    $inbound_gaussian_radius = $_POST['radius_of_gaussian'];
    $inbound_standard_deviation = $_POST['standard_deviation_of_gaussian'];

        // Grab Inbound Data -- Read-File and Write-File
        // --------------------------------------------------

    $filename_for_function = $_POST['file_target'];
    $inbound_save_as_filename = $_POST['saveable_result_file'];
       
        // Grab Image File Data
        // ---------------------------------------------
       
    $folder_location = "images/workshop/";
    $file_to_grab_with_location = $folder_location . $filename_for_function;
   
    $imagick_type = new Imagick();
   
        // Open File
        // ---------------------------------------------
           
    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');
   
        // Read File
        // ---------------------------------------------
   
    $imagick_type->readImageFile($file_handle_for_viewing_image_file);
   
        // Perform Function
        // ---------------------------------------------
       
    $imagick_type->charcoalImage($inbound_gaussian_radius, $inbound_standard_deviation);
   
        // Save File
        // ---------------------------------------------
       
    $folder_location = "images/workshop/";
    $file_to_grab_with_location = $folder_location . $inbound_save_as_filename;
           
    $file_handle_for_saving_image_file = fopen($file_to_grab_with_location, 'a+');
   
        // Write File
        // ---------------------------------------------
   
    $imagick_type->writeImageFile($file_handle_for_saving_image_file);
       
?>

The following is an example using a GoogleImage search result for the word "Ocean":

 

Official Function Page: http://www.php.net/manual/en/imagick.charcoalimage.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php

Verifying and Viewing Info on Your ImageMagick Installation in PHP

You will probably want to take a look at the basic package statistics for Imagick when getting to work with it.  This will provide you with the simple understanding that you have the right package and version numbers installed for PHP that you think you have :

(Note:  Imagick::getImageMagickLicense is a function that produces an error in PHP Version 5.2.17.)

The Politics:  This was originally posted with the ImageMagick class, but was then removed, either because it's too simple or because it points out another broken, undocumented function in PHP.

<?php

        // Grab and Display Copyright Information
        // ---------------------------------------------------

    $imagick_copyright = Imagick::getCopyright();
   
    print("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><u>ImageMagick Copyright:</u></b><br>");
    print("$imagick_copyright<br>");
   
    print("<br>");
   
        // Grab and Display License Information
        // ---------------------------------------------------

//    $imagick_license = Imagick::getImageMagickLicense();
   
    print("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><u>ImageMagick License:</u></b><br>");
    print("$imagick_license<br>");
   
    print("<br>");
   
        // Grab and Display Package Name Information
        // ---------------------------------------------------

    $imagick_package_name = Imagick::getPackageName();
   
    print("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><u>ImageMagick Package Name:</u></b><br>");
    print("$imagick_package_name<br>");
   
    print("<br>");
   
        // Grab and Display Version Information
        // ---------------------------------------------------

    $imagick_version = Imagick::getVersion();
   
    $imagick_version_number = $imagick_version['versionNumber'];
    $imagick_version_string = $imagick_version['versionString'];
   
    print("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><u>ImageMagick Version:</u></b><br>");
    print("Number: $imagick_version_number<br>");
    print("String: $imagick_version_string<br>");
   
    print("<br>");
   
        // Grab and Display Release Date Information
        // ---------------------------------------------------

    $imagick_release_date = Imagick::getReleaseDate();
   
    print("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><u>ImageMagick Release Date:</u></b><br>");
    print("$imagick_release_date<br>");
   
    print("<br>");
   
        // Grab and Display Home URL Information
        // ---------------------------------------------------

    $imagick_homeurl = Imagick::getHomeURL();
   
    print("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><u>ImageMagick Home URL:</u></b><br>");
    print("$imagick_homeurl<br>");

?>

Example Output:
(I had to disable the license option,
since it appears to be invalid on my
current install.)
---------------------------------------

        ImageMagick Copyright:
Copyright (C) 1999-2012 ImageMagick Studio LLC

        ImageMagick License:
ERROR -- Function not callable!

        ImageMagick Package Name:
ImageMagick

        ImageMagick Version:
Number: 1654
String: ImageMagick 6.7.6-1 2012-04-09 Q16 http://www.imagemagick.org

        ImageMagick Release Date:
2012-04-09

        ImageMagick Home URL:
/usr/[...Some URL on my Server]

Official Function Page: http://php.net/manual/en/book.imagick.php

// Note: All code appearing on the PHP Revolution blog by the blog owner is released under the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), unless otherwise noted.  http://www.hacktivismo.com/about/hessla.php