The Pan# User Manual
top | back | next
5
Reference
Since the Pan# language is for the most part a subset of Haskell we
will describe Pan# mainly in comparison to Haskell. Many of the
functional graphics operators available in Pan# are implemented in
the Pan# Prelude, found in the bin directory of the
installation. Looking at the function definitions in the Prelude is
probably the best way to understand many of these functions.
5
.1 Types
The best way to describe Pan functions is the type
language. The following base types are built in:
- numbers, denoted by the type Number,
- booleans (true / false), denoted by Boolean,
- colors, denoted by the type Color, and
- character strings, denoted by the type String.
- rasters (2-D arrays of colors), denoted by the type Raster,
- arrays of numbers, denoted by the type Arr,
The only data structure available to the user is the tuple. Composite
values such as points, vectors, or matrices are all built using
tuples.
Functions types are
represented by -> as in Haskell. A function that has two
arguments, a number
and a boolean, and returns a string, would have the following type:
f :: Number -> Boolean -> String
The type of an object of type t that exists within a
frame of reference is Framed t. Some functions take arguments
which may or may not be framed; the MFramed a type denotes an
object of type a which might be in a frame.
The following type definitions are used to simplify type signatures:
type Integer = Number
type Fraction = Number
type Angle = Number
type Point2 = (Number, Number)
type Vector2 = (Number, Number)
type Point3 = (Number, Number, Number)
type Vector3 = (Number, Number, Number)
type Image a = Point -> a
type ImageC = Image Color
type SizedImage a = (Number, Number, Image a)
type SizedImageC = (Number, Number, ImageC)
type Region = Image Boolean
type Filter a = Image a -> Image a
type Interval = (Number, Number)
type BoundingBox = (Interval, Interval)
type Transform = Image Point2
type Font = String
type Prec = Number -- precision
type FWidth = Number -- Field width
type Label = String
type Timing = Arr Number
A type name such as Integer is used to give the user a hint that
a numeric value ought to be an integer but type inference will not
guarantee that a value declared to be Integer is in fact an
integer an not some other sort of number.
As in Haskell, type synonyms are interchangeable with their
definitions. The type declaration is the only way to extend the
type language in Pan#: there is no data declaration. The
type declarations must appear at the top of a module.
5
.2 Expression and Definition Syntax
An expression is one of the following:
- A variable or constant. Variables start with an alphabetic
character and many contain any number of alphanumerics or the
_ character. Constants are either numbers in decimal or
exponential notation or strings. Unlike Haskell, numeric constants
may start with ".". Strings are enclosed in double quotes and a
backslash can be used to escape double quotes and backslashes within
a string. Tab
and newline are represented by \t and \n,
respectively. An operator can be converted into an ordinary
variable by wrapping it in parenthesis.
- A function application. A function is applied in
prefix form, as in f x, or in infix form, as in x+y.
An identifier can be used as an infix operator using back-quotes (as
in Haskell). Thus x `over` y is the same as
over x y. There is currently no way to define new operators
or to assign a precedence other than 9 (left associative) to an
identifier coerced into an operator.
- A tuple of expressions enclosed in parenthesis and separated by
commas.
- A pair of expressions enclosed in parenthesis and separated by
@ (point in polar coordinates).
- An if -- then -- else expression.
- A let expression in which all inner declarations start in
the same column.
The operator precedence is listed from highest to lowest:
- . (function composition)
- ^ (exponentiation)
- *, /
- +, -
- ++ (string concatenation)
- ==, /=, ==, >, >=, <, <=
- .&. (bitwise and), .&&. (boolean and)
- .|. (bitwise or), .||. (boolean or)
- $ (infix function application)
Declarations are in the form p = e or p <- e,
where e is an expression and p is a pattern. The
following patterns are provided:
- A variable: matches anything and binds the variable to the value matched.
- _: matches anything but does not bind a variable.
- A tuple of patterns (same syntax as tuple expressions): matches a tuple
of the same length and binds corresponding patterns.
- ( r @ t ): matches a 2-tuple of
numbers, matching r to the magnitude and t to the angle (in
radians) of the point.
- A function name (identifier) followed by function argument patterns.
A function may be defined using guards, as in Haskell.
Unlike Haskell, functions cannot be defined by more than one clause.
Thus instead of
f 0 = a
f x = b
you must define f using an if statement or guards.
5
.3 Modules
A module packages a set of definitions for import into other Pan#
programs. The Pan# module system is very simple; there is no selective
or qualified import and every definition in a module is exported.
There is no module keyword at the start of a file.
Modules must be located in either the Pan binary directory (created
on installation) or the directory containing the program being
compiled. If a program contains
import M
then the file M.pan must be in one of these directories.
An imported module cannot contain any connection definitions
(definitions using <-) at the top level; these are only allowed
in the main module.
The module Prelude is imported implicitly by every Pan
module.
5
.4 Boolean Functions
true, false :: Boolean
(||), (&&) :: Boolean -> Boolean -> Boolean
not :: Boolean -> Boolean
otherwise :: Boolean
otherwise = true
5
.5 Numeric Functions
Pan# does not distinguish between integers and reals. Functions
which range over integers round their inputs. For example,
even 2.2 is true and not an error. We will, however,
distinguish integers in the type signatures below.
(+), (-), (*), (/) :: Number -> Number -> Number
negate, recip :: Number -> Number
truncate, round :: Number -> Integer
ceiling, floor :: Number -> Integer
frac :: Number -> Fraction
mod :: Integer -> Integer -> Integer
gcd, lcm :: Integer -> Integer -> Integer
min, max :: Number -> Number -> Number
abs, signum :: Number -> Number
(==), (/=) :: Number -> Number -> Boolean
(>), (<), (<=), (>=) :: Number -> Number -> Boolean
even, odd :: Number -> Boolean
pi :: Number
exp, log, sqrt :: Number -> Number
sin, cos, tan :: Number -> Number
(**), logBase, atan2 :: Number -> Number -> Number
-- ^ is the same as ** except that the second argument is an integer
(^) :: Number -> Integer -> Number
(.&.), (.|.) :: Integer -> Integer -> Integer -- bitwise and/or
-- Linear interpolation between numbers
lerpN :: Number -> Number -> Number -> Number
5
.6 Colors
The behavior of these functions when applied to invalid fractional
arguments (arguments outside the 0 to 1 range) is unspecified. The
fraction argument to fadeC, lightenC, and darkenC ranges from 0
(preserve input color) to 1 (interpolate to white / black /
transparent).
red, orange, green, yellow :: Color
blue, white, black, invisible :: Color
cyan, pink, magenta :: Color
darkRed, lightRed, darkGreen :: Color
lightGreen, darkCyan, lightYellow :: Color
gold, lightGold, darkBlue :: Color
lightBlue, brown, darkBrown :: Color
lightBrown :: Color
grey :: Number -> Color
overC :: Color -> Color -> Color
fadeC, lightenC, darkenC :: Fraction -> Color -> Color
lerpC :: Number -> Color -> Color -> Color
rgb :: Fraction -> Fraction -> Fraction -> Color
hsv :: Angle -> Fraction -> Fraction -> Color
withinC :: Number -> Color -> Color -> Bool
colorR, colorG, colorB, colorA :: Color -> Fraction
negC :: Color -> Color
5
.7 Strings
Pan# has a very limited string handling capability. Numbers can be
converted string form using
the C# format language; this allows an image to include text
containing numeric values. A number of functions are provided to hide
the details of the format language; these use the "W" suffix
to indicate that a field width is specified.
(++) :: String -> String -> String
format :: String -> Number -> String -- C# formats
showNumber :: Number -> String
showFixed :: Prex -> Number -> String
showFixedW :: FWidth -> Prec -> Number -> String
showExp :: Prec -> Number -> String
showExpW :: FWidth -> Prex -> Number -> String
5
.8 Rasters
A raster is used to convert strings to image form. Most users will
never need to use rasters. These functions allow the user to choose
either a fast "square pixel" conversion or a slower bi-linear
interpolation when converting to continuous images. For convenience,
the stringImage functions avoid exposing the intermediate raster.
image.
rasterizeFont :: Font -> Number -> String -> Raster
rasterize :: String -> Raster
rasterToSizedImage :: Raster -> SizedImage Color
stringImage :: String -> SizedImage Color
stringImageFont :: Font -> Number -> String -> SizedImage Color
rasterWidth :: Raster -> Number
rasterHeight :: Raster -> Number
rasterToImage :: Raster -> ImageC -- square pixels
rasterToImageB :: Raster -> ImageC -- bilinear interpolation
5
.9 Functions
Many of these functions are taken from the Haskell Prelude. The
lifting functions are described in Elliott's Fun of Programming
chapter.
-- Infix function application
($) :: (a -> b) -> a -> b
(.) :: (b -> c) -> (a -> b) -> a -> c
fst :: (a,b) -> a
snd :: (a,b) -> b
curry :: ((a,b) -> c) -> (a -> b -> c)
uncurry :: (a -> b -> c) -> ((a,b) -> c)
id :: a -> a
const :: a -> (b -> a)
-- Same as ``if''
cond :: Bool -> a -> a -> a
-- same as ``const''
lift0 :: a -> (b -> a)
lift :: (a -> b) -> (c -> a) -> (c -> b)
lift2 :: (a -> b -> c) -> (d -> a) -> (d -> b) -> (d -> c)
lift3 :: (a -> b -> c -> d) -> (e -> a) ->
(e -> b) -> (e -> c) -> (e -> d)
5
.10 Operations on 1-D numeric functions
Many other 1-D numerics are defined in the textures library.
-- translate the domain
translateF :: Number -> (Number -> Number) -> (Number -> Number)
-- scale both the range and domain
uscaleF :: Number -> (Number -> Number) -> (Number -> Number)
-- just scale the domain
scaleF :: Number -> (Number -> Number) -> (Number -> Number)
-- Scaled frac function
sfrac :: Number -> Number -> Number
5
.11 2D Points
Use fst and snd to access the components of a 2-D point.
rotateP :: Number -> Transform
translateP, scaleP :: Vector -> Transform
uscaleP :: FloatE -> Transform
distP :: Point2 -> Point2 -> Number
lerpP :: Number -> Point2 -> Point2 -> Point2
-- Map over the x/y coordinate or both
mapx :: (a -> b) -> (a,c) -> (b,c)
mapy :: (a -> b) -> (c,a) -> (c,b)
mapxy :: (a -> b) -> (a,a) -> (b,b)
-- For polar coordinates
mapr :: (a -> b) -> Point2 -> Point2
-- Names for the components of a polar point
norm :: Point2 -> Number
angle :: Point2 -> Number
5
.12 Sized Image Placement
These functions translate and scale a rectangular image, moving either
the center to lower left corner to a specified point and uniformly
scaling by a given amount or to produce a specified height or width.
-- L: point is lower left corner
-- C: point is center
-- H: Size is height
-- W: Size is width
-- Z: Size is zoomIn factor
placeImageLW :: Point2 -> Number -> SizedImage a -> Image a
placeImageCW :: Point2 -> Number -> SizedImage a -> Image a
placeImageLH :: Point2 -> Number -> SizedImage a -> Image a
placeImageCH :: Point2 -> Number -> SizedImage a -> Image a
placeImageLZ :: Point2 -> Number -> SizedImage a -> Image a
placeImageCZ :: Point2 -> Number -> SizedImage a -> Image a
5
.13 Generic Images
These functions can be applied to images of any sort (color images,
regions, intensity regions).
-- Transform an image
imXf :: Transform -> Image a -> Image a
condI :: Image Bool -> Image a -> Image a -> Image a
translate, scale :: Vector2 -> Filter a
rotate, uscale :: Number -> Filter a
5
.14 Color Images
invisibleI :: ImageC
whiteI, blackI, redI, greenI :: ImageC
blueI, orangeI, yellowI :: ImageC
overI :: ImageC -> ImageC -> ImageC
-- See through the white parts of an image
seeThrough :: ImageC -> ImageC
5
.15 Regions
rectangle :: Point2 -> Point2 -> Region
circle :: Point2 -> Number -> Region
stripes :: Number -> Number -> Number -> Boolean
vstripes :: Number -> Number -> Region
checkerboard :: Region
intersectR, unionR :: Region -> Region -> Region
xorR, diffR :: Region -> Region -> Region
complementR :: Region -> Region
universeR, emptyR :: Region
colorRegion :: Color -> Region -> ImageC
colorRegion2 :: Color -> Color -> Region -> ImageC
crop :: Region -> ImageC -> ImageC
5
.16 Interaction
These functions allow the user to interact with the image through
either a control attached to the view window or mouse
movement in view window. All interactive devices must created within
a frame of reference. Functions with the "D" suffix take a default
image file name as the second argument.
slider :: Label -> Interval -> Number -> Framed Number
islider :: Label -> Interval -> Number -> Framed Integer
timer :: Label -> Number -> Boolean -> Framed Number
tick :: Label -> Bool -> Framed Bool
displaySize :: Framed (Number, Number)
mouse :: Framed Point2
movablePoint :: Label -> Point2 -> Number -> Framed (Point2, Boolean)
localBounds, viewBounds :: Framed BoundingBox
image :: String -> Framed ImageC
imageD :: String -> String -> Framed ImageC
sizedImageD :: Label -> String -> Framed SizedImageC
sizedImage :: Label -> Framed SizedImageC
imageRaster :: Label -> String -> Framed Raster
centeredImageD :: Label -> String -> ImageC
centeredImage :: Label -> ImageC
textBox :: Label -> Framed ImageC
sizedTextbox :: Label -> String -> Framed SizedImageC
5
.17 Random Numbers
A random number supply interpolates a fixed-sized set of random
numbers between 0 and 1 into a total 1-D or 2-D function. The randoms2 function
resembles image except that image contains numbers instead of
colors. Menu commands
in the viewer allow the user to change the random numbers to produce a
different image.
randoms :: Number -> Framed (Number -> Number)
randoms2 :: (Number, Number) -> Framed (Point2 -> Number)
5
.18 Timing Tracks
A timing track is a sequence of real-valued events. Tracks are
created by the Haskore computer music system and are used to create
animations that synchronize to music. A track is a series of events,
each associated with a numeric value. Think of a timing track as a rhythm and the
values in the track as note characteristics such as pitch or
dynamic. The findEvent function returns the most recent event
value, the elapsed time since the event, and the length of time
between this and the next event. If there are no more events, -1 is
returned as the event duration.
getTiming :: String -> Timing
findEvent :: Timing -> Number -> (Number, Number, Number)
-- returns time since last event, event value, event duration
5
.19 Frames
A frame defines a local coordinate system and allows new controls to be
added to the system.
-- Fit a region of the coordinate place into the view window
-- fit uses uniform scaling, fills the viewframe completely
fit, fitStretch :: (Point2, Point2) -> MFramed (Image a) -> Framed (Image a)
-- Return the size of a screen pixel in user coordinates
xPixelSize, yPixelSize :: Framed Number
-- Scale the coordinate system in the current frame
zoomIn, zoomOut :: Number -> MFramed (Image a) -> Framed (Image a)
-- Pan the current frame
translateFrame :: Vector2 -> MFramed (Image a) -> Framed (Image a)
-- Translate a given point to the center / lowerleft
recenter :: Point2 -> MFramed (Image a) -> Framed (Image a)
lowerLeft :: Point2 -> MFramed (Image a) -> Framed (Image a)
-- Functions to split the frame
above, below :: Framed Image -> Framed Image -> Framed Image
above3, below3 :: Framed Image -> Framed Image -> Framed Image
-> Framed Image
beside :: MFramed (Image a) -> MFramed (Image a) -> Framed (Image a)
beside3 :: MFramed (Image a) -> MFramed (Image a) -> MFramed (Image a)
-> Framed Image
-- Split the frame in the X direction, centering subframes
partitionXC :: Fraction -> Framed Image -> Framed Image -> Framed Image
-- Split the frame in the X direction, preserving X coordinate
-- at the left of the frame
partitionXL :: Fraction -> Framed Image -> Framed Image -> Framed Image
-- Split evenly into 2 / 3 frames
-- Split the frame in the Y direction, centering subframes
partitionYC :: Fraction -> Framed Image -> Framed Image -> Framed Image
-- Split the frame in the Y direction, preserving the Y coordinate
-- at the bottom of the frame.
partitionYL :: Fraction -> Framed Image -> Framed Image -> Framed Image
-- Overlay two frames using ``overC''
overF :: MFramed ImageC -> MFramed ImageC -> Framed ImageC
-- Draw a grid in the current frame.
-- grid color lineWidth distanceBetweenLines
grid :: Color -> Number -> Number -> Framed Image
-- Utilities used in coordinate transformation
-- Translate a place in the first interval into the second one
translatePoint :: BoundingBox -> BoundingBox -> Point2 -> Point2
translateInterval :: Interval -> Interval -> Number -> Number
5
.20 Display Functions
These functions are used to convert various types into images. They
are used to display "picture" for various types.
displayRegion :: MFramed Region -> Framed ImageC
displayGrey :: MFramed (Image Number) -> Framed ImageC
displayImageC :: MFramed ImageC -> Framed ImageC
displayColor :: MFramed Color -> Framed ImageC
displayString :: MFramed String -> Framed ImageC
displayNumber :: MFramed Number -> Framed ImageC
displayPoint2 :: MFramed Point2 -> Framed ImageC
displayPoint3 :: MFramed Point3 -> Framed ImageC
displayTransform :: MFramed Transform -> Framed ImageC
displaySizedImageC :: MFramed SizedImageC -> Framed ImageC
displayBoolean :: MFramed Boolean -> Framed ImageC
5
.21 Misc Utilities
-- Used to hilight a selected point on the image
showSelected :: Boolean -> Point2 -> Number -> ImageC
-- creates a region that follows a function. This is not a true line
-- since the width is not constant
strokeFunction :: (Number -> Number) -> Number -> Region
-- This makes it easy to overlay text on an image - it takes care
-- of font sizing and placement. Line numbers are positive from the bottom
-- or negative from the top.
labelLine :: Number -> String -> Framed ImageC
The Pan# User Manual
top | back | next |
March, 2004