# Tiny Autostereogram Construction Kit ## Overview There was a buzz created in the 1990s when the series of "Magic Eye" books were first published. These books displayed 3D images on plain paper without the need of any special head gear like red-green, Polaroid or LCD shutter glasses. These 3D images could be seen with the naked eye. The secret was the use of a horizontal repeating series of dots with a slight variation in the repeating series to give the illusion of depth in the 2D image. These images have been called a few names, including autostereograms, single image random dot stereograms (SIRDS), and single image stereograms (SIS). We will call them autostereograms in this learning guide. With the Tiny Autostereogram Construction Kit (or TACK for short), you can create your own autostereograms using CircuitPython and an Adafruit Metro M4 Express and an Adafruit ePaper shield. It creates these 3D images from black and white or grayscale BMP images and display them on an Adafruit ePaper shield. You can even save them to a file and post them on social media. They are small enough be displayed on a smart phone and still retain the 3D effect. This project will require you to create and copy files onto the Metro M4 Express device. You will also need the help of a paint program that can resize images and save them to either 2 color or grayscale BMP files.  ## Parts Building this project requires no soldering and uses just two parts: the Adafruit Metro M4 Express and the Adafruit 2.7" Tri-Color eInk / ePaper Shield with SRAM.  Either the Metro M4 or Metro M4 Airlift Express can be used. If you are interested in ePaper displays for other projects, check out the entire line of [Adafruit's ePaper displays](https://www.adafruit.com/category/150). If you like this no solder project, you may also like the [ePaper Maze Maker](https://learn.adafruit.com/epaper-maze-maker), the [eInk / ePaper Weather Station](https://learn.adafruit.com/epaper-weather-station), and the [ePaper Calendar](https://learn.adafruit.com/epaper-calendar-featuring-metro-m4-express-airlift-and-epaper-shield) projects, which use the same components as this project: the ePaper shield and either the Metro M4 Express or Metro M4 Express Airlift light board. Since this project does not require a WiFi connection either Metro M4 Express board will work. ## Parts Featured ### Adafruit 2.7" Tri-Color eInk / ePaper Shield with SRAM [Adafruit 2.7" Tri-Color eInk / ePaper Shield with SRAM](https://www.adafruit.com/product/4229) Easy e-paper finally comes to microcontrollers, with this breakout that's designed to make it a breeze to add a tri-color eInk display. Chances are you've seen one of those new-fangled 'e-readers' like the Kindle or Nook. They have gigantic electronic paper 'static'... Out of Stock [Buy Now](https://www.adafruit.com/product/4229) [Related Guides to the Product](https://learn.adafruit.com/products/4229/guides) ![Top down view of a Adafruit 2.7" Tri-Color eInk / ePaper Shield with SRAM - Red Black White. ](https://cdn-shop.adafruit.com/640x480/4229-05.jpg) Featured ### Adafruit Metro M4 feat. Microchip ATSAMD51 [Adafruit Metro M4 feat. Microchip ATSAMD51](https://www.adafruit.com/product/3382) Are you ready? Really ready? Cause here comes the fastest, most powerful Metro ever. The **Adafruit Metro M4** featuring the **Microchip ATSAMD51**. This Metro is like a bullet train, with its 120MHz Cortex M4 with floating point support. Your code will zig and zag... In Stock [Buy Now](https://www.adafruit.com/product/3382) [Related Guides to the Product](https://learn.adafruit.com/products/3382/guides) ![Angled shot of a Adafruit Metro M4 feat. Microchip ATSAMD51. ](https://cdn-shop.adafruit.com/640x480/3382-13.jpg) Featured ### Adafruit Metro M4 Express AirLift (WiFi) - Lite [Adafruit Metro M4 Express AirLift (WiFi) - Lite](https://www.adafruit.com/product/4000) Give your next project a lift with _AirLift_ - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the  **Adafruit Metro M4**  featuring the  **Microchip ATSAMD51** , with it's 120MHz Cortex M4 with... In Stock [Buy Now](https://www.adafruit.com/product/4000) [Related Guides to the Product](https://learn.adafruit.com/products/4000/guides) ![Adafruit Metro M4 Airlift Lite dev board with SAMD51 an ESP32 Wifi Co-processor.](https://cdn-shop.adafruit.com/640x480/4000-08.jpg) Featured ### USB cable - USB A to Micro-B [USB cable - USB A to Micro-B](https://www.adafruit.com/product/592) This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller Approximately 3 feet / 1 meter long In Stock [Buy Now](https://www.adafruit.com/product/592) [Related Guides to the Product](https://learn.adafruit.com/products/592/guides) ![USB cable - USB A to Micro-B - 3 foot long](https://cdn-shop.adafruit.com/640x480/592-01.jpg) # Tiny Autostereogram Construction Kit ## How to View an Autostereogram Viewing an autostereogram can be difficult at first and some people simply can not see the 3D effect. However, once you can see your first image then other 3D images will be easier to see. The key is to focus your eyes beyond the screen. One technique is to use a flashlight (or flashlight app) and shine it on the screen displaying the autostereogram. Focus on the light beyond the plane of the display instead of the display itself. Slowly move the light towards the screen and hopefully your eyes will be converge to a plane beyond the screen and see the 3D effect. Here is an image to try out that was created from the TACK. ![](https://cdn-learn.adafruit.com/assets/assets/000/079/318/medium800/circuitpython_shark792.bmp?1565660253 What image to you see? (Hint: cue the John Williams music)) # Tiny Autostereogram Construction Kit ## How It Works Autostereograms trick the eye by using a repeating horizontal series of random dots. Because of the repeating nature of the autostereogram, you can not only focus on the dots directly but also on one of the other repeating series. What makes it cool is that the series of random dots can be shifted slightly to simulate depth. This is similar to how a ViewMaster and other stereo photo viewers work, where a slight difference in images can simulate an object as being closer or further away. A computer is required to generate an autostereogram since each dot must be calculated. With our ePaper display, that means there are over 46,000 dots, or pixels that must be calculated. The animation below shows how the pixels move when creating an autostereogram of a square. The repeating series is shifted to make it appear the square is in front of the background. It is also interesting to note that although the moving pixels are on the right side of the image, the 3D image is centered since the stationary pixels are combined with the moved pixels to create the 3D image. ![](https://cdn-learn.adafruit.com/assets/assets/000/079/391/medium800/circuitpython_asgsquare.gif?1565728535) You can find a more detailed explanation on how autostereograms work and their history from [this Wikipedia page](https://en.wikipedia.org/wiki/Autostereogram). # Tiny Autostereogram Construction Kit ## Installing the Code Download the project files from the [GitHub repo](https://github.com/adafruit/Adafruit_Learning_System_Guides/tree/master/EInk_Autostereograms) linked to the green button below. [Project files on GitHub](https://github.com/adafruit/Adafruit_Learning_System_Guides/tree/master/EInk_Autostereograms) In any of the code boxes below you can get all the files in one step by clicking "Download: Zip". In addition to the **code.py** file, this project also requires several supporting folders and files. Create these folders, if you do not have them: - **asgfiles** - **backgrounds** - **images** - **jobs** You will also need to copy the background files, sample jobs and images, and the **config.json** and **boot.py** files from the Github repository.  The **config.json** file is used to define which jobs to run and folders to use. Here is the **config.json** that comes with the project: https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/EInk_Autostereograms/config.json The **boot.py** file allows the project to create autostereogram BMP files and write to the CircuitPython file system by pressing a button at boot time. Normally, CircuitPython can not write to the file system since the host operating system has that access by default. Using this boot file and pressing a button during the boot process reverses this access, giving CircuitPython read/write access and read only access to the host operating system. Rebooting without a button press reverts back CircuitPython's access to read only. You can see which boot mode you are currently using by looking at the boot\_out file on the file system. When you press a button during the boot process you will be able to create BMP files and the boot\_out file will include this line: > CircuitPython has write access to drive Here is the **boot.py** code: https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/EInk_Autostereograms/boot.py The code.py contains the code to create the autostereograms as well as display them on the ePaper shield and save them to a BMP file. https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/EInk_Autostereograms/code.py # Tiny Autostereogram Construction Kit ## 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: ```auto { "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. ![](https://cdn-learn.adafruit.com/assets/assets/000/079/320/medium800/circuitpython_shark.jpg?1565664666 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. ![](https://cdn-learn.adafruit.com/assets/assets/000/079/319/medium800/circuitpython_adafruit792.bmp?1565662008 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: ```auto { "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: ![](https://cdn-learn.adafruit.com/assets/assets/000/079/393/medium800/circuitpython_sailboat.bmp?1565729644) And here is the image converted to an autostereogram: ![](https://cdn-learn.adafruit.com/assets/assets/000/079/392/medium800/circuitpython_asgsailboat.bmp?1565729408) ## Guide Products ### Adafruit 2.7" Tri-Color eInk / ePaper Shield with SRAM [Adafruit 2.7" Tri-Color eInk / ePaper Shield with SRAM](https://www.adafruit.com/product/4229) Easy e-paper finally comes to microcontrollers, with this breakout that's designed to make it a breeze to add a tri-color eInk display. Chances are you've seen one of those new-fangled 'e-readers' like the Kindle or Nook. They have gigantic electronic paper 'static'... Out of Stock [Buy Now](https://www.adafruit.com/product/4229) [Related Guides to the Product](https://learn.adafruit.com/products/4229/guides) ### Adafruit Metro M4 feat. Microchip ATSAMD51 [Adafruit Metro M4 feat. Microchip ATSAMD51](https://www.adafruit.com/product/3382) Are you ready? Really ready? Cause here comes the fastest, most powerful Metro ever. The **Adafruit Metro M4** featuring the **Microchip ATSAMD51**. This Metro is like a bullet train, with its 120MHz Cortex M4 with floating point support. Your code will zig and zag... In Stock [Buy Now](https://www.adafruit.com/product/3382) [Related Guides to the Product](https://learn.adafruit.com/products/3382/guides) ### Adafruit Metro M4 Express AirLift (WiFi) - Lite [Adafruit Metro M4 Express AirLift (WiFi) - Lite](https://www.adafruit.com/product/4000) Give your next project a lift with _AirLift_ - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the  **Adafruit Metro M4**  featuring the  **Microchip ATSAMD51** , with it's 120MHz Cortex M4 with... In Stock [Buy Now](https://www.adafruit.com/product/4000) [Related Guides to the Product](https://learn.adafruit.com/products/4000/guides) ### USB cable - USB A to Micro-B [USB cable - USB A to Micro-B](https://www.adafruit.com/product/592) This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller Approximately 3 feet / 1 meter long In Stock [Buy Now](https://www.adafruit.com/product/592) [Related Guides to the Product](https://learn.adafruit.com/products/592/guides) ## Related Guides - [Adafruit Metro M4 Express featuring ATSAMD51](https://learn.adafruit.com/adafruit-metro-m4-express-featuring-atsamd51.md) - [Adafruit Metro M4 Express AirLift (WiFi)](https://learn.adafruit.com/adafruit-metro-m4-express-airlift-wifi.md) - [Adafruit 2.7" eInk Display Breakouts and Shields](https://learn.adafruit.com/adafruit-2-7-eink-display-breakouts-and-shields.md) - [CLUE Sensor Plotter in CircuitPython](https://learn.adafruit.com/clue-sensor-plotter-circuitpython.md) - [Controlling a Classic Nintendo R.O.B. Robot Using Circuit Playground Express](https://learn.adafruit.com/controlling-a-classic-nintendo-r-o-b-robot-using-circuit-playground-express.md) - [Chinese Dragon Puppet with Motion-Reactive Flame Effect](https://learn.adafruit.com/chinese-dragon-puppet-with-motion-reactive-flame-effect.md) - [A colorful CLUE slideshow purse with Bright Wearables](https://learn.adafruit.com/a-colorful-clue-slideshow-purse.md) - [Mouse and Keyboard Control Using TinyUSB and BLE](https://learn.adafruit.com/mouse-and-keyboard-control-using-tinyusb-and-ble.md) - [Adafruit IO Basics: Schedule Actions](https://learn.adafruit.com/adafruit-io-basics-scheduled-triggers.md) - [PyPortal NeoPixel Color Picker](https://learn.adafruit.com/pyportal-neopixel-color-picker.md) - [Paper Craft Zoetrope with Crickit](https://learn.adafruit.com/paper-craft-zoetrope-with-circuit-python.md) - [Crickit Dancing Marionette Kit](https://learn.adafruit.com/universal-marionette-with-crickit.md) - [Bluetooth LE Sensor Nodes to Raspberry Pi WiFi Bridge](https://learn.adafruit.com/bluetooth-le-broadcastnet-sensor-node-raspberry-pi-wifi-bridge.md) - [Quickstart using Adafruit eInk/ePaper displays with CircuitPython](https://learn.adafruit.com/quickstart-using-adafruit-eink-epaper-displays-with-circuitpython.md) - [Crickit Powered Maker Ice Cream Truck!](https://learn.adafruit.com/crickit-maker-ice-cream-truck.md) - [No-Solder LED Disco Tie with Bluetooth](https://learn.adafruit.com/no-solder-circuit-playground-bluetooth-disco-tie.md) - [CLUE Custom CircuitPython Badge](https://learn.adafruit.com/clue-custom-circuit-python-badge.md) - [Crickit Powered Mini Chair Swing Ride!](https://learn.adafruit.com/mini-chair-swing-ride.md)