Package net.paulhertz.pixelaudio

# Class PixelMapGen

java.lang.Object
net.paulhertz.pixelaudio.PixelMapGen

Direct Known Subclasses:
  `BoustropheGen`, `BuildFromPathGen`, `DiagonalZigzagGen`, `HilbertGen`, `MooreGen`, `MultiGen`, `RandomContinousGen`

public abstract class PixelMapGen extends Object

Abstract class for handling coordinates and LUT generation for PixelAudioMapper. PixelAudioMapper is designed to be independent of any specific mapping between its audio and pixel arrays. It uses PixelMapGen classes as plug-ins to obtain values for its LUTs. Keeping the LUT generation class outside PixelAudioMapper removes dependencies on the particular mapping.

The PixelAudioMapper class handles the combinatorial math for mapping between two arrays whose elements are in one-to-one correspondence but in different orders. PixelMapGen generates the mapping between the two arrays. PixelAudioMapper, as its name suggests, considers one array to be floating point audio samples and other to be RGBA integer pixel data, but of course the relationship is completely arbitrary as far as the mapping goes. The mapping was given its own class precisely because it is generalizable, though PixelMapGen does assume that the cardinality of its arrays can be factored by width and height.

The following short program shows the typical initialization of PixelAudio classes in Processing:

       import net.paulhertz.pixelaudio.*;

       PixelAudio pixelaudio;
       HilbertGen hGen;
       PixelAudioMapper mapper;
       PImage mapImage;
       int[] colors;

       public void setup() {
         size(512, 512);
         pixelaudio = new PixelAudio(this);
         hGen = new HilbertGen(width, height);
         mapper = new PixelAudioMapper(hGen);
         mapImage = createImage(width, height, RGB);
         mapImage.loadPixels();
         mapper.plantPixels(getColors(), mapImage.pixels, 0, 0, mapper.getSize());
         mapImage.updatePixels();
       }

       public int[] getColors() {
         int[] colorWheel = new int[mapper.getSize()];
         pushStyle();
         colorMode(HSB, colorWheel.length, 100, 100);
         int h = 0;
         for (int i = 0; i < colorWheel.length; i++) {
           colorWheel[i] = color(h, 66, 66);
           h++;
         }
         popStyle();
         return colorWheel;
       }

       public void draw() {
         image(mapImage, 0, 0);
       }

