Exploring Color Histograms In GraphicsMagick And Lucee CFML 5.2.9.31

<cfscript>

	param name="url.image" type="string" default="beach-small.jpg";

	startedAt = getTickCount();

	// CAUTION: For the sake of the demo, I am not validating the input image. However,
	// in a production setting, I would never allow an arbitrary filepath to be provided
	// by the user! Not without some sort of validation.
	inputFilename = url.image;
	inputFilepath = expandPath( "../images/#inputFilename#" );	

	// To get the top colors in the image, we need to generate a histogram. But, to make
	// the demo a bit more interesting (and easier for me to learn from), I'm going to
	// generate an intermediary image so that we can see what the input of histogram is.
	// We will then display the intermediary image as well as use it as the input to the
	// histogram.
	gm([
		"convert",

		// This is the image we are inspecting.
		applyReader( inputFilepath ),

		// Fill in the background with white and remove any alpha-channel data. To keep
		// things simple, we want to remove any alpha-channel data.
		"-background ##ffffff",
		"-extent 0x0",
		"+matte",

		// Let's convert images to the RGB colors-space.
		"-colorspace RGB",
		"-depth 8",

		// Scale the image size down so that reducing the colors and generating the
		// histogram is faster (disabling dithering to reduce noise artifacts).
		"+dither",
		"-scale 75x",

		// Now that we have a scaled-down image, let's reduce the color-space to [at
		// most] 50 unique colors.
		"-colors 50",

		// Scale the image up to make the demo more visually interesting - this will show
		// the pixelation caused by the scaling-down of the image.
		// --
		// NOTE: This doesn't change the outcome of the histogram (as long as the new
		// SCALE is a multiple of the RESIZE).
		"-scale 375x",

		expandPath( "./out.png" )
	]);

	// Using the scaled-down and color-reduced image, generate a histogram file.
	gm([
		"convert",
		applyReader( expandPath( "./out.png" ) ),
		"histogram:#expandPath( './histogram.miff' )#"
	]);

	// The resultant MIFF file (what format GraphicsMagick uses to generate a histogram)
	// includes the color-counts in the COMMENT. As such, we can pluck out the comment
	// using the identify command.
	comment = gm([
		"identify",
		"-format %c",
		expandPath( './histogram.miff' )
	]);

	// In the GraphicsMagick histogram, the top / most frequent colors are defined in the
	// Comment (%c) using the following format:
	// --
	// count: ( r, g, b, a ) hex
	// --
	// As such, we can just pattern-match on the first 4-numbers in each line to get the
	// Count, R, G, and B (I have no alpha channels in this demo).
	colors = comment.listToArray( chr( 13 ) & chr( 10 ) )
		.map(
			( line ) => {

				var numbers = line.reMatch( "\d+" );
				var count = val( numbers[ 1 ] );
				var red = val( numbers[ 2 ] );
				var green = val( numbers[ 3 ] );
				var blue = val( numbers[ 4 ] );

				return({
					count: count,
					hex: rgbToHex( red, green, blue )
				});

			}
		)
		// Sort the colors so that the most frequent colors are listed first.
		.sort(
			( a, b ) => {

				// By using simple subtraction:
				// --
				// ( a.count > b.count ) results in negative number.
				// ( a.count < b.count ) results in positive number.
				// ( a.count == b.count ) results in zero.
				return( b.count - a.count );

			}
		)
	;

	duration = ( getTickCount() - startedAt );

	// ------------------------------------------------------------------------------- //
	// ------------------------------------------------------------------------------- //

	/**
	* I prefix the given filepath with an explicit reader. We want to be EXPLICIT about
	* which input reader GraphicsMagick should use when reading in an image. If we leave
	* it up to "automatic detection", a malicious actor could fake the file-type and
	* potentially exploit a weakness in a given reader. As such, we want to align the
	* reader with the articulated file-type.
	* 
	* READ MORE: http://www.graphicsmagick.org/security.html
	* 
	* @filepath I am the filepath being decorated.
	*/
	public string function applyReader( required string filepath ) {

		switch ( listLast( filepath, "." ).lcase() ) {
			case "gif":
				var reader = "gif";
			break;
			case "jpg":
			case "jpeg":
				var reader = "jpg";
			break;
			case "png":
				var reader = "png";
			break;
			default:
				throw( type = "UnsupportedImageFileExtension" );
			break;
		}

		return( reader & ":""" & filepath & """" );

	}


	/**
	* I execute the given options against the GM (GraphicsMagick) command-line tool. If
	* there is an error, the error is dumped-out and the processing is halted. If there
	* is no error, the standard-output is returned.
	* 
	* NOTE: Options are flattened using a space (" ").
	* 
	* @options I am the collection of options to apply.
	* @timeout I am the timeout to use during the execution.
	*/
	public string function gm( required array options ) {

		execute
			name = "gm"
			arguments = options.toList( " " )
			variable = "local.successResult"
			errorVariable = "local.errorResult"
			timeout = 5
		;

		// If the error variable has been populated, it means the CFExecute tag ran into
		// an error - let's dump-it-out and halt processing.
		if ( local.keyExists( "errorVariable" ) && errorVariable.len() ) {

			dump( errorVariable );
			abort;

		}

		return( successResult ?: "" );

	}


	/**
	* I convert the given RGB values to a single, 6-character hexadecimal format.
	* 
	* @red I am the red channel value.
	* @green I am the green channel value.
	* @blue I am the blue channel value.
	*/
	public string function rgbToHex(
		required numeric red,
		required numeric green,
		required numeric blue
		) {

		return(
			( "0" & formatBaseN( red, 16 ) ).right( 2 ) &
			( "0" & formatBaseN( green, 16 ) ).right( 2 ) &
			( "0" & formatBaseN( blue, 16 ) ).right( 2 )
		);

	}

</cfscript>
<cfoutput>

	<link rel="stylesheet" type="text/css" href="./demo.css">

	<p>
		<strong>Images:</strong>
		<a href="./index.cfm?image=beach-small.jpg">Beach</a> ,
		<a href="./index.cfm?image=goose.jpg">Goose</a> ,
		<a href="./index.cfm?image=face-square.jpg">Face</a> ,
		<a href="./index.cfm?image=deer.jpg">Deer</a> ,
		<a href="./index.cfm?image=sleeping.jpg">Sleeping</a> ,
		<a href="./index.cfm?image=staring.jpg">Staring</a> ,
		<a href="./index.cfm?image=engineering.jpg">Engineering</a> ,
		<a href="./index.cfm?image=circle.png">Circle</a> ,
		<a href="./index.cfm?image=beans.jpg">Beans</a> ,
		<a href="./index.cfm?image=calm.jpg">Calm</a>
	</p>

	<div class="images">
		<img src="../images/#inputFilename#" />
		<img src="./out.png" />
	</div>

	<!--- Output the top / most frequent colors in the source image. --->
	<div class="colors">
		<cfloop index="color" array="#colors#">
			
			<span
				title="Color: ###color.hex#, Count: #numberFormat( color.count )#"
				style="background-color: ###color.hex# ;">
				<br />
			</span>

		</cfloop>
	</div>

	<p>
		Duration: #numberFormat( duration )# ms
	</p>

</cfoutput>