Antiprism Up Next

Colour maps in Antiprism

Colour maps    |    Entry lookup    |    Parameters example    |    Map index modifiers    |    Combining maps    |    Examples

Colour Maps

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.

Map Entry Types and Sequential Lookup

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).

Example of Specific Parameters and Map Index Modifiers

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

Map Index Modifiers

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


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

Combining Maps

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

Home   |   Programs   |   Examples   |   Album   |   Download   |   Development   |   Forum   |   About

Contact:      -      Modified 14.6.2024