Colour maps in Antiprism
OFF elements can be coloured with index numbers (integers) as well
as colour values (displayable colours). Colour maps provide a way to convert
these index numbers into colour values.
The primary documentation for colour maps can be viewed by running
off_util -H col_map. This displays the map formats supported
by Antiprism, a list of the colour maps provided with Antiprism, and the
parameters that can be used to specify and modify internal colour maps.
A colour map contains entries that map a colour index number to a colour
value (a colour specified by red/green/blue/alpha values) or to another
index number. A colour map might not include an entry for every
index number.
If a sequence of colour maps is being used for lookup, then each map
is used in turn for lookup. Lookup starts with the input colour index,
which becomes the current index, then the map index modifiers (general map
parameters, see below) are applied before lookup. The lookup result is:
- a colour value, and this is returned as the final lookup result
- a colour index, and this is used for lookup in the next map, or is returned as the final lookup result if there are no further maps
- no entry found, and the current index is used for lookup in the next map, or is returned as the final lookup result if there are no further maps
Note that, if any map index modifiers are specified for a map then they only
modify the lookup index for this particular map. If no mapping is found
then lookup continues with the next map using the unmodified current
index (or this is the final lookup result if there are no further maps).
As a consequences of this processing, index-to-index maps can
be used to modify future maps during sequential lookup. Antiprism
includes several internal index-to-index maps
that can be used in this way (e.g. index, reverse, deal).
The range map is a color map that sequentially transitions
between colours. It is an internal map, generated by Antiprism, rather
than a file. The map name can include specific parameters, to
specify the colours used in the transition, and general parameters, which
are the map size and the map index modifiers, applicable to many of the internal
maps.
The range map default has size 256 and transitions between all hues
col_util -d 3 -m range -Z 256 | antiview
The range map accepts a map size, which immediatedly follows
the name, set here to 128 entries
col_util -d 3 -m range128 -Z 256 | antiview
Specific parameters for range come after any map size parameter,
if supplied, and are introduced by an underscore, _. To
transition from red to magenta, specify these two hues. Examples
with the default map size of 256, and with a specified map size of 128
col_util -d 3 -m range_H1.0:0.8 -Z 256 | antiview
col_util -d 3 -m range128_H1.0:0.8 -Z 256 | antiview
After a name, and an optional map size, and an optional underscore followed
by specific parameters, some map index modifier parameters may be specified.
The general parameters can be any of + followed by a shift number,
* followed by a step number,
% optionally followed by a wrap size. If more than one of these
map index modifiers is specified then they must be specified in the order
shift before step before wrap, The following commands domnstrate the
valid parameter order
col_util -d 3 -m range+5 -Z 256 | antiview
col_util -d 3 -m range*4 -Z 256 | antiview
col_util -d 3 -m range%16 -Z 256 | antiview
col_util -d 3 -m range+5*4 -Z 256 | antiview
col_util -d 3 -m range+5%16 -Z 256 | antiview
col_util -d 3 -m range*4%16 -Z 256 | antiview
col_util -d 3 -m range+5*4%16 -Z 256 | antiview
col_util -d 3 -m range128_H1.0:0.4+5*4%16 -Z 256 | antiview
A map may be modified by modifying the index number that is used for
lookup. The modifiers are all optional, but must appear in the order:
shift before step before wrap. If all three modifiers are specied,
the form would therefore be
map_name+shift*step%wrap
Any index, idx, is modified before lookup as follows
- wrap is 0: lookup index is shift + idx*step
- wrap is not 0: lookup index is (shift + idx*step) % wrap [where % is modulo]
-
The defaults are shift=0, step=1, wrap=0. If a bare % is given then the
the wrap value will be the largest index number in the map, plus one.
Negative parameters can be specified for shift and step, but note that
the shift parameter always starts with a +, and so a shift
of -1 is specified as +-1.
If a wrap is specified without a value (a bare %), then the wrap
value used will be the largest index number in the map plus one.
The modifiers act on the lookup index rather than the map entries. If the
intention is to model a map with transformed entries, then specify "opposite"
modifiers. For example, to shift all the map entries 15 entries forward is
the same as a lookup that steps 15 entries back. However, if the map size
is finite then the entries outside of it will be lost. The lost entries
could be wrapped to the start (effectively rotating the entries in the
colour map) using a separate map that modifies the lookup from 0 to start
at map_size-16
col_util -d 3 -m range128 -Z 256 | antiview
col_util -d 3 -m range128+-15 -Z 256 | antiview
col_util -d 3 -m range128+-15,range128+113 -Z 256 | antiview
A map's entries can be overriden by index-to-value maps, and manipulated by
index-to-index maps.
Examples reversing a map. Show the map, reverse using the index
map, reverse using the reverse map (note that the map size must
be specified)
col_util -d 3 -m range32 -Z 256 | antiview
col_util -d 3 -m index+31*-1,range32 -Z 256 | antiview
col_util -d 3 -m reverse32,range32 -Z 256 | antiview
Example randomising a map. Show the map, randomise it.
col_util -d 3 -m range32 -Z 256 | antiview
col_util -d 3 -m deal32,range32 -Z 256 | antiview
Example rotating entries in a map. Show the map, rotate entries three entries
forward and combine with rotating entries 29 entries back
col_util -d 3 -m range32 -Z 256 | antiview
col_util -d 3 -m range32+-3,range32+29 -Z 256 | antiview
Example wrapping a combined map. Show a combined map that rotates map
entries, then wrap at its size by wrapping the index number first.
col_util -d 3 -m range32+-3,range32+29 -Z 256 | antiview
col_util -d 3 -m index%32,range32+-3,range32+29 -Z 256 | antiview
Example of appending maps. Show a greyscale map of size 32,
append a range map of size 16, then further append a greyscale
map of size 8. The indexmap is used to shift back higher
index numbers before the next map is used for lookup.
col_util -d 3 -m grey32 -Z 256 | antiview
col_util -d 3 -m grey32,index+-32,range16 -Z 256 | antiview
col_util -d 3 -m grey32,index+-32,range16,index+-16,grey8 -Z 256 | antiview
Example of appending a reversed copy of the map (creates a smoothly
wrapping map when the base map changes smoothly but doesn't naturally
wrap). Show a map, append a copy in order, append a copy reversed.
The reversal uses the reverse map such that the second half
indexes of the double-sized map are mapped into the first half in
reverse order.
col_util -d 3 -m range32_H0.5:1.0 -Z 256 | antiview
col_util -d 3 -m range32_H0.5:1.0,index+-32,range32_H0.5:1.0 -Z 256 | antiview
col_util -d 3 -m range32_H0.5:1.0,reverse64,range32_H0.5:1.0 -Z 256 | antiview
Example overriding some specific entries in a map. Show a map. Specify
a colour map with the override mappings, in this example the map
map with black for index 4 (the fifth entry) and white entry for index 7,
and use it for lookup first
col_util -d 3 -m range32 -Z 256 | antiview
col_util -d 3 -m map_4=black:7=white,range32 -Z 256 | antiview
Show only some faces of a model. Make a map that colours the desired
face index numbers, and colour remaining index numbers invisible.
Show one face of small stellated dodecahedon, show square faces of
a cuboctahedron
off_color sm_st_dod -f U -m map_1=red,map_invisible% | antiview
off_color cubo -f N -m map_4=red,map_invisible% | antiview
Next:
Using edges in Antiprism
Up:
Programs and Documentation
|