PICTools Programmer's Reference
OP_CAMERARAWE
| Operations > OP_CAMERARAWE |
OP_CAMERARAWE: Expand a RAW Digital Camera File
See the CAMERARAWE and REGION2 structure sections for additional information.
The purpose of OP_CAMERARAWE is to decompress RAW digital camera images. Images of this type are created by various digital cameras and, in most cases, represent data produced by the CCD with no additional processing. RAW digital camera images generally have more than 8 bits per sample and this opcode allows pixels to be returned as either 24 or 48 bits per pixel.
In this implementation of the opcode, REQ_INIT will read the image into an internal buffer and return the width and height. The caller will typically allocate a buffer to contain the decompressed image between calling REQ_INIT and REQ_EXEC. During REQ_EXEC, the opcode will copy the pixels from the internal buffer into the put queue.
Because most processing occurs during REQ_INIT, all parameters should be set to their desired value before calling REQ_INIT.
WhiteBalanceMethod can be set to one of several values to indicate the method used to balance the white: camera (0), automatic (1), and manual (2). In all cases, the RedFactor and BlueFactor manual white balancing parameters will also be applied to the pixels.
The camera (0) white balance method examines the raw file to determine the white balance information designated by the camera. If that information is not present or cannot be read, the opcode will change this setting to automatic (1) and proceed as if that was the original value.
The automatic (1) white balance method examines the image pixels and attempts to discern the best setting to balance the white.
The manual (2) white balance method does nothing and relies on the caller to set RedFactor and BlueFactor to do white balancing.
To perform manual white balancing (or to perform additional adjustment after camera or automatic white balancing), you can specify separate red and blue scaling factors. RedFactor and BlueFactor control this option. The green scaling factor is implicitly set to 1.0. Setting these factors to 0.0 or 1.0 will cause no additional balancing to be performed.
After balancing the white value, the opcode also allows the color values to be scaled by a user-selectable value. Set BrightnessFactor to control this scaling. 0.0 or 1.0 indicates no change to the values. Any other setting will modify the color values of each pixel by replacing each with the product of this parameter and the original pixel value. To effectively use this parameter, DoNotStretchColors should be set to 1.
After adjusting the white value, the opcode will normally constrain the range of each pixel. To turn off that constraint, set DoNotClipColors to 1. Otherwise leave it set to 0.
After all other color adjustments are done, the opcode will stretch the range of colors in the image to fill the sRGB color space, leaving some part of the image at or near white. To turn off that stretching, set DoNotStretchColors to 1. Otherwise leave it set to 0.
To retrieve the pixels in a form suitable for using as a DIB, add F_Bmp to PicFlags. To retrieve the pixels in a more flexible form, including having the ability to get 2-byte samples, add F_Raw to PicFlags.
By default, the opcode will produce pixels with 3 1-byte samples: red, green, and blue (24 bits per pixel with each sample ranging from 0 to 255.) If the RF_2Byte flag is added to Region.Flags, the opcode will produce pixels with 3 2-byte samples: red, green, and blue (48 bits per pixel with each sample ranging from 0 to 65,535.) The order of each 2-byte sample will be little-endian by default or big-endian if RF_BigEndian is added to Region.Flags. The default sample order is blue in the lowest-indexed address and red in the highest-indexed address. That order can be reversed by adding RF_SwapRB to Region.Flags. All of the flags in Region.Flags will be ignored if F_Bmp is added to PicFlags.
Normally, the opcode will convert RGB camera images to sRGB. To leave the camera images in their native RGB color space, set DoNotConvertTosRGB to 1. Otherwise, leave it set to 0.
To choose a fast interpolation method for constructing color pixels from the raw CCD data, set InterpolationMethod to 1. This will read and convert the image faster than the default method (0), but the quality will not be as good.
To return an image that has been reduced by half horizontally and vertically, set QuarterSizeImage to 1. This option is much faster than setting InterpolationMethod to 1, but the resolution will, of course, be only half.
To adjust the gamma of the pixels, set Gamma to the desired value. Using a value of 0.0 or 1.0 will cause no gamma correction to be applied.
In some cases, a faint 2x2 pattern will be visible in images. This pattern can be eliminated by setting FourColorRGB to 1. Otherwise, leave it set to 0.
If F_Crop is added to PicFlags, the opcode will return a subset of the image, as specified in CropWidth, CropHeight, CropXoff, and CropYoff.
Fuji Super CCD raw images are rotated 45 degrees due to the nature of the physical device used to capture the image. To leave the output image rotated like the input, set DoNotRemoveRotation to 1. Otherwise, leave it set to 0.
Fuji Super CCD SR images have two sets of pixels: a primary set and a less sensitive secondary set. Normally, this opcode will use the primary set, but the secondary set can be used by setting UseSecondaryPixels to 1. Otherwise, leave it set to 0.
Some RAW digital camera files contain thumbnail images. If PF_ExpandThumbnail is set in PicFlags and the file contains a thumbnail image then after REQ_INIT is called ThumbnailBuffer will point to the thumbnail image. ThumbnailLength will be the length of the image in bytes, and ThumbnailType will be set to one of the following: BI_picJPEG, BI_PGM, or BI_PPM. The ThumbnailBuffer is allocated in REQ_INIT by the opcode and deallocated in REQ_TERM by the opcode, the user does not need to do anything with this buffer.
If the RAW digital camera file contains metadata then this information will be returned after REQ_INIT in the form of P2PktTiffTags on the PIC2List.
When recognizing a file type (during REQ_INIT), the opcode will always determine the size of the file in the get queue. In situations where it is not certain that the file is a camera raw image and where it would be expensive to read through the entire get queue, a parameter is available so the length of the file may be specified. Simply set FileLength to the actual length of the file. If FileLength is zero, the opcode will scan through the get queue, looking for the length of the file. When it finds it, it will save the length in FileLength.
The opcode will attempt to determine the file type (during REQ_INIT) from the file header before using information outside of the header. The opcode will save the method of detection in DetectionMethod, which will be set to one of the following: DETECTION_METHOD_NONE, DETECTION_METHOD_HEADERLESS, DETECTION_METHOD_HEADER.