.\" As its sole author, I explicitly place this file in the public domain. .\" It may be used by anyone in any way for any purpose, though I would .\" appreciate credit where it's due. .\" Mouse, mouse@rodents-montreal.org, 2015-08-03 .Dd August 03, 2015 .Dt PNMTARTAN 1 .Os NetBSD 1.4T .Sh NAME .Nm pnmtartan .Nd generate tartan patterns .Sh SYNOPSIS .Nm .Op options .Ar threading \&... .Sh DESCRIPTION .Nm generates images looking very much like Scottish tartans. .Pp The threading consists of multiple arguments (usually; it may be only one, but in that case the result is not very interesting). Normally, each argument consists of a thread count followed by a colour specification letter. However, the letter can be replaced by an RGB triple, delimited by slashes, possibly with an alpha value appended. A letter may also be followed by an equal sign and a similar colour spec, which causes that letter to refer to that colour thereafter. When the letter-and-equal-sign syntax is used, the thread count may be omitted or may be specified as 0, in which case it just defines the colour letter without adding any threads. .Pp Eight colour letters are predefined: .Bl -tag -compact -width indent .It K Black. .It R Red. .It G Green. .It Y Yellow. .It B Blue. .It M Magenta. .It C Cyan. .It W White. .El .Pp .Pp By default, a symmetric tartan is produced; in this case, the first and last thread specs are the pivots of the sett, with the specs in between repeated in reverse order after the second pivot to produce the full pattern. The .Fl asymm flag changes this, producing an asymmetric tartan. .Pp By default, the colour pattern is identical in the X and Y directions. However, this can be changed; if a single slash appears as an argument in the threading pattern, it separates the threading in the X direction (before the slash) from that in the Y direction (after). .Pp Different weave patterns are available. They all take the form of each thread going over N crossing threads, then under the next N threads, with the next thread following the same pattern shifted by one thread. If N is 1, this is a simple over/under checkerboard; larger N produce diagonal stripes. .Pp By default, the output contains one tile of the resulting tartan. That is, it is the smallest image that produce the correct result when tiled. This usually will be just one full sett (including the reflected sequence for a symmetric tartan), but, in unusual cases (mostly involving odd thread counts), it may be more than one copy because of the way the weave interacts with the sett's thread count. .Pp Various options may be specified: .Bl -tag -width indent .It Fl asymm Specifies an asymmetric tartan. For a symmetric tartan, the thread specs between the pivots (the first and last specs) are repeated in reverse order after the second pivot. For an asymmetric tartan, this is not done; the specified thread sequence is repeated as-is. (This flag applies in both dimensions. If the tartan is symmetric in one dimension and asymmetric in the other, .Fl asymm must be given and the symmetry in the symmetric direction implemented by explicitly repeating the relevant threadings in the argument list.) .It Fl weave Ar N Specifies the weave. The argument, .Ar N , specifies how many crossing threads each thread goes over, then under, in turn. The pattern is repeated, shifted by one warp thread per weft thread, leading to a diagonal pattern. If .Ar N is positive, the diagonals run from upper right to lower left; if negative, from upper left to lower right. If .Ar N is 1 or -1, a simple over/under checkerboard weave results. The default is 2. .It Fl size Ar X Y Specifies that the output image is to be .Ar X by .Ar Y pixels. If either argument is negative, the default output size is used in that dimension. .It Fl offset Ar X Y Offsets the resulting pattern by the specified number of pixels in each dimension. Conceptually, the output image is a rectangle extracted from an infinite area tiled with the tartan; this option is equivalent to offsetting the rectangle before doing the extraction. .It Fl maxval Ar N Sets the PPM maxval for the output file. By default, this is 255. This is relevant in two respects: (1) raw PPM output requires that this be no greater than 255 and (2) this is the limit on each primary in colour specs (values larger than the maxval will be limited to the maxval). The predefined colours always use the maxval for the relevant primaries; for example, if the maxval is 77, the predefined colour .Sq M is equivalent to .Sq \&/77/0/77 . .It Fl maxval2 Ar N Sets the PAM alpha maxval for the output file. By default, this is 255. If all colours are fully opaque (alpha is set to zero or not specified), the output file is PPM rather than PAM and this value is irrelevant. The predefined colours are opaque. .El .Sh BUGS When using different threadings in X and Y, there is no way to express one dimension in terms of small changes to the other; the identical portions must be repeated. .Pp Never generates a PGM or PBM file, even when it could. .Sh AUTHOR Mouse, .Aq mouse@rodents-montreal.org .