# (lispkit draw) Library `(lispkit draw)` provides an API for creating *drawings*. A drawing is defined in terms of a sequence of instructions for drawing *shapes* and *images*. Drawings can be composed and saved as a PDF. It is also possible to draw a drawing into a *bitmap* and save it in formats like PNG, JPG, or TIFF. A *bitmap* is a special *image* that is not based on vector graphics. Both drawings and shapes are based on a coordinate system whose zero point is in the upper left corner of a plane. The x and y axis extend to the right and down. Coordinates and dimensions are always expressed in terms of floating-point numbers. ## Drawings Drawings are mutable objects created via `make-drawing`. The functions listed in this section change the state of a drawing object and they persist drawing instructions defining the drawing. For most functions, the drawing is an optional argument. If it is not provided, the function applies to the drawing provided by the `current-drawing` parammeter object. **drawing-type-tag** Symbol representing the `drawing` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all drawing objects. **current-drawing** Defines the *current drawing*, which is used as a default by all functions for which the drawing argument is optional. If there is no current drawing, this parameter is set to `#f`. **(drawing? *****obj*****)** Returns `#t` if *obj* is a drawing. Otherwise, it returns `#f`. **(make-drawing)** Returns a new, empty drawing. A drawing consists of a sequence of drawing instructions and drawing state consisting of the following components: * Stroke color (set via `set-color`) * Fill color (set via `fill-color`) * Shadow (set via `set-shadow` and `remove-shadow`) * Transformation (add transformation via `enable-transformation` and remove via `disable-transformation`) **(copy-drawing *****drawing*****)** Returns a copy of the given *drawing*. **(clear-drawing *****drawing*****)** Clears the given *drawing*. **(set-color *****color*****)** \ \&#xNAN;**(set-color *****color drawing*****)** Sets the *stroke color* for the given drawing, or `current-drawing` if the drawing argument is not provided. **(set-fill-color *****color*****)** \ \&#xNAN;**(set-fill-color *****color drawing*****)** Sets the *fill color* for the given drawing, or `current-drawing` if the drawing argument is not provided. **(set-line-width *****width*****)** \ \&#xNAN;**(set-line-width *****width drawing*****)** Sets the default *stroke width* for the given drawing, or `current-drawing` if the drawing argument is not provided. **(set-shadow *****color size blur-radius*****)** \ \&#xNAN;**(set-shadow *****color size blur-radius drawing*****)** Defines a shadow for the given drawing, or `current-drawing` if the drawing argument is not provided. *color* is the color of the shade, *blur-radius* defines the radius for bluring the shadow. **(remove-shadow)** \ \&#xNAN;**(remove-shadow *****drawing*****)** Removes shadow for the subsequent drawing instructions of the given drawing, or `current-drawing` if the drawing argument is missing. **(enable-transformation *****tf*****)** \ \&#xNAN;**(enable-transformation *****tf drawing*****)** Enables the transformation *tf* for subsequent drawing instructions of the given drawing, or `current-drawing` if the drawing argument is missing. Each drawing maintains an active affine transformation for shifting, rotating, and scaling the coordinate systems of subsequent drawing instructions. **(disable-transformation *****tf*****)** \ \&#xNAN;**(disable-transformation *****tf drawing*****)** Disables the transformation *tf* for subsequent drawing instructions of the given drawing, or `current-drawing` if the drawing argument is missing. **(draw *****shape*****)** \ \&#xNAN;**(draw *****shape width*****)**\ \&#xNAN;**(draw *****shape width drawing*****)** Draws *shape* with a given stroke *width* into the drawing specified via *drawing* or parameter object `current-drawing` if *drawing* is not provided. The default for *width*, in case it is not provided, is set via *set-line-width*. The stroke is drawn in the current stroke color of the drawing. **(draw-dashed *****shape lengths phase*****)** \ \&#xNAN;**(draw-dashed *****shape lengths phase width*****)**\ \&#xNAN;**(draw-dashed *****shape lengths phase width drawing*****)** Draws *shape* with a dashed stroke of width *width* into the drawing specified via *drawing* or parameter object `current-drawing` if *drawing* is not provided. `1.0` is the default for *width* in case it is not provided. *lengths* specifies an alternating list of dash/space lengths. *phase* determines the start of the dash/space pattern. The dashed stroke is drawn in the current stroke color of the drawing. **(fill *****shape*****)** \ \&#xNAN;**(fill *****shape drawing*****)** Fills *shape* with the current *fill color* in the drawing specified via *drawing* or parameter object `current-drawing` if *drawing* is not provided. **(fill-gradient *****shape colors*****)** \ \&#xNAN;**(fill-gradient *****shape colors spec*****)**\ \&#xNAN;**(fill-gradient *****shape colors spec drawing*****)** Fills *shape* with a gradient in the drawing specified via argument *drawing* or parameter object `current-drawing` if *drawing* is not provided. The gradient is specified in terms of a list of *colors* and argument *spec*. *spec* can either be a number or a point. If *spec* is a number, this number determines an angle for a linear gradient. If *spec* is a point, it is the center of a radial gradient. **(draw-line *****start end*****)** \ \&#xNAN;**(draw-line *****start end drawing*****)** Draws a line between point *start* and point *end* in the drawing specified via argument *drawing* or parameter object `current-drawing`, if *drawing* is not provided. The line is drawn in the default *stroke width* and the current *stroke color*. **(draw-rect *****rect*****)** \ \&#xNAN;**(draw-rect *****rect drawing*****)** Draws a rectangular given by *rect* in the drawing specified via argument *drawing* or parameter object `current-drawing`, if *drawing* is not provided. The rectangular is drawn in the default *stroke width* and the current *stroke color*. **(fill-rect *****rect*****)** \ \&#xNAN;**(fill-rect *****rect drawing*****)** Fills a rectangular given by *rect* with the current *fill color* in the drawing specified via argument *drawing* or parameter object `current-drawing`, if *drawing* is not provided. **(draw-ellipse *****rect*****)** \ \&#xNAN;**(draw-ellipse *****rect drawing*****)** Draws an ellipse into the rectangular *rect* in the drawing specified via argument *drawing* or parameter object `current-drawing`, if *drawing* is not provided. The ellipse is drawn in the default *stroke width* and the current *stroke color*. **(fill-ellipse *****rect*****)** \ \&#xNAN;**(fill-ellipse *****rect drawing*****)** Fills an ellipse given by rectangular *rect* with the current *fill color* in the drawing specified via argument *drawing* or parameter object `current-drawing`, if *drawing* is not provided. **(draw-text *****str location font*****)** \ \&#xNAN;**(draw-text *****str location font color*****)**\ \&#xNAN;**(draw-text *****str location font color drawing*****)** Draws string *str* at *location* in the given font and color in the drawing specified by argument *drawing* or parameter object `current-drawing` if *drawing* is not provided. *location* is either the left, top-most point at which the string is drawn, or it is a rect specifying a bounding box. *color* specifies the text color. If it is not provided, the text is drawn in black. **(text-size *****str*****)** \ \&#xNAN;**(text-size *****str font*****)**\ \&#xNAN;**(text-size *****str font dimensions*****)** Returns a size object describing the width and height needed to draw string *str* using *font* in a space constrained by *dimensions*. *dimensions* is either a size object specifying the maximum width and height, or it is a number constraining the width only, assuming infinite hight. If *dimensions* is omitted, the maximum width and height is infinity. **(draw-styled-text *****txt location*****)** \ \&#xNAN;**(draw-styled-text *****txt location drawing*****)** Draws styled text *txt* at *location* in the drawing specified by argument *drawing* or parameter object `current-drawing` if *drawing* is not provided. *location* is either the left, top-most point at which the styled text is drawn, or it is a rect specifying a bounding box. **(styled-text-size *****txt*****)** \ \&#xNAN;**(styled-text-size *****txt dimensions*****)** Returns a size object describing the width and height needed to draw styled text *txt* in a space constrained by *dimensions*. *dimensions* is either a size object specifying the maximum width and height, or it is a number constraining the width only, assuming infinite hight. If *dimensions* is omitted, the maximum width and height is infinity. **(draw-html *****html location*****)** \ \&#xNAN;**(draw-html *****html location drawing*****)** Draws a string *html* containing HTML source code at *location* in the drawing specified by argument *drawing* or parameter object `current-drawing` if *drawing* is not provided. *location* is either the left, top-most point at which the HTML is drawn, or it is a rect specifying a bounding box. **(html-size *****html*****)** \ \&#xNAN;**(html-size *****html dimensions*****)** Returns a size object describing the width and height needed to render the HTML in string *html* in a space constrained by *dimensions*. *dimensions* is either a size object specifying the maximum width and height, or it is a number constraining the width only, assuming infinite hight. If *dimensions* is omitted, the maximum width and height is infinity. **(draw-image *****image location*****)** \ \&#xNAN;**(draw-image *****image location opacity*****)**\ \&#xNAN;**(draw-image *****image location opacity composition*****)**\ \&#xNAN;**(draw-image *****image location opacity composition drawing*****)** Draws image *image* at *location* with the given *opacity* and *composition* method. The image is drawn in the drawing specified by argument *drawing* or parameter object `current-drawing` if *drawing* is not provided. *location* is either the left, top-most point at which the image is drawn, or it is a rect specifying a bounding box for the image. *composition* is a floating-point number between 0.0 (= transparent) and 1.0 (= completely not transparent) with 1.0 being the default. *composition* refers to a symbol specifying a composition method. The following methods are supported (the source is the image, the destination is the drawing): * `clear`: Transparency everywhere. * `copy`: The source image (default). * `multiply`: The source color is multiplied by the destination color. * `overlay`: Source colors overlay the destination. * `source-over`: The source image wherever it is opaque, and the destination elsewhere. * `source-in`: The source image wherever both images are opaque, and transparent elsewhere. * `source-out`: The source image wherever it is opaque and the destination is transparent, and transparent elsewhere. * `source-atop`: The source image wherever both source and destination are opaque, the destination wherever it is opaque but the source image is transparent, and transparent elsewhere. * `destination-over`: The destination wherever it is opaque, and the source image elsewhere. * `destination-in`: The destination wherever both images are opaque, and transparent elsewhere. * `destination-out`: The destination wherever it is opaque and the source image is transparent, and transparent elsewhere. * `destination-atop`: The destination wherever both image and destination are opaque, the source image wherever it is opaque and the destination is transparent, and transparent elsehwere. **(draw-drawing *****other*****)** \ \&#xNAN;**(draw-drawing *****other drawing*****)** Draws drawing *other* into the drawing specified by argument *drawing* or parameter object `current-drawing` if *drawing* is not provided. This function can be used to compose drawings. **(clip-drawing *****other clippingshape*****)** \ \&#xNAN;**(clip-drawing *****other clippingshape drawing*****)** Draws drawing *other* into the drawing specified by argument *drawing* or parameter object `current-drawing` if *drawing* is not provided. This function clips the drawing using shape *clippingshape*; i.e. only parts within *clippingshape* are drawn. **(inline-drawing *****other*****)** \ \&#xNAN;**(inline-drawing *****other drawing*****)** Draws drawing *other* into the drawing specified by argument *drawing* or parameter object `current-drawing` if *drawing* is not provided. This function can be used to compose drawings in a way such that the drawing instructions from *other* are inlined into *drawing*. **(save-drawing *****path drawing size*****)** \ \&#xNAN;**(save-drawing *****path drawing size title*****)**\ \&#xNAN;**(save-drawing *****path drawing size title author*****)** Saves *drawing* into a PDF file at the given filepath *path*. *size* is a size specifying the width and height of the PDF page containing the drawing in points; i.e. the media box of the page is `(rect zero-point` *size*`)`. *title* and *author* are optional strings defining the title and author metadata for the generated PDF file. **(save-drawings *****path pages*****)** \ \&#xNAN;**(save-drawings *****path pages title*****)**\ \&#xNAN;**(save-drawings *****path pages title author*****)** Saves a list of pages into a PDF file at the given filepath *path*. A page is defined in terms of a list of two elements (*drawing* *size*), where *drawing* is a drawing for that page and *size* is a media box for the page. *title* and *author* are optional strings defining the title and author metadata for the generated PDF file. **(drawing *****body ...*****)** Creates a new empty drawing, binds parameter object `current-drawing` to it and executes the body statements in the dynamic scope of this binding. This special form returns the new drawing. **(with-drawing *****drawing body ...*****)** Binds parameter object `current-drawing` to *drawing* and executes the body statements in the dynamic scope of this binding. This special form returns the result of the last statement in the body. **(transform *****tf body ...*****)** This form is used in the context of drawing into `current-drawing`. It enables the transformation *tf*, executes the statements in the body and disables the transformation again. ## Shapes Shapes are mutable objects created via a number of constructors, including `make-shape`, `copy-shape`, `line`, `polygon`, `rectangular`, `circle`, `oval`, `arc`, and `glyphs`. Besides the constructors, functions like `move-to`, `line-to` and `curve-to` are used to extend a shape. For those functions, the affected shape is an optional argument. If it is not provided, the function applies to the shape defined by the `current-shape` parammeter object. **shape-type-tag** Symbol representing the `shape` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all shape objects. **current-shape** Defines the *current shape*, which is used as a default by all functions for which the shape argument is optional. If there is no current shape, this parameter is set to `#f`. **(shape? *****obj*****)** Returns `#t` if *obj* is a shape. Otherwise, it returns `#f`. **(make-shape)** \ \&#xNAN;**(make-shape *****prototype*****)**\ \&#xNAN;**(make-shape *****prototype freeze?*****)** Returns a new shape object. If argument *prototype* is provided, the new shape object will inherit from shape *prototype*; i.e. the new shape's definition will extend the definition of shape *prototype*. If *freeze?* is provided and set to true, if will create a copy of *prototype* and make the new shape inherit from the copy. In this case, the returned shape has no dependency on *prototype*, i.e. further changes to *prototype* are ignored. **(copy-shape *****shape*****)** Returns a copy of *shape*. **(line *****start end*****)** Retuns a new line shape. *start* and *end* are the start and end points of the line. **(polygon *****point ...*****)** Returns a new polygon shape. The polygon is defined in terms of a sequence of points. **(closed-polygon *****point ...*****)** Returns a new closed polygon shape. The polygon is defined in terms of a sequence of points and automatically closes by connecting the last point to the first. **(rectangle *****point size*****)** \ \&#xNAN;**(rectangle *****point size radius*****)**\ \&#xNAN;**(rectangle *****point size xradius yradius*****)** Returns a new rectangular shape. The rectangle is defined in terms of the left, topmost point and a *size* defining both width and height of the rectangle. The optional *radius*, *xradius* and *yradius* arguments are used to create a rounded rectangular whose rounded edges are defined in terms of an x and y-radius. If only one radius is provided, it defines both x and y-radius. **(circle *****point radius*****)** Returns a new circle shape. The circle is defined in terms of a center point and a radius. **(oval *****point size*****)** Returns a new oval shape. The oval is defined in terms of a rectangle whose left, topmost point is provided as argument *point*, and whose width and height are given via argument *size*. **(arc *****point radius start end*****)** \ \&#xNAN;**(arc *****point radius start end clockwise*****)** Returns a new arc shape. The arc is defined via the arguments *point*, *radius*, *start* , *end* and optionally *clockwise*. *point* is the starting point of the arc, *radius* defines the radius of the arc, *start* is a starting angle in radians, and *end* is the end angle in radians. *clockwise* is a boolean argument defining whether the arc is drawn clockwise or counter-clockwise. The default is `#t`. **(glyphs *****str point size font*****)** Returns a new "glyphs" shape. This is a shape defined by a string *str* rendered in the given size and font at a given point. *font* is a font object, *size* is the font size in points, and *point* are the start coordinates where the glyphs are drawn. **(move-shape *****shape dx*****)** \ \&#xNAN;**(move-shape *****shape dx dy*****)** Returns a new shape by translating *shape* by *dx* horizontally and *dy* vertically. If *dy* is not provided, the shape is moved by *dx* in both directions. **(scale-shape *****shape sx*****)** \ \&#xNAN;**(scale-shape *****shape sx sy*****)** Returns a new shape by scaling *shape* by factor *sx* horizontally and *sy* vertically. If *sy* is not provided, the shape is scaled uniformly by *sx* in both directions. **(transform-shape *****shape tf*****)** Returns a new shape derived from *shape* by applying transformation *tf*. **(flip-shape *****shape*****)** \ \&#xNAN;**(flip-shape *****shape box*****)**\ \&#xNAN;**(flip-shape *****shape box orientation*****)** Returns a new shape by flipping/mirroring *shape* within *box*. *box* is a rect. If it is not provided, the bounding box of *shape* is used as a default. Argument *orientation* is a symbol defining along which axis the shape is flipped. Supported are `horizontal`, `vertical`, and `mirror`. Default is `vertical`. **(interpolate *****points*****)** \ \&#xNAN;**(interpolate *****points closed*****)**\ \&#xNAN;**(interpolate *****points closed alpha*****)**\ \&#xNAN;**(interpolate *****points closed alpha method*****)** Returns a shape interpolating a list of points. *closed* is an optional boolean argument specifying whether the shape is closed. The default for *closed* is `#f`. *alpha* is an interpolation parameter in the range \[0.0,1.0]; default is 0.33. *method* specifies the interpolation method via a symbol. The following two methods are supported: `hermite` and `catmull-rom`; default is `hermite`. **(move-to *****point*****)** \ \&#xNAN;**(move-to *****point shape*****)** Sets the "current point" to *point* for the shape specified by argument *shape* or parameter object `current-shape` if *shape* is not provided. **(line-to *****point ...*****)** \ \&#xNAN;**(line-to *****point ... shape*****)** Creates a line from the "current point" to *point* for the shape specified by argument *shape* or parameter object `current-shape` if *shape* is not provided. *point* becomes the new "current point". **(curve-to *****point cntrl1 cntrl2*****)** \ \&#xNAN;**(curve-to *****point cntrl1 cntrl2 shape*****)** Creates a curve from the "current point" to *point* for the shape specified by argument *shape* or parameter object `current-shape` if *shape* is not provided. *cntrl1* and *cntrl2* are control points defining tangets shaping the curve at the start and end points. **(relative-move-to *****point*****)** \ \&#xNAN;**(relative-move-to *****point shape*****)** This function is equivalent to `move-to` with the exception that *point* is relative to the "current point". **(relative-line-to *****point ...*****)** \ \&#xNAN;**(relative-line-to *****point ... shape*****)** This function is equivalent to `line-to` with the exception that *point* is relative to the "current point". **(relative-curve-to *****point cntrl1 cntrl2*****)** \ \&#xNAN;**(relative-curve-to *****point cntrl1 cntrl2 shape*****)** This function is equivalent to `curve-to` with the exception that *point*, *cntrl1* and *cntrl2* are relative to the "current point". **(add-shape *****other*****)** \ \&#xNAN;**(add-shape *****other shape*****)** Adds shape *other* to the shape specified by argument *shape* or parameter object `current-shape` if *shape* is not provided. This function is typically used to compose shapes. **(shape-bounds *****shape*****)** Returns the bounding box for the given shape as a rect. **(shape-contains? *****shape point*****)** \ \&#xNAN;**(shape-contains? *****shape points*****)**\ \&#xNAN;**(shape-contains? *****shape points some?*****)** Returns `#t` if *shape* contains the given *point* or *points*. *point* is a single point, or *points* is a list of points. If *some?* is `#f` (the default), all points must be contained in the shape. If *some?* is `#t`, returns `#t` if at least one point is contained in the shape. **(shape *****body ...*****)** Creates a new empty shape, binds parameter object `current-shape` to it and executes the body statements in the dynamic scope of this binding. This special form returns the new drawing. **(with-shape *****shape body ...*****)** Binds parameter object `current-shape` to *shape* and executes the body statements in the dynamic scope of this binding. This special form returns the result of the last statement in the body. ## Images Images are objects representing immutable pictures of mutable size and metadata. Images are either loaded from image files or they are created from drawings. Images are either vector-based or bitmap-based. The current image API only allows loading vector-based images from PDF files. Bitmap-based images, on the other hand, can be loaded from PNG, JPG, GIF, etc. image files or they are created by drawing a drawing object into an empty bitmap. Bitmap-based images optionally have mutable EXIF data. **image-type-tag** Symbol representing the `image` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all image objects. **(image? *****obj*****)** Returns `#t` if *obj* is an image. Otherwise, it returns `#f`. **(load-image *****path*****)** Loads an image from the file at *path* and returns the corresponding image object. **(load-image-asset *****path type*****)** \ \&#xNAN;**(load-image-asset *****path type dir*****)** Loads an image from the file at the given relative file *path* and returns the corresponding image object. *type* refers to the default suffix of the file to load (e.g. `"png"` for PNG images). `load-image-asset` constructs a relative file path in the following way (assuming *path* does not have a suffix already): *dir/path.type* where *dir* is `"Images"` if it is not provided as a parameter. It then searches the asset paths in their given order for a file matching this relative file path. Once the first matching file is found, the file is loaded as an image file and the image gets returned by `load-image-asset`. It is an error if no matching image was found. **(bytevector->image *****bvec*****)** \ \&#xNAN;**(bytevector->image *****bvec start*****)**\ \&#xNAN;**(bytevector->image *****bvec start end*****)** Loads an image from the binary data provided by bytevector *bvec* between positions *start* and *end* and returns the corresponding image object. **(image->bytevector *****image format*****)** \ \&#xNAN;**(image->bytevector *****image format quality*****)** Returns a bytevector containing the encoded image data for *image* in the specified *format*. *format* is a symbol specifying the image format (e.g., `png`, `jpg`, `gif`, `bmp`, `tiff`, or `pdf`). *quality* is an optional floating-point number between 0.0 and 1.0 specifying the compression quality for formats that support it (e.g., JPEG). Returns `#f` if the conversion fails. **(save-image *****path image format*****)** \ \&#xNAN;**(save-image *****path image format quality*****)** Saves *image* to a file at the given filepath *path* in the specified *format*. *format* is a symbol specifying the image format (e.g., `png`, `jpg`, `gif`, `bmp`, `tiff`, or `pdf`). *quality* is an optional floating-point number between 0.0 and 1.0 specifying the compression quality for formats that support it (e.g., JPEG). Returns `#t` if successful, `#f` otherwise. **(image-size *****image*****)** Returns the size of the given image object in points. **(set-image-size! *****image size*****)** Sets the size of *image* to *size*, a size in points. **(bitmap? *****obj*****)** Returns `#t` if *obj* is a bitmap-based image. Otherwise, it returns `#f`. **(bitmap-size *****bmap*****)** Returns the size of the bitmap *bmap* in points. If *bmap* is not a bitmap object, `bitmap-size` returns `#f`. **(bitmap-pixels *****bmap*****)** Returns the number of horizontal and vertical pixels of the bitmap *bmap* as a size. If *bmap* is not a bitmap object, `bitmap-size` returns `#f`. **(bitmap-ppi *****bmap*****)** Returns the pixels per inch (PPI) resolution of the bitmap *bmap*. This is calculated from the pixel dimensions and the size in points. If *bmap* is not a bitmap object or the PPI cannot be determined, returns `#f`. **(bitmap-exif-data *****bmap*****)** Returns the EXIF metadata associated with bitmap *bmap*. EXIF metadata is represented as an association list in which symbols are used as keys. ```scheme > (define photo (load-image (asset-file-path "Regensberg" "jpeg" "Images"))) > (bitmap-exif-data photo) ((ExposureBiasValue . 0) (CustomRendered . 6) (SensingMethod . 2) (SubsecTimeOriginal . "615") (SubsecTimeDigitized . "615") (Flash . 0) (ExposureTime . 0.00040306328093510683) (OffsetTime . "+01:00") (PixelXDimension . 8066) (ExifVersion 2 3 1) (OffsetTimeDigitized . "+01:00") (ISOSpeedRatings 25) (OffsetTimeOriginal . "+01:00") (DateTimeDigitized . "2019:10:27 14:21:39") (FlashPixVersion 1 0) (WhiteBalance . 0) (PixelYDimension . 3552) (LensSpecification 4.25 4.25 1.7999999523162842 1.7999999523162842) (ColorSpace . 65535) (LensModel . "iPhone XS back camera 4.25mm f/1.8") (SceneCaptureType . 0) (ApertureValue . 1.6959938128383605) (SceneType . 1) (ShutterSpeedValue . 11.276932534193945) (FocalLength . 4.25) (FNumber . 1.8) (LensMake . "Apple") (FocalLenIn35mmFilm . 26) (BrightnessValue . 10.652484683458134) (ComponentsConfiguration 1 2 3 0) (MeteringMode . 5) (DateTimeOriginal . "2019:10:27 14:21:39")) ``` **(set-bitmap-exif-data! *****bmap*** ***exif*****)** Sets the EXIF metadata for the given bitmap *bmap* to *exif*. *exif* is an association list defining all the EXIF attributes with symbols being used as keys. ```scheme > (define photo (load-image (asset-file-path "Regensberg" "jpeg" "Images"))) > (set-bitmap-exif-data! photo '((ExposureBiasValue . 0) (Flash . 0) (ExposureTime . 0.0005) (PixelXDimension . 8066) (PixelYDimension . 3552) (ExifVersion 2 3 1) (ISOSpeedRatings 25) (FlashPixVersion 1 0) (WhiteBalance . 0) (LensSpecification 4.25 4.25 1.7999999523162842 1.7999999523162842) (ColorSpace . 65535) (SceneCaptureType . 0) (ApertureValue . 1.6959938128383605) (SceneType . 1) (ShutterSpeedValue . 11.276932534193945) (FocalLength . 4.25) (FNumber . 1.8) (BrightnessValue . 10.652484683458134) (ComponentsConfiguration 1 2 3 0) (OffsetTime . "+01:00") (OffsetTimeOriginal . "+01:00") (DateTimeOriginal . "2019:10:27 14:21:39") (OffsetTimeDigitized . "+01:00") (DateTimeDigitized . "2019:10:27 14:21:39"))) ``` **(make-bitmap *****drawing size*****)** \ \&#xNAN;**(make-bitmap *****drawing size ppi*****)** Creates a new bitmap-based image by drawing the object *drawing* into an empty bitmap of size *size* in points. *ppi* determines the number of pixels per inch. By default, *ppi* is set to 72. In this case, the number of pixels of the bitmap corresponds to the number of points (since 1 pixel corresponds to 1/72 of an inch). For a *ppi* value of 144, the horizontal and vertial number of pixels is doubled, etc. **(bitmap-crop *****bitmap rect*****)** Crops a rectangle from the given bitmap and returns the result in a new bitmap. *rect* is a rectangle in pixels. Its intersection with the dimensions of *bitmap* (in pixels) are used for cropping. **(bitmap-blur *****bitmap radius*****)** Blurs the given bitmap with the given blur radius and returns the result in a new bitmap of the same size. **(save-bitmap *****path bitmap format*****)** \ \&#xNAN;**(save-bitmap *****path bitmap format compr*****)** Saves a given bitmap-based image *bitmap* in a file at filepath *path*. *format* is a symbol specifying the image file format. Supported are: `png`, `jpg`, `gif`, `bmp`, and `tiff`. *compr* is a floating-point number between 0.0 and 1.0, with 1.0 resulting in no compression and 0.0 resulting in the maximum compression possible. This compression factor applies only if `jpg` is used. **(bitmap->bytevector *****bitmap format*****)** \ \&#xNAN;**(bitmap->bytevector *****bitmap format compr*****)** Returns a bytevector with an encoding of *bitmap* in the given format. *format* is a symbol specifying the image format. Supported are: `png`, `jpg`, `gif`, `bmp`, and `tiff`. *compr* is a floating-point number between 0.0 and 1.0, with 1.0 resulting in no compression and 0.0 resulting in the maximum compression possible. This compression factor applies only if `jpg` is used. ## Transformations A transformation is an immutable object defining an affine transformation. Transformations can be used to: * shift, * scale, and * rotate coordinate systems. Transformations are typically used in drawings to transform drawing instructions. They can also be used to transform shapes. **transformation-type-tag** Symbol representing the `transformation` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all transformation objects. **(transformation? *****obj*****)** Returns `#t` if *obj* is a transformation. Otherwise, it returns `#f`. **(transformation *****tf ...*****)** Creates a new transformation by composing the given transformations *tf*. **(invert *****tf*****)** Inverts transformation *tf* and returns a new transformation object for it. **(translate *****dx dy*****)** \ \&#xNAN;**(translate *****dx dy tf*****)** Returns a transformation for shifting the coordinate system by *dx* and *dy*. If transformation *tf* is provided, the translation transformation extends *tf*. **(scale *****dx dy*****)** \ \&#xNAN;**(scale *****dx dy tf*****)** Returns a transformation for scaling the coordinate system by *dx* and *dy*. If transformation *tf* is provided, the scaling transformation extends *tf*. **(rotate *****angle*****)** \ \&#xNAN;**(rotate *****angle tf*****)** Returns a transformation for rotating the coordinate system by *angle* (in radians). If transformation *tf* is provided, the rotation transformation extends *tf*. ## Colors Colors are immutable objects defining colors in terms of four components: red, green, blue and alpha. Library `(lispkit draw)` currently only supports RGB color spaces. `(lispkit draw)` supports the concept of *color lists* on *macOS*. A color list is provided as a `.plist` file and stored in the "ColorLists" asset directory of LispKit. It maps color names expressed as symbols to color values. Color lists need to be loaded explicitly via procedure `load-color-list`. **color-type-tag** Symbol representing the `color` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all color objects. **(color? *****obj*****)** Returns `#t` if *obj* is a color. Otherwise, it returns `#f`. **(color *****spec*****)** \ \&#xNAN;**(color *****name clist*****)**\ \&#xNAN;**(color *****r g b*****)**\ \&#xNAN;**(color *****r g b alpha*****)** This procedure returns new color objects. If *spec* is provided, it either is a string containing a color description in hex format, or it is a symbol referring to the name of a color in the default color list `(White Yellow Red Purple Orange Magenta Green Cyan Brown Blue Black)`. If a different color list should be used, its name can be specified via string *clist*. Procedure `(available-color-lists)` returns a list of all available color lists. If the color is specified via a hex string, the following formats can be used: `"ccc"`, `"#ccc"`, `"rrggbb"`, and `"#rrggbb"`. The color can also be specified using color components *r, g, b,* and *alpha*. *alpha* determines the transparency of the color (0.0 = fully transparent, 1.0 = no transparency). The default value for *alpha* is 1.0. **(color-red *****color*****)** Returns the red color component of *color*. **(color-green *****color*****)** Returns the green color component of *color*. **(color-blue *****color*****)** Returns the blue color component of *color*. **(color-alpha *****color*****)** Returns the alpha color component of *color*. **(color->hex *****color*****)** Returns a representation of the given *color* in hex form as a string. ```scheme (color->hex (color 1.0 0.5 0.1)) ⇒ "#FF801A" (color->hex (color "#6AF")) ⇒ "#66AAFF" ``` **black** \ **gray**\ **white**\ **red**\ **green**\ **blue**\ **yellow** Predefined color objects. **(available-color-lists)** Returns a list of available color lists. The LispKit installation guarantees that there is at least color list "HTML" containing all named colors from the HTML 5 specification. ```scheme (available-color-lists) ⇒ ("HTML" "Web Safe Colors" "Crayons" "System" "Apple") ``` **(load-color-list *****name path*****)** Loads a new color list stored as a `.plist` file in the assets directory of LispKit at the given file *path* (which can also refer to color lists outside of the assets directory via absolute file paths). *name* is a string which specifies the name of the color list. It is added to the list of available colors if loading of the color list was successful. `load-color-list` returns `#t` if the color list could be successfully loaded, `#f` otherwise. **(available-colors *****clist*****)** Returns a list of color identifiers supported by the given color list. *clist* is a string specifying the name of the color list. ```scheme (available-colors "HTML") ⇒ (YellowGreen Yellow WhiteSmoke White Wheat Violet Turquoise Tomato Thistle Teal Tan SteelBlue Snow SlateGrey SlateGray SlateBlue SkyBlue Silver Sienna SeaShell SeaGreen SandyBrown Salmon SaddleBrown RoyalBlue RosyBrown Red RebeccaPurple Purple PowderBlue Plum Pink Peru PeachPuff PapayaWhip PaleVioletRed PaleTurquoise PaleGreen PaleGoldenRod Orchid OrangeRed Orange OliveDrab Olive OldLace Navy NavajoWhite Moccasin MistyRose MintCream MidnightBlue MediumVioletRed MediumTurquoise MediumSpringGreen MediumSlateBlue MediumSeaGreen MediumPurple MediumOrchid MediumBlue MediumAquaMarine Maroon Magenta Linen LimeGreen Lime LightYellow LightSteelBlue LightSlateGrey LightSlateGray LightSkyBlue LightSeaGreen LightSalmon LightPink LightGrey LightGreen LightGray LightGoldenRodYellow LightCyan LightCoral LightBlue LemonChiffon LawnGreen LavenderBlush Lavender Khaki Ivory Indigo IndianRed HotPink HoneyDew Grey GreenYellow Green Gray GoldenRod Gold GhostWhite Gainsboro Fuchsia ForestGreen FloralWhite FireBrick DodgerBlue DimGrey DimGray DeepSkyBlue DeepPink DarkViolet DarkTurquoise DarkSlateGrey DarkSlateGray DarkSlateBlue DarkSeaGreen DarkSalmon DarkRed DarkOrchid DarkOrange DarkOliveGreen DarkMagenta DarkKhaki DarkGrey DarkGreen DarkGray DarkGoldenRod DarkCyan DarkBlue Cyan Crimson Cornsilk CornflowerBlue Coral Chocolate Chartreuse CadetBlue BurlyWood Brown BlueViolet Blue BlanchedAlmond Black Bisque Beige Azure Aquamarine Aqua AntiqueWhite AliceBlue) ``` ## Fonts Fonts are immutable objects defining fonts in terms of a font name and a font size (in points). **font-type-tag** Symbol representing the `font` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all font objects. **(font? *****obj*****)** Returns `#t` if *obj* is a font. Otherwise, it returns `#f`. **(font *****fontname size*****)** \ \&#xNAN;**(font *****familyname size weight trait ...*****)** If only two arguments, *fontname* and *size*, are provided, `font` will return a new font object for a font with the given font name and font size (in points). If more than two arguments are provided, `font` will return a new font object for a font with the given font family name, font size (in points), font weight, as well as a number of font traits. The weight of a font is specified as an integer on a scale from 0 to 15. Library `(lispkit draw)` exports the following weight constants: * `ultralight` (1) * `thin` (2) * `light` (3) * `book` (4) * `normal` (5) * `medium` (6) * `demi` (7) * `semi` (8) * `bold` (9) * `extra` (10) * `heavy` (11) * `super` (12) * `ultra` (13) * `extrablack` (14) Font traits are specified as integer masks. The following trait constants are exported from library `(lispkit draw)`: * `italic` * `boldface` * `unitalic` * `unboldface` * `narrow` * `expanded` * `condensed` * `small-caps` * `poster` * `compressed` * `monospace` **(font-name *****font*****)** Returns the font name of *font*. **(font-family-name *****font*****)** Returns the font family name of *font*. **(font-size *****font*****)** Returns the font size of *font* in points. **(font-weight *****font*****)** Returns the font weight of *font*. See documentation of function `font` for details. **(font-traits *****font*****)** Returns the font traits of *font* as an integer bitmask. See documentation of function `font` for details. **(font-has-traits *****font trait ...*****)** Returns `#t` if font *font* has all the given traits. **(available-fonts)** \ \&#xNAN;**(available-fonts *****trait ...*****)** Returns all the available fonts that have matching font traits. **(available-font-families)** Returns all the available font families, i.e. all font families for which there is at least one font installed. ## Points A *point* describes a location on a two-dimensional plane consisting of a *x* and *y* coordinate. Points are represented as pairs of floating-point numbers where the car representes the x-coordinate and the cdr represents the y-coordinate. Even though an expression like `'(3.5 . -2.0)` does represent a point, it is recommended to always construct points via function `point`; e.g. `(point 3.5 -2.0)`. **zero-point** The *zero point*, i.e `(point 0.0 0.0)`. **(point? *****obj*****)** Returns `#t` if *obj* is a valid point. Otherwise, it returns `#f`. **(point *****x y*****)** Returns a point for coordinates *x* and *y*. **(point-x *****point*****)** Returns the x-coordinate for *point*. **(point-y *****point*****)** Returns the y-coordinate for *point*. **(move-point *****point dx dy*****)** Moves *point* by *dx* and *dy* and returns the result as a point. **(scale-point *****point sx*****)** \ \&#xNAN;**(scale-point *****point sx sy*****)** Scales *point* by factor *sx* horizontally and *sy* vertically, and returns the result. If *sy* is not provided, the point is scaled uniformly by *sx* in both directions. **(transform-point *****point transformation*****)** Applies the given affine *transformation* to *point* and returns the result. ## Size A *size* describes the dimensions of a rectangle consisting of *width* and *height* values. Sizes are represented as pairs of floating-point numbers where the car representes the width and the cdr represents the height. Even though an expression like `'(5.0 . 3.0)` does represent a size, it is recommended to always construct sizes via function `size`; e.g. `(size 5.0 3.0)`. **zero-size** The zero size, i.e. `(size 0.0 0.0)`. **(size? *****obj*****)** Returns `#t` if *obj* is a valid size. Otherwise, it returns `#f`. **(size *****w h*****)** Returns a size for the given width *w* and height *h*. **(size-width *****size*****)** Returns the width for *size*. **(size-height *****size*****)** Returns the height for *size*. **(increase-size *****size dx dy*****)** Returns a new size object whose width is increased by *dx* and whose height is increased by *dy*. **(size-ratio *****size*****)** Returns the aspect ratio of *size*, i.e. the width divided by the height. **(scale-size *****size factor*****)** Returns a new size object whose width and height is multiplied by *factor*. ## Rects A *rect* describes a rectangle in terms of an upper left *point* and a *size*. Rects are represented as pairs whose car is a point and whose cdr is a size. Even though an expression like `'((1.0 . 2.0) . (3.0 4.0))` does represent a rect, it is recommended to always construct rects via function `rect`; e.g. `(rect (point 1.0 2.0) (size 3.0 4.0))`. **(rect? *****obj*****)** Returns `#t` if *obj* is a valid rect. Otherwise, it returns `#f`. **(rect *****point size*****)** \ \&#xNAN;**(rect *****x y width height*****)** Returns a rect either from the given *point* and *size*, or from x-coordinate *x*, y-coordinate *y*, width *w*, and height *h*. **(rect-point *****rect*****)** Returns the upper left corner point of *rect*. **(rect-size *****rect*****)** Returns the size of *rect* as a size object, i.e. as a pair of floating-point numbers where the car representes the width and the cdr represents the height of *rect*. **(rect-x *****rect*****)** Returns the x-coordinate of the upper left corner point of *rect*. **(rect-y *****rect*****)** Returns the y-coordinate of the upper left corner point of *rect*. **(rect-width *****rect*****)** Returns the width of *rect*. **(rect-height *****rect*****)** Returns the height of *rect*. **(rect-max-point *****rect*****)** Returns the lower right corner point of *rect*. **(rect-max-x *****rect*****)** Returns the x-coordinate of the lower right corner point of *rect*. **(rect-max-y *****rect*****)** Returns the y-coordinate of the lower right corner point of *rect*. **(rect-mid-point *****rect*****)** Returns the center point of *rect*, i.e. the midpoint between the upper left and lower right corners. **(rect-mid-x *****rect*****)** Returns the x-coordinate of the center point of *rect*. **(rect-mid-y *****rect*****)** Returns the y-coordinate of the center point of *rect*. **(move-rect *****rect d*****)** \ \&#xNAN;**(move-rect *****rect dx dy*****)** Moves *rect* by *dx* and *dy* and returns the result. If only one argument *d* is provided, *rect* is moved by *d* both horizontally and vertically. **(scale-rect *****rect sx*****)** \ \&#xNAN;**(scale-rect *****rect sx sy*****)**\ \&#xNAN;**(scale-rect *****rect sx sy preserve-mid?*****)** Scales *rect* by factor *sx* horizontally and *sy* vertically, and returns the result. If *sy* is not provided, the rect is scaled uniformly by *sx* in both directions. If *preserve-mid?* is true, the rectangle's center point is preserved during scaling. **(inset-rect *****rect d*****)** \ \&#xNAN;**(inset-rect *****rect horizental vertical*****)**\ \&#xNAN;**(inset-rect *****rect left top right bottom*****)** Insets *rect* on all sides as specified by the arguments. If only *d* is provided, it specifies the amount added to the rectangle's left and top and the amount subtracted from the rectangle's right and bottom. *horizontal* specifies the amount added to the rectangle's left and subtracted from the rectangle's right. *vertical* specifies the amount added to the rectangle's top and subtracted from the rectangle's bottom. If *left*, *top*, *right*, and *bottom* are given individually, they specify the amounts to add/subtract from the individual sides. **(transform-rect *****rect tf*****)** Applies the given transformation *tf* to *rect* and returns the result. **(intersect-rect *****rect1 rect2*****)** Returns the intersection of *rect1* and *rect2* as a new rect. If the rectangles do not intersect, returns `#f`. **(union-rect *****rect1 rect2*****)** Returns the smallest rect that contains both *rect1* and *rect2*. **(rect-contains? *****rect obj*****)** Returns `#t` if *rect* contains *obj*. *obj* can be either a point or another rect. For a rect to contain another rect, the second rect must be completely within the first rect. ## Utilities **(transpose *****expr cur-size new-size*****)** \ \&#xNAN;**(transpose *****expr cur-size new-size flip?*****)** Transposes coordinates in *expr* from a coordinate system with *cur-size* to a new coordinate system with *new-size*. This is useful for transforming drawings between different canvas sizes. *expr* can be a point, rect, list, or vector containing points and rects. If *flip?* is true or if *new-size* is `#f`, the y-coordinates are flipped vertically. *cur-size* and *new-size* are either size objects, rects, or images.