Need help with photosaic?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

130 Stars 11 Forks MIT License 35 Commits 2 Opened issues


Create beautiful mosaics from images and photos

Services available


Need anything else?

Contributors list

# 222,967
33 commits


Create beautiful mosaics of an image from an original you specify, and are made up of many small images/photos you also provide!


$ npm install -s photosaic


import fs from 'fs'
import Photosaic from 'photosaic'

const mosaic = Photosaic(./targetImgForMosaic.png, [ ./subImg1.png, ./subImg2.png, ./subImg3.png, ]) const finalMosaicBuffer = await await fs.promises.writeFile(./finalMosaic.png, finalMosaicBuffer)

Main Image Type

  • type PhotosaicImage = string | Buffer | Readable
    : main abstraction of an "image" used by Photosaic
    • string
      : the full file path of the image on the local file system
    • Buffer
      : a raw buffer of an image
    • Readable
      : a readable stream of an image to be piped to a writable stream


  • Photosaic(sourceImg, subImages, options?)
    : factory function containing functionality to build mosaics
    • sourceImg: PhotosaicImage
      : The image of the final mosaic that will be created
    • subImages: PhotosaicImage[]
      : The small, subImages that will be used to build the mosaic
    • options?
      : additional options you can provide to customize the output mosaic created
    • options.gridNum?: number = 10
      : The final mosaic will be made up of a
      gridNum x gridNum
      grid of subImages
    • options.intensity?: number = 0.5
      : Number between 0-1 indicating the opacity of the shading on the subImages to help make the output image clearer. 0 is fully transparent shading (main image will be impossible to see), 1 is fully opaque (subImages will be impossible to make out). The default of 0.5 should be fine in most cases.
    • options.outputType?: string = 'png'
      : The output type of the final mosaic. To preserve transparency in the image, use the default, 'png'.
    • options.outputWidth?: number = 400
      : Number of pixels the output mosaic's width will be (height will auto scale). The larger the width, the bigger the mosaic and the larger in size the final mosaic will be. The larger the output the longer it takes to generate a mosaic
    • options.algo?: 'closestColor' | 'random' = 'closestColor'
      : How the subImages will be dispersed throughout when building the mosaic.
      • 'random'
        selects one of the subImages randomly each iteration to be inserted in that slice of the mosaic
      • 'closestColor'
        selects the subImage that is closest to the average color of the slice of the main image that the subImage is getting inserted to build the mosaic.






const photosaic = Photosaic(source, subImgs, opts)
, the methods below are exposed on
  • Promise
    : create a mosaic and return the result in a raw Buffer
  • photosaic.setSourceImage(newSrc: PhotosaicImage) => PhotosaicImage
    : reset source image created in mosaic
  • photosaic.setSubImages(subImgs: PhotosaicImage[]) => PhotosaicImage[]
    : reset subImages used to build mosaic
  • photosaic.addSubImage(img: PhotosaicImage): PhotosaicImage[]
    : add an image to the subImage list to build mosaic
  • photosaic.imgToStream(img: PhotosaicImage): Readable
    : convert a PhotosaicImage to a Readable stream
  • photosaic.imgToBuffer(img: PhotosaicImage): Promise
    : convert a PhotosaicImage to a raw Buffer

Tracking Mosaic Progress

Depending on the options provided (specifically

) and the hardware you're running to build the mosaic, it could take several to tens of minutes for
to complete. Therefore,
has an
you can listen for
events to get the progress of the mosaic being built.

There will be a total of

2 * gridNum^2
iterations processed.
const photosaic = Photosaic(source, subImgs, opts)
photosaic.emitter.on('processing', (iteration) => {
  console.log(`Currently processing '${iteration}' subImage for the mosaic`)

// Currently processing '1' subImage for the mosaic // Currently processing '2' subImage for the mosaic // Currently processing '3' subImage for the mosaic // ...

CLI Task

You can use the following task to create a mosaic via the CLI with files on your local file system.

$ npm install -s photosaic
$ node ./node_modules/photosaic/dist/tasks/createMosaic.js -i ./pathToMosaicFile.js --dir ./path/to/sub/images -g 40 -w 1000

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.