NAME
    Lego::From::PNG - Convert PNGs into plans to build a two dimensional
    lego replica.

SYNOPSIS
      use Lego::From::PNG;

      my $object = Lego::From::PNG;

      $object->brick_tally();

DESCRIPTION
    Convert a PNG into a block list and plans to build a two dimensional
    replica of the PNG. The plans are built with brick knobs pointed
    vertically so the picture will look like a flat surface to the viewer.
    Meaning the only dimension of the brick being determined is the length.
    Depth and height are all the same for all bricks.

    $hash->{'filename'} = $args{'filename'};

        $hash->{'unit_size'} = $args{'unit_size'} || 1;

        # Brick depth and height defaults
        $hash->{'brick_depth'} = 1;

        $hash->{'brick_height'} = 1;

        # White list default
        $hash->{'whitelist'} = ($args{'whitelist'} && ref($args{'whitelist'}) eq 'ARRAY' && scalar(@{$args{'whitelist'}}) > 0) ? $args{'whitelist'} : undef;

        # Black list default
        $hash->{'blacklist'} = ($args{'blacklist'} && ref($args{'blacklist'}) eq 'ARRAY' && scalar(@{$args{'blacklist'}}) > 0) ? $args{'blacklist'} : undef;

USAGE
  new
     Usage     : ->new()
     Purpose   : Returns Lego::From::PNG object

     Returns   : Lego::From::PNG object
     Argument  :
        filename - Optional. The file name of the PNG to process. Optional but if not provided, can't process the png.
            e.g. filename => '/location/of/the.png'

        unit_size - Optional. The size of pixels squared to determine a single unit of a brick. Defaults to 1.
            e.g. unit_size => 2 # pixelated colors are 2x2 in size

        brick_depth - Optional. The depth of all generated bricks. Defaults to 1.
            e.g. brick_depth => 2 # final depth of all bricks are 2. So 2 x length x height

        brick_height - Optional. The height of all generated bricks. Defaults to 1.
            e.g. brick_height => 2 # final height of all bricks are 2. So depth x length x 2

        whitelist - Optional. Array ref of colors, dimensions or color and dimensions that are allowed in the final plan output.
            e.g. whitelist => [ 'BLACK', 'WHITE', '1x1x1', '1x2x1', '1x4x1', 'BLACK_1x6x1' ]

        blacklist - Optional. Array ref of colors, dimensions or color and dimensions that are not allowed in the final plan output.
            e.g. blacklist => [ 'RED', '1x10x1', '1x12x1', '1x16x1', 'BLUE_1x8x1' ]

        knob_orientation - Optional. The facing direction of lego knobs, Either 'up' or 'forward'. This controls whether bricks are determined by depth and length ('forward') or lenght only ('up'). Defaults to 'forward'.
            e.g. knob_orientation => 'up'

     Throws    :

     Comment   :
     See Also  :

  lego_dimensions
     Usage     : ->lego_dimensions()
     Purpose   : returns a hashref with lego dimension information in millimeters (metric) or inches (imperial)

     Returns   : hashref with lego dimension information, millimeters is default
     Argument  : $type - if set to imperial then dimension information is returned in inches
     Throws    :

     Comment   :
     See Also  :

  lego_colors
     Usage     : ->lego_colors()
     Purpose   : returns lego color constants consolidated as a hash.

     Returns   : hashref with color constants keyed by the official color name in key form.
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  lego_bricks
     Usage     : ->lego_bricks()
     Purpose   : Returns a list of all possible lego bricks

     Returns   : Hash ref with L<Lego::From::PNG::Brick> objects keyed by their identifier
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  max_lego_brick_length
     Usage     : ->max_lego_brick_length()
     Purpose   : Returns a the max brick length we could build a brick with

     Returns   : highest brick length value
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  max_lego_brick_depth
     Usage     : ->max_lego_brick_depth()
     Purpose   : Returns a the max brick depth we could build a brick with

     Returns   : highest brick depth value
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  lego_knob_orientations
     Usage     : ->lego_knob_orientations()
     Purpose   : Returns a list of all possible lego knob orientations

     Returns   : Hash ref with L<Lego::From::PNG::Const> knob orientation values keyed by their identifier
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  knob_orientation
     Usage     : ->knob_orientation()
     Purpose   : Returns current knob orientation, defaults to LEGO_KNOB_ORIENTATION_FORWARD.

     Returns   : value of the current knob orientation (either 'up' or 'forward')
     Argument  :
     Throws    :

     Comment   : 'up' means knobs are pointed vertically. 'forward' means knobs are pointed towards the viewer.
     See Also  :

  validate_knob_orientation
     Usage     : ->validate_knob_orientation()
     Purpose   : Make sure a potential knob orientation value is valid

     Returns   : Returns 1 if passed value is a valid knob orientation, 0 otherwis
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  png
     Usage     : ->png()
     Purpose   : Returns Image::PNG::Libpng object.

     Returns   : Returns Image::PNG::Libpng object. See L<Image::PNG::Libpng> for more details.
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  png_info
     Usage     : ->png_info()
     Purpose   : Returns png IHDR info from the Image::PNG::Libpng object

     Returns   : A hash of values containing information abou the png such as width and height. See get_IHDR in L<Image::PNG::Libpng> for more details.
     Argument  : filename  => the PNG to load and part
                 unit_size => the pixel width and height of one unit, blocks are generally identified as Nx1 blocks where N is the number of units of the same color
     Throws    :

     Comment   :
     See Also  :

  block_row_length
     Usage     : ->block_row_length()
     Purpose   : Return the width of one row of blocks. Since a block list is a single dimension array this is useful to figure out whict row a block is on.

     Returns   : The length of a row of blocks (image width / unit size)
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  block_row_height
     Usage     : ->block_row_height()
     Purpose   : Return the height in blocks.

     Returns   : The height of a row of blocks (image height / unit size)
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  process
     Usage     : ->process()
     Purpose   : Convert a provided PNG into a list of lego blocks that will allow building of a two dimensional lego replica.

     Returns   : Hashref containing information about particular lego bricks found to be needed based on the provided PNG.
                 Also included is the build order for those bricks.
     Argument  : view => 'a view' - optionally format the return data. options include: JSON and HTML
     Throws    :

     Comment   :
     See Also  :

  whitelist
     Usage     : ->whitelist()
     Purpose   : return any whitelist settings stored in this object

     Returns   : an arrayref of whitelisted colors and/or blocks, or undef
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  has_whitelist
     Usage     : ->has_whitelist(), ->has_whitelist($filter)
     Purpose   : return a true value if there is a whitelist with at least one entry in it based on the allowed filters, otherwise a false value is returned

     Returns   : 1 or 0
     Argument  : $filter - optional scalar containing the filter to restrict test to
     Throws    :

     Comment   :
     See Also  :

  is_whitelisted
     Usage     : ->is_whitelisted($value), ->is_whitelisted($value, $filter)
     Purpose   : return a true if the value is whitelisted, otherwise false is returned

     Returns   : 1 or 0
     Argument  : $value - the value to test, $filter - optional scalar containing the filter to restrict test to
     Throws    :

     Comment   :
     See Also  :

  blacklist
     Usage     : ->blacklist
     Purpose   : return any blacklist settings stored in this object

     Returns   : an arrayref of blacklisted colors and/or blocks, or undef
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  has_blacklist
     Usage     : ->has_blacklist(), ->has_whitelist($filter)
     Purpose   : return a true value if there is a blacklist with at least one entry in it based on the allowed filters, otherwise a false value is returned

     Returns   : 1 or 0
     Argument  : $filter - optional scalar containing the filter to restrict test to
     Throws    :

     Comment   :
     See Also  :

  is_blacklisted
     Usage     : ->is_blacklisted($value), ->is_whitelisted($value, $filter)
     Purpose   : return a true if the value is blacklisted, otherwise false is returned

     Returns   : 1 or 0
     Argument  : $value - the value to test, $filter - optional scalar containing the filter to restrict test to
     Throws    :

     Comment   :
     See Also  :

  _png_blocks_of_color
     Usage     : ->_png_blocks_of_color()
     Purpose   : Convert a provided PNG into a list of rgb values based on [row][color]. Size of blocks are determined by 'unit_size'

     Returns   : A list of hashes contain r, g and b values. e.g. ( { r => #, g => #, b => # }, { ... }, ... )
     Argument  :
     Throws    :

     Comment   :
     See Also  :

     =head2  _color_score

     Usage     : ->_color_score()
     Purpose   : returns a score indicating the likeness of one color to another. The lower the number the closer the colors are to each other.

     Returns   : returns a positive integer score
     Argument  : $c1 - array ref with rgb color values in that order
                 $c2 - array ref with rgb color values in that order
     Throws    :

     Comment   :
     See Also  :

  _find_lego_color
     Usage     : ->_find_lego_color
     Purpose   : given an rgb params, finds the optimal lego color

     Returns   : A lego color common name key that can then reference lego color information using L<Lego::From::PNG::lego_colors>
     Argument  : $r - the red value of a color
                 $g - the green value of a color
                 $b - the blue value of a color
     Throws    :

     Comment   : this subroutine is memoized as the name _find_lego_color_fast
     See Also  :

  _approximate_lego_colors
     Usage     : ->_approximate_lego_colors()
     Purpose   : Generate a list of lego colors based on a list of blocks ( array of hashes containing rgb values )

     Returns   : A list of lego color common name keys that can then reference lego color information using L<Lego::From::PNG::lego_colors>
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  _generate_brick_list
     Usage     : ->_approximate_lego_colors()
     Purpose   : Generate a list of lego colors based on a list of blocks ( array of hashes containing rgb values ) for either knob orientation (calls _knob_forward_brick_list or _knob_up_brick_list)

     Returns   : A list of lego color common name keys that can then reference lego color information using L<Lego::From::PNG::lego_colors>
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  _knob_forward_brick_list
     Usage     : ->_knob_forward_brick_list()
     Purpose   : Generate a list of lego colors based on a list of blocks ( array of hashes containing rgb values ) for knob forward orientation

     Returns   : A list of lego color common name keys that can then reference lego color information using L<Lego::From::PNG::lego_colors>
     Argument  :
     Throws    :

     Comment   :
     See Also  :

     =head2 _knob_up_brick_list

     Usage     : ->_knob_up_brick_list()
     Purpose   : Generate a list of lego colors based on a list of blocks ( array of hashes containing rgb values ) for knob up orientation

     Returns   : A list of lego color common name keys that can then reference lego color information using L<Lego::From::PNG::lego_colors>
     Argument  :
     Throws    :

     Comment   :
     See Also  :

  _list_filters
     Usage     : ->_list_filters()
     Purpose   : return whitelist/blacklist filters

     Returns   : an hashref of filters
     Argument  : an optional filter restriction to limit set of filters returned to just one
     Throws    :

     Comment   :
     See Also  :

BUGS
SUPPORT
AUTHOR
        Travis Chase
        CPAN ID: GAUDEON
        gaudeon@cpan.org
        https://github.com/gaudeon/Lego-From-Png

COPYRIGHT
    This program is free software licensed under the...

        The MIT License

    The full text of the license can be found in the LICENSE file included
    with this module.

SEE ALSO
    perl(1).