NAME

tuple2color - convert a list of tuples into colors using Color::TupleEncode encoding and optionally generate a bit map of color patches.

SYNOPSIS

The default Color::TupleEncode::Baran encoding implementation is used.

Generate a report of colors to STDOUT.

  # report values, do not generate an image
  tuple2color 

  # specify range of matrix values (default is min=0, max=1, step=(max-min)/10)
  tuple2color -min 0 -max 1 -step 0.1

  # you can overwrite one or more matrix settings
  tuple2color -step 0.2

  # instead of using an automatically generated matrix, 
  # specify input data (tuples)
  tuple2color -data matrix_data.txt

  # specify how matrix entries should be sorted (default no sort)
  tuple2color -data matrix_data.txt -sortby a,b,c
  tuple2color -data matrix_data.txt -sortby b,c,a
  tuple2color -data matrix_data.txt -sortby c,a,b

  # specify implementation
  tuple2color -data matrix_data.txt -method Color::TupleEncode::Baran

  # specify options for Color::Threeway
  draw_color_char ... -options "-saturation=>{dmin=>0,dmax=>1}"

In addition, generate a PNG image of values and corresponding encoded colors.

  # draw color patch matrix using default settings
  tuple2color -draw

  # make color patches circles (default is "compound", a circle with a
  # rectangular background)
  tuple2color ... -glyph compound|circle|rectangle

  # specify output image size
  tuple2color ... -width 500 -height 500

  # specify output file
  tuple2color ... -outfile somematrix.png

DESCRIPTION

Draws color patches for a list of tuples values using the color encoding of Color::TupleEncode.

INPUT DATA OPTIONS

-min 0, -max 1, -step 0.25

If -data is not used (see below), a list of input values is automatically generated within the range min..max. Each component in the tuple is sampled at a rate of -step.

By default, (min,max) = (0,1) and step = (max-min)/10. You can override one or more of these settings. For example,

  -min 0.5 -step 0.1

will result (min,max,step) = (0.5,1,0.1)

-data matrix_data.txt

Defines the file containing the list of tuples (space separated)

  1.0 0.5 0.2
  1.0 0.2 0.0
  0.0 0.1 0.5
  ...

It's assumed that the values will be in the range [0,1]. If not, you need to adjust any ecoding parameters that are sensitive to absolute values (see below).

If -data is not used, then a matrix of values is automatically generated (see min/max/step, above).

Make sure that the number of components in the tuple match the required number in the implementation. For example, Color::TupleEncode::Baran requires three values.

COLOR ENCODING OPTIONS

-options "-ha=0,-hb=>120,-hc=>240">

-options "-saturation={dmin=>0,dmax=>1}">

-options "-ha=20,-hb=>60,-hc=>100,-saturation=>{dmin=>0,dmax=>1}">

Specify options for the color encoding engine. All encodings require that the characteristic hues of each input variable are set. These correspond to options -ha, -hb, and -hc and are by default 0, 120 and 240, respectively.

The options are passed as a string that evalutes to a hash. Options must be compatible with the -method chosen for the encoding.

If no options are defined and the encoding method is Color::TupleEncode::Baran, then the following options are automatically set

  -saturation=>{dmin=>0,dmax=>1};

Make sure that all of the options are supported by the encoding implementation.

-method Color::TupleEncode::Baran

Specifies the encoding implementation. By default, it is the method by Baran et al. If no options are passed, then the following are also set by default

  -saturation=>{dmin=>0,dmax=>1};

For more details about the default, see Color::TupleEncode::Baran.

REPORTING OPTIONS

-sortby "a,b,c"

Specify the order of tuple components to sort the matrix entries by. By default it is a,b,c.

DRAWING OPTIONS

-draw

If you want to create a PNG image of the color swatches, use -draw.

-glyph compound|circle|rectangle

Determines the shape of the color patch. -glyph compound produces a circular patch inset in a slightly darker rectangle.

-width 500 -height 500

Specify the width and height of the output image. No attempt is made to automatically fit the color patches within the image. Therefore, choose a canvas size that accomodates all values.

-outputfile myfile.png

Specify the output image file. If not defined, color_chart.png is used.

EXAMPLES

The charts produced by these examples are included in examples/color-chart-*.png.

A large 2-tuple encoding chart with [a,b] in the range [0,2] sampling every 0.15.

  ./tuple2color -method "Color::TupleEncode::2Way"  \
                -min 0 -max 2 -step 0.15            \
                -outfile color-chart-2way.png       \
                -width 600 -height 1360             \
                -draw

A small 2-tuple encoding chart with [a,b] in the range [0,2] sampling every 0.3.

  ./tuple2color -method "Color::TupleEncode::2Way"  \
                -min 0 -max 2   -step 0.3           \
                -outfile color-chart-2way-small.png \
                -width 600 -height 430              \
                -draw

A large 3-tuple encoding chart with [a,b,c] in the range [0,1] sampling every 0.2.

  ./tuple2color -step 0.2                           \
                -outfile color-chart-3way.png       \
                -width 650 -height 1450             \
                -draw

A large 2-tuple encoding chart with [a,b,c] in the range [0,1] sampling every 1/3.

  ./tuple2color -step 0.33333333333                 \
                -outfile color-chart-3way-small.png \
                -width 650 -height 450              \
                -draw

HISTORY

• 11 March 2010

  First version.

BUGS

Please report any bugs or feature requests to bug-color-tupleencode at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Color-TupleEncode. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

AUTHOR

Martin Krzywinski, <martin.krzywinski at gmail.com>

cpanm Color::TupleEncode

perl -MCPAN -e shell
install Color::TupleEncode