JImage Mosaic
News :: About :: Screen Shots :: Download :: Documentation :: FAQ :: Samples :: Register :: Log In
not logged in


SourceForge.net Logo

Valid HTML 4.01!

Valid CSS!

JImage Mosaic Documentation
Software Documentation

Software Documentation

Installing JImage Mosaic
Running JImage Mosaic
Overview of using JImage Mosaic
Maintaining an Image Library
Creating an Image Map
Setting render options
Rendering and saving an image


Welcome to JImage Mosaic - the free, open-source, Java-based photomosaic creation utility. JImage Mosaic was written with the intention of giving the public and easy to use solution to creating eye-catching photomosaics, on any platform out there. Also, by making JImage Mosaic easily extensible, developers can create their own plugins to do just about anything - open images, save images, create image libraries, create rendering algorithms, or create post-rendering fliters.

Installing JImage Mosaic

To download and install JImage Mosaic, you can go to the Download Page, and read the instructions there. However, more information is available here.
The most important step in a successful JImage Mosaic installation is to make sure you have downloaded and installed ALL of the appropriate packages. There are three primary things you need to have...
  • The current version of JImage Mosaic
  • The 1.4 version of the Java Runtime Environment (JRE)
  • Sun's JAI API for Java

To check to see if you already have the 1.4 or higher version of the Java Runtime Environment installed, go to a command prompt (Windows) or a shell terminal (*nix) and type "java -version" (Without the quotes. Note that there is a space between "java" and the hyphen.) Here is an example of what you should type on a Linux system.

terminal window

If the number listed after "java version" (in this case it is "1.4.0_02") is 1.4 or greater, than you are okay. Otherwise, you need to install the JRE. If you do need to install the JRE, go to http://java.sun.com/j2se/1.4/download.html. On this website, there will be three columns, the last two marked "JRE" and "SDK". If you are planning on writing your own plugins for JImage Mosaic, or you plan on downloading the source code instead of the binaries, you will need to follow a link in the SDK (Software Development Kit) column, as JRE is included in the SDK. If you aren't planning on writing plugins for JImage Mosaic, you only need to concern yourself with the "JRE" column. Find your operating system in the far left column, and click on the link in either the JRE or SDK column, depending on if you want to write plugins or not. Once you download the JRE (or SDK), you need to install the software. If you have any problems installing the JRE, you can check Sun's help page, at http://servlet.java.sun.com/help/installation/.

At this point, you should have JRE successfully installed. You can check this by doing the "java -version" command again. If you have any problems, try Sun's installation link above, or email jimage-mosaic@jimdrewes.com for some help.

Next, you need to download JAI, which is the Java Advanced Imaging API for Java. Chances are, unless you are developing your own applications in JAI, you probably don't already have it installed. To download and install JAI, go to http://java.sun.com/products/java-media/jai/downloads/download-1_1_1_01.html. On this page, you will see drop-boxes under several categories (JDK, JRE, CLASSPATH, etc..) Under the "JRE" category, click on the drop-box and select your operating system. Continue from there to download and install JAI. If you have any problems, check Suns' website, http://java.sun.com/products/java-media/jai/INSTALL.html or email jimage-mosaic@jimdrewes.com.

Now you are finally ready to download and install JImage Mosaic. There are two options for installing JImage Mosaic. The first option is to download the source code, then compile the program yourself. Unless you are planning on changing JImage Mosaic, or writing modifications to the code, I would STRONGLY recommend against installing JImage Mosaic this way. Compiling it yourself will only make things more difficult. Instead, you should download the already compiled version. Just go to jimage-mosaic.sourceforge.net/download.php. If you scroll down the page a little, there will be a "JImage Mosaic Files" section. From there, select the appropriate operating system out of either the "Executables" or "Source Code" categories. Also, if you want to download a collection of images that you can easily use in JImage Mosaic, go ahead and download the library of beer-labels Here.
Once you have downloaded JImage Mosaic, all you should need to do is uncompress the file.

Windows users, you should probably already have WinZip installed on your computer. If you do, just double-click on the file you downloaded, and extract the files to whatever directory you need. If you don't already have WinZip, you can download it at www.winzip.com. If you have any other questions or problems installing or uncompressing the files, email jimage-mosaic@jimdrewes.com.

Linux/Unix/BSD users, all you need to do is uncompress the tar.gz file. You can easily do this by typing tar -zxvf filename in a terminal window. If you have any problems uncompressing, or you need the file in a different compressed version, just email jimage-mosaic@jimdrewes.com.

Running JImage Mosaic

At this point, it is assumed that you have already downloaded and installed the JRE, JAI and JImage Mosaic programs. If you haven't done this yet, read the section on installation.
If you downloaded one of the executable versions of JImage Mosaic, there should be an executable script that was included with the distribution. Simply navigate to the directory that you installed JImage Mosaic to, and execute this script. In Windows, you just need to double-click on the JimageMosaic.bat file, or typing JImageMosaic at a command prompt when you are in the directory where you installed JImage Mosaic. Linux/Unix/BSD users should just click on the JImageMosaic shell script which is located in your install directory. Another option is to open a terminal and navigate to the install directory. From there, just type ./JImageMosaic
If you still can't get JImage Mosaic to run, try typing java MainForm and hitting enter. If you are still having problems, see the Troubleshooting section.
Once you get JImage Mosaic running, the main window for the program should appear.

Overview of using JImage Mosaic

This section will give a brief overview of how to use JImage Mosaic to start creating your own images!
Using JImage Mosaic is actually pretty easy. The steps involved in generating a final image can be summarized in just a few actions.
  • Generate a tile library.
  • Select a base image.
  • Create a tile map from the base image.
  • Render the image.
  • Save the image.
Some of these steps are just one-click actions. However, some of them require a little more work (for example, generating a tile library, or creating a tile map.)
The first step, generating the tile library, is described in-depth in the next section. In short, simply click on the "Maintain Image Library" selection in the "Project" menu at the top of the main window. This takes you to the image library maintainance screen. From here, just select the files you want to use in your library out of the left-hand box, and use the arrow button to move them to the right-hand box. Then, you just "Evaluate" the library, then save it to a file (ending with .jml).
After you are finished creating an image library, you can close out that window and go back to the main JImage Mosaic screen. If you click on the "Load Image Library" button, you can search for the library you just created. When you load it, the number of images in the library should appear in the "Mosaic Info" box. By clicking on the "Load Base Image" button, you can select an image that you want to use as the base image for your photomosaic. The base image is basically the picture JImage Mosaic will try to create, using only images out of your image library. The base image should appear in a tabbed window on the JImage Mosaic form.
The next step, which also has a more elaborate description here, is to create a tile map from the base image. The purpose of the tile map is to provide somewhat of a preview as to what the final image may look like. Simply specify the number of tiles across and down that you want in your final image, and then specify the dimensions you want the tiles to be. JImage Mosaic will calculate the dimensions of the final image and display them in the "Mosaic Info" box. When you click on the "Generate Map" button, JImage Mosaic will pixillate the base image, according to the dimensions you specified. When it completes, a "Map" tab will appear next to the base image tab. Click on the tab to see the image map. If you like the way it looks, you can continue on. Otherwise, adjust the dimensions and re-generate the map.
For now, the next two steps are one-click operations. Once you have the map the way you want it, click on the "Render" button (or select "Render" from the "Render" menu). This will render the final image in two steps. First, it will select the images for the tiles, based on the image map. Then, it will actually build the final image based on the images it selected. The final step is to save your output image. Just select the "Save Output Image" option from the "Render" menu. Name your file, and suffix it with .bmp

Maintaining an image library