If you create your own PixelMapGen subclass, please follow the convention of generating the first coordinate at (0,0). This allows for consistent behavior when coordinates and LUTs undergo the transforms implemented in the BitmapTransform class.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `ArrayList<int[]>`
  `coords`
  the 2D coordinates of the signal path as it traverses the bitmap of dimensions width * height
  `static final String`
  `description`
  a String that summarizes the features of a PixelMapGen class
  `static AffineTransformType`
  `flipx`
  `static AffineTransformType`
  `flipy`
  `static AffineTransformType`
  `fx270`
  `static AffineTransformType`
  `fx90`
  `int`
  `h`
  height of the PixelMapGen in pixels, and by extension, height of images to which it is applied
  `static AffineTransformType`
  `nada`
  `int[]`
  `pixelMap`
  signalToImageLUT source for PixelAudioMapper, value at signal index returns index to pixel in bitmap
  `static AffineTransformType`
  `r180`
  `static AffineTransformType`
  `r270`
  `static AffineTransformType`
  `r90`
  `int[]`
  `sampleMap`
  imageToSignalLUT source for PixelAudioMapper, value at bitmap index returns index to sample in signal
  `int`
  `size`
  the total number of pixels or audio samples handled by the PixelMapGen, == width * height
  `static AffineTransformType[]`
  `transArray`
  `AffineTransformType`
  `transformType`
  an `AffineTransformType` applied to the coordinate pairs in `coords` prior to generating `pixelMap` and `sampleMap`
  `int`
  `w`
  width of the PixelMapGen in pixels, and by extension, width of images to which it is applied

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PixelMapGen(int width, int height)`
  Constructor for classes that extend PixelMapGen.
  `PixelMapGen(int width, int height, AffineTransformType type)`
  Constructor for classes that extend PixelMapGen.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract String`
  `describe()`
  `static int`
  `findNearestPowerOfTwoLessThan(int n)`
  `static int`
  `findPowerOfTwo(int n)`
  `abstract int[]`
  `generate()`
  Initialization method that sets `this.coords`, and then `this.pixelMap` and `this.sampleMap`: `this.coords` is a list of coordinate pairs representing the signal path, the (x,y) pixel locations along a path that visits every pixel in a bitmap exactly once.
  `ArrayList<int[]>`
  `getCoordinates()`
  `ArrayList<int[]>`
  `getCoordinatesCopy()`
  `int`
  `getHeight()`
  `static int[]`
  `getInversMapFromPixelArray(int[] pixelArr)`
  `int[]`
  `getPixelMap()`
  `int[]`
  `getPixelMapCopy()`
  `static int[]`
  `getPixelMapFromCoordinates(ArrayList<int[]> coordsList, int w)`
  `int[]`
  `getSampleMap()`
  `int[]`
  `getSampleMapCopy()`
  `int`
  `getSize()`
  `AffineTransformType`
  `getTransformType()`
  `int`
  `getWidth()`
  `static boolean`
  `isPowerOfTwo(int n)`
  `void`
  `loadIndexMaps()`
  Creates pixelMap and sampleMap from coords, which must already be initialized.
  `static AffineTransformType`
  `randomTransform(Random rand)`
  `int[]`
  `setMapsFromCoords(ArrayList<int[]> coordinates)`
  Sets `this.coords`, `this.pixelMap` and `this.sampleMap` instance variables from coordinates ArrayList argument.
  `void`
  `setTransformType(AffineTransformType transformType)`
  Sets the AffineTransformType associated with this PixelMapGen and transforms its coordinates and associated sampleMap and pixelMap fields.
  `void`
  `transformCoords(ArrayList<int[]> coordinates, AffineTransformType type)`
  `abstract boolean`
  `validate(int width, int height)`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### w

    public int w
    width of the PixelMapGen in pixels, and by extension, width of images to which it is applied

  - ### h

    public int h
    height of the PixelMapGen in pixels, and by extension, height of images to which it is applied

  - ### size

    public int size
    the total number of pixels or audio samples handled by the PixelMapGen, == width * height

  - ### pixelMap

    public int[] pixelMap
    signalToImageLUT source for PixelAudioMapper, value at signal index returns index to pixel in bitmap

  - ### sampleMap

    public int[] sampleMap
    imageToSignalLUT source for PixelAudioMapper, value at bitmap index returns index to sample in signal

  - ### coords

    public ArrayList<int[]> coords
    the 2D coordinates of the signal path as it traverses the bitmap of dimensions width * height

  - ### transformType

    public AffineTransformType transformType
    an `AffineTransformType` applied to the coordinate pairs in `coords` prior to generating `pixelMap` and `sampleMap`

  - ### description

    public static final String description
    a String that summarizes the features of a PixelMapGen class
    See Also:
      - Constant Field Values

  - ### r270

    public static AffineTransformType r270

  - ### r90

    public static AffineTransformType r90

  - ### r180

    public static AffineTransformType r180

  - ### flipx

    public static AffineTransformType flipx

  - ### fx270

    public static AffineTransformType fx270

  - ### fx90

    public static AffineTransformType fx90

  - ### flipy

    public static AffineTransformType flipy

  - ### nada

    public static AffineTransformType nada

  - ### transArray

    public static AffineTransformType[] transArray

- ## Constructor Details

  - ### PixelMapGen

    public PixelMapGen(int width, int height, AffineTransformType type)
    Constructor for classes that extend PixelMapGen. You will need to create you own constructor for your class, but it can just call super(width, height) if everything it does can be handled in your generate() method. Note that generate() should be called on the last line of your constructor, after any additional initializations or calculations required for your class. See `DiagonalZigzagGen` and `HilbertGen` for examples of how to organize and initialize your own `PixelMapGen` class.
    Parameters:
      `width` - width of the PixelMapGen in pixels
      `height` - height of the PixelMapGen in pixels
      `type` - an AffineTransformType to apply to the coordinates of the PixelMapGen prior to creating the index maps `pixelMap` and `sampleMap`

  - ### PixelMapGen

    public PixelMapGen(int width, int height)
    Constructor for classes that extend PixelMapGen. You will need to create you own constructor for your class, but it can just call super(width, height) if everything it does can be handled in your generate() method. Note that generate() should be called on the last line of your constructor, after any additional initializations or calculations required for your class. See `DiagonalZigzagGen` and `HilbertGen` for examples of how to organize and initialize your own `PixelMapGen` class.
    Parameters:
      `width` -
      `height` -

