The cl-netpbm Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-netpbm Reference Manual

This is the cl-netpbm Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Fri May 24 08:17:50 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-netpbm is a pure Common Lisp library for reading and writing the netpbm image formats (PPM, PGM, and PBM).

These image formats are very simple, but not efficient. If you need extreme performance you should not use these formats (or this library).


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-netpbm

Author

Steve Losh <steve@stevelosh.com>

Home Page

https://sjl.bitbucket.io/cl-netpbm/

License

MIT/X11

Description

Common Lisp support for reading/writing the netpbm image formats (PPM, PGM, and PBM).

Version

1.0.0

Source

cl-netpbm.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Next: , Previous: , Up: Modules   [Contents][Index]

3.1 cl-netpbm/vendor

Parent

cl-netpbm (system)

Location

vendor/

Components

Previous: , Up: Modules   [Contents][Index]

3.2 cl-netpbm/src

Dependency

package.lisp (file)

Parent

cl-netpbm (system)

Location

src/

Component

main.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 cl-netpbm.asd

Location

cl-netpbm.asd

Systems

cl-netpbm (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 cl-netpbm/vendor/quickutils-package.lisp

Parent

vendor (module)

Location

vendor/quickutils-package.lisp

Packages

netpbm.quickutils

Internal Definitions

*utilities* (special variable)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 cl-netpbm/vendor/quickutils.lisp

Dependency

quickutils-package.lisp (file)

Parent

vendor (module)

Location

vendor/quickutils.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 cl-netpbm/package.lisp

Dependency

vendor (module)

Parent

cl-netpbm (system)

Location

package.lisp

Packages

netpbm


Previous: , Up: Lisp files   [Contents][Index]

4.1.5 cl-netpbm/src/main.lisp

Parent

src (module)

Location

src/main.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 netpbm.quickutils

Package that contains Quickutil utility functions.

Source

quickutils-package.lisp (file)

Use List

common-lisp

Used By List

netpbm

Exported Definitions
Internal Definitions

Previous: , Up: Packages   [Contents][Index]

5.2 netpbm

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Macros

Macro: with-gensyms NAMES &body FORMS

Binds each variable named by a symbol in ‘names‘ to a unique symbol around ‘forms‘. Each of ‘names‘ must either be either a symbol, or of the form:

(symbol string-designator)

Bare symbols appearing in ‘names‘ are equivalent to:

(symbol symbol)

The string-designator is used as the argument to ‘gensym‘ when constructing the unique symbol the named variable will be bound to.

Package

netpbm.quickutils

Source

quickutils.lisp (file)

Macro: with-unique-names NAMES &body FORMS

Binds each variable named by a symbol in ‘names‘ to a unique symbol around ‘forms‘. Each of ‘names‘ must either be either a symbol, or of the form:

(symbol string-designator)

Bare symbols appearing in ‘names‘ are equivalent to:

(symbol symbol)

The string-designator is used as the argument to ‘gensym‘ when constructing the unique symbol the named variable will be bound to.

Package

netpbm.quickutils

Source

quickutils.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Compiler macros

Compiler Macro: curry FUNCTION &rest ARGUMENTS
Package

netpbm.quickutils

Source

quickutils.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Functions

Function: curry FUNCTION &rest ARGUMENTS

Returns a function that applies ‘arguments‘ and the arguments it is called with to ‘function‘.

Package

netpbm.quickutils

Source

quickutils.lisp (file)

Function: read-from-file PATH

Read a PPM image file from ‘path‘, returning an array of pixels and more.

The primary return value will be a 2D array with dimensions ‘(width height)‘. Each element of the array will be a single pixel whose type depends on the image file format:

* PBM: ‘bit‘
* PGM: ‘(integer 0 maximum-value)‘
* PPM: ‘(simple-array (integer 0 maximum-value) (3))‘

Two other values are returned:

* The format of the image that was read (one of ‘:pbm‘, ‘:pgm‘, ‘:ppm‘). * The bit depth of the image.

Package

netpbm

Source

main.lisp (file)

Function: read-from-stream STREAM

Read a PPM image file from ‘stream‘, returning an array of pixels and more.

‘stream‘ must be a binary input stream, specifically of ‘(unsigned-byte 8)‘s unless you *really* know what you’re doing.

The primary return value will be a 2D array with dimensions ‘(width height)‘. Each element of the array will be a single pixel whose type depends on the image file format:

* PBM: ‘bit‘
* PGM: ‘(integer 0 maximum-value)‘
* PPM: ‘(simple-array (integer 0 maximum-value) (3))‘

Two other values are returned:

* The format of the image that was read (one of ‘:pbm‘, ‘:pgm‘, ‘:ppm‘). * The bit depth of the image.

Package

netpbm

Source

main.lisp (file)

Function: read-texture-from-file PATH

Read a PPM image file from ‘path‘, returning an OpenGL-style array and more.

The primary return value will be an OpenGL-style array of type:

(simple-array (single-float 0.0 1.0) (* width height 3))

The vertical axis of the image will be flipped, which is what OpenGL expects.

Three values are returned: the array, the width, and the height.

Package

netpbm

Source

main.lisp (file)

Function: read-texture-from-stream STREAM

Read a PPM image file from ‘stream‘, returning an OpenGL-style array and more.

‘stream‘ must be a binary input stream, specifically of ‘(unsigned-byte 8)‘s unless you *really* know what you’re doing. The stream must contain a PPM formatted image — PBM and PGM images are not supported.

The primary return value will be an OpenGL-style array of type:

(simple-array (single-float 0.0 1.0) (* width height 3))

The vertical axis of the image will be flipped, which is what OpenGL expects.

Three values are returned: the array, the width, and the height.

Package

netpbm

Source

main.lisp (file)

Function: symb &rest ARGS

Receives any number of objects, concatenates all into one string with ‘#’mkstr‘ and converts them to symbol.

Extracted from _On Lisp_, chapter 4.

See also: ‘symbolicate‘

Package

netpbm.quickutils

Source

quickutils.lisp (file)

Function: transpose LISTS

Analog to matrix transpose for a list of lists given by ‘lists‘.

Package

netpbm.quickutils

Source

quickutils.lisp (file)

Function: write-to-file PATH DATA &key IF-EXISTS FORMAT ENCODING MAXIMUM-VALUE

Write a PPM image array ‘data‘ to a file at ‘path‘.

Nothing is returned.

‘format‘ must be one of ‘:pbm‘, ‘:pgm‘, ‘:ppm‘.

‘encoding‘ must be one of ‘:binary‘, ‘:ascii‘.

‘maximum-value‘ must be the desired bit depth of the image (the maximum value any particular pixel can have). For PBM images it must be ‘1‘.

For PBM and PGM images, ‘data‘ must be a two dimensional array of integers between ‘0‘ and ‘maximum-value‘ inclusive.

For PPM images, ‘data‘ must be a two dimensional array of pixels, each of which must be a 3 element vector of integers between ‘0‘ and ‘maximum-value‘ inclusive.

Package

netpbm

Source

main.lisp (file)

Function: write-to-stream STREAM DATA &key FORMAT ENCODING MAXIMUM-VALUE

Write a PPM image array ‘data‘ to ‘stream‘.

Nothing is returned.

‘stream‘ must be a binary output stream, specifically of ‘(unsigned-byte 8)‘s unless you *really* know what you’re doing.

‘format‘ must be one of ‘:pbm‘, ‘:pgm‘, ‘:ppm‘.

‘encoding‘ must be one of ‘:binary‘, ‘:ascii‘.

‘maximum-value‘ must be the desired bit depth of the image (the maximum value any particular pixel can have). For PBM images it must be ‘1‘.

For PBM and PGM images, ‘data‘ must be a two dimensional array of integers between ‘0‘ and ‘maximum-value‘ inclusive.

For PPM images, ‘data‘ must be a two dimensional array of pixels, each of which must be a 3 element vector of integers between ‘0‘ and ‘maximum-value‘ inclusive.

Package

netpbm

Source

main.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Constants

Constant: +carriage-return+
Package

netpbm

Source

main.lisp (file)

Constant: +comment-char+
Package

netpbm

Source

main.lisp (file)

Constant: +form-feed+
Package

netpbm

Source

main.lisp (file)

Constant: +line-feed+
Package

netpbm

Source

main.lisp (file)

Constant: +space+
Package

netpbm

Source

main.lisp (file)

Constant: +tab+
Package

netpbm

Source

main.lisp (file)

Constant: +vertical-tab+
Package

netpbm

Source

main.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Special variables

Special Variable: *utilities*
Package

netpbm.quickutils

Source

quickutils-package.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Macros

Macro: check-number PLACE MAXIMUM-VALUE
Package

netpbm

Source

main.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Functions

Function: bits BYTE
Package

netpbm

Source

main.lisp (file)

Function: byte-to-digit BYTE
Package

netpbm

Source

main.lisp (file)

Function: copy-peekable-stream INSTANCE
Package

netpbm

Source

main.lisp (file)

Function: ensure-function FUNCTION-DESIGNATOR

Returns the function designated by ‘function-designator‘:
if ‘function-designator‘ is a function, it is returned, otherwise it must be a function name and its ‘fdefinition‘ is returned.

Package

netpbm.quickutils

Source

quickutils.lisp (file)

Function: error-junk SECTION BYTE
Package

netpbm

Source

main.lisp (file)

Function: file-format MAGIC-BYTE

Return ‘(values format binary?)‘ for the given magic byte character.

Package

netpbm

Source

main.lisp (file)

Function: format-to-stream STREAM &rest FORMAT-ARGS
Package

netpbm

Source

main.lisp (file)

Function: line-terminator-p BYTE
Package

netpbm

Source

main.lisp (file)

Function: magic-byte FILE-FORMAT BINARY?

Return the magic byte character to use for the given format/encoding combination.

Package

netpbm

Source

main.lisp (file)

Function: make-color R G B
Package

netpbm

Source

main.lisp (file)

Function: make-gensym-list LENGTH &optional X

Returns a list of ‘length‘ gensyms, each generated as if with a call to ‘make-gensym‘, using the second (optional, defaulting to ‘"G"‘) argument.

Package

netpbm.quickutils

Source

quickutils.lisp (file)

Function: make-peekable-stream S
Package

netpbm

Source

main.lisp (file)

Function: mkstr &rest ARGS

Receives any number of objects (string, symbol, keyword, char, number), extracts all printed representations, and concatenates them all into one string.

Extracted from _On Lisp_, chapter 4.

Package

netpbm.quickutils

Source

quickutils.lisp (file)

Function: p INSTANCE
Function: (setf p) VALUE INSTANCE
Package

netpbm

Source

main.lisp (file)

Function: peek-byte STREAM
Package

netpbm

Source

main.lisp (file)

Function: peekable-stream-p OBJECT
Package

netpbm

Source

main.lisp (file)

Function: pixel-type FORMAT BIT-DEPTH

Return the type specifier for a pixel of an image with the given ‘format‘ and ‘bit-depth‘.

Package

netpbm

Source

main.lisp (file)

Function: read-bitmap-ascii STREAM
Package

netpbm

Source

main.lisp (file)

Function: read-bitmap-binary STREAM &aux BUFFER
Package

netpbm

Source

main.lisp (file)

Function: read-byte STREAM &optional EOF-ERROR-P
Package

netpbm

Source

main.lisp (file)

Function: read-graymap STREAM BINARY?
Package

netpbm

Source

main.lisp (file)

Function: read-header-number STREAM

Read the next ASCII-encoded number from ‘stream‘ (allows comments).

Package

netpbm

Source

main.lisp (file)

Function: read-magic-byte STREAM

Read the initial ‘P#‘ from ‘stream‘, returning the magic ‘#‘ character.

Package

netpbm

Source

main.lisp (file)

Function: read-netpbm STREAM FORMAT BINARY? TEXTURE?
Package

netpbm

Source

main.lisp (file)

Function: read-pixmap STREAM BINARY?
Package

netpbm

Source

main.lisp (file)

Function: read-raster-number STREAM

Read the next ASCII-encoded number from ‘stream‘ (does not allow comments).

Package

netpbm

Source

main.lisp (file)

Function: read-texture STREAM BINARY?
Package

netpbm

Source

main.lisp (file)

Function: s INSTANCE
Function: (setf s) VALUE INSTANCE
Package

netpbm

Source

main.lisp (file)

Function: skip-comment-body STREAM
Package

netpbm

Source

main.lisp (file)

Function: skip-whitespace STREAM
Package

netpbm

Source

main.lisp (file)

Function: unread-byte STREAM BYTE
Package

netpbm

Source

main.lisp (file)

Function: white-space-p BYTE
Package

netpbm

Source

main.lisp (file)

Function: write-bitmap-ascii DATA STREAM
Package

netpbm

Source

main.lisp (file)

Function: write-bitmap-binary DATA STREAM &aux BUFFER BUFFER-LENGTH
Package

netpbm

Source

main.lisp (file)

Function: write-graymap DATA STREAM BINARY? MAXIMUM-VALUE
Package

netpbm

Source

main.lisp (file)

Function: write-line-feed STREAM
Package

netpbm

Source

main.lisp (file)

Function: write-netpbm DATA STREAM FORMAT BINARY? MAXIMUM-VALUE
Package

netpbm

Source

main.lisp (file)

Function: write-number-ascii VALUE STREAM MAXIMUM-VALUE

Write ‘value‘ to stream as an ASCII-encoded number, with sanity check.

Package

netpbm

Source

main.lisp (file)

Function: write-number-binary VALUE STREAM MAXIMUM-VALUE

Write ‘value‘ to ‘stream‘ as a binary value, with sanity check.

Package

netpbm

Source

main.lisp (file)

Function: write-pixmap DATA STREAM BINARY? MAXIMUM-VALUE
Package

netpbm

Source

main.lisp (file)

Function: write-string-as-bytes STRING STREAM
Package

netpbm

Source

main.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.5 Structures

Structure: peekable-stream ()
Package

netpbm

Source

main.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: p
Type

(or null (unsigned-byte 8))

Readers

p (function)

Writers

(setf p) (function)

Slot: s
Type

stream

Initform

(error "required")

Readers

s (function)

Writers

(setf s) (function)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.6 Types

Type: string-designator ()

A string designator type. A string designator is either a string, a symbol, or a character.

Package

netpbm.quickutils

Source

quickutils.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-netpbm.asd: The cl-netpbm<dot>asd file
cl-netpbm/package.lisp: The cl-netpbm/package<dot>lisp file
cl-netpbm/src: The cl-netpbm/src module
cl-netpbm/src/main.lisp: The cl-netpbm/src/main<dot>lisp file
cl-netpbm/vendor: The cl-netpbm/vendor module
cl-netpbm/vendor/quickutils-package.lisp: The cl-netpbm/vendor/quickutils-package<dot>lisp file
cl-netpbm/vendor/quickutils.lisp: The cl-netpbm/vendor/quickutils<dot>lisp file

F
File, Lisp, cl-netpbm.asd: The cl-netpbm<dot>asd file
File, Lisp, cl-netpbm/package.lisp: The cl-netpbm/package<dot>lisp file
File, Lisp, cl-netpbm/src/main.lisp: The cl-netpbm/src/main<dot>lisp file
File, Lisp, cl-netpbm/vendor/quickutils-package.lisp: The cl-netpbm/vendor/quickutils-package<dot>lisp file
File, Lisp, cl-netpbm/vendor/quickutils.lisp: The cl-netpbm/vendor/quickutils<dot>lisp file

L
Lisp File, cl-netpbm.asd: The cl-netpbm<dot>asd file
Lisp File, cl-netpbm/package.lisp: The cl-netpbm/package<dot>lisp file
Lisp File, cl-netpbm/src/main.lisp: The cl-netpbm/src/main<dot>lisp file
Lisp File, cl-netpbm/vendor/quickutils-package.lisp: The cl-netpbm/vendor/quickutils-package<dot>lisp file
Lisp File, cl-netpbm/vendor/quickutils.lisp: The cl-netpbm/vendor/quickutils<dot>lisp file

M
Module, cl-netpbm/src: The cl-netpbm/src module
Module, cl-netpbm/vendor: The cl-netpbm/vendor module

Jump to:   C   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
B   C   E   F   L   M   P   R   S   T   U   W  
Index Entry  Section

(
(setf p): Internal functions
(setf s): Internal functions

B
bits: Internal functions
byte-to-digit: Internal functions

C
check-number: Internal macros
Compiler Macro, curry: Exported compiler macros
copy-peekable-stream: Internal functions
curry: Exported compiler macros
curry: Exported functions

E
ensure-function: Internal functions
error-junk: Internal functions

F
file-format: Internal functions
format-to-stream: Internal functions
Function, (setf p): Internal functions
Function, (setf s): Internal functions
Function, bits: Internal functions
Function, byte-to-digit: Internal functions
Function, copy-peekable-stream: Internal functions
Function, curry: Exported functions
Function, ensure-function: Internal functions
Function, error-junk: Internal functions
Function, file-format: Internal functions
Function, format-to-stream: Internal functions
Function, line-terminator-p: Internal functions
Function, magic-byte: Internal functions
Function, make-color: Internal functions
Function, make-gensym-list: Internal functions
Function, make-peekable-stream: Internal functions
Function, mkstr: Internal functions
Function, p: Internal functions
Function, peek-byte: Internal functions
Function, peekable-stream-p: Internal functions
Function, pixel-type: Internal functions
Function, read-bitmap-ascii: Internal functions
Function, read-bitmap-binary: Internal functions
Function, read-byte: Internal functions
Function, read-from-file: Exported functions
Function, read-from-stream: Exported functions
Function, read-graymap: Internal functions
Function, read-header-number: Internal functions
Function, read-magic-byte: Internal functions
Function, read-netpbm: Internal functions
Function, read-pixmap: Internal functions
Function, read-raster-number: Internal functions
Function, read-texture: Internal functions
Function, read-texture-from-file: Exported functions
Function, read-texture-from-stream: Exported functions
Function, s: Internal functions
Function, skip-comment-body: Internal functions
Function, skip-whitespace: Internal functions
Function, symb: Exported functions
Function, transpose: Exported functions
Function, unread-byte: Internal functions
Function, white-space-p: Internal functions
Function, write-bitmap-ascii: Internal functions
Function, write-bitmap-binary: Internal functions
Function, write-graymap: Internal functions
Function, write-line-feed: Internal functions
Function, write-netpbm: Internal functions
Function, write-number-ascii: Internal functions
Function, write-number-binary: Internal functions
Function, write-pixmap: Internal functions
Function, write-string-as-bytes: Internal functions
Function, write-to-file: Exported functions
Function, write-to-stream: Exported functions

L
line-terminator-p: Internal functions

M
Macro, check-number: Internal macros
Macro, with-gensyms: Exported macros
Macro, with-unique-names: Exported macros
magic-byte: Internal functions
make-color: Internal functions
make-gensym-list: Internal functions
make-peekable-stream: Internal functions
mkstr: Internal functions

P
p: Internal functions
peek-byte: Internal functions
peekable-stream-p: Internal functions
pixel-type: Internal functions

R
read-bitmap-ascii: Internal functions
read-bitmap-binary: Internal functions
read-byte: Internal functions
read-from-file: Exported functions
read-from-stream: Exported functions
read-graymap: Internal functions
read-header-number: Internal functions
read-magic-byte: Internal functions
read-netpbm: Internal functions
read-pixmap: Internal functions
read-raster-number: Internal functions
read-texture: Internal functions
read-texture-from-file: Exported functions
read-texture-from-stream: Exported functions

S
s: Internal functions
skip-comment-body: Internal functions
skip-whitespace: Internal functions
symb: Exported functions

T
transpose: Exported functions

U
unread-byte: Internal functions

W
white-space-p: Internal functions
with-gensyms: Exported macros
with-unique-names: Exported macros
write-bitmap-ascii: Internal functions
write-bitmap-binary: Internal functions
write-graymap: Internal functions
write-line-feed: Internal functions
write-netpbm: Internal functions
write-number-ascii: Internal functions
write-number-binary: Internal functions
write-pixmap: Internal functions
write-string-as-bytes: Internal functions
write-to-file: Exported functions
write-to-stream: Exported functions

Jump to:   (  
B   C   E   F   L   M   P   R   S   T   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
C   P   S  
Index Entry  Section

*
*utilities*: Internal special variables

+
+carriage-return+: Internal constants
+comment-char+: Internal constants
+form-feed+: Internal constants
+line-feed+: Internal constants
+space+: Internal constants
+tab+: Internal constants
+vertical-tab+: Internal constants

C
Constant, +carriage-return+: Internal constants
Constant, +comment-char+: Internal constants
Constant, +form-feed+: Internal constants
Constant, +line-feed+: Internal constants
Constant, +space+: Internal constants
Constant, +tab+: Internal constants
Constant, +vertical-tab+: Internal constants

P
p: Internal structures

S
s: Internal structures
Slot, p: Internal structures
Slot, s: Internal structures
Special Variable, *utilities*: Internal special variables

Jump to:   *   +  
C   P   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   N   P   S   T  
Index Entry  Section

C
cl-netpbm: The cl-netpbm system

N
netpbm: The netpbm package
netpbm.quickutils: The netpbm<dot>quickutils package

P
Package, netpbm: The netpbm package
Package, netpbm.quickutils: The netpbm<dot>quickutils package
peekable-stream: Internal structures

S
string-designator: Internal types
Structure, peekable-stream: Internal structures
System, cl-netpbm: The cl-netpbm system

T
Type, string-designator: Internal types

Jump to:   C   N   P   S   T