LibRaw: Usage Examples[back to Index]

LibRaw: Usage Examples

Overview of Examples in the Distribution Package (samples/*)

The LibRaw package contains several examples illustrating the use of this library. Their source codes are located in the samples/ folder, and after library build they will be in the bin/ folder:

• raw-identify The only LibRaw call it uses is open_file(); further code prints the values of the fields of the imgdata structure.
  raw-identify -v provides extensive dump of metadata/
  Command line key -u shows unpacking function name, while -u -f prints function name and masked are sizes.
  raw-identify -w will print white balance tables stored in RAW file.
• simple_dcraw A simple "emulation" of dcraw reproducing the behavior of dcraw [-e] [-v] [-T].  A simplified version of this example is considered below.
  -B command-line switch turns on use of open_buffer() API call used via mmap() of input file (Unix only).
• dcraw_half Demonstrates the use of C API. The example emulates the behavior of dcraw -h (no other control parameters can be specified in this example).
• dcraw_emu Almost complete emulation of dcraw (except for keys -D -d -E -i -v -e, which are considered in other usage examples). Of most interest is processing of command line keys (copied from dcraw).
  

  This sample supports additional command-line parameters absent in original dcraw:

  -mmap

  Use open_buffer() interface. Buffer prepared by mmap() call. This option not supported under Win32.

  -meme

  Use open_buffer() interface. Buffer prepared by malloc()+read() calls.

  -c float-value

  This key sets params.adjust_maximum_thr parameter.
  Use -c 0 to completely disable automatic maximum calculation.
  Default value: 0.75

  -timing

  Turns on detailed timing print.

  -G

  Turns on "green_matching" mode to suppress color mazes on cameras with different green channels.

  -B x y w h

  Crops output to rectangle with width w, height h and x,y coordinates of left upper corner. All coordinates applied before any image rotation.

  -F

  Will use FILE I/O (bigfile_datastream) instead on standard LibRaw_file_datastream.

  -dcbi N

  Sets number of additional DCB-demosaic iterations (option valid only for -q 4, i.e. for DCB demosaic).

  -dcbe

  Turns on DCB color enhance mode (only for DCB demosaic, -q 4).

  -aexpo e p

  Turns on exposure correction. e is exposure shift in linear scale from 0.25 (darken 2 stops) to 8.0 (lighten 3 stops). p is highlights preservation amount from 0.0 (no preservation, full clipping) to 1.0 (full preservation, S-like curve in highlights).

  -apentax4shot

  Will merge 4 frames from Pentax 4-shot RAWs

  -apentax4shotorder abce

  Order of frames in pentax 4-shot files (default is 3102)

  -mmap

  Use mmap + memory IO instead of file IO (unix only)

  -disars

  Disable RawSpeed library (if compiled with this library)

  -doutputflags N

  set imgdata.params.output_flags to N

  -disinterp

  Do not run interpolation step

  -dsrawrgb1

  Disable YCbCr to RGB conversion for sRAW (Cb/Cr interpolation enabled)

  -dsrawrgb2

  Disable YCbCr to RGB conversion for sRAW (Cb/Cr interpolation disabled)

• half_mt Emulation of dcraw -h. It "understands" the following keys: -a (automatic white balance over the entire image), -w (white balance of the camera), -T (output in the tiff format), and -J n (number of parallel threads launched for image processing).
  On multiprocessor/multicore computers, the speed gain is notable in the case of mass processing. On a Win32 machine, the example is assembled from the initial file half_mt_win32.c, since work with threads under Windows is fundamentally different and it it easier to copy simple source codes than write one complex code.
• mem_image This sample uses dcraw_make_mem_image and dcraw_make_mem_thumb calls, than writes data in PPM format.
• unprocessed_raw This sample extracts (mostly) unaltered RAW data including masked pixels data (on supported cameras). If black frame exists and black frame extraction is supported for given format, masked pixels data is added to resulting .TIFF file. Command line options: -q - be quiet, -A - autoscale data (integer multiplier), -g gamma-correction (gamma 2.2) for data (instead of precise linear one), -B turns on black level subtraction
• 4channnels - splits RAW-file into four separate 16-bit grayscale TIFFs (per RAW channel).
  Command line switches:
  • -s N selects N-th image from RAW with multiple images
  • -g gamma correction (gamma 2.2)
  • -A values autoscale by auto-calculated integer factor
  • -B turn off black subtraction
  • -N no RAW curve
• multirender_test - very simple example of multiple rendering on one file without reopen.
• postprocessing_benchmark - will print timings of RAW processing steps

Example of docmode

Below we consider the samples/simple_dcraw.cpp example, which emulates the behavior of dcraw [-e][-v][-t]. To save space, let us assume that keys -t -v are always specified (to avoid comments on command line parsing) and there is always one parameter (name of file), which is the only one and always passed to the program.

int main(int ac, char *av[])
{
 int i, ret, verbose=0, output_thumbs=0;
 char outfn[1024],thumbfn[1024];
 // Creation of image processing object
 LibRaw RawProcessor;
 // The date in TIFF is written in the local format; let us specify the timezone for compatibility with dcraw
 putenv ((char*)"TZ=UTC");
// Let us define variables for convenient access to fields of RawProcessor
#define P1 RawProcessor.imgdata.idata
#define S RawProcessor.imgdata.sizes
#define C RawProcessor.imgdata.color
#define T RawProcessor.imgdata.thumbnail
#define P2 RawProcessor.imgdata.other
#define OUT RawProcessor.imgdata.params
 OUT.output_tiff = 1; // Let us output TIFF
 // Let us open the file
 if( (ret = RawProcessor.open_file(av[1])) != LIBRAW_SUCCESS)
 {
 fprintf(stderr,"Cannot open %s: %s\n",av[i],libraw_strerror(ret));
 // recycle() is needed only if we want to free the resources right now.
 // If we process files in a cycle, the next open_file()
 // will also call recycle(). If a fatal error has happened, it means that recycle()
 // has already been called (repeated call will not cause any harm either).
 RawProcessor.recycle();
 goto end;
 }
 // Let us unpack the image
 if( (ret = RawProcessor.unpack() ) != LIBRAW_SUCCESS)
 {
 fprintf(stderr,"Cannot unpack_thumb %s: %s\n",av[i],libraw_strerror(ret));
 if(LIBRAW_FATAL_ERROR(ret))
 goto end;
 // if there has been a non-fatal error, we will try to continue
 }
 // Let us unpack the thumbnail
 if( (ret = RawProcessor.unpack_thumb() ) != LIBRAW_SUCCESS)
 {
 // error processing is completely similar to the previous case
 fprintf(stderr,"Cannot unpack_thumb %s: %s\n",av[i],libraw_strerror(ret));
 if(LIBRAW_FATAL_ERROR(ret))
 goto end;
 }
 else // We have successfully unpacked the thumbnail, now let us write it to a file
 {
 snprintf(thumbfn,sizeof(thumbfn),"%s.%s",av[i],T.tformat == LIBRAW_THUMBNAIL_JPEG ? "thumb.jpg" : "thumb.ppm");
 if( LIBRAW_SUCCESS != (ret = RawProcessor.dcraw_thumb_writer(thumbfn)))
 {
 fprintf(stderr,"Cannot write %s: %s\n",thumbfn,libraw_strerror(ret));
 // in the case of fatal error, we should terminate processing of the current file
 if(LIBRAW_FATAL_ERROR(ret))
 goto end;
 }
 }
 // Data unpacking
 ret = RawProcessor.dcraw_process();
 if(LIBRAW_SUCCESS != ret ) // error at the previous step
 {
 fprintf(stderr,"Cannot do postprocessing on %s: %s\n",av[i],libraw_strerror(ret));
 if(LIBRAW_FATAL_ERROR(ret))
 goto end;
 }
 else // Successful document processing
 {
 snprintf(outfn,sizeof(outfn),"%s.%s", av[i], "tiff");
 if( LIBRAW_SUCCESS != (ret = RawProcessor.dcraw_ppm_tiff_writer(outfn)))
 fprintf(stderr,"Cannot write %s: error %d\n",outfn,ret);
 }
 // we don't evoke recycle() or call the destructor; C++ will do everything for us
 return 0;
end:
 // got here after an error
 return 1;
}

[back to Index]