Creating an Autostereogram

Job Files

The program uses JSON files to create autostereograms. Job files, typically in the /jobs folder, contain the information on creating an autostereogram image. This includes various parameters and the name of a BMP file containing the image to use for creating the autostereogram.

Here is an example job file:

Download: file
{
	"image": "shark.bmp"
	"imagegrayscale": 1
	"grayscalecolors": 16
	"bkpixelsize": 2
	"bkratio": 7
}

The "image" option specifies the BMP file to use, typically in the "images" folder. The code supports both monochrome and grayscale BMP files. Monochrome BMP files create a 3D image with a foreground image and background image. Grayscale BMP files use the grayscale color to indicate the depth of the image, with white being closest to the viewer and black the furthest. You can find these images on the internet using search terms like "grayscale depth map" or "3d depth map". Use 1 for "imagegrayscale" if using a grayscale BMP file, otherwise, use 0.

Images should match the ePaper shield size of 264 by 176 pixels, since no scaling is done to the images. 

For monochrome images, the "imageheight" option determines how high in the Z direction to display the image. A value of 4 works well here. For grayscale images, the "grayscalecolors" option determines how many planes to use to display the image. The maximum # is 20. You may wish to use a lower number if you find the image is disproportionately large in the Z direction.

circuitpython_shark.jpg
A grayscale depth map image

The "bkpixelsize" and "bkratio" specify the pixel size and white to black pixel ratio to use for the background. The bkpixelsize can range from 1 to 4, specifying a pixel from 1x1 dots in size to 4x4 dots in size, respectively. The bkratio can range from 1 to 9 with 1 specifying 1 out of 10 pixels  are white (a dark background), and 9 specifying 9 out of 10 pixels are white (a light background). The random pixels at the various ratios and sizes have been precalculated to save time in creating the autostereograms and are typically located in the /backgrounds folder. Most images look best with a bkratio between 4 to 7, however, some simple images can work well using a 1,2, 8 or 9 bkratio value. Here is a monochrome image that works quite well with a bkratio of 9.

circuitpython_adafruit792.bmp
Even with a low number of black pixels, simple images can still be seen in 3D

The config.json File

The config.json file contains information on where files are located, as well as which job(s) to run. Here is a typical config.json file:

Download: file
    {
    "jobs": ["adafruitlogo.json"]
    "asgfolder": "/asgfiles"
    "jobfolder": "/jobs"
    "bkfolder": "/backgrounds"
    "imagefolder": "/images"
    "slidefolder": "/slides"
}
  

Here is a description of the options in the config.json file:

  • jobs: one or more jobs to run to create the autostereograms. Job files are located in the job folder. Separate multiple jobs with commas.
  • asgfolder: This is where autostereograms are saved if writing them to disk (explained in more detail below)
  • jobfolder: The location of the job files
  • bkfolder: the location of the background pixel files  used by the "bkpixelsize" and "bkratio" options in the job file
  • imagefolder: the location of the image files used to create the autostereograms.
  • slidefolder: the location of image files used for displaying a slideshow (explained in more detail below).

Creating an Autostereogram

Once the job file has been defined and the config.cfg file has been updated to include the job name, the job can then be run. Pressing the "A" button on the ePaper display generates the autostereogram from the specified job file and displays it on the ePaper display. You will notice the LED on the Metro M4 Express will blink while it is being generated. 

Autostereograms can be saved to a file for sharing on social media, but an additional step is needed to accomplish that. By default, CircuitPython does not have write access to files on its drive, instead the host computer has write access, which is needed to copy images the modify job files, for example. This is to prevent the host computer and CircuitPython possibly opening the same file for writing and corrupting a file. In order for CircuitPython to be able to write to its drive (and make the drive read only to the host computer), press the Reset button then quickly press and hold the "A" button. Leave the "A" button pressed for a few seconds to allow the device to boot up. Once the device has booted up, released the "A" button. The device is now running the job as before (with the LED flashing), but this time it is writing an autostereogram file to the /asgfolder. The name of the autostereogram will be the same as the image file name with the prefix "asg" in the name. Once the job is completed and the image is displayed, press the reset button to switch back to the original host computer read write mode, where you can then copy the newly created file in the /asgfolder.

Slideshow Mode

There is a slide show mode, where you can display previously created autostereogram files. Copy the files you wish to include in the slideshow from the /asgfolder to /slidefolder. Once you have your slideshow images ready, press the "B" button to start the show. The show will continue indefinitely until you power off the device or press the reset button.

Finding Images to Convert to Autostereograms

As mentioned earlier, you can find 3D images to convert on the internet using search terms like "grayscale depth map" or "3d depth map". Remember that these images need to be scaled to 264x176 pixels, so simple images without detail work best. Text is usually not a good choice unless you are converting large block lettering. You can also create images from 2 color bitmaps or even create a grayscale image using a paint program. Images must be saved as either 2 color or grayscale BMP files. Create a 3D image by creating a grayscale image, black being the background and using white for the closest object. A black to white gradient can be used to create a floor, or ocean waves as shown here:

And here is the image converted to an autostereogram:

This guide was first published on Aug 21, 2019. It was last updated on Aug 21, 2019. This page (Creating an Autostereogram) was last updated on Feb 07, 2020.