- ## Method Details

  - ### describe

    public abstract String describe()
    Returns:
      A String describing the mapping generated by your class and any initialization requirements.

  - ### validate

    public abstract boolean validate(int width, int height)
    Parameters:
      `width` -
      `height` -
    Returns:
      true if the width and height parameters are valid for creating a mapping with this generator, otherwise, false.

  - ### generate

    public abstract int[] generate()

    Initialization method that sets `this.coords`, and then `this.pixelMap` and `this.sampleMap`: `this.coords` is a list of coordinate pairs representing the signal path, the (x,y) pixel locations along a path that visits every pixel in a bitmap exactly once. Once you have created it, you can call `setMapsFromCoords()` to set `this.pixelMap` and `this.sampleMap` automatically.

    `generate()` must be called from your class, so that you can initialize any local variables before generating coordinates and LUTs. The best place to call it is typically on the last line of the constructor for your class, after calling super() on the first line and after initializing any local variables needed to generate your coordinates and LUTs. You must initialize `this.coords`, `this.pixelMap`, and `this.sampleMap` within generate(). See `DiagonalZigzagGen` or `HilbertGen` for sample code.

    Returns:
      this.pixelMap, the value for PixelAudioMapper.signalToImageLUT.

  - ### setMapsFromCoords

    public int[] setMapsFromCoords(ArrayList<int[]> coordinates)
    Sets `this.coords`, `this.pixelMap` and `this.sampleMap` instance variables from coordinates ArrayList argument. This method is provided as a convenience: all you have to do in a child class is set the coordinates of the signal path as it steps through a bitmap of dimensions this.w * this.h.
    Parameters:
      `coordinates` - a list of coordinate pairs representing the signal path, the (x,y) pixel locations along a path that visits every pixel in a bitmap exactly once. This should be created within your generate() method in your child class that extends PixelMapGen.
    Returns:
      the `pixelMap` value, which has already been set in this method and may be ignored

  - ### transformCoords

    public void transformCoords(ArrayList<int[]> coordinates, AffineTransformType type)
    Parameters:
      `coordinates` - an array of coordinate pairs
      `type` - the AffineTransformType to apply

  - ### loadIndexMaps

    public void loadIndexMaps()
    Creates pixelMap and sampleMap from coords, which must already be initialized.

  - ### getWidth

    public int getWidth()
    Returns:
      Width of the bitmap associated with this PixelMapGen.

  - ### getHeight

    public int getHeight()
    Returns:
      Height of the bitmap associated with this PixelMapGen.

  - ### getSize

    public int getSize()
    Returns:
      Size (width * height) of the bitmap associated with this PixelMapGen.

  - ### getPixelMap

    public int[] getPixelMap()
    Returns:
      pixelMap array, which steps through the signal and returns indexes to each pixel in the corresponding bitmap

  - ### getPixelMapCopy

    public int[] getPixelMapCopy()
    Returns:
      a copy of the pixelMap array

  - ### getSampleMap

    public int[] getSampleMap()
    Returns:
      the sampleMap array, which steps through the bitmap and returns indexes to each sample in the corresponding signal

  - ### getSampleMapCopy

    public int[] getSampleMapCopy()
    Returns:
      a copy of the sampleMap

  - ### getCoordinates

    public ArrayList<int[]> getCoordinates()
    Returns:
      `this.coords`, the array of coordinate pairs that mark a path (the "signal path") through every pixel in a bitmap. getCoordinatesCopy() is the preferred method for obtaining the coordinates.

  - ### getCoordinatesCopy

    public ArrayList<int[]> getCoordinatesCopy()
    Returns:
      a copy of `this.coords`

  - ### getTransformType

    public AffineTransformType getTransformType()
    Returns:
      the AffineTransformType associated with this PixelMapGen

  - ### setTransformType

    public void setTransformType(AffineTransformType transformType)
    Sets the AffineTransformType associated with this PixelMapGen and transforms its coordinates and associated sampleMap and pixelMap fields.
    Parameters:
      `transformType` - an AffineTransformType

  - ### isPowerOfTwo

    public static boolean isPowerOfTwo(int n)

  - ### findPowerOfTwo

    public static int findPowerOfTwo(int n)

  - ### findNearestPowerOfTwoLessThan

    public static int findNearestPowerOfTwoLessThan(int n)

  - ### getPixelMapFromCoordinates

    public static int[] getPixelMapFromCoordinates(ArrayList<int[]> coordsList, int w)
    Parameters:
      `coordsList` - a list of coordinate pairs representing the (x,y) pixel locations along a path that visits every pixel in a bitmap
      `w` - the width of the bitmap
    Returns:
      the bitmap index numbers of the coordinates

  - ### getInversMapFromPixelArray

    public static int[] getInversMapFromPixelArray(int[] pixelArr)

  - ### randomTransform

    public static AffineTransformType randomTransform(Random rand)