deepx

README

DeepX

Add a new dimension to your pixels!

About

As a child, I really loved looking at stereograms from various magazines and newspapers. I eagerly searched for them in every publication. As an adult, I realized that now I can create them myself. I hope you too are amazed at how easily the human eye can be fooled.

The implementation of the algorithm is based on a scientific publication of Harold W. Thimbleby (University of Stirling), Stuart Inglis and Ian H. Witten (University of Waikato).

Quick Start

Make sure you have the latest version of the golang compiler installed.

Currently, the creation of stereograms is supported only based on other images (i.e. masks)

Prepare your mask image. For example:

The mask image will be interpreted as monochrome, regardless of the actual number of colors encoded in that image. All pixels in the mask image that have a zero alpha channel (transparent) will be ignored (by default), and the remaining pixels will be included in the final mask image.

You can specify your own color, which should be considered transparent for each specific mask.

Create a new .go file and import deepX package. Write a piece of code that will load the mask image and convert it into a stereogram:

package main

import (
	"fmt"
	"image/png"
	"os"

	"github.com/MonkeyBuisness/deepx"
)

func main() {
	// INFO: load mask image.
	mask, err := os.OpenFile("mask.png", os.O_RDONLY, os.ModePerm)
	if err != nil {
		panic(fmt.Errorf("could not load mask: %v", err))
	}
	defer mask.Close()

	// INFO: generate stereogram.
	stereogramImg, err := deepx.NewStereogramFromMask(mask,
		// INFO: set a custom palette colors.
		deepx.WithColorPalette(
			deepx.MustColorFromHex("#6ad6e3"),
			deepx.MustColorFromHex("#000000"),
		),

		// INFO: increase the default DPI to avoid stereogram artifacts.
		deepx.WithOutputDPI(144),

		// INFO: the mask has a #6ad6e3 color as a background, select it as transparent.
		deepx.WithMaskTransparentColor(deepx.MustColorFromHex("#ffffff")),
	)
	if err != nil {
		panic(fmt.Errorf("could not generate stereogram image: %v", err))
	}

	// INFO: save the image with gererated stereogram.
	out, err := os.OpenFile("result.png", os.O_CREATE|os.O_WRONLY, os.ModePerm)
	if err != nil {
		panic(fmt.Errorf("could not open file to write stereogram: %v", err))
	}
	defer out.Close()
	if err := png.Encode(out, stereogramImg); err != nil {
		panic(fmt.Errorf("could not encode stereogram into png image: %v", err))
	}
}

The library code is documented, so refer to it for additional functionality.

Run your program:

$ go run main.go

Result:

You can find more examples here.

General Tips

To achieve better generation result:

• Try not to use very large or very small images as masks
• If possible, convert the image to PNG format to explicitly indicate transparency
• Avoid images with a lot of detail or color
• If, after generating a stereogram, there are artifacts in the image, experiment with the values for the DPI parameter. Make it larger or smaller and see what results it produces
• Use contrasting colors (such as white and black) for the final palette, and don't use colors with low intensity

Documentation

Index

• func NewStereogramFromMask(maskSrc io.Reader, opts ...StereogramOption) (*image.RGBA, error)
• type Color
  • func ColorFromHex(hex string) (*Color, error)
  • func ColorRGBA(c color.Color) Color
  • func MustColorFromHex(hex string) Color
  • func (c Color) Equal(other Color) bool
  • func (c Color) Hex() string
  • func (c Color) RGBA() color.RGBA
• type StereogramConfig
• type StereogramOption
  • func WithColorPalette(palette ...Color) StereogramOption
  • func WithEyeSepartionRatio(ratio float64) StereogramOption
  • func WithMaskTransparentColor(color Color) StereogramOption
  • func WithOutputDPI(dpi int) StereogramOption

Functions

func NewStereogramFromMask

func NewStereogramFromMask(maskSrc io.Reader, opts ...StereogramOption) (*image.RGBA, error)

NewStereogramFromMask creates a new "Random-Dot Stereogram" image from the provided mask source using the algorithm of Harold W. Thimbleby, Stuart Inglis and Ian H: https://www2.cs.sfu.ca/CourseCentral/414/li/material/refs/SIRDS-Computer-94.pdf

The mask source must contain an encoded valid png, jpeg or gif image data. The mask image will be interpreted as monochrome, regardless of the actual number of colors encoded in that image. All pixels in the mask image that have a zero alpha channel (transparent) will be ignored (by default), and the remaining pixels will be included in the final mask image. To explicitly specify the color that should be perceived as transparent in the mask image, specify a `WithMaskTransparentColor(...)` in the list of options.

A list of options can be provided to specify additional stereogram processing settings.

Types

type Color

type Color color.RGBA

Color represents color type.

func ColorFromHex

func ColorFromHex(hex string) (*Color, error)

ColorFromHex converts hex color string (#RRGGBBAA) into color model.

func ColorRGBA

func ColorRGBA(c color.Color) Color

ColorRGBA converts built-in color.Color model into Color representation.

func MustColorFromHex

func MustColorFromHex(hex string) Color

MustColorFromHex converts hex color string (#RRGGBBAA) into color model.

It panics if the provided hes string is not a valid hexidecimal encoded color.

func (Color) Equal

func (c Color) Equal(other Color) bool

Equal compares two color models.

func (Color) Hex

func (c Color) Hex() string

Hex returns color representation in hex format: #RRGGBBAA.

func (Color) RGBA

func (c Color) RGBA() color.RGBA

RGBA returns color in native RGBA format.

type StereogramConfig

type StereogramConfig struct {

	// Contains the color of the mask image pixels that should be considered transparent.
	//
	// If not specifed, every pixel in a mask image that has a zero alpha channel
	// will be considered transparent.
	MaskTransparentColor *Color

	// Represents a list of colors used to create pixels in a stereogram image.
	//
	// It's recommended to specify at least 2 different colors so that
	// the final stereogram image is colored (if you specify one color, the final image
	// will always be monotonously filled with this color, which doesn't make sense 0_o).
	// Each color presented will be randomly selected to form a unique pixel
	// in the stereogram image.
	//
	// If the list of colors is not specified (by defaul), then a randomization algorithm
	// will be applied when forming each individual pixel color.
	Palette []Color

	// Depth of field (fraction of viewing distance).
	//
	// Equal to 1/3 by default.
	Mu float64

	// Output stereogram image DPI.
	//
	// By defualt has 72 pixels per inch.
	DPI int

	// Eye separation ratio.
	//
	// Eye separation is assumed to be 2.5 * DPI in by default.
	ERatio float64
}

StereogramConfig represents a stereogram image processing configuration model.

type StereogramOption

type StereogramOption func(*StereogramConfig)

StereogramOption represents type for stereogram image processing option.

func WithColorPalette

func WithColorPalette(palette ...Color) StereogramOption

WithColorPalette sets the list of colors used to create pixels in a stereogram image.

By default, this list is empty and therefore the colors of each pixel will be selected randomly.

func WithEyeSepartionRatio

func WithEyeSepartionRatio(ratio float64) StereogramOption

WithEyeSepartionRatio sets the eye separtion ratio.

2.5 by default.

func WithMaskTransparentColor

func WithMaskTransparentColor(color Color) StereogramOption

WithMaskTransparentColor sets the color that must be transparent for the mask source image.

By default, every pixel in a mask image that has a zero alpha channel will be considered transparent.

func WithOutputDPI

func WithOutputDPI(dpi int) StereogramOption

WithOutputDPI sets the DPI of the stegeogram image.

72 by default.