rawkit package

Introduction

The rawkit module contains high-level APIs for manipulating raw photos using the low-level libraw module (which in turn uses the even lower-level LibRaw C library).

Eg. quickly processing a raw Canon CR2 file without using the camera white balance and saving it as a PPM image might look like this:

from rawkit.raw import Raw
from rawkit.options import WhiteBalance

with Raw(filename='some/raw/image.CR2') as raw:
  raw.options.white_balance = WhiteBalance(camera=False, auto=True)
  raw.save(filename='some/destination/image.ppm')
rawkit.VERSION = '0.6.0'

The current version of the rawkit package.

Submodules

rawkit.errors — Errors thrown by rawkit

These errors are thrown by various rawkit functions and methods when things go wrong. They will only be raised by rawkit; for lower level errors raised by the underlying libraw bindings, see libraw.errors.

exception rawkit.errors.InvalidFileType[source]

Bases: exceptions.ValueError

Raised when an invalid file type or file extension is passed to a rawkit method.

exception rawkit.errors.NoFileSpecified[source]

Bases: exceptions.ValueError

Raised when the method or function excpects a filename argument, but no file name (or a value of None) was specified.

rawkit.metadata — Metadata structures

class rawkit.metadata.Metadata(aperture, timestamp, shutter, flash, focal_length, height, iso, make, model, orientation, width)

Bases: tuple

Common metadata for a photo.

Orientation matches the values from the EXIF 2.3 specification:

1 - The 0th row is at the visual top of the image, and the 0th
column is the visual left-hand side.
2 - The 0th row is at the visual top of the image, and the 0th
column is the visual right-hand side.
3 - The 0th row is at the visual bottom of the image, and the
0th column is the visual right-hand side.
4 - The 0th row is at the visual bottom of the image, and the
0th column is the visual left-hand side.
5 - The 0th row is the visual left-hand side of the image, and
the 0th column is the visual top.
6 - The 0th row is the visual right-hand side of the image,
and the 0th column is the visual top.
7 - The 0th row is the visual right-hand side of the image,
and the 0th column is the visual bottom.
8 - The 0th row is the visual left-hand side of the image, and
the 0th column is the visual bottom.
aperture

Alias for field number 0

flash

Alias for field number 3

focal_length

Alias for field number 4

height

Alias for field number 5

iso

Alias for field number 6

make

Alias for field number 7

model

Alias for field number 8

orientation

Alias for field number 9

shutter

Alias for field number 2

timestamp

Alias for field number 1

width

Alias for field number 10

rawkit.options — High level options for processing raw files

class rawkit.options.Options(attrs=None)[source]

Bases: object

Represents a set of options which can be used when processing raw data.

Parameters:attrs (dict) – A subscriptable object from which to take the initial state of the options object.
adjust_maximum_threshold[source]

Automatically adjusts the maximum pixel value based on per channel maximum data.

Note

If this value is set above 0.99999, the default value will be used instead. If it is set below 0.00001, no adjustment will happen.

Type:float
Default:0.75
Dcraw:None
Libraw:libraw.structs.libraw_output_params_t.adjust_maximum_thr
auto_brightness[source]

Set the brightness automatically based on the image histogram and the auto_brightness_threshold.

Type:boolean
Default:True
Dcraw:-W
Libraw:libraw.structs.libraw_output_params_t.no_auto_bright
auto_brightness_threshold[source]

The allowable percentage of clipped pixels when auto_brightness is used.

Type:float
Default:0.001 (0.1%)
Dcraw:None
Libraw:libraw.structs.libraw_output_params_t.auto_bright_thr
auto_stretch[source]

Stretches images taken on cameras with non-square pixels to the correct aspect ratio. For Fuji Super CCD cameras, rotates the image 45 degrees. This guarantees that the output pixels share a 1:1 correspondence with the raw pixels.

Type:boolean
Default:True
Dcraw:-j
Libraw:libraw.structs.libraw_output_params_t.use_fuji_rotate
bad_pixels_file[source]

