═══ 1. Introduction ═══ PMJPEG is a shareware image viewer with image processing and conversion capabilities for OS/2 2.x. PMJPEG is a port of WinJPEG to OS/2 2.x. PMJPEG v.1.30 has the following features: ■ display JPEG, GIF, TIFF, Targa, PCX, Windows BMP, or OS/2 BMP images ■ export an image to JPEG, GIF, TIFF, Targa, PCX, Windows BMP, or OS/2 BMP images ■ capability of generating 256-color OS/2 desktop-background bitmaps that use the system colors ■ display of 24-bit images with 1-pass/2-pass quantization and Floyd-Steinberg dithering ■ color balance: red, green, and blue adjustment ■ hue, saturation, and brightness adjustment ■ contrast enhancement ■ image rotation, vertical or horizontal flip, and image resizing ■ image cropping ■ batch file compression of GIF, TIFF, or TARGA files to JPEG File Interchange Format (JFIF) ■ copy an image to the clipboard ■ paste an image from the clipboard ■ slideshow: display selected files sequentially with a cycle option ■ image buffering in a cyclic slideshow ■ support for file name extension association and starting a slideshow from the command line In order to see images displayed with the right colors, you must use a version of OS/2 and a 256 color driver that support palette manager. Both OS/2 2.0 with the Service Pack and December 1992 OS/2 2.1 beta support palette manager. If you are using the 256 color ET4000 driver that comes with OS/2 2.1 beta, you'll notice that the image under the dialog box or under the drop-down menu is not re-drawn correctly. This is a bug in the ET4000 driver. Use the Auto-Refresh option if you have this problem. When you exit, the system colors may not return to normal. This appears to be a bug with the palette manager of the December 1992 OS/2 2.1 beta. However, the palette does appear to correct itself after you open and/or close a window, such as the window list. ═══ 2. JPEG ═══ Joint Photographic Experts Group (JPEG) refers to a still-picture compression standard that specifies several modes of operation. The mode used by the Independent JPEG Group's(IJPEG) software, which is incorporated into PMJPEG, is sequential buildup; in this mode, each component of an image is encoded in a left-to-right and top-to-bottom scan. Sequential mode is lossy, which means that when you compress an image, you will lose information. That is, when you decode the compressed image, the decoded image will not exactly match the original. One reason that sequential mode JPEG is lossy is that the algorithm compresses an image by removing visually insignificant information, colors that the human eye cannot detect. ═══ 3. Converting File Formats with PMJPEG ═══ Because most photographic images with 2 colors(monochrome) or 16 colors do not have decent fidelity, PMJPEG does not fully support these color modes. On the basis of the display mode, the image format, and PMJPEG options, PMJPEG will quantize or dither an image before displaying it. Regardless of these factors, when PMJPEG loads images stored in 1 or 4 bits per pixel, it will losslessly convert them to an 8 bits per pixel format. If you are using a 16 color display driver and you enable the "8-bit Bitmap" option, PMJPEG will quantize an image to 16 colors in some cases. We recommend that you do not use this color mode to convert images from one format to another. In 256 color video mode or better, with the "8-bit Bitmap" option enabled, all 24-bit images(i.e. 24 bits per pixel) are quantized to 256 colors before displaying them. With this option enabled, you can convert a 24-bit image to an 8-bit one. 1, 4, and 8-bit images are automatically stored in 8-bit format with no data loss and displayed. If you are converting a 24-bit image to a 24-bit output format in this color mode, you should turn off the "8-bit Bitmap" option before loading that image. The preceding conversion restrictions do not apply when using Batch Compression to compress images to JPEG format. They only apply when the Save option is used from the menu. If you are creating a bitmap to be used as a 256-color OS/2 desktop-background image, use the Map to System Colors function before saving the image as an OS/2 BMP file. If you are converting a 24-bit image to a 256-color OS/2 BMP, remember to turn of f the 8-bit Bitmap option before you load the image. The Map to System Colors feature forces the image to use the system colors defined by the OS/2 desktop. ═══ 4. Image File Formats ═══ o JPEG File Formats o TIFF o Graphics Interchange Format (GIF) o Targa o PCX o BMP ═══ 4.1. JPEG File Formats ═══ The JPEG committee has not specified a standard file format, and consequently, many applications of the JPEG algorithm use their own proprietary format. PMJPEG uses the JPEG File Interchange Format(JFIF) which transports only pixel information. JFIF is supported by the IJPEG Group's software and other programs based on their code. Handmade Software's GIF2JPG and Image Alchemy use a proprietary JPEG format that is not compatible with the JFIF standard. This proprietary format is not supported by PMJPEG. When you use GIF2JPG v.2.0, remember to leave out the "-s" option to produce a JPEG file that is compatible with the JFIF standard and viewable with PMJPEG. If you have to use a DOS converter, we recommend that you use the IJPEG Group's cjpeg program. Otherwise, you should use PMJPEG's Batch Compression feature, which performs the same task as cjpeg except that GIF, TIFF, and TARGA are the only formats supported. ═══ 4.2. Graphics Interchange Format (GIF) ═══ PMJPEG can view interlaced/non-interlaced GIF87a and GIF89a files, and it can save non-interlaced GIF87a files. If a GIF89a file contains more than one image, it will display the first image in the file. ═══ 4.3. Targa ═══ PMJPEG can view uncompressed TARGA files stored with 8, 15, 16, 24, or 32 bits per pixel and it can save uncompressed TARGA files with 8 or 24 bits per pixel. ═══ 4.4. PCX ═══ PMJPEG can view PCX files stored with 1, 4, 8, or 24 bits per pixel. If a 1, 4, or 8 bits per pixel PCX file does not have a valid palette, PMJPEG will use a default palette. It can save PCX Version 5.0 files with 8 or 24 bits per pixel. ═══ 4.5. BMP ═══ PMJPEG can view Windows and OS/2 (1.x and 2.0) BMP files stored with 1, 4, 8, or 24 bits per pixel and can view BMP files that are run-length encoded(RLE). It can save uncompressed Windows or OS/2 BMP files in 8 or 24 bits per pixel and can save BMP files with RLE. Note that some graphics viewers use the file extension ".RLE" for run-length encoded Windows BMP files. PMJPEG uses the ".BMP" extension as a default for such files. ═══ 4.6. Tagged Interchange File Format (TIFF) ═══ PMJPEG supports a subset of the TIFF 6.0 specification. PMJPEG can view TIFF files stored with 1, 2, 4, 8, or 24 bits per pixel. PMJPEG can read TIFF images stored in strip format, in which the image is divided into horizontal strips of pixels, and tile format, in which an image is divided into rectangular grids of pixels. The compression modes LZW, Packbits, Thunderscan, and CCITT(RLE,RLEW,FAX3,FAX4) can be read as well as uncompressed TIFF images. PMJPEG can save uncompressed or LZW compressed TIFF files with 8 or 24 bits per pixel. TIFF files are saved in strip format. ═══ 5. Menu Commands ═══ The menus are ordered by the following main topics: o File Menu o Edit Menu o Options ═══ 5.1. File Menu ═══ The File menu includes commands that enable you to open and save files, to batch convert files to JPEG, and to display multiple images in a selected order. o Open o Save o Save All Options o Delete o Batch Compression o Slide Show o Exit ═══ 5.1.1. File Open ═══ Select a file to display. The list boxes in the left column display the drives and the directories in the current path, and the list box in the right column displays the files in the current path. To display a file, click on a file from the file list and press "OK," or double click on the desired file. ═══ 5.1.2. File Save ═══ Select a file name to save the currently displayed image. The list boxes in the left column display the drives and the directories in the current path, and the list box in the right column displays the files in the current path. ═══ 5.1.3. Save All Options ═══ This will save all the PMJPEG options to a file named "pmjpeg.sav" in the same directory as the PMJPEG executable. When PMJPEG is initially loaded, the options will be loaded if "pmjpeg.sav" exists. ═══ 5.1.4. Delete ═══ This menu command lets you delete the file containing the currently displayed image. PMJPEG will prompt you for confirmation before deleting the file. ═══ 5.1.5. Batch Compression ═══ Select GIF, TIFF, and TARGA files to compress to JPEG format with the options specified in the JPEG Options dialog. The list boxes in the left column display the drives and the directories in the current path, the list box in the middle displays the files in the current path, and the one in the right displays a list of files to be converted. To add file(s) to the "Files Selected" box, select the file(s) you want to convert and press the "Add" button. To remove file(s) from this box, select the file(s) in this box and press the "Remove" button. The output file(s) will have the same name as the input file(s) except that they will have a ".jpg" extension. Also, the output file(s) will be placed in the same directory path in which the input file(s) were located. See also JPEG Options. ═══ 5.1.6. Slideshow ═══ Select the JPEG, TIFF, GIF, Targa, and BMP files to display in a slideshow. The order in which you add the files will be the order in which they are displayed. After a picture is loaded and displayed, if Automatic Slide Advancement is selected, there will be a user-selected delay before the next picture is loaded. To advance to the next picture before the delay has elapsed, click on the window with the right mouse button. If Manual Slide Advancement is selected, PMJPEG will wait until you click with the right mouse button before advancing to the next picture. If you would like the slideshow to continue from the beginning of the list after the last picture is displayed, check off the Cycle Slideshow menu option. To abort the slideshow, click on the window with the left mouse button, click on the "Yes" button in the confirmation dialog, and the slideshow will stop after the currently loading picture is displayed. See also Slideshow Options. ═══ 5.1.7. Exit ═══ Exit from PMJPEG. ═══ 5.2. Edit Menu ═══ The Edit menu includes commands that enable you to transfer images to and from the clipboard, change the color components of an image, and to manipulate the image. o Copy o Paste o Crop o HSV Adjustment o Color Balance o Contrast Enhancement o Grayscale o Grayscale o Rotate o Flip Horizontal o Flip Vertical o Resize ═══ 5.2.1. Copy ═══ Copy the entire image to the clipboard. ═══ 5.2.2. Paste ═══ Paste an image from the clipboard. ═══ 5.2.3. Crop ═══ If a region of the image is selected (see Selecting a Region to Crop), keep that region and discard the image outside of the selected region. ═══ 5.2.4. HSV Adjustment ═══ Use the scroll bars to adjust the amount of hue, saturation, and value/brightness in an image. A value of 0 on the scroll bar means that there is no change in the corresponding color component. When the value is increased or decreased, the color component is increased or decreased, respectively. ═══ 5.2.5. Color Balance ═══ Use the scroll bars to adjust the amount of red, green, and blue in an image. A value of 0 on the scroll bar means that there is no change in the corresponding color component. When the value is increased or decreased, the color component is increased or decreased, respectively. ═══ 5.2.6. Contrast Enhancement ═══ Use the scroll bar to adjust the amount of contrast in an image. A value of 0 on the scroll bar means that there is no change in the contrast. When the value is increased or decreased, the contrast is increased or decreased, respectively. ═══ 5.2.7. Grayscale ═══ Convert a color image into a grayscale one. ═══ 5.2.8. Map To System Colors ═══ Converts the displayed image to an image that has a 256-color palette containing the system colors of the OS/2 desktop. Use this option to generate an image that can be used as a 256-color OS/2 desktop-background image. ═══ 5.2.9. Rotate ═══ Rotate the image clockwise by 90 degrees. ═══ 5.2.10. Flip Horizontal ═══ Flip the image around the vertical axis. ═══ 5.2.11. Flip Vertical ═══ Flip the image around the horizontal axis. ═══ 5.2.12. Resize ═══ Change the spatial resolution of the displayed image. Common sizes such as 640x680, 800x600, 1024x768, and 1280x1024 can be easily selected. The Maximize Fit on Desktop option will resize the image into the largest possible window that will fit on the desktop while keeping the aspect ratio, the ratio between the original width and height. Also, a custom size can be manually entered. If Keep Aspect Ratio is enabled, only one dimension needs to be entered because the other one is automatically changed to maintain the aspect ratio. ═══ 5.3. Options Menu ═══ The Options menu includes commands that let you determine how other commands operate. The settings for the options can be saved with the Save All Options command. o 8-bit Bitmap o Display Old Image during Load o Move Window after Load o Auto-Refresh o JPEG Options o Slideshow Options ═══ 5.3.1. 8-bit Bitmap ═══ When you load a JPEG, 24-bit TIFF, 24-bit Targa, or 24-bit BMP image with this menu item checked, PMJPEG will quantize the number of colors to 256 before displaying the image. If this menu item is unchecked, the image will be loaded into a 24-bit bitmap with no quantization. ═══ 5.3.2. Display Old Image during Load ═══ If this option is checked, you can continue viewing the currently displayed image while another image is being loaded. However, this option will use more memory because PMJPEG has to maintain two images. Consequently, it may slow down the loading of the next image if PMJPEG runs out of physical memory and must use slower virtual memory. ═══ 5.3.3. Move Image after Load ═══ If this option is checked, the PMJPEG window is moved to the upper left-hand corner of the desktop after an image is loaded. ═══ 5.3.4. Auto-Refresh ═══ The purpose of this option is to provide a temporary solution to a bug in the 256 color drivers. This bug is evident when the area of the image under a drop-down menu or under a dialog box is not properly redrawn after the drop-down menu or the dialog, respectively, is closed. If this menu item is checked, PMJPEG will automatically refresh the image when it is necessary. ═══ 5.3.5. JPEG Options ═══ 2-pass(Heckbert) quantization produces better looking output than 1-pass quantization and it is slower. Also, 2-pass quantization uses more memory so it may be even slower because PMJPEG will swap to hard disk when it runs out of virtual memory. The output of 1-pass generally looks more grainy. Dithering uses available colors in a palette to simulate additional colors. The dithering method that PMJPEG uses is called Floyd-Steinberg Dithering. Dithering is useful when quantizing to 256 colors or less but it is not needed for a true-color (24-bit) display. You may want to turn off dithering since it sometimes causes a grainy output image. The Quality Factor, an integer between 0 and 100 inclusive, determines the tradeoff between the output file size and the output image quality. If you choose a high quality factor, the image quality will be high but the file size will be large. A lower quality setting will yield a smaller file at a cost of lower fidelity. Since the JPEG algorithm is lossy, a quality factor of 100 will not give you a losslessly compressed image. The Smoothing Factor, also an integer between 0 and 100 inclusive, determines the degree of smoothing to apply to an image before compressing that image with JPEG. The higher you set the factor, the higher the degree of smoothing that is applied. A smoothing factor of 0 means that no smoothing is performed. Smoothing removes noise introduced when an image is dithered, and, in turn, smoothing produces a smaller JPEG file. It should be used for only dithered images, like photographic GIF pictures. Generally, a factor between 10 and 50 removes the dithering noise from an image. Entropy Optimization produces a smaller JPEG file but it takes more time to encode the image. If PMJPEG runs out of virtual memory while it is decoding/encoding JPEG files, it will use temporary files that are created in the specified path. ═══ 5.3.6. Slideshow Options ═══ When a slideshow is running, the Cycle Slideshow option determines whether or not a list of images are continuously displayed in a cycle. If this option is on, the slideshow returns back to the first picture after the last one is displayed and continues to display all the images in a selected list until you abort the slideshow. The Slide Advancement options determine how to advance to the next image in a slideshow. In Manual mode, PMJPEG will wait until you click with the right mouse button before advancing to the next picture. In Automatic mode, there will be a user-selected time delay before the next picture is loaded. To advance to the next picture before the delay has elapsed, click on the window with the right mouse button. The Delay can be set to a value between 0 and 999 seconds. The Buffer Image Formats options allow buffering of selected image formats during a cyclic slideshow. If a type is selected, all images of that type are stored in memory after they are loaded and decompressed, and they will not be loaded/decompressed the next time they are displayed. This feature must be used in conjunction with the Cycle Slideshow option. Buffering images can use a lot of memory; if you don't have much physical memory, be certain that there is enough disk space on OS/2's swap drive to handle this memory usage. ═══ 5.3.7. Progress Options ═══ For time-consuming tasks like loading, saving, batch compressing, and mapping to system colors, PMJPEG displays a percentage that indicates how much of the task has been completed. The progress can be displayed in either a dialog box or the title bar of the PMJPEG window. ═══ 6. Selecting a Region to Crop ═══ To select a region of the image, click on the image with the left mouse button. While holding down that button, move your mouse until the rectangle surrounds the desired region, and then release the mouse button. The dimensions of the selected region are displayed in the center of the indicated region. ═══ 7. How to Register ═══ If you use PMJPEG for more than 14 days, you are expected to register PMJPEG. When you register, you will receive the latest version of PMJPEG, a user manual, and a collection of JPEG images (we will put as many as we can fit on 2 720k 3 1/2" floppies, on 1 1.44M 3 1/2" floppy, or on 4 360k 5 1/4" floppies). Also, the registered version does not have the reminder-to-register screen at the start. The registration fee is only $20. MA residents, add 5% sales tax to the registration fee. US residents, add $3 for shipping and handling; non-US residents, add $8 for shipping and handling. If you want PMJPEG e-mailed to your account instead of having it physically mailed to you, there is no extra shipping charge. Updates are free but the shipping charge described above applies to updates. Users who register PMJPEG and provide an e-mail address will automatically receive updates via e-mail. For e-mail registrations, you need to use a program called "uudecode" to decode the uuencoded file that we e-mail to you. For your information, a uuencoded file is a binary file that is converted to text by a program called "uuencode". If your mail system rejects large messages, we will split the uuencoded file into smaller parts before mailing the parts to you, and you will need to edit the messages with a text editor before you can decode them. Compuserve, for example, does not permit large e-mail messages. Also, the uuencoded file is rather large; it is approximately 300k for PMJPEG v.1.3. Compuserve users may find it less expensive to receive PMJPEG via U.S. Mail. Registrations with the incorrect fee or with non-US currency will be returned. To register, complete the order form and send a check in US funds to: Norman Yee 58 Chandler St. Boston, MA 02116 Registration of PMJPEG is based on "personal usage." Corporate or organizational users must register all copies used on an individual basis; a specific person (name) must be explicitly assigned to each registrant who will be provided with a personalized copy of PMJPEG. Registration grants a specific person (not an organization or corporate entity) the right to use PMJPEG. Although we will try to mail your copy of PMJPEG 1-3 weeks after we receive your registration, please allow up to 4-6 weeks for delivery. ═══ 8. Reporting Bugs ═══ If you find a bug in PMJPEG, we would appreciate it if you would inform us of the bug through one of our e-mail accounts: Norman Yee nyee@osiris.ee.tufts.edu Ken Yee kenyee@ksr.com When you send us a bug report, include a description of the procedure for reproducing the bug and a description of your system configuration(hardware and software). ═══ 9. License Agreement (applicable to registered users) ═══ You are licensed to single-copy use of PMJPEG; this means that you can install your registered version of PMJPEG simultaneously on one computer at work, one computer at home, and one portable computer, if only one copy is in use by the registered individual at a time. You may make copies of the registered PMJPEG disk as necessary for normal backup purposes; you agree not to make any copies of the printed PMJPEG manual or the registered version of PMJPEG for others. ═══ 10. Disclaimer ═══ The authors of this program accept no responsibility for damages that are caused by this program and make NO WARRANTY or representation, either express or implied, with respect to this software. This software is provided "AS IS," and you, its user, assume the entire risk when you use it. ═══ 11. Acknowledgments ═══ PMJPEG is based in part on the work of the Independent JPEG Group. TIFF support in PMJPEG is based in part on Sam Leffler's TIFF library. System Color Mapping is based in part on the PBMPLUS library. Windows is a trademark of Microsoft Corporation. OS/2 is a trademark of International Business Machines Corporation. The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated. GIF2JPG and Image Alchemy are trademarks of Handmade Software, Inc. WinJPEG is copyright (C) 1992, 1993, Norman Yee and Ken Yee. All rights reserved. PMJPEG is copyright (C) 1993, Norman Yee and Ken Yee. All rights reserved. o Copyright Notice for Sam Leffler's TIFF Library o Copyright Notice for PBMPLUS Library ═══ 11.1. Copyright Notice for Sam Leffler's TIFF Library ═══ Copyright (c) 1988, 1989, 1990, 1991, 1992 Sam Leffler Copyright (c) 1991, 1992 Silicon Graphics, Inc. Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that (i) the above copyright notices and this permission notice appear in all copies of the software and related documentation, and (ii) the names of Sam Leffler and Silicon Graphics may not be used in any advertising or publicity relating to the software without the specific, prior written permission of Sam Leffler and Silicon Graphics. ═══ 11.2. Copyright Notice for PBMPLUS ═══ Copyright (C) 1991 by Bill Davidson and Jef Poskanzer. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty.