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
.
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
isTrue
.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:
-
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) D65wide_gammut_rgb
— Wide Gamut RGB D65kodak_prophoto_rgb
— Kodak ProPhoto RGB D65xyz
— 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
- VNG
- PPG
- AHD
- DCB
- Modified AHD
- AFD
- VCD
- Mixed VCD and Modified AHD
- LMMSE
- 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")
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.
-
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 typeoutput_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: Raises: rawkit.errors.NoFileSpecified
– If filename isNone
.libraw.errors.FileUnsupported
– If the specified file is not a supported raw type.libraw.errors.InsufficientMemory
– If we run out of memory while loading the raw file.IOError
– If the file does not exist, or cannot be opened (eg. incorrect permissions).
-
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
-
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
-
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: libraw.errors.DataError
– If invalid or corrupt data is encountered in the data struct.libraw.errors.BadCrop
– If the image has been cropped poorly (eg. the edges are outside of the image bounds, or the crop box coordinates don’t make sense).libraw.errors.InsufficientMemory
– If we run out of memory while processing the raw file.
-
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: rawkit.errors.NoFileSpecified
– If filename isNone
.rawkit.errors.InvalidFileType
– If filetype is not None or inoutput_file_types
.
-
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 isNone
.
-
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_thumb
()[source]¶ Unpack the thumbnail data.
Raises: libraw.errors.NoThumbnail
– If the raw file does not contain athumbnail.
libraw.errors.UnsupportedThumbnail
– If the thumbnail format isunsupported.
-
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.