Points to a bad pixels map in dcraw format

column row unix-timestamp\n
Type:str
Default:None
Dcraw:-P
Libraw:libraw.structs.libraw_output_params_t.bad_pixels
bps[source]

Set the bits per sample used for the photo (8 or 16). Setting this to 16 is effectively the same as running dcraw with the -4 option.

Type:int
Default:8
Dcraw:-4
Libraw:libraw.structs.libraw_output_params_t.output_bps
brightness[source]

Sets the brightness level by dividing the white level by this value. This is ignored if auto_brightness is True.

Type:float
Default:1.0
Dcraw:-b
Libraw:libraw.structs.libraw_output_params_t.bright
chromatic_aberration[source]

A Red-Blue scale factor that’s used to correct for chromatic aberration by scaling the respective channels.

eg.

# (red_scale, blue_scale)
raw.options.chromatic_aberration = (0.999, 1.001)
Type:double tuple
Default:(1, 1)
Dcraw:-C
Libraw:libraw.structs.libraw_output_params_t.aber
colorspace[source]

Sets the colorspace used for the output image. Supported colorspaces are defined as constants in rawkit.options.colorspaces.

Type:int
Default:rawkit.options.colorspaces.srgb
Dcraw:-o
Libraw:libraw.structs.libraw_output_params_t.output_color
cropbox[source]

Crops the image.

Type:4 float tuple
Default:None
Dcraw:None
Libraw:libraw.structs.libraw_output_params_t.cropbox
dark_frame[source]

A dark frame in 16-bit PGM format. This may either be a path to an existing file, or an instance of rawkit.raw.DarkFrame.

Type:rawkit.raw.DarkFrame str
Default:None
Dcraw:-K
Libraw:libraw.structs.libraw_output_params_t.dark_frame
darkness[source]

Raise the black level of a photo.

Type:int
Default:None
Dcraw:-k
Libraw:libraw.structs.libraw_output_params_t.user_black
gamma[source]

Sets the gamma-curve of the photo. The two values in the tuple correspond to:

  • gamma[0] — Correction function power (inverted Gamma power, $\gamma^{-1}$)
  • gamma[1] — toe-slope ($\phi$)

For a simple power curve, set the toe-slope to zero.

Type:2 double tuple
Default:None
Dcraw:-g
Libraw:libraw.structs.libraw_output_params_t.gamm
green_matching[source]

Performs a second post-processing pass to correct for green channel imbalance.

Type:boolean
Default:False
Dcraw:None
Libraw:libraw.structs.libraw_output_params_t.green_matching
half_size[source]

When developing the image, output it at 50% size. This makes developing preview images much faster.

Type:boolean
Default:False
Dcraw:-h
Libraw:libraw.structs.libraw_output_params_t.half_size
highlight_mode[source]

The mode for dealing with highlights in the image. Some constants have been defined in rawkit.options.highlight_modes to make things easier, or you can set an integer directly.

Integers that are greater than or equal to 3 will attempt to reconstruct highlights. Lower numbers favor whites, and higher colors favor colors. rawkit.options.RECONSTRUCT (5) is a good compromise.

Type:int
Default:rawkit.options.highlight_modes.clip
Dcraw:-H
Libraw:libraw.structs.libraw_output_params_t.highlight
input_profile[source]

Path to an ICC color profile file containing the input profile. Only used if the version of LibRaw that you’re linking against was compiled with LCMS support.

Note that LibRaw defines a magic string, ‘embed’, which causes it to use the profile embedded in the raw image if present. This is the same as setting the use_camera_profile option.

Type:string
Default:None
Dcraw:-o -p
Libraw:libraw.structs.libraw_output_params_t.camera_profile
interpolation[source]

Sets the interpolation algorithm.

Type:rawkit.options.interpolation
Default:ahd
Dcraw:-q
Libraw:libraw.structs.libraw_output_params_t.user_qual
keys()[source]

A list of keys which have a value other than None and which have been set by the user (even if those options are set to the default value).

