1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
.TH PICFILE 3X
.CT graphics files
.SH NAME
picopen_r, picopen_w, picread, picwrite, picclose, picputprop, picgetprop, picunpack, picpack, picerror \- picture file I/O
.SH SYNOPSIS
.nf
.B #include <picfile.h>
.PP
.B PICFILE *picopen_r(name)
.B char *name;
.PP
.B "PICFILE *picopen_w(name, type, x0, y0, w, h, chan, argv, cmap)
.B "char *name, *type, *chan, *argv[], *cmap;
.PP
.B int picread(pf, buf)
.B PICFILE *pf;
.B char *buf;
.PP
.B int picwrite(pf, buf)
.B PICFILE *pf;
.B char *buf;
.PP
.B void picclose(pf)
.B PICFILE *pf;
.PP
.B PICFILE *picputprop(pf, name, value)
.B PICFILE *pf;
.B char *name, *value;
.PP
.B char *picgetprop(pf, name)
.B PICFILE *pf;
.B char *name;
.PP
.B "void picunpack(pf, pix, fmt, arg ...)
.B PICFILE *pf;
.B char *pix, *fmt;
.PP
.B "void picpack(pf, pix, fmt, arg ...)
.B PICFILE *pf;
.B char *pix, *fmt;
.PP
.B "void picerror(string)
.B char *string;
.fi
.SH DESCRIPTION
These functions read and write raster images in
.IR picfile (5)
format.
They are loaded by option
.B -lpicfile
of
.IR ld (1).
Open picture files are referred to by pointers of type
.BR PICFILE* .
.PP
.I Picopen_r
opens the named picfile for reading and returns a pointer
to the open file.
If
.I name
is
.L
"IN"\fR,
standard input is used.
.PP
.I Picopen_w
similarly creates the named image file for writing.
The name
.L
"OUT"
refers to standard output.
.I Type
is a
.B TYPE
attribute, as described in
.IR picfile (5);
.I x0
and
.I y0
are the upper left coordinates of the
.BR WINDOW
attribute;
.I w
and
.I h
are the image width and heigth in pixels.
.I Chan
is a string specifying the order of channels for the
.B CHAN
attribute; the length of this string becomes the value of
.BR NCHAN .
.I Argv,
if nonzero, is
conventionally the second argument of the main program;
see
.IR exec (2).
It becomes a
.B COMMAND
attribute recording the provenance of the file.
.PP
The special call
.B picopen_w(name, PIC_SAMEARGS(pf))
creates a file with the same attributes as an already open
picfile.
.B PIC_SAMEARGS
mentions
.I argv
by name, hence the name must be visible at the point of call.
.PP
.I Picread
and
.I picwrite
read or write a single row of pixels using the
character array
.I buf.
The length of the row is determined from the file's
.B WINDOW
and
.B NCHAN
attributes.
One-bit-per-pixel images (of type
.B bitmap
or
.BR ccitt-g4 ,
for example)
are decoded to one byte per pixel, 0 for black, 255 for white, and
are encoded as 1 for pixel values less than 128 and 0 otherwise.
Files of type
.B ccir601
are decoded into conventional
.B rgb
channels.
.PP
.I Picclose
closes a picfile and frees associated storage.
.PP
.I Picputprop
called after
.I picopen_w
but before
.I picwrite
adds header attributes, returning a (probably changed) value of the
.B PICFILE
pointer.
.PP
.I Picgetprop
returns a pointer to the value of the named attribute, or
0 if the picfile does not have the attribute.
In both
.I Picputprop
and
.I picgetprop,
with multiple appearances (e.g.
.BR COMMAND )
are expressed as a sequence of
values separated by newlines.
.PP
The header file defines macros to extract commonly-used
attributes:
.IP
.EX
PIC_NCHAN(pf), PIC_WIDTH(pf), PIC_HEIGHT(pf),
PIC_SAMEARGS(pf) \fR(see \fP\&picopen_w\fR)\fP
.EE
.PP
.I Picunpack
extracts the channels of pixel array
.I pix
into separate array
.I args
of types described by the
.I fmt
character string.
Format characters are
.BR c ,
.BR s ,
.BR l ,
.BR f ,
.BR d ,
for arrays of types unsigned char, short, long,
float, and double.
Format character
.B _
designates a picfile channel to be skipped.
.I Picpack
reverses the process.
These routines effect a standard machine-independent byte
ordering.
.PP
.IR Picerror
prints messages for errors resulting from calls to
.I picfile
routines.
.RI ( Perror (3)
cannot describe some error conditions,
like malformed header lines.)
.SH EXAMPLES
Unpack the green and z channels from a file with channels
.B rgbz...
.br
.ns
.IP
.EX
PICFILE *pf = picopen_r("file");
extern char pixels[], green[][1000];
extern float zdepth[][1000];
for(i=0; picread(pf, pixels); i)
picunpack(pf, pixels, "_c_f", green[i], zdepth[i]);
.EE
.PP
Reflect a picture about its vertical midline.
.br
.ns
.IP
.EX
PICFILE *in = picopen_r("picture");
PICFILE *out = picopen_w("OUT", PIC_SAMEARGS(in));
int w = PIC_WIDTH(in);
int n = PIC_NCHAN(in);
char *buffer = malloc(w*n), *temp = malloc(n);
while (picread(in, buffer)) {
char *left = buffer;
char *right = buffer + n*(w - 1);
for( ; left<right; left+=n, right-=n) {
strncpy(temp, left, n);
strncpy(left, right, n);
strncpy(right, temp, n);
}
picwrite(out, buffer);
}
.EE
.SH SEE ALSO
.IR picfile (5),
.IR pico (1),
.IR bcp (1)
.SH DIAGNOSTICS
.I Picread
returns 1 on success, 0 on end of file or error.
.br
.I Picopen_r
and
.I picopen_w
return 0 for unopenable files.
.SH BUGS
.I Picpack
and
.I picunpack
store and retrieve floating point channels (types
.B f
and
.BR d )
using native floating-point, rather than something
machine independent like IEEE format.
|
