diff options
Diffstat (limited to 'doc/picture-language.texi')
| -rw-r--r-- | doc/picture-language.texi | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/doc/picture-language.texi b/doc/picture-language.texi new file mode 100644 index 0000000..d4196f1 --- /dev/null +++ b/doc/picture-language.texi @@ -0,0 +1,357 @@ +\input texinfo +@c -*-texinfo-*- + +@c %**start of header +@setfilename picture-language.info +@documentencoding UTF-8 +@settitle Guile Picture Language Reference Manual +@c %**end of header + +@include version.texi + +@copying +Copyright @copyright{} 2019 Ricardo Wurmus@* + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled ``GNU Free +Documentation License''. +@end copying + +@dircategory The Algorithmic Language Scheme +@direntry +* Guile Picture Language: (picture-language). Compose pictures with Guile. +@end direntry + +@titlepage +@title Guile Picture Language Reference Manual +@subtitle Composing pictures with Guile +@author Ricardo Wurmus + +@page +@vskip 0pt plus 1filll +Edition @value{EDITION} @* +@value{UPDATED} @* + +@insertcopying +@end titlepage + +@contents + +@c ********************************************************************* +@node Top +@top Guile Picture Language + +This document describes the Guile Picture Language version +@value{VERSION}, a simple language to compose shapes and pictures using +vector graphics. + +@menu +* Introduction:: What is this all about? +* Installation:: Installing the picture language. +* A Picture Vocabulary:: Learning to speak the language. + +* Acknowledgments:: Thanks! +* GNU Free Documentation License:: The license of this manual. +* Concept Index:: Concepts. +* Programming Index:: Data types, functions, and variables. +@end menu + +@c ********************************************************************* +@node Introduction +@chapter Introduction + +This package provides a Guile library containing simple procedures to +generate primitive shapes, to manipulate them, and to compose them to +build complex pictures. While this library could be used to +procedurally generate images, it is really meant to be used +interactively. + +Pictures in this language are first class values like numbers or +strings, so they are displayed as actual pictures, not as text. We +suggest using Guile Studio to play with the picture language, as it +comes with everything you need to play with the picture language +interactively. You can jump straight to @xref{A Picture Vocabulary} and +follow along. + +If you aren't using Guile Studio you will probably want to use a +graphical instance of Emacs and set up Geiser for use with Guile. + + +@c ********************************************************************* +@node Installation +@chapter Installation + +The easiest way to install the Picture Language is through GNU Guix. + +@example +guix install guile-picture-language +@end example + +If you cannot use Guix or want to build it manually from a release +tarball, just unpack it and run the usual GNU build system commands: + +@example +./configure +make +make install +@end example + +If you want to build the sources from the source repository you need to +bootstrap the build system first. Run the @code{bootstrap.sh} script +first and then perform the above steps. + +Once installed you should make sure that the @code{GUILE_LOAD_PATH} +includes the directory containing this library. Start a Guile REPL with +Geiser and load up the module with @code{,use(pict)}. If everything +went well read on to learn how to use the picture language. + +If you're getting errors feel free to write email to the Guile user +mailing list @email{guile-user@@gnu.org}, or ask for help on the +@code{#guile} IRC channel on the Freenode network. + +@c ********************************************************************* +@node A Picture Vocabulary +@chapter A Picture Vocabulary + +The goal of the picture language is to allow you to interactively work +with pictures as you would with any other seemingly primitive data type, +such as numbers or strings of text. To compose numbers in an we use the +digits 0 to 9. Similarly, strings of text compose of a wide range of +characters enclosed in double quotes. What, then, are the building +blocks of pictures? + +One approach is to think of a picture as an arrangement of little +colored dots or pixels. Building pictures from dots, however, would be +rather tedious and dull. It would not be a very expressive language. +Another approach is to start with a small set of simple shapes that can +be modified and combined. Let's first take a look at the different +kinds of simple shapes that make up the ``nouns'' of our picture +language vocabulary. + +@menu +* Simple shapes:: The ``nouns'' of our picture language. +* Modifiers:: Procedures for modifying pictures. +* Combinators:: Build large pictures from smaller pictures. +@end menu + +@c ********************************************************************* +@node Simple shapes +@section Simple shapes + +@cindex line, simple shape +@deffn {Scheme Procedure} line @ + @var{x1} @var{y1} @var{x2} @var{y2} @ + [@var{maxw} @var{maxh} @ + #:color @var{"black"} #:stroke-width @var{1}] + +Return a straight line connecting the start point described by the +numbers @var{X1} and @var{Y1} and the end point described by the numbers +@var{X2} and @var{Y2}. Optionally, the numbers @var{MAXW} and +@var{MAXH} can be provided to limit the width or height, respectively, +of the resulting picture. The keys @var{COLOR} (a string) and +@var{STROKE-WIDTH} (a number) are accepted to override the line color +and line thickness, respectively. +@end deffn + +@cindex line, example +@example +@verbatiminclude images/line.svg.scm +@image{images/line.svg.scm,,,A straight line.} +@end example + + +@cindex hline, simple shape +@deffn {Scheme Procedure} hline @ + @var{w} @var{h} @ + [#:color @var{"black"} #:stroke-width @var{1}] + +Return a horizontal line segment of width @var{W}. The bounding box +height is @var{H} and the line is drawn in the vertical center of the +bounding box. The keys @var{COLOR} (a string) and @var{STROKE-WIDTH} (a +number) are accepted to override the line color and line thickness. +@end deffn + +@cindex hline, example +@example +@verbatiminclude images/hline.svg.scm +@image{images/hline.svg.scm,,,A horizontal line.} +@end example + + +@cindex vline, simple shape +@deffn {Scheme Procedure} vline @ + @var{w} @var{h} @ + [#:color @var{"black"} #:stroke-width @var{1}] + +Return a vertical line segment of height @var{H}. The bounding box +width is @var{W} and the line is drawn in the horizontal center of the +bounding box. The keys @var{COLOR} (a string) and @var{STROKE-WIDTH} (a +number) are accepted to override the line color and line thickness. +@end deffn + +@cindex vline, example +@example +@verbatiminclude images/vline.svg.scm +@image{images/vline.svg.scm,,,A vertical line.} +@end example + + +@cindex polyline, simple shape +@deffn {Scheme Procedure} polyline @ + @var{points} @ + [#:color @var{"black"} #:stroke-width @var{1}] + +A polyline is a multi-segment line that is drawn through any number of +points. This procedure draws a polyline from @var{POINTS}, a list of x +and y coordinate pairs. The keys @var{COLOR} (a string) and +@var{STROKE-WIDTH} (a number) are accepted to override the line color +and line thickness. +@end deffn + +@cindex polyline, example +Here is a simple zig zag line: +@example +@verbatiminclude images/polyline.svg.scm +@image{images/polyline.svg.scm,,,A zig zag polyline.} +@end example + +Of course, you could also compute the points. Here we use @code{iota} +and @code{list-tabulate} of the @code{(srfi srfi-1)} module to generate +a list for increasing X coordinates and a list for alternating Y +coordinates before merging them to a single list of coordinate pairs +with @code{map} and @code{cons}: + +@example +@verbatiminclude images/polyline2.svg.scm +@image{images/polyline2.svg.scm,,,A longer zig zag polyline.} +@end example + + +@cindex polygon, simple shape +@deffn {Scheme Procedure} polygon @ + @var{points} @ + [#:color @var{"black"} #:stroke-width @var{1}] + +The @code{polygon} procedure has almost the exact same behavior as +@code{polyline}, except that it connects the first point and the last +point with a line segment. @code{polyline}, on the other hand, leaves +the two points unconnected. + +This procedure draws a line through @var{POINTS}, a list of x and y +coordinate pairs, connecting the first and last points. The keys +@var{COLOR} (a string) and @var{STROKE-WIDTH} (a number) are accepted to +override the line color and line thickness. +@end deffn + +@cindex polygon, example +Here is a simple polygon: +@example +@verbatiminclude images/polygon.svg.scm +@image{images/polygon.svg.scm,,,A polygon.} +@end example + +There are more primitive shapes that still need to be documented: +@code{triangle}, @code{filled-triangle}, @code{octagon}, +@code{filled-octagon}, @code{circle}, @code{disk}, @code{ellipse}, +@code{filled-ellipse}, @code{rectangle}, @code{filled-rectangle}, and +@code{text}. + +@c ********************************************************************* +@node Modifiers +@section Modifiers + +Imagine you have a list of ten identical triangles: all with the same +size and the same color. Boring, isn't it? Perhaps it was easier to +produce them all alike. Perhaps it was done like this: + +@example +@verbatiminclude images/boring-triangles.svg.scm +@image{images/boring-triangles.svg.scm,,,A boring list of triangles.} +@end example + +Luckily, we have a wide range of modifiers to change the properties of +existing pictures, including the fill color, the border color, the +orientation, the transparency, and even the properties of the bounding +box. + +@cindex modifiers, example +Here's a preview of what we can do to the boring triangles: + +@example +@verbatiminclude images/modifiers.svg.scm +@image{images/modifiers.svg.scm,,,A less boring list of triangles.} +@end example + +Much better! + +The following modifiers exist and still need to be documented: +@code{fill}, @code{colorize}, @code{remove-outline}, @code{rotate}, +@code{scale}, @code{expand}, @code{grow}, @code{shrink}, @code{blur}, +@code{cellophane}, @code{frame}, and @code{ghost}. + +@c ********************************************************************* +@node Combinators +@section Combinators + +Now that we have learned about simple shapes we can generate lines and +shapes with different colors and dimensions, and with modifiers we can +scale them up or rotate them, but we still cannot compose complex +pictures that consist of more than just one shape. To compose and +arrange shapes we need combinators: procedures that operate on pictures +and return new pictures. + +Combinators cannot only be used on simple shapes but also on complex +pictures. This is what makes them very powerful. For example, we can +combine circles, lines, and ellipses to build a picture of a flower. We +can then take this picture of a flower, duplicate and scale it a hundred +times, and then combine these pictures to a new picture of a meadow. +This picture of a meadow can be duplicated, the duplicates tinted and +arranged as a pop art print. The picture of a pop art print can be +duplicated and arranged as a wall in an art gallery... + +The following combinators exist and still need to be documented: +@code{append-align}, @code{ht-append}, @code{hc-append}, +@code{hb-append}, @code{vl-append}, @code{vc-append}, @code{vr-append}, +@code{lt-superimpose}, @code{lc-superimpose}, @code{lb-superimpose}, +@code{ct-superimpose}, @code{cc-superimpose}, @code{cb-superimpose}, +@code{rt-superimpose}, @code{rc-superimpose}, @code{rb-superimpose}, +@code{pin-over}, and @code{pin-under}. + +@c ********************************************************************* +@node Acknowledgments +@chapter Acknowledgments + +Thanks to the following people who contributed to the Picture Language +through bug reports, patches, ideas, encouragement, or suggestions: + +@itemize @bullet +@item Ludovic Courtès @email{ludo@@gnu.org} +@item Christopher Lemmer Webber @email{cwebber@@dustycloud.org} +@end itemize + +Thank you. + +@c ********************************************************************* +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl-1.3.texi + +@page + +@c ********************************************************************* +@node Concept Index +@unnumbered Concept Index + +@printindex cp + +@node Programming Index +@unnumbered Programming Index +@syncodeindex tp fn +@syncodeindex vr fn +@printindex fn + +@bye |