Returns:List of option keys which have been set.
Return type:tuple
median_filter_passes[source]

Useful for cleaning up color artifacts by running a 3x3 median filter over the R-G and B-G channels.

Type:int
Default:0
Dcraw:-m
Libraw:libraw.structs.libraw_output_params_t.med_passes
noise_threshold[source]

Sets the threshold for noise reduction using wavelet denoising.

Type:float
Default:None
Dcraw:-n
Libraw:libraw.structs.libraw_output_params_t.threshold
output_profile[source]

Path to an ICC color profile file containing the output profile. Only used if the version of LibRaw that you’re linking against was compiled with LCMS support.

Type:string
Default:None
Dcraw:-o -p
Libraw:libraw.structs.libraw_output_params_t.output_profile
rgbg_interpolation[source]

Determines if we should use four channel RGB interpolation.

Type:boolean
Default:False
Dcraw:-f
Libraw:libraw.structs.libraw_output_params_t.four_color_rgb
rotation[source]

Rotates the image by the given number of degrees. Must be a multiple of 90 (0, 90, 180, 270, etc).

The default (None) is to use the rotation provided by the camera.

Type:int
Default:None
Dcraw:-t
Libraw:libraw.structs.libraw_output_params_t.user_flip
saturation[source]

Determines the saturation level of the output image.

Type:int
Default:None
Dcraw:-S
Libraw:libraw.structs.libraw_output_params_t.user_sat
shot[source]

Selects the shot to process for raw images that contain multiple images.

Type:int
Default:0
Dcraw:-s
Libraw:libraw.structs.libraw_output_params_t.shot_select
use_camera_matrix[source]

Use the color matrix from the raw’s metadata. Only affects Olympus, Leaf, and Phase One cameras (and DNG files).

Note that we differ from the LibRaw defaults on this option. LibRaw defaults to true if the photo is in DNG format or the camera white balance is being used, and false otherwise. rawkit always defaults to true.

Type:boolean
Default:True
Dcraw:+M -M
Libraw:libraw.libraw_output_params_t.use_camera_matrix
use_camera_profile[source]

True if we should use the embedded camera profile (if present in the raw file and we’re linking against a version of LibRaw with LCMS support).

Type:boolean
Default:True
Dcraw:-o -p
Libraw:libraw.structs.libraw_output_params_t.camera_profile
values()[source]

The values of all options which appear in keys().

Returns:List of options values.
Return type:tuple
white_balance[source]

The white balance of the image.

Type:rawkit.options.WhiteBalance
Default:WhiteBalance(auto=True, camera=True)
Dcraw:-a -w -A -r
Libraw:libraw.structs.libraw_output_params_t.use_auto_wb libraw.structs.libraw_output_params_t.use_camera_wb libraw.structs.libraw_output_params_t.greybox libraw.structs.libraw_output_params_t.user_mul
class rawkit.options.WhiteBalance[source]

Bases: rawkit.options.WhiteBalance

Represents the white balance of a photo. If the camera white balance is used, but not present, we fallback to the other options. Other options white balance multipliers stack (eg. you can use auto white balance, and then specify a manual rgbg multiplier on top of that).

Parameters:
  • auto (boolean) – Determines if we should automatically set the WB.
  • camera (boolean) – Causes us to use the camera defined WB if present.
  • greybox (4 int tuple) – Set the WB based on a neutral grey region of the image.
  • rgbg (4 float tuple) – Set the WB manually based on an RGBG channel multiplier.
Returns:

A white balance object.

Return type:

WhiteBalance

rawkit.options.colorspaces = ColorSpaces(raw=0, srgb=1, adobe_rgb=2, wide_gammut_rgb=3, kodak_prophoto_rgb=4, xyz=5)

Constants for setting the colorspace.

  • raw_color — Raw colorspace (unique to each camera)
  • srgb — sRGB D65 (default colorspace)
  • adobe_rgb — Adobe RGB (1998) D65
  • wide_gammut_rgb — Wide Gamut RGB D65
  • kodak_prophoto_rgb — Kodak ProPhoto RGB D65
  • xyz — XYZ colorspace
rawkit.options.gamma_curves = GammaCurves(linear=[1, 1], bt709=[0.45004500450045004, 4.5], srgb=[0.4166666666666667, 12.92], adobe_rgb=[0.4547069271758437])

Gamma curves for a few common color profiles.

  • linear — A basic linear transfer function.
  • bt709 — The BT.709 (Rec. 709) curve used by HDTVs (uses the median power of sRGB, and a similar but shifted transfer function).
  • srgb — The sRGB gamma curve (uses the max power to account for linear discontinuity and to attain the standard IEC 61966-2-1 solution $K_0 \approx 0.04045 $).
  • adobe_rgb — The correction function power for the Adobe RGB colorspace. The toe-slope is left off.
rawkit.options.highlight_modes = HighlightMode(clip=0, ignore=1, blend=2, reconstruct=5)

Constants for setting the highlight mode.

  • clip — Clip all highlights to white (default).
  • ignore — Leave highlights unclipped.
  • blend — Blend clipped and unclipped highlights.
  • reconstruct — A good average value for reconstruction of clipped highlights which compromises between favoring whites and favoring colors.
rawkit.options.interpolation = InterpolationAlgo(linear=0, vng=1, ppg=2, ahd=3, dcb=4, modified_ahd=5, afd=6, vcd=7, mixed_vcd_modified_ahd=8, lmmse=9, amaze=10)
Constants for setting the interpolation algorithm – 0. Linear
  1. VNG
  2. PPG
  3. AHD
  4. DCB
  5. Modified AHD
  6. AFD
  7. VCD
  8. Mixed VCD and Modified AHD
  9. LMMSE
  10. AMaZE

Modified AHD (5) through LMMSE (9) are only useful if you’re using a version of LibRaw with the “LibRaw Demosaic Pack GPL2” built in and AMaZE (10) is only useful if LibRaw was built with the “LibRaw Demosaic Pack GPL3”. If you attepmt to use an interpolation method that’s not built into your version of LibRaw, it will silently fallback to AHD.

Usage example:

from rawkit.raw import Raw
from rawkit.options import interpolation

with Raw(filename="RawFile.CR2") as raw:
    raw.options.interpolation = interpolation.ahd
    raw.save("RawFile.ppm")
class rawkit.options.option(param=None, ctype=None)[source]

Bases: object

The option decorator is an internal decorator which allows you to define an option in a clean manner (specifying its name and how it maps to the libraw params).

param_writer(func)[source]
setter(func)[source]
write_param(obj, params)[source]
rawkit.orientation.get_orientation(data)[source]

rawkit.raw — High-level raw file API

class rawkit.raw.DarkFrame(filename=None)[source]

Bases: rawkit.raw.Raw

Represents a dark frame—a raw photo taken in low light which can be subtracted from another photos raw data.

Creates a temporary file which is not cleaned up until the dark frame is closed.

cleanup()[source]

Cleanup temp files.

close()[source]

Free the underlying raw representation and cleanup temp files.

name

A tempfile in a unique directory.

Returns:The name of a temp file.
Return type:str
save(filename=None, filetype='ppm')[source]

Save the image data, defaults to using a temp file.

Parameters:
  • filename (str) – The name of an image file to save.
  • filetype (output_file_types) – The type of file to output.
Raises:

rawkit.errors.InvalidFileType – If filetype is not of type output_file_types.

class rawkit.raw.Raw(filename=None)[source]

Bases: object

Represents a raw file (of any format) and exposes development options to the user.

For example, the basic workflow (open a file, process the file, save the file) looks like this:

from rawkit.raw import Raw
from rawkit.options import WhiteBalance

with Raw(filename='some/raw/image.CR2') as raw:
    raw.options.white_balance = WhiteBalance(camera=False, auto=True)
    raw.save(filename='some/destination/image.ppm')
Parameters:

filename (str) – The name of a raw file to load.

Returns:

A raw object.

Return type:

Raw

Raises:
as_array()[source]