The first step in generating a tile library is to find a collection of images to use. One such collection is here -- This is a collection of 1,800 beer labels. You might decide to use pictures of your family, or a bunch of pictures of animals, or whatever. For JImage Mosaic to be able to generate a reasonable final image, your library needs to have at least 300 images in it of varying colors. 1,000 or more images would be your best bet. The more images you have, the better your final image will be. But if your library gets TOO big, it will take much longer to render the final image.
To get to the image library window, click on "Maintain Image Library" in the "Project" menu on main window. This should load up a new window that says "JImage Mosaic Maintain Library [Untitled]" on the bar at the top. You will now notice a "File Selection" area, that has two large boxes. The box on the left should display the files in your current working directory (Note, it defaults to only showing .JPG files). Using the box on the left, and the various controls directly above and below it, you can navigate through your computer to find the files you would like to include in your image library. For now, JImage Mosaic can only use JPEG (.jpg) files in the image library. Single-click on the images you want to include (Use CTRL to select multiple files, and SHIFT to select blocks of files). Once you have some images selected that you want to include, click on the ">" button in-between the boxes, to include those images in the library list (the box on the right).
If you want to remove an image from the library list, click on the file in the box on the right, then click the "<" button to remove it. To remove all of the files from your library list, click on the "Clear List" button above the box on the right.
Once you have all of the images included in your list that you would like, its time to "Evaluate" those images. Whats happens when you evaluate the images is JImage Mosaic opens each file, and comes up with an average color for every picture. This average color is used in selecting which images to use where in the final image. To evaluate the images, select "Evaluate Images" out of the "Evaluate" menu at the top. Keep in mind that if the images in your library are large (640x480, for example) the evaluation process may take a while. To abbreviate the process a little, try using scaled-down images (64x48). This will speed up the process a great deal.

After the progress indicator reaches "100%" at the bottom, the "Save" option under the "File" menu will become enabled. Click on this to save your library. You need to give it a name, and suffix it with ".jml", for "Jimage Mosaic Library."

If you have already created a JImage Mosaic library, and have it saved as a .jml file on your computer, you can still easily add or remove images from this library. Simply click on the "Open" selection under the "File" menu. This will allow you to select and open an existing library. Once the library is open, it will populate the right-side box with the names of all of the files in that library. From there, you can remove existing entries, or add additional files. Unfortunatly, in the current version of JImage Mosaic, the entire library will need to be re-evaluated whenever a change is made. This is a problem that will be fixed in future versions of JImage Mosaic.

Creating an image map

The first step in actually creating a photomosaic image, assuming that there is already an image library and a base image, is to create an image map. The image map serves two purposes:
  • Externally, the image map allows the user to see approximately how the final image will look, before it is even rendered. However, the map shows what the ideal outcome would look like. The final image will never be as perfect as the image map.
  • Internally, the image map allows JImage Mosaic to more quickly render the final image, because the rendering process only concerns itself with the image map, and not the full base image.
To create the image map, a base image must be already loaded into JImage Mosaic. To do this, click on the "Load Base Image" button on the main form of JImage Mosaic. Currently, you can only select JPEG images to use as base images. It is not necessary to load an image library in order to make the map, although it will be necessary to load one to render the final image. Once the base image is loaded, the "Generate Map" button becomes active. Clicking the "Generate Map" button starts the map generation procedure. Once the procedure starts, some controls will be disabled until the map is finished, or the "Stop" button is clicked. When JImage Mosaic is finished generating the map, a tab will appear above the base image that says "Map." Clicking on this tab will show the map image. Clicking on the "Base Image" tab will go back to the view of the base image.
To alter the size of the tiles in the image, as well as the dimensions of the final image, the values in the "Horizontal Tiles," "Vertical Tiles," "Tile Width (px)," and "Tile Height (px)" boxes can be changed. The horizontal and vertical tiles boxes specify the dimensions of the image in terms of tiles. If the final image should have 10 tiles across, and 20 tiles down, the horizontal and vertical boxes will have 10 and 20 in them respectively. The tile width and height boxes determine the dimensions of each tile in the image, in terms of pixels. If each tile should be 64 pixels wide and 48 pixels high, the numbers 64 and 48 will be entered into the tile width and height boxes respectively. To make sure the final image has the appropriate dimensions, examine the "Final Image Dimensions" field in the Mosaic Info box. This field displays the final image dimensions, calculated by multiplying the number of tiles by the tiles dimensions. For example, a 10 tile by 20 tile image, where each tile is 64 pixels by 48 pixels will result in a 640 x 960 final image (10 x 64 = 640, and 20 x 48 = 960). Generally, it is a good idea to make sure the final image dimensions have the same ratio as the base image dimensions. For example, if your base image is 640 x 480, you would want a final image of 320 x 240, or 1280 x 960, otherwise the image will become stretched. Future versions of JImage Mosaic will enable the "Maintain Aspect Ratio" button, so the ratio will automatically be maintainted. When the map dimensions have been set where they should be, click the "Generate Map" button to create the image map. Once the image map is complete, and an image library is loaded, the final image can be rendered.


© 2002 Jim Drewes