path: root/doc/picture-language.texi

\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