DrawImage ( width ; height ; colors ; pixelData ; options )

Generates a dynamic image (BMP format) using a color list and a list of pixel values.

Be the first to rate this function Log in to vote

Joe Rovang - Show more from this author

Sample input:

DrawImage ( 50; 1; "880000¶00DD00"; "11111111111111111111111111111100000000000000000000"; "" )

Sample output:

BMP image 50px wide, 1px tall, with green bar occupying leftmost 30px, dark red in rightmost 20px

Function definition: (Copy & paste into FileMaker's Edit Custom Function window)

// DrawImage ( width; height; colors; pixelData; options )

/*

This function generates a dynamic image (BMP format) for use in a calculated container field. FileMaker Pro Advanced 18 or higher is required due to use of the While function.

Basic use of this function is as follows:

	• width and height specify the dimensions of the image in pixels (will be auto-resized if "reduce or enlarge image to fit" is selected for container field)

	(Default options allow a maximum of 44,636 pixels, or roughly a 200x200 image, but this limit can be larger or smaller depending on settings below.)

	• colors is a return- or comma-separated list of colors (each in RRGGBB hex format) which pixelData (below) can reference by their index number (with the first color as index 0, the second as index 1, etc.); the maximum number of colors is determined by the color depth (below)

	(The following aliases are allowed in the colors list: aqua, black, blue, fuchsia, gray, green, lime, magenta, maroon, navy, olive, orange, purple, red, silver, teal, white, yellow. Hex shorthand is also allowed here, such as F80 for FF8800.)

	• pixelData contains a series of index values from the colors list, with each value representing each pixel from left to right (use returns or commas to separate rows of pixels); example: "100¶010¶001" generates a 3x3 pixel grid with a background using the first color (index 0) and a diagonal line using the second color (index 1) going from upper left to lower right

The way in which the index values in pixelData should be expressed is determined by the color depth (specified in the options parameter, detailed below).

	• If the color depth is 1-bit, the colors list can contain up to 2 colors; in pixelData, refer to the first color as "0" and the second as "1".

	• If the color depth is 4-bit (default), the colors list can contain up to 16 colors; in pixelData, refer to the first through tenth colors as "0" through "9", and the 11th through 16th colors as "A" through "F".

	• If the color depth is 8-bit, the colors list can contain up to 256 colors; in pixelData, refer to colors using hexadecimal byte notation "00" through "FF" (each pixel uses 2 characters).

	• If the color depth is 24-bit, the colors list is ignored, and each pixel will specify its color in RRGGBB hex format (each pixel uses 6 characters).

Notes:
	• You may use extra whitespace in the colors and pixelData parameters for readability, such as spaces between color index values in pixelData.
	• If a row in pixelData, upon being sanitized, contains fewer than the expected number of characters, the right side will be padded with zeroes. Example: "1¶01¶001" is the same as "100¶010¶001"
	• If a pixel references a color index which is undefined in the colors list, the last available color index will be used instead. (Example: If the colors list contains "red, orange, yellow" but a pixel refers to the undefined 15th color using the letter "F", that pixel will use yellow instead.)
	• If the colors list is empty, all pixels in the image will be black (this doesn't apply in 24-bit color, which doesn't use the colors list).

---

The options parameter (optional, may be left blank) accepts a JSON object containing any or all of the following keys (keys are case-sensitive):

	• colorDepth accepts the values 1, 4, 8, or 24 (default: 4). These values affect how pixelData is expected to reference a pixel's color or color index (see above).

	• filename specifies the name the resulting image should receive (applicable when exporting from a container field). The filename should end with a .bmp extension for the image to render properly in a container. The default filename is "image.bmp"

	Example options parameter for 24-bit color with filename "My Image.bmp":

		JSONSetElement ( "";
			[ "colorDepth"; 24; JSONNumber ];
			[ "filename"; "My Image.bmp"; JSONString ]
		)

The following two option keys are for advanced users (these keys disable normal transformations this function automatically performs on the colors and pixelData parameters):

	• rawColorFormat can be used to tell the function to regard the contents of the colors parameter as raw data (specify "hex" to indicate raw hex data or "bin" to specify raw binary data). This data must conform to BMP specifications (colors are 4 bytes in BGR order, with the 4th byte being padding).

	• rawPixelFormat can be used to tell the function to regard the contents of the pixelData parameter as raw data (specify "hex" to indicate raw hex data or "bin" to specify raw binary data). This data must conform to BMP specifications (byte usage is determined by the color depth, and rows must be padded to be a multiple of 4 bytes long; 24-bit colors are 3 bytes in BGR order).

---

Size limits: To minimize processing time, this function limits itself to processing 30,000 sextets (for a maximum filesize of 22,500 bytes). Considering 54 bytes are used by BMP header information, this yields the following limits by color depth (where C is the number of colors defined in the colors list):
	• 1-bit color: ( 22446 - ( C * 8 ) ) * 8 = 179,440 (2 colors defined) to 179,504 pixels (1 color defined)
	• 4-bit color: ( 22446 - ( C * 8 ) ) * 2 = 44,636 (16 colors defined) to 44,876 pixels (1 color defined)
	• 8-bit color: ( 22446 - ( C * 8 ) ) = 20,398 (256 colors defined) to 22,438 pixels (1 color defined)
	• 24-bit color: 22446 / 3 = 7,482 pixels (colors list ignored)

*/

Let (

[
	/* ----- PREFERENCES ----- */

	defaultColor = "000000"; // used when no color list is specified or when a color entry isn't understood

	maxSextets = 30000; // recursion limit when converting binary to base 64 (determines function's byte limits)

	// 30000 sextets = 22500 bytes (sextets * 6 / 8)
	// 54 bytes are used by headers, plus 8 bytes per indexed color (indexed colors N/A in 24-bit color mode)
	// to calculate max number of pixels, multiply remaining space by 8 / color depth (example: for 4-bit color, x2)


	/* ----- GENERAL ----- */

	hexChars = "0123456789ABCDEF";

	bytes = List ( // for quick conversion of integers 0-255 to their byte equivalents
		"00"; "01"; "02"; "03"; "04"; "05"; "06"; "07"; "08"; "09"; "0A"; "0B"; "0C"; "0D"; "0E"; "0F";
		"10"; "11"; "12"; "13"; "14"; "15"; "16"; "17"; "18"; "19"; "1A"; "1B"; "1C"; "1D"; "1E"; "1F";
		"20"; "21"; "22"; "23"; "24"; "25"; "26"; "27"; "28"; "29"; "2A"; "2B"; "2C"; "2D"; "2E"; "2F";
		"30"; "31"; "32"; "33"; "34"; "35"; "36"; "37"; "38"; "39"; "3A"; "3B"; "3C"; "3D"; "3E"; "3F";
		"40"; "41"; "42"; "43"; "44"; "45"; "46"; "47"; "48"; "49"; "4A"; "4B"; "4C"; "4D"; "4E"; "4F";
		"50"; "51"; "52"; "53"; "54"; "55"; "56"; "57"; "58"; "59"; "5A"; "5B"; "5C"; "5D"; "5E"; "5F";
		"60"; "61"; "62"; "63"; "64"; "65"; "66"; "67"; "68"; "69"; "6A"; "6B"; "6C"; "6D"; "6E"; "6F";
		"70"; "71"; "72"; "73"; "74"; "75"; "76"; "77"; "78"; "79"; "7A"; "7B"; "7C"; "7D"; "7E"; "7F";
		"80"; "81"; "82"; "83"; "84"; "85"; "86"; "87"; "88"; "89"; "8A"; "8B"; "8C"; "8D"; "8E"; "8F";
		"90"; "91"; "92"; "93"; "94"; "95"; "96"; "97"; "98"; "99"; "9A"; "9B"; "9C"; "9D"; "9E"; "9F";
		"A0"; "A1"; "A2"; "A3"; "A4"; "A5"; "A6"; "A7"; "A8"; "A9"; "AA"; "AB"; "AC"; "AD"; "AE"; "AF";
		"B0"; "B1"; "B2"; "B3"; "B4"; "B5"; "B6"; "B7"; "B8"; "B9"; "BA"; "BB"; "BC"; "BD"; "BE"; "BF";
		"C0"; "C1"; "C2"; "C3"; "C4"; "C5"; "C6"; "C7"; "C8"; "C9"; "CA"; "CB"; "CC"; "CD"; "CE"; "CF";
		"D0"; "D1"; "D2"; "D3"; "D4"; "D5"; "D6"; "D7"; "D8"; "D9"; "DA"; "DB"; "DC"; "DD"; "DE"; "DF";
		"E0"; "E1"; "E2"; "E3"; "E4"; "E5"; "E6"; "E7"; "E8"; "E9"; "EA"; "EB"; "EC"; "ED"; "EE"; "EF";
		"F0"; "F1"; "F2"; "F3"; "F4"; "F5"; "F6"; "F7"; "F8"; "F9"; "FA"; "FB"; "FC"; "FD"; "FE"; "FF";
	);

	maxNum = 65535; // max unsigned integer encodable with two bytes (256²-1)

	maxBits = maxSextets * 6;
	maxBytes = maxBits / 8;

	ok = True; // switched to false in the event of an unrecoverable error


	/* ----- OPTIONS ----- */

	options = JSONFormatElements ( options );
	options = If ( Left ( options; 1 ) = "?"; "{}"; options );
		// options parameter (if specified) should be a JSON object
		// available keys (case-sensitive):
			// colorDepth (number)
			// filename (text)
			// rawColorFormat (text)
			// rawPixelFormat (text)

	colorDepth = GetAsNumber ( JSONGetElement ( options; "colorDepth" ) );
		// bits per pixel (default: 4)
		// 1-bit: "0" = first color, "1" = other color
		// 4-bit: "0" = first color, "F" = 16th color
		// 8-bit: "00" = first color, "FF" = 256th color
		// 24-bit: no color indexes, every pixel is 6 chars (000000-FFFFFF)

	colorDepth = Case (
		colorDepth = 1; colorDepth;
		colorDepth = 4; colorDepth;
		colorDepth = 8; colorDepth;
		colorDepth = 24; colorDepth;
		IsEmpty ( colorDepth ); 4;
		0 // problem if colorDepth was unrecognized and not empty
	);

	ok = ok and colorDepth > 0;

	filename = JSONGetElement ( options; "filename" );
		// filename for output image (include .bmp extension); default is "image.bmp"

	filename = If ( IsEmpty ( filename ); "image.bmp"; filename );

	rc = JSONGetElement ( options; "rawColorFormat" );
		// "hex" = use color data as-is (read as hexadecimal)
		// "bin" = use color data as-is (read as binary data)
		// empty = sanitize color list as normal

	rp = JSONGetElement ( options; "rawPixelFormat" );
		// "hex" = use pixel data as-is (read as hexadecimal)
		// "bin" = use pixel data as-is (read as binary data)
		// empty = sanitize pixelData as normal

	ok = ok and ( IsEmpty ( rc ) or rc = "hex" or rc = "bin" );
	ok = ok and ( IsEmpty ( rp ) or rp = "hex" or rp = "bin" );


	/* ----- COLOR DEPTH ----- */

	maxColors = 2 ^ colorDepth;
	bytesPerPixel = colorDepth / 8; // 8-bit color indexes take 1 byte; lower color depth is fraction-bytes
	charsPerPixel = If (
		colorDepth = 1 and rp ≠ "hex"; 1; // assume 1-bit colors are in binary unless raw pixels are in hex
		bytesPerPixel * 2
	);


	/* ----- DIMENSIONS ----- */

	width = Round ( width; 0 );
	height = Round ( height; 0 );

	maxWidthOrHeight = Min ( maxBytes / bytesPerPixel; maxNum );
	maxWidth = maxWidthOrHeight;
	maxHeight = maxWidthOrHeight;

	ok = ok and width > 0 and height > 0 and width ≤ maxWidth and height ≤ maxHeight;

	// the total number of pixels (width * height) is checked against maxBytes later


	/* ----- HEADERS ----- */

	header = // BMP header (bytes after "BM" are arranged in little-endian order)
		"42" & "4D" & // "BM" signature
		"s1" & "s2" & "00" & "00" & // filesize in bytes (placeholder)
		"00" & "00" & // reserved
		"00" & "00" & // reserved
		"o1" & "o2" & "00" & "00"; // offset to pixel data (placeholder)

	headerByteCount = Length ( header ) / 2;

	infoHeader = // info header
		"i1" & "i2" & "00" & "00" & // info header size (placeholder)
		"w1" & "w2" & "00" & "00" & // image width (placeholder)
		"h1" & "h2" & "00" & "00" & // image height (placeholder)
		"01" & "00" & // number of planes (always 1)
		"d1" & "d2" & // color depth (placeholder)
		"00" & "00" & "00" & "00" & // compression (0)
		"00" & "00" & "00" & "00" & // compressed image size (N/A)
		"00" & "00" & "00" & "00" & // horizontal pixels per meter (N/A)
		"00" & "00" & "00" & "00" & // vertical pixels per meter (N/A)
		"c1" & "c2" & "00" & "00" & // colors in palette (placeholder)
		"00" & "00" & "00" & "00"; // important colors (N/A)

	infoHeaderByteCount = Length ( infoHeader ) / 2;


	/* ----- COLORS LIST ----- */

	colors = Case ( // sanitize color list
		colorDepth = 24; "";
		rc = "hex"; Filter ( Upper ( colors ); hexChars );
		rc = "bin"; Filter ( colors; "01" );
		IsEmpty ( colors ); defaultColor;
		LeftValues (
			Substitute ( colors; // standardize returns
				[ ",¶"; ¶ ];
				[ ","; ¶ ];
				[ Char ( 10 ); ¶ ];
				[ Char ( 8232 ); ¶ ];
				[ Char ( 8233 ); ¶ ]
			);
			maxColors
		)
	);

	colorCount = Case (
		rc = "hex"; Length ( colors ) / 8;
		rc = "bin"; Length ( colors ) / 64;
		ValueCount ( colors )
	);

	ok = ok and Case (
		IsEmpty ( rc ); True;
		colorCount = 0 and colorDepth = 24; True;
		colorCount = 0; False; // error if raw color data is empty (excluding 24-bit color)
		colorCount ≠ Floor ( colorCount ); False; // error if raw color data contains fraction-bytes
		True
	);

	colors = Case ( // transform each color to match BMP specifications

		not ok; "";
		not IsEmpty ( rc ); colors; // leave raw color data alone

		SetRecursion ( While (
		[
			n = 1;
			result = ""
		];
			n ≤ colorCount;
		[
			this = Trim ( GetValue ( colors; n ) );
			this = Case (
				this = "aqua"; "00FFFF";
				this = "black"; "000000";
				this = "blue"; "0000FF";
				this = "fuchsia" or this = "magenta"; "FF00FF";
				this = "gray"; "808080";
				this = "green"; "008000";
				this = "lime"; "00FF00";
				this = "maroon"; "800000";
				this = "navy"; "000080";
				this = "olive"; "808000";
				this = "purple"; "800080";
				this = "red"; "FF0000";
				this = "silver"; "C0C0C0";
				this = "teal"; "008080";
				this = "white"; "FFFFFF";
				this = "yellow"; "FFFF00";
				this = "orange"; "FF8000";
				Filter ( Upper ( this ); hexChars )
			);
			this_len = Length ( this );
			this = Case (
				this_len = 6; this;
				this_len = 3; // example: FC0 -> FFCC00
					Let (
						[ r = Left ( this; 1 ); g = Middle ( this; 2; 1 ); b = Right ( this; 1 ) ];
						r & r & g & g & b & b
					);
				defaultColor
			);
			this = Let (
				[ rr = Left ( this; 2 ); gg = Middle ( this; 3; 2 ); bb = Right ( this; 2 ) ];
				bb & gg & rr & "00" // convert to 4-byte little-endian
			);
			result = result & this;
			n = n + 1
		];
			result
		); colorCount )

	); // end case

	palette = colors;
	paletteByteCount = Length ( palette ) / If ( rc = "bin"; 8; 2 );


	/* ----- HEADER CALCS ----- */

	offsetToPixels = Sum ( headerByteCount; infoHeaderByteCount; paletteByteCount );

	totalPixels = width * height;
	pixelByteCount = totalPixels * bytesPerPixel;

	fileByteCount = Sum ( offsetToPixels; pixelByteCount );

	ok = ok and fileByteCount ≤ maxBytes;

	header = Substitute ( header;
		[ "s1"; GetValue ( bytes; Mod ( fileByteCount; 256 ) + 1 ) ];
		[ "s2"; GetValue ( bytes; Div ( fileByteCount; 256 ) + 1 ) ];
		[ "o1"; GetValue ( bytes; Mod ( offsetToPixels; 256 ) + 1 ) ];
		[ "o2"; GetValue ( bytes; Div ( offsetToPixels; 256 ) + 1 ) ]
	);

	infoHeader = Substitute ( infoHeader;
		[ "i1"; GetValue ( bytes; Mod ( infoHeaderByteCount; 256 ) + 1 ) ];
		[ "i2"; GetValue ( bytes; Div ( infoHeaderByteCount; 256 ) + 1 ) ];
		[ "w1"; GetValue ( bytes; Mod ( width; 256 ) + 1 ) ];
		[ "w2"; GetValue ( bytes; Div ( width; 256 ) + 1 ) ];
		[ "h1"; GetValue ( bytes; Mod ( height; 256 ) + 1 ) ];
		[ "h2"; GetValue ( bytes; Div ( height; 256 ) + 1 ) ];
		[ "d1"; GetValue ( bytes; Mod ( colorDepth; 256 ) + 1 ) ];
		[ "d2"; GetValue ( bytes; Div ( colorDepth; 256 ) + 1 ) ];
		[ "c1"; GetValue ( bytes; Mod ( colorCount; 256 ) + 1 ) ];
		[ "c2"; GetValue ( bytes; Div ( colorCount; 256 ) + 1 ) ]
	);


	/* ----- PIXEL DATA ----- */

	widthInBytes = width * bytesPerPixel;
	widthInBytesIdeal = 4 * Ceiling ( widthInBytes / 4 ); // pixel rows have to be a multiple of 4 bytes
	rowLengthIdeal = widthInBytesIdeal / bytesPerPixel * charsPerPixel;

	nulls = If ( ok and IsEmpty ( rp );
		SetRecursion ( While (
			// prepare a string of null bytes long enough to handle width
		[
			nul = "0";
			target = Ceiling ( Log ( rowLengthIdeal ) );
			n = 0
		];
			n < target;
		[
			nul = nul & nul & nul & nul & nul & nul & nul & nul & nul & nul; // x10
			n = n + 1
		];
			nul
		); 10 )
	);

	pixels = pixelData;
	pixels = Case ( // sanitize pixel data
		rp = "hex"; Filter ( Upper ( pixels ); hexChars );
		rp = "bin"; Filter ( pixels; "01" );
		colorDepth = 1;
			Filter (
				Substitute ( pixels; // standardize returns
					[ ",¶"; ¶ ];
					[ ","; ¶ ];
					[ Char ( 10 ); ¶ ];
					[ Char ( 8232 ); ¶ ];
					[ Char ( 8233 ); ¶ ]
				);
				"01¶"
			);
		Filter (
			Substitute ( upper ( pixels ); // standardize returns
				[ ",¶"; ¶ ];
				[ ","; ¶ ];
				[ Char ( 10 ); ¶ ];
				[ Char ( 8232 ); ¶ ];
				[ Char ( 8233 ); ¶ ]
			);
			hexChars & ¶
		)
	);

	pixels = Case ( // transform each row to match BMP specifications

		not ok; "";
		not IsEmpty ( rp ); pixels; // leave raw pixel data alone

		SetRecursion ( While (
		[
			target_len = rowLengthIdeal;
			n = height;
			result = ""
		];
			n ≥ 1;
		[
			this = GetValue ( pixels; n );
			this_len = Length ( this );
			this = Case (
				this_len > target_len; Left ( this; target_len ); // trim
				this_len < target_len; this & Left ( nulls; target_len - this_len ); // pad
				this
			);
			result = result & this;
			n = n - 1 // reverse draw order (BMP draws from bottom to top)
		];
			result		
		); height )

	); // end case


	/* ----- OUTPUT ----- */

	// Step 1: protect any raw binary data if present

	palette = Case (
		rc = "bin"; Substitute ( palette; [ "0"; "." ]; [ "1"; "-" ] ); // protect binary data
		palette
	);

	pixels = Case (
		rp = "bin"; Substitute ( pixels; [ "0"; "." ]; [ "1"; "-" ] ); // protect binary data
		colorDepth = 1 and rp = "hex"; pixels;
		colorDepth = 1; Substitute ( pixels; [ "0"; "." ]; [ "1"; "-" ] ); // protect binary data
		pixels
	);

	// Step 2: combine headers, palette, and pixel data as hex data (maybe including some protected binary data)

	hexData = If ( ok; header & infoHeader & palette & pixels );

	// Step 3: convert hex data to binary, convert protected binary data back to regular binary

	binData = Substitute ( hexData;
		[ "0"; "0000" ]; [ "1"; "0001" ]; [ "2"; "0010" ]; [ "3"; "0011" ];
		[ "4"; "0100" ]; [ "5"; "0101" ]; [ "6"; "0110" ]; [ "7"; "0111" ];
		[ "8"; "1000" ]; [ "9"; "1001" ]; [ "A"; "1010" ]; [ "B"; "1011" ];
		[ "C"; "1100" ]; [ "D"; "1101" ]; [ "E"; "1110" ]; [ "F"; "1111" ];
		[ "."; "0" ]; [ "-"; "1" ] // bring protected binary data back in as-is
	);

	// Step 4: convert binary data to base 64 data

	base64Data = SetRecursion ( While (

	[
		b = binData;
		b_len = Length ( b );
		chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
		result = "";
		padding = ""
	];

		b_len > 0;

	[

		chunk = Left ( b; 6 );
		chunk = If ( b_len < 6; Left ( chunk & "000000"; 6 ); chunk );

		val = Sum (
			32 * Left ( chunk; 1 );
			16 * Middle ( chunk; 2; 1 );
			8 * Middle ( chunk; 3; 1 );
			4 * Middle ( chunk; 4; 1 );
			2 * Middle ( chunk; 5; 1 );
			Right ( chunk; 1 )
		);
		this = Middle ( chars; val + 1; 1 );

		result = result & this;
		padding = Case ( b_len ≤ 2; "=="; b_len ≤ 4; "="; "" );

		b = Replace ( b; 1; 6; "" );
		b_len = b_len - 6
	];

		result & padding

	); maxSextets )

];

If ( ok;

	// Finally, we use Base64Decode to convert the base 64 data into an image

	Base64Decode ( base64Data; filename )

)

) // end Let

This function is a single, portable function that can create a custom BMP image for a calculated container field. This image could be used to generate a custom color swatch, a progress bar, a Gantt chart, or a much more complicated image as desired.

The image is built using a list of hex colors you provide, and a string of letters and numbers representing which color each pixel should be (in the default color depth, you can use 0-9 and A-F for a total of sixteen possible colors, but see the in-calc documentation for how to use different color depths for additional colors).

A simple two-color progress bar would only require you to feed the calculation a string of zeroes and ones to indicate which pixels should be the first defined color (0) and which should be the second defined color (1). You determine which color number each pixel should use, and the function draws the image.

FileMaker 18 is required.

Comments

		Jonn Howell, DataExperience, Inc. Mar 30, 2020
Joe, This is a wonderful custom function. I have employed it in a system with FileMaker Pro Advanced 18. It turns out that the same client is mostly still on FMP-16. Is there anyway to get this CF without the While function (else it crashes the application)? - This is way to complex for me to reverse engineer. Thanks! ~Jonn

		Joe Rovang Mar 30, 2020
Hi John, I'm glad you've found a good use for it. The While function could theoretically be replaced with recursive functions, but because it's used in four different logical loops here, it would require an enormous rewrite and multiple sub-functions to pull off. I think about the best you could do is somehow get the FM18 machine(s) to store the images that the FM16 users need to see. Any chance they have Server 18 and the FM16 clients could call Perform Script on Server?

Note: these functions are not guaranteed or supported by BrianDunning.com. Please contact the individual developer with any questions or problems.

DrawImage ( width ; height ; colors ; pixelData ; options )

Comments

Support this website.

Support this website.