Skip to content
Recreate a target images bymaking a mosaic out of multiple input images
Python Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Recreate a target images by making a mosaic out of multiple input images.


bond grayscale mosaic examples

bond3 grayscale mosaic examples

Note: Images have been scale down to take less space


To get started quickly you can use the provided example input and target images. The example is using the --grayscale option as it yields better results. Also, the --multithreading option is really important to get sufficient speed. The algorithm is quite long, and without multithreading you'll wait for a long time, especially if the image is big.

Simply run

make lena_grayscale_multithreading

or use the equivalent script call

python --target_im=images/target/lena.jpg			        \
	--inputs=images/input/ --resize_factor=1 --pixel_density=0.25	\
	--grayscale --output_size_factor=5 --contrast 					\
	--multithreading --num_workers=12 --save

To get a detailed list of the arguments, head to How to use section.

  • --resize_factor=1 ensures the initial image size is kept the same when going through it
  • --pixel_density=0.25 tells how big the pixel scanning must be
  • --grayscale to use grayscale mode (yields better results)
  • --output_size_factor=5 the output image will be 5 times the initial image size
  • --contrast applies CLAHE to the image to enhance the constrat before using it

Resulting image

mosaic examples

Note: Image has been scale down to take less space

How to use

You need to run python with the arguments described beneath. Take a look at the makefile to see well working examples.


If you want to use the Makefile provided, please change the first line

python-bin = ~/.pyenv/versions/3.6.7/envs/pymosaic/bin/python

to your python bin path.

Required arguments

  • --target_im : Path to target image
  • --inputs : Path to input images

Optional arguments

  • --output_size_factor : How much times the output should be bigger than the target
  • --resize_factor : Factor to resize target image
  • --grayscale : Convert to grayscale
  • --contrast : Apply auto contrast to target image
  • --color_filter : Apply color filters to get closer to the desired color
  • --pixel_density : Path to target image
  • --multithreading : Use multiple thread to create the mosaic
  • --num_workers : Number of workers to use in multithreading
  • --save : Save the output mosaic in results/
  • --show : Show output mosaic

Recommended arguments

From what I've experienced, using --contrast in combination with --grayscale yields the best results. To keep the process short enough, use --multithreading with the highest --num_workers for your machine.

Don't forget --save to actually save the created mosaic!

How does it work?

I'm in the process of writing a post on my blog to give a detailed tutorial on that.


Simply run

pip install -r requirements.txt


  • Add argument parsing
  • B&W support
  • Be able to select output resolution
  • Add option to save mosaic
  • Add/test contrast increasing before mosaic
  • Use pixel density argument
  • Add color filtering option (for smoother results)
  • Add option to choose to display the output or not
  • [] Add script to download input images (from ImageNet)
  • [] Handle case where kernel size = 1
  • [] Handle case where kernel size is > 1 and < to kmean clusters (3)
  • [] Improve color filtering
  • [] Add web interface


Want to support me? Buy me a coffee!

Buy Me A Coffee

You can’t perform that action at this time.