Get a NumPy array of the raw image data

Returns:
A NumPy array of bayer pixel data structured as a list of
rows, or array([]) if there is no bayer data. The margin with calibration pixels is always included. For example, if the color format is RGGB, the array would be of the format:
array([
    [R, G, R, G, ...],
    [G, B, G, B, ...],
    [R, G, R, G, ...],
    ...
])
Return type:array
bayer_data(include_margin=False)[source]

Get the bayer data and color_description for an image.

Returns:
Tuple of bayer data and color filter array. This is a
convenience method to return rawkit.raw.Raw.raw_image and rawkit.raw.Raw.color_filter_array as a single tuple.
Return type:tuple
close()[source]

Free the underlying raw representation.

color(y, x)[source]

Get the active color of a pixel of bayer data.

Parameters:
  • y (int) – the y coordinate (or row) of the pixel
  • x (int) – the x coordinate (or column) of the pixel
Returns:

Character representing the color, such as ‘R’ for red.

Return type:

str

color_description

Get the color_description of an image.

Returns:4 character string representing color format, such as ‘RGGB’.
Return type:str
color_filter

EXPERIMENTAL – This method only supports bayer filters for the time being. It will be incorrect when used with other types of sensors.

Get the color filter array for the camera sensor.

Returns:
2D array representing the color format array pattern.
For example, the typical ‘RGGB’ pattern of abayer sensor would be of the format:
[
    ['R', 'G'],
    ['G', 'B'],
]
Return type:list
color_filter_array

EXPERIMENTAL – This method only supports bayer filters for the time being. It will be incorrect when used with other types of sensors.

Get the color filter array for the camera sensor.

Returns:
Numpy array representing the color format array pattern.
For example, the typical ‘RGGB’ pattern of abayer sensor would be of the format:
array([
    ['R', 'G'],
    ['G', 'B'],
])
Return type:list
data_pointer()[source]
metadata

Common metadata for the photo

Returns:A metadata object.
Return type:rawkit.metadata.Metadata
process()[source]

Process the raw data based on self.options.

Raises:
raw_image(include_margin=False)[source]

Get the bayer data for an image if it exists.

Parameters:include_margin (bool) – Include margin with calibration pixels.
Returns:
2D array of bayer pixel data structured as a list of rows,
or [] if there is no bayer data. For example, if the color format is RGGB, the array would be of the format:
[
    [R, G, R, G, ...],
    [G, B, G, B, ...],
    [R, G, R, G, ...],
    ...
]
Return type:list
save(filename, filetype=None)[source]

Save the image data as a new PPM or TIFF image.

Parameters:
  • filename (str) – The name of an image file to save.
  • filetype (output_file_types) – The type of file to output. By default, guess based on the filename, falling back to PPM.
Raises:
save_thumb(filename=None)[source]

Save the thumbnail data.

Parameters:filename (str) – The name of an image file to save.
Raises:rawkit.errors.NoFileSpecified – If filename is None.
thumbnail_to_buffer()[source]

Convert the thumbnail data as an RGB buffer.

Returns:RGB data of the thumbnail.
Return type:bytearray
to_buffer()[source]

Convert the image to an RGB buffer.

Returns:RGB data of the image.
Return type:bytearray
unpack()[source]

Unpack the raw data.

unpack_thumb()[source]

Unpack the thumbnail data.

Raises:
rawkit.raw.output_file_types = OutputFileType(ppm='ppm', tiff='tiff')

Constants for setting the output filetype.

  • ppm — PGM data file.
  • tiff — TIFF file.

rawkit.util — Utility functions

These functions perform helpful tasks which don’t really fit anywhere else such as searching for Raw files on the disk, or checking what cameras are supported by LibRaw.

rawkit.util.camera_list()[source]

Return a list of cameras which are supported by the currently linked version of LibRaw.

Returns:A list of supported cameras.
Return type:str array
rawkit.util.discover(path)[source]

Recursively search for raw files in a given directory.

Parameters:path (str) – A tree to recursively search.