Usage

The package contains a main file in cmd/mosaic/mosaic.go. You can compile this file to an executable mosaic or mosaic.exe on Windows, or use one of the pre-compiled files on the releases page.

The program currently is only available in command line mode. Here is an example that uses the interactive mode of the program (just start the executable mentioned above). Enter the commands after >>>.

Welcome to the gomosaic generator
Copyright © 2018 Fabian Wenzelmann
>>> storage load ~/Pictures/mosaic/
>>> gch create
Creating histograms for all images in storage with k = 8 sub-divisions
[...]
Computed 5000 histograms in 2m31.663844803s
>>> mosaic cat.jpg mosaic.jpg gch-euclid 20x30
Reading image cat.jpg

Selecting database images for tiles
[...]
Composing mosaic
[...]
Mosaic saved to mosaic.jpg

There is also an easier way to achieve this if you're starting the program from the command line:

./mosaic simple ~/Pictures/mosaic/ cat.jpg mosaic.jpg 20x30

For all paths the backslash \ must be escaped by \ (backslash is used as an escape character for quotes). Thus something like this should work:

>>> storage load C:\\Users\\John\\Pictures 

The nicest way is to use the power shell: Click the Windows button and search for Power Shell, start the powershell and use it like

PS > cd PATH-TO-mosaic.exe
PS > .\mosaic.exe

Or you can just double click on mosaic.exe, probably a security warning will pop-up, just click "More Info" (or something like that) and open it anyway. A command prompt will appear. For example

The first example runs the mosaic generator in an interactive mode, called REPL. Use >>> help to show a list of commands, here's the workflow: First create an image index with the storage command:

>>> storage load <DIR>

This will index all images in the specified directory. If you use it like

>>> storage load <dir> true

it will also include images from sub-directories. The storage command can also be used to show information about the indexed files: Just storage shows the number of images and storage list shows a list of all files in the index. Next you have to initialize data for the image database. This process may take some time depending on the number of images in the index. That's way it's possible to save this precomputed data to a file and load it again.

You can use global color histograms (GCHs) or local color histograms (LCHs). The gch and lch commands can be used to initialize data:

>>> gch create [k]

creates GCHs for each image in the storage. The optional k parameter specifies how many sub-directions are used for color quantization. The default value is 8. RGB stores images with 256 values for each color component (red, green, blue). This yields to 256 x 256 x 256 possible combinations. That is too much to store (basically a histograms stores how often a color appears in an image). With k = 8 for example we have 8 x 8 x 8 colors. If k is not provided the default value 8 is used. It must be a value 1 ≤ k ≤ 256. These histograms are required required to compose a mosaic. To save the images to a file use

>>> gch save <fike>

To save the information to a file. The file extension should be .gob or .json. You don't have to know what this means just use it like this

>>> gch save ~/Pictures/gch-8.gob

Later you can use the data from that file without computing the histograms again with

>>> gch load <file>

Instead of using GCHs you can use local color histograms (LCHs). Create it with the lch command:

>>> lch create <k> <scheme>

k has the same meaning as before. The idea behind .lca. color histograms is to divide an image into regions and compute a histogram for each part. Thus, we have more information about how the colors are distributed in a specific part of the image (for example in the north). scheme is the number of such parts, it must be 4 or 5. Example:

>>> lch create 8 5

LCHs ca be save as well with lch save <file> and loaded with lch load <file>.

Once GCHs or LCHs are available (either by create or load) these can be used to create a mosaic. Use the mosaic command.

mosaic <in> <out> <metric> <tiles> [dimension]

The first argument in is the input file (.png or .jpg), out is the path to save the created mosaic to. metric must be a valid metric which is used to determine how equal two images are. A metric is always prefixed with either gch- or lch- (depending on if you want to use GCHs or LCHs) and followed by one of euclid, min, cosine, chessboard, canberra, manhattan. For example gch-euclid for euclidean distance with GCHs. GCHs / LCHs must have been loaded before. tiles is the number of tiles, i.e. 20x30 for 20 tiles in x direction and 30 in y direction. Thus 20x30 creates a mosaic with 600 tiles. The optional argument dimension defines the size of the created mosaic image. If omitted the size of the query image is used. For example a dimension 1024x768 creates an output with width 1024 and height 768 pixels. width / height can also be omitted and the original ratio will be kept. For example x768 or 1024x.

Some variables can be changed that are used in the mosaic generation process. Use the stats command to show all variables with their value:

>>> stats
cache ==> 15
cut ==> false
interp ==> Lanczos3
jpeg-quality ==> 100
routines ==> 8
verbose ==> true

Variable meaning:

• cache An image is probably used multiple times during mosaic composition. The images need to be scaled to fit into tiles and this process takes (much) time. Images are cached during composition and this parameter controls how many images will be cached. Depending on your RAM / the size of the mosaic you might want to change this value. Note that scaling png files is much faster than scaling jpg files.
• cut Cut describes whether the image should be "cut". Cutting means to cut the resulting image s.t. each tile has the same bounds. Example: Suppose you want to divide an image with width 99 and want ten tiles horizontally. This leads to an image where each tile has a width of 9. Ten tiles yields to a final width of 90. As you see 9 pixels are "left over". The distribution in ten tiles is fixed, so we can't add another tile. But in order to force the original proposed width we can enlarge the last tile by 9 pixels. So we would have 9 tiles with width 9 and one tile with width 18. Cut controls what to do with those remaining pixels: If cut is set to true we skip the 9 pixels and return an image of size 90. If set to false we enlarge the last tile and return an image with size 99.
• interp Is the interpolation function to use when images get scaled. Possible values range from 0 to 5: 0: NearestNeighbor, 1: Bilinear, 2: Bicubic, 3: MitchellNetravali, 4: Lanczos2, 5: Lanczos3.
• jpeg-quality Quality when saving jpg images, the higher the better. Value must be between between 1 and 100.
• routines The number of things to run concurrently. This is more a hint and not the absolute maximal number of things running concurrently.
• verbose If true more progress information is printed.

To set a variable to a new value use

>>> set <var> <value>

For example

>>> set cache 100
>>> set verbose false

Use the executable like this to easily create an image:

./mosaic simple ~/Pictures/ input.jpg output.png 20x30

to easily create a mosaic from input.jpg and save it to a file output.png with 20x30 tiles. This command uses GCHs with k = 8 and euclidean distance.

You can write smalls "scripts" to automize the mosaic generation process. A script is just a file in which each line contains a command as you can use in the REPL. For example the script

set cache 100
load ~/Pictures/
gch create
gch save ~/Pictures/

Save to a file script.mosaic and run with

./mosaic --run script.mosaic

Scripts can be parameterized by placeholders $1 to $n. The placeholders get replaced by the additional arguments, for example

./mosaic --run script.mosaic in.jpg

will run script.mosaic and replace each occurrence of $1 with in.jpg. The simple command for example just executes the following script:

storage load $1
gch create
mosaic $2 $3 gch-euclid $4 $5`