Embedding Images Within Your Application - Image2Code

Often you write applications in which image files are displayed as your application runs. This is good for images that change. But your application may depend on fixed (unchanging or permanent) images, such as for panel background textures, or button icons. Referencing image-files at run-time may be inconvenient for several reasons:
  1. You may not know where the user will install your application files or where she will run it from. So relative path references to the image files may break, and absolute paths may be wrong.
  2. When moving your application, or sending it to a user, you would need to also send all the image files, and be sure the user places them in the correct location(s).
The are some ways of dealing with these problems, such as packaging all your application files into a tar or zip package to ensure they unpack next to each other in a known configuration. And then decomposing the argv[0] path at run-time, to find the absolute path to the package-files, assuming no one inadvertantly moves of rearranges any of them.

However, a conceptually simpler and more reliable approach is to compile any fixed images directly into your executable. Your application can then be distributed as a single stand-alone executable file, without dependencies on other files.

The overriding concept is that, as a developer, you are in complete control of all files only at build-time. After that, you have little knowledge nor control where your application will turn up when it is run by various users. You want to simplify their experience, and maximize the chances everything will work correctly.
A set of convenience functions is provided below for efficiently embedding image-data into your programs and displaying it at run-time.

Download:

You can download the package from image2code.tgz or image2code.zip [95-KB].

This package consists of:

Generally you will want to keep the image2code application around, because it is a re-usable utility. You will use it to convert any permanent images into C-code data structures. By default, it outputs the C data-structures to a file called tmp_data.c, which you can then include within your applications.

You will also want to keep the decode_image_data.c file around, since you will include that in your OTK applications to display the stored C data structures as images.

The test_display program is an example application that includes the tmp_data.c and decode_image_data.c files at compile-time, and displays the image at run-time. This shows how to do it from within your applications.

Naturally, these routines depend on Otk, so you will need the Otk library. It is assumed to be in the otk_lib directory directly below the present working directory. If you have it somewhere else, just make a link to there, or change the #include reference at the top of the image2code.c and test_display.c programs to point at your otk_lib.

To compile on Linux, type:     make.
(Compile commands for some other OS's are generally provided within the header comment of each program.)

Usage Scenario:

Here is a simple usage scenario based on the files included in the image2code.tgz download package.

Suppose you have an image file, image.ppm, which is always needed by your application, and it never changes. First, convert it to a C data structure:

     ./image2code   image.ppm

This creates file tmp_data.c, whose contents appears like this: 

int imgmtrx_N0 = 39268;

unsigned char imgmtrxbytes0[39274] = {
	"112iWW2iSW0mWW0qaa0uae1yei0yim0ymm0yii1yie1yee0yea0yaW0yWS0ySO0yKK1yKG0yGG0yCC0y883y480y442y48Vy84Ly44"
	"vy841y440y841y44Ay841y44Ky840y88Jy484y88Ey8C5yCC1yCG0yGG0yKK2ySO0yWS0yaW0yaa0yee1yie0ymi0yii0yie0yee0yWa"
	...
	...
	"ii001m007i000i441i000m000q006m00|m00|m00|m00fi000m008i000a441e000i000m000q003m00|m00|m00|m00ji003m002i00"
	"0e000S441W440e000i000m00Ei004m00|m00|m00|m008i00Hm002i006e040W000321"
	};

/* Use as:
        struct Otk_image *your_image0;

        your_image0 = Otk_Make_Image_From_Matrix( "YourImage0", 256, 256, decode_image( imgmtrx_N0, 256, 256, imgmtrxbytes0 ) );
        OtkMakeImagePanel_ImgPtr( OtkOuterWindow, your_image0, 10, 10, 80, 80 );
*/
(Note: The array dimensions will generally be less than the number of image pixels due to run-length encoding for greater compactness. The array dimension will be slightly larger than the size parameter (imgmtrx_N0) due to some framing and check-markers added to the array data. )

Next, you will include the tmp_data.c file in your OTK application. You can do this by either pasting the whole file directly into your C program file with a text editor, or by simply using C's #include construct, as shown in line 30 of the test_display.c file. You should next include the re-usable decode_image_data.c routines within your application. The two include-lines could look like this: 

#include "tmp_data.c"   /* <--- The image-data is included here, produced by "image2code". */

#include "decode_image_data.c"  /* Core Re-Usable Routines */

Finally, within your OTK aplication, you can display the image using the syntax suggested at the bottom of the tmp_data.c file, as shown in the test_display.c file: 

  /* This is how to display the image from the included data-table. */
  your_image0 = Otk_Make_Image_From_Matrix( "YourImage0", 256, 256, decode_image( imgmtrx_N0, 256, 256, imgmtrxbytes0 ) );
  OtkMakeImagePanel_ImgPtr( OtkOuterWindow, your_image0, 14, 26, 70, 34 );
(Note that the image coordinates (in the second statement) were changed (from the suggestion comment in tmp_data.c) to be appropriate to this application.)

It is interesting to compare how this would have been done, if instead we referenced the file directly. The above statements replace: 

/* This would be the alternative way to display an image, by referencing a file. */
OtkMakeImagePanel( OtkOuterWindow, "image.ppm", 14, 26, 70, 34 );

Image2Code Options:

The Image2Code program accepts the following command-line options:
     
  -o xx Send output to file xx instead of tmp_data.c.
     
  -qual xx Sets quality level to xx. Allowable values range from 3 down to 0. Default quality level is 3, which preserves good quality for all images while requiring only a reasonable code size. A value of 2 reduces code size, with usually little loss in image quality. A value of 1 tends to reduce code size further, and may be OK for line drawings. Quality of zero produces the most compact code tables, but compression artifacts are more likely to be visible, especially on large photo-like images.
     
  -help Lists these options.

You can process any number of images in one run of Image2Code.
For example:   image2code   *.ppm  xyz.jpg  qrs.gif     -o your_images.c

All the image data structures will be sent to the same output file, and each will be distinguished by a sequential numerical identifier added to their variable names.
<-- Back to Image Functions

Back to main OTK page

SourceForge.net Logo