![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to picfile.ms CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / vol2 / graphics|
Return to picfile.ms CVS log | Up to [Research Unix] / researchv10dc / vol2 / graphics |
1.1 ! root 1: .so ../ADM/mac ! 2: .XX 36 571 "A Research Picture File Format and I/O Library" ! 3: .fp 5 T CW \" T for Typewriter ! 4: .TL ! 5: A Research Picture File Format and I/O Library ! 6: .AU ! 7: Tom Duff ! 8: Don Mitchell ! 9: .AI ! 10: .MH ! 11: .SP ! 12: .2C ! 13: .NH ! 14: Introduction ! 15: .PP ! 16: Researchers in centers 1122, 1125 and 1127 have for several years used ! 17: a general file format for storing digital images, ! 18: depth maps, mattes, and other two-dimensional digital signals. ! 19: We have a convenient, portable library of C-language functions for ! 20: manipulating picture files and a rapidly growing collection of graphics ! 21: and image-processing software that uses the picfile format and library. ! 22: .1C ! 23: .KF bottom ! 24: .P1 0 ! 25: TYPE=dump ! 26: WINDOW=0 0 512 512 ! 27: NCHAN=1 ! 28: CHAN=m ! 29: COMMAND= antiquantize 'halftone CLASSIC' 512.halftone LIBERTY.anticlassic ! 30: COMMAND= halftone CLASSIC 512.liberty 512.halftone 1.75 512.halftone ! 31: COMMAND= transpose IN OUT ! 32: COMMAND= resample 512 IN OUT ! 33: COMMAND= transpose IN OUT ! 34: COMMAND= resample 512 IN OUT ! 35: COMMAND= clip 400 400 LIBERTY OUT ! 36: .P2 ! 37: .ce ! 38: Figure 1 ! 39: .KE ! 40: .2C ! 41: .NH ! 42: The File Format ! 43: .PP ! 44: A picture file (often called a `picfile') contains a variable-length ascii header ! 45: followed by a optional color-look-up table ! 46: and binary data representing a two-dimensional array of multi-byte pixels. ! 47: .PP ! 48: The header is a list of attribute/value pairs ! 49: separated by newlines, terminated by an ! 50: empty line. A pure ascii header is ! 51: machine independent. ! 52: Its open-ended form allows applications to annotate pictures ! 53: any way that they wish. Figure 1 shows a typical header. ! 54: Each header line is of the form ! 55: .I `attribute=value' ! 56: where ! 57: .I attribute ! 58: is any string not containing an equal sign `=', an ascii nul (zero byte), or a ! 59: newline, and ! 60: .I value ! 61: is any string not containing a newline or nul. The newline-terminated ! 62: entries are separated from the binary data by an empty line (i.e. a pair of newlines). ! 63: Thus, ! 64: .P1 0 ! 65: sed '/^$/q' \fIfilename\fP ! 66: .P2 ! 67: will print a picfile's header. ! 68: .PP ! 69: Several attributes are mandatory. ! 70: The ! 71: .CW TYPE ! 72: attribute ! 73: .I must ! 74: come first, ! 75: acting as a ``magic number'' and specifying the binary encoding of the ! 76: image data. Currently, five binary formats are supported: ! 77: .IP \fTTYPE=dump\fP 5n ! 78: .br ! 79: The binary data follows in traditional scan-line order. ! 80: The first pixel in the file is at the upper left corner of ! 81: the image. ! 82: .I X ! 83: coordinates increase to the ! 84: .I right ! 85: on a ! 86: display, and ! 87: .I y ! 88: coordinates increase ! 89: .I down. ! 90: Pixels are stored in row-major order (i.e., ! 91: .I x ! 92: increases faster than ! 93: .I y ). ! 94: .IP \fTTYPE=runcode\fP ! 95: .br ! 96: Each pixel is preceded by a one-byte count that indicates how many adjacent ! 97: pixels have the given value. Count ! 98: values of 0 to 255 represent a replication factor of 1 to 256. No ! 99: run may extend from one scan-line to the next. ! 100: This format is useful in reducing the size of mattes or pictures containing ! 101: large areas of constant color, but it may be a poor choice for digitized ! 102: natural images or pictures containing noise. ! 103: .IP \fTTYPE=bitmap\fP ! 104: .br ! 105: Pixels are one bit each, packed ! 106: 8 bits to a byte, with the leftmost pixel in the high-order bit of ! 107: the first byte. Each row must be an even number of bytes, ! 108: so there can be up to 15 zero bits after the right-most pixel. ! 109: A bit value of 1 represents black; 0 represents white. ! 110: This is exactly the encoding used by SUN Microsystems and compatible ! 111: manufacturers. ! 112: .IP \fTTYPE=ccitt-g4\fP ! 113: .br ! 114: A black-and-white image encoded according to the CCITT FAX Group 4 standard. ! 115: This is highly compressive on printed text and sparse line-graphics. ! 116: .IP \fTTYPE=ccir601\fP ! 117: .br ! 118: The image is encoded according to the IEEE digital component video standard. ! 119: (Y,U,V) values are stored as 8-bit values with chrominance compressed to half ! 120: as much bandwidth as luminance. The layout of each row is ! 121: Y U Y V Y U Y V ... ! 122: .LP ! 123: The other mandatory attribute is: ! 124: .IP "\fTWINDOW=\fIx0 y0 x1 y1\fR" ! 125: .br ! 126: Specifies the size of the image by the ! 127: coordinates ! 128: .I "(x0, y0) ! 129: of the upper left ! 130: corner of the picture and ! 131: .I "(x1, y1) ! 132: of the pixel one beyond the lower right. ! 133: The C interface uses ! 134: .I "x0, y0, width, height ! 135: to avoid confusion about whether ! 136: the corner is in or out of the picture. ! 137: .LP ! 138: For ! 139: .CW TYPE=dump ! 140: and ! 141: .CW TYPE=runcode , ! 142: the following attribute is mandatory: ! 143: .IP \fTNCHAN=\fInbytes\fR ! 144: .br ! 145: Specifies the number of bytes in each pixel. ! 146: .CW TYPE=bitmap ! 147: and ! 148: .CW TYPE=ccitt-g4 ! 149: may optionally take ! 150: .CW NCHAN=1 , ! 151: and ! 152: .CW TYPE=ccir601 ! 153: may optionally take ! 154: .CW NCHAN=3 . ! 155: .LP ! 156: It is conventional but not mandatory to include: ! 157: .IP "\fTCHAN=\fIformat\fR" ! 158: .br ! 159: Specifies the internal structure ! 160: of a pixel. ! 161: .I Format ! 162: is a string of length equal to the value of ! 163: .CW NCHAN . ! 164: For example: ! 165: .RS ! 166: .IP \fTCHAN=rgb\fP\ \ ! 167: 24-bit red-green-blue pixel. ! 168: .IP \fTCHAN=rgbz...\fP\ \ ! 169: 24-bit red, green and blue ! 170: entries and a 32-bit depth ! 171: value (floating point). ! 172: .IP \fTCHAN=m\fP\ \ ! 173: 1-byte monochrome or ! 174: color mapped values. ! 175: .RE ! 176: The picfile routines specified here do ! 177: not care how the user names channels. ! 178: However, there are some conventions: ! 179: .RS ! 180: .IP \fTrgb\fP ! 181: red, green, and blue channels ! 182: .IP \fTyiq\fP ! 183: NTSC luminance/chrominance channels ! 184: .IP \fTyuv\fP ! 185: IEEE or PAL luminance/chrominance channels ! 186: .IP \fTa\fP ! 187: alpha channel (matte) ! 188: .IP \fTm\fP ! 189: monochrome or mapped value ! 190: .IP \fTf...\fP ! 191: dots indicate a ! 192: multiple-byte channel (e.g. a floating-point number) ! 193: .RE ! 194: .IP "\fTCOMMAND=\fIcommand line\fR" ! 195: .br ! 196: Store picfile history information. ! 197: Multiple ! 198: .CW COMMAND ! 199: entries may be present in the header. ! 200: The first is the command line used to make ! 201: this picture, and following it are the ! 202: .CW COMMAND ! 203: entries (indented by one space) from ! 204: all picfiles opened before this header ! 205: was written. ! 206: The header in Figure 1 shows ! 207: a picture clipped to 400\(mu400, digitally ! 208: resampled to 512\(mu512, converted to bitmap ! 209: by a halftone screen, and then converted ! 210: back to gray-level by Wiener-filter ! 211: reconstruction. ! 212: .IP "\fTRES=\fIxres yres\fR" ! 213: .br ! 214: Specifies the horizontal and vertical resolution in pixels per inch. ! 215: This attribute is often used for images of documents. ! 216: .IP \fTCMAP=\fP ! 217: .br ! 218: The ! 219: .CW CMAP ! 220: attribute has no value associated with it. It flags ! 221: the presence of a color-look-up table after the header. ! 222: This table is 768 bytes long and consists of 256 values of red, green, ! 223: and blue. ! 224: The bytes of the ! 225: colormap are stored as rgbrgbrgb... ! 226: .LP ! 227: The colormap should be loaded into the frame buffer's ! 228: colormap when the image is displayed. ! 229: The mapping from pixel channels to colormap values ! 230: in a full-color (e.g. ! 231: .CW CHAN=rgb ) ! 232: picture is usually: ! 233: .P1 0 ! 234: displayed red = colormap[3*r + 0] ! 235: displayed green = colormap[3*g + 1] ! 236: displayed blue = colormap[3*b + 2] ! 237: .P2 ! 238: In a monochrome picture, channel ! 239: .CW m ! 240: is normally mapped: ! 241: .P1 0 ! 242: displayed red = colormap[3*m + 0] ! 243: displayed green = colormap[3*m + 1] ! 244: displayed blue = colormap[3*m + 2] ! 245: .P2 ! 246: Applications may add other header lines. It is perfectly ! 247: permissible to include ! 248: .CW SHOESIZE=10 ! 249: in the header, which all ! 250: standard software will pass uninterpreted. ! 251: .PP ! 252: Following the ASCII header and the optional colormap is the ! 253: binary data for the image. ! 254: The routines described below assume nothing about this data ! 255: except what is specified by ! 256: .CW TYPE , ! 257: .CW WINDOW ! 258: and ! 259: .CW NCHAN . ! 260: .PP ! 261: Pixels ! 262: .I N ! 263: bytes long, where ! 264: .I N ! 265: is the value of the ! 266: .CW NCHAN ! 267: attribute. ! 268: .I Picread ! 269: and ! 270: .I picwrite , ! 271: described below, do not interpret pixel values, except for conversion to ! 272: a uniform format. ! 273: Higher level software must assign format and meaning to ! 274: pixels and specify byte ordering ! 275: of short or long integers and the format of floating point data. ! 276: .NH ! 277: The Picfile Library ! 278: .PP ! 279: Picture files are referred to by a pointer to a ! 280: .I PICFILE ! 281: data structure, ! 282: analogous to the standard I/O library's ! 283: .I FILE ! 284: structure. There ! 285: are just a few routines for opening, reading and writing ! 286: picture files one scan line at a time. To use them, a program ! 287: must include the header file ! 288: .CW picfile.h . ! 289: On 10th edition ! 290: .UX ! 291: systems this file is in ! 292: .CW /usr/include . ! 293: On center 1125's SUNs it may for ! 294: administrative reasons be found elsewhere. ! 295: .P1 0 ! 296: PICFILE * picopen_r(char *filename); ! 297: .P2 ! 298: .P1 0 ! 299: PICFILE * picopen_w(char *filename, ! 300: char *type, int x0, int y0, ! 301: int width, int height, char * ! 302: chan, char *argv[], char *cmap); ! 303: .P2 ! 304: .I Picopen_r ! 305: opens a picture file for reading; ! 306: .I picopen_w ! 307: opens it for writing. ! 308: For both routines, ! 309: .I filename ! 310: is usually a name of a ! 311: .UX ! 312: file. ! 313: Some implementations may treat certain names specially, ! 314: although this not part of the standard for now. ! 315: The current implementation reserves the names ! 316: .CW OUT ! 317: and ! 318: .CW IN ! 319: to mean standard output and input. ! 320: .PP ! 321: For ! 322: .I picopen_w , ! 323: .I type ! 324: is the value of the ! 325: .CW TYPE ! 326: attribute (e.g., ! 327: .CW dump , ! 328: .CW runcode , ! 329: etc.) ! 330: .PP ! 331: .I X0 ! 332: and ! 333: .I y0 ! 334: are the coordinates of the upper left corner of the image. ! 335: .I Width ! 336: and ! 337: .I height ! 338: are the size of the image. ! 339: .I Chan ! 340: is a string (e.g. ! 341: .CW rgb , ! 342: or ! 343: .CW m , ! 344: or ! 345: .CW rgbaz... ) ! 346: giving the ! 347: value of the ! 348: .CW CHAN ! 349: attribute and, by implication, ! 350: .CW NCHAN , ! 351: which is always the string length of ! 352: .I chan. ! 353: .PP ! 354: If nonzero, ! 355: .I argv ! 356: is the second ! 357: argument of ! 358: .I main . ! 359: This passes information to the picture file routines ! 360: that allow them to construct the ! 361: .CW COMMAND ! 362: attributes that maintain history ! 363: information. It is strongly advised that users provide this pointer so ! 364: proper history can be kept in picture files. ! 365: .PP ! 366: If non-zero, ! 367: .I cmap ! 368: points at a color-look-up table. ! 369: .PP ! 370: Once a picfile has been opened, I/O can be performed by the routines ! 371: .P1 0 ! 372: int picread(PICFILE *pid, char *buffer); ! 373: ! 374: int picwrite(PICFILE *pid, char *buffer); ! 375: .P2 ! 376: .I Buffer ! 377: must be large enough to hold one row of the ! 378: image (i.e., picture width times number of bytes per pixel). These ! 379: routines read or write one row of an image, ! 380: returning 1 if successful and 0 if error or end-of-file. ! 381: .PP ! 382: If an image has ! 383: .CW TYPE=runcode , ! 384: .I picread ! 385: and ! 386: .I picwrite ! 387: will do the run-length ! 388: decoding and encoding. If ! 389: .CW TYPE=bitmap ! 390: or ! 391: .CW TYPE=ccitt-g4 , ! 392: .I picread ! 393: will unpack each row of the image into one byte per pixel (with values of 0 or 255), and ! 394: .I picwrite ! 395: will pack the pixels back into one bit each by a threshold ! 396: test (1 if pixel < 128, otherwise 0). ! 397: .CW TYPE=ccir601 ! 398: files are unpacked and converted into ! 399: .CW CHAN=rgb ! 400: format, ! 401: so that they can be processed by programs designed for conventional ! 402: color images. ! 403: .I Picread ! 404: and ! 405: .I picwrite ! 406: do these conversions so that programs ! 407: need not be greatly concerned with which image ! 408: type is being used. ! 409: The idea is to make all encodings look like ! 410: the simplest, ! 411: .CW TYPE=dump . ! 412: .PP ! 413: A picfile can be closed by ! 414: .P1 0 ! 415: void picclose(PICFILE *pid); ! 416: .P2 ! 417: .I Picclose ! 418: closes the file descriptors and frees allocated memory associated with the picture file. ! 419: .PP ! 420: After calling ! 421: .I picopen_w , ! 422: but before the first call to ! 423: .I picwrite ! 424: (at which time the header is written out), ! 425: users may add or change attribute values by calling ! 426: .P1 0 ! 427: PICFILE *picputprop(PICFILE *pid, ! 428: char *name, char *value); ! 429: .P2 ! 430: .I Picputprop ! 431: adds the attribute ! 432: .I name=value ! 433: to the picture file. The modified picfile descriptor is returned. ! 434: .P1 0 ! 435: char *picgetprop(PICFILE *pid, char *name); ! 436: .P2 ! 437: .I Picgetprop ! 438: returns the value of the named attribute of a picfile descriptor, ! 439: or a zero (\fINULL\fP) pointer if absent. ! 440: .PP ! 441: Attributes such as ! 442: .CW COMMAND ! 443: sometimes appear more than once in a header, ! 444: as in the example at the start of section 2. ! 445: .I Picgetprop ! 446: and ! 447: .I picputprop ! 448: treat these as a single attribute-value pair, with newline characters ! 449: delimiting the sequence of values. ! 450: .PP ! 451: There are macros defined in ! 452: .CW picfile.h ! 453: to extract commonly-used ! 454: numeric attributes from picfiles. Each of the following returns an integer value: ! 455: .P1 0 ! 456: PIC_NCHAN(pid) /* value of NCHAN */ ! 457: PIC_WIDTH(pid) /* picture width */ ! 458: PIC_HEIGHT(pid) /* picture height */ ! 459: .P2 ! 460: Other attributes should be accessed using ! 461: .I picgetprop ! 462: and not by inspecting the ! 463: .I PICFILE ! 464: data structure, which may change in the future. ! 465: .PP ! 466: The call ! 467: .P1 0 ! 468: pid2=picopen_w(name, PIC_SAMEARGS(pid1)); ! 469: .P2 ! 470: will create a picture with the same arguments as a previously opened picture. ! 471: The ! 472: .I PIC_SAMEARGS ! 473: macro includes argv in the argument list, so that variable ! 474: must be defined at the point of call. ! 475: .PP ! 476: While not directly related to picture file I/O, the following two routines ! 477: can assist some application programs which deal with complex pixel definitions. ! 478: .P1 0 ! 479: void picunpack(PICFILE *pid, char *pixels, ! 480: char *format[, void *chan_ptr] ...); ! 481: ! 482: void picpack(PICFILE *pid, char *pixels, ! 483: char *format[, void *chan_ptr] ...); ! 484: .P2 ! 485: .I Picunpack ! 486: takes ! 487: an array of pixels (as produced by ! 488: .I picread ) ! 489: and extracts channels into separate arrays of types specified by ! 490: .I format . ! 491: Similarly, ! 492: .I picpack ! 493: copies data from various channel arrays and packs ! 494: them into a single array of pixels (as expected by ! 495: .I picwrite ). ! 496: .LP ! 497: Characters in ! 498: .I format ! 499: can be: ! 500: .IP \fTc\fP ! 501: read or write a one-byte channel. The corresponding ! 502: .I channel_pointer ! 503: must be of type ! 504: .I char ! 505: (or ! 506: .I "unsigned char" ). ! 507: .IP \fTs\fP ! 508: read or write a two-byte channel. The corresponding ! 509: .I channel_pointer ! 510: must be of type ! 511: .I short . ! 512: .IP \fTl\fP ! 513: read or write a four-byte channel. The corresponding ! 514: .I channel_pointer ! 515: must be of type ! 516: .I long . ! 517: .IP \fTf\fP ! 518: read or write a four-byte channel. The corresponding ! 519: .I channel_pointer ! 520: must be of type ! 521: .I float . ! 522: .IP \fTd\fP ! 523: read or write an eight-byte channel. The corresponding ! 524: .I channel_pointer ! 525: must be of type ! 526: .I double . ! 527: .IP \fT_\fP ! 528: underscore indicates a byte in the pixel should be skipped. ! 529: .PP ! 530: For example, in a picture with ! 531: .CW CHAN=rgbz... , ! 532: an unpacking of the ! 533: green channel and the z channel would be done as follows: ! 534: .P1 ! 535: PICFILE *pid; ! 536: char *pixels, *green; ! 537: float *zdepth; ! 538: picread(pid, pixels); ! 539: picunpack(pid, pixels, "_c_f", ! 540: green, zdepth); ! 541: .P2 ! 542: By using ! 543: .I picpack ! 544: and ! 545: .I picunpack , ! 546: the user also benefits from the standard ! 547: machine-independent byte ordering that these routines will specify ! 548: for ! 549: .I short ! 550: and ! 551: .I long ! 552: type date. Data of type ! 553: .I float ! 554: should also be standardized to use IEEE floating point format, but that ! 555: is not being done now, so as not to inconvenience users of ! 556: non-IEEE hardware. ! 557: .PP ! 558: Random-access routines such as ! 559: .I picseek ! 560: and ! 561: .I pictell ! 562: have not been ! 563: included in order to encourage the development of ! 564: .UX -style ! 565: tool programs which can be combined with pipes. For example, ! 566: using currently existing tools, a picture file can be resampled ! 567: to 320\(mu256 as follows: ! 568: .P1 ! 569: resample 320 pfile1 OUT | ! 570: transpose IN OUT | ! 571: resample 256 IN OUT | ! 572: transpose IN pfile2 ! 573: .P2 ! 574: .NH ! 575: Example Program ! 576: .PP ! 577: Figure 2 shows a complete sample program. ! 578: .1C ! 579: .KF ! 580: .P1 0 ! 581: /* reflect a picture about horizontal median */ ! 582: #include <picfile.h> ! 583: ! 584: main(int argc, char *argv[]) ! 585: { ! 586: PICFILE *in, *out; ! 587: register char *left, *right, channel; ! 588: char *buffer, *malloc(); ! 589: int i; ! 590: ! 591: if (argc != 3) ! 592: usage("reflect infile outfile"); ! 593: in = picopen_r(argv[1]); ! 594: if (in == 0) { ! 595: perror(argv[1]); ! 596: exit(1); ! 597: } ! 598: out = picopen_w(argv[2], PIC_SAMEARGS(in)); ! 599: if (out == 0) { ! 600: perror(argv[2]); ! 601: exit(2); ! 602: } ! 603: buffer = malloc(w*n); ! 604: while (picread(in, buffer)) { ! 605: left = buffer; ! 606: right = buffer + n*(w - 1); ! 607: while (left < right) { ! 608: for (i = 0; i < n; i++) { ! 609: channel = *left; ! 610: *left++ = *right; ! 611: *right++ = channel; ! 612: } ! 613: right -= n + n; ! 614: } ! 615: picwrite(out, buffer); ! 616: } ! 617: exit(0); ! 618: } ! 619: .P2 ! 620: .sp ! 621: .ce ! 622: Figure 2 ! 623: .KE ! 624: .2C ! 625: .NH ! 626: Acknowledgements ! 627: .PP ! 628: We would like to thank John Amanatides, Jon Helfman and Bob Safranek for ! 629: there comments and experiences with this picture format. ! 630: .PP ! 631: The highly complex CCITT FAX format was implemented by Henry Baird.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.