""":mod:`rawkit.options` --- High level options for processing raw files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"""
import ctypes
from collections import namedtuple
[docs]class option(object):
"""
The :class:`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).
"""
def __init__(self, param=None, ctype=None):
if callable(param):
func = param
param = None
else:
func = None
self._prepare_func(func)
self.param = param
self.ctype = ctype
self.setter_func = None
self.param_func = None
def _prepare_func(self, func):
self.func = func
if func is not None:
self.__doc__ = getattr(func, '__doc__')
self.__name__ = getattr(func, '__name__')
self.internal_name = '_{name}'.format(name=self.__name__)
self.__module__ = getattr(func, '__module__')
def __call__(self, func=None):
self._prepare_func(func)
if func is None:
raise TypeError("option should not be called except as a property")
self.func = func
return self
[docs] def setter(self, func):
self.setter_func = func
return self
[docs] def param_writer(self, func):
self.param_func = func
return self
[docs] def write_param(self, obj, params):
if self.param_func is None:
val = self.__get__(obj, None)
try:
setattr(params, self.param, self.ctype(*val))
except TypeError:
setattr(params, self.param, self.ctype(val))
else:
self.param_func(obj, params)
def __set__(self, obj, value):
if self.setter_func is None:
setattr(obj, self.internal_name, value)
else:
self.setter_func(obj, value)
def __get__(self, obj, cls):
try:
val = getattr(obj, self.internal_name)
if val is None:
return self.func(obj)
else:
return val
except AttributeError:
# We're probably generating the documentation...
return self
highlight_modes = namedtuple(
'HighlightMode', ['clip', 'ignore', 'blend', 'reconstruct']
)(0, 1, 2, 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.
"""
gamma_curves = namedtuple(
'GammaCurves', ['linear', 'bt709', 'srgb', 'adobe_rgb']
)([1, 1], [1 / 2.222, 4.5], [1 / 2.4, 12.92], [256 / float(563)])
"""
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.
"""
colorspaces = namedtuple(
'ColorSpaces', ['raw', 'srgb', 'adobe_rgb', 'wide_gammut_rgb',
'kodak_prophoto_rgb', 'xyz']
)(0, 1, 2, 3, 4, 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
"""
interpolation = namedtuple(
'InterpolationAlgo', ['linear', 'vng', 'ppg', 'ahd', 'dcb', 'modified_ahd',
'afd', 'vcd', 'mixed_vcd_modified_ahd', 'lmmse',
'amaze']
)(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 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:
.. sourcecode:: python
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")
.. _LibRaw Demosaic Pack GPL2:
https://github.com/LibRaw/LibRaw-demosaic-pack-GPL2
.. _LibRaw Demosaic Pack GPL3:
https://github.com/LibRaw/LibRaw-demosaic-pack-GPL3
"""
[docs]class WhiteBalance(namedtuple('WhiteBalance',
['auto', 'camera', 'greybox', 'rgbg'])):
"""
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).
Args:
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:
WhiteBalance: A white balance object.
"""
__slots__ = ()
def __new__(cls, auto=False, camera=False, greybox=None, rgbg=None):
return super(WhiteBalance, cls).__new__(
cls, auto, camera, greybox, rgbg)
[docs]class Options(object):
"""
Represents a set of options which can be used when processing raw data.
Args:
attrs (dict): A subscriptable object from which to take the initial
state of the options object.
"""
__slots__ = [
'_bps',
'_brightness',
'_auto_brightness',
'_auto_brightness_threshold',
'_chromatic_aberration',
'_darkness',
'_half_size',
'_noise_threshold',
'_rgbg_interpolation',
'_saturation',
'_shot',
'_use_camera_matrix',
'_white_balance',
'_highlight_mode',
'_colorspace',
'_output_profile',
'_input_profile',
'_use_camera_profile',
'_cropbox',
'_gamma',
'_interpolation',
'_auto_stretch',
'_rotation',
'_dark_frame',
'_green_matching',
'_bad_pixels_file',
'_median_filter_passes',
'_adjust_maximum_threshold',
]
def __init__(self, attrs=None):
"""
Create the options object, initializing values to ``None`` or their
corresponding value from `attrs`.
"""
for i in self.__slots__:
try:
param = i[1:]
setattr(self, param, attrs[param])
except (KeyError, TypeError):
setattr(self, i, None)
def __iter__(self):
"""Allow iterating over the options."""
idx = 0
while True:
idx += 1
try:
yield self.keys()[idx - 1]
except IndexError:
return
def __repr__(self):
"""Represents the options as a dict."""
return repr(dict(self))
[docs] def keys(self):
"""
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:
tuple: List of option keys which have been set.
"""
return [slot[1:] for slot in self.__slots__ if getattr(self, slot) is
not None]
[docs] def values(self):
"""
The values of all options which appear in :func:`keys`.
Returns:
tuple: List of options values.
"""
return [self.__getitem__(k) for k in self.keys()]
def __getitem__(self, k):
"""
Allow accessing options with dictionary syntax eg. ::
opts['half_size'].
"""
return getattr(self, k)
[docs] @option(param='output_color', ctype=ctypes.c_int)
def colorspace(self):
"""
Sets the colorspace used for the output image. Supported colorspaces
are defined as constants in :class:`rawkit.options.colorspaces`.
:type: :class:`int`
:default: :class:`rawkit.options.colorspaces.srgb`
:dcraw: ``-o``
:libraw: :class:`libraw.structs.libraw_output_params_t.output_color`
"""
return colorspaces.srgb
[docs] @option(param='highlight', ctype=ctypes.c_int)
def highlight_mode(self):
"""
The mode for dealing with highlights in the image. Some constants have
been defined in :class:`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. :class:`rawkit.options.RECONSTRUCT` (5) is a good
compromise.
:type: :class:`int`
:default: :class:`rawkit.options.highlight_modes.clip`
:dcraw: ``-H``
:libraw: :class:`libraw.structs.libraw_output_params_t.highlight`
"""
return highlight_modes.clip
@option
def white_balance(self):
"""
The white balance of the image.
:type: :class:`rawkit.options.WhiteBalance`
:default: WhiteBalance(auto=True, camera=True)
:dcraw: ``-a``
``-w``
``-A``
``-r``
:libraw: :class:`libraw.structs.libraw_output_params_t.use_auto_wb`
:class:`libraw.structs.libraw_output_params_t.use_camera_wb`
:class:`libraw.structs.libraw_output_params_t.greybox`
:class:`libraw.structs.libraw_output_params_t.user_mul`
"""
return WhiteBalance(auto=True, camera=True)
[docs] @white_balance.param_writer
def white_balance(self, params):
if self.white_balance.greybox is not None:
params.greybox = (ctypes.c_uint * 4)(*self.white_balance.greybox)
if self.white_balance.rgbg is not None:
params.user_mul = (ctypes.c_float * 4)(*self.white_balance.rgbg)
params.use_camera_wb = ctypes.c_int(self.white_balance.camera)
params.use_auto_wb = ctypes.c_int(self.white_balance.auto)
[docs] @option(param='use_camera_matrix', ctype=ctypes.c_int)
def use_camera_matrix(self):
"""
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: :class:`boolean`
:default: True
:dcraw: ``+M``
``-M``
:libraw: :class:`libraw.libraw_output_params_t.use_camera_matrix`
"""
return True
[docs] @option(param='shot_select', ctype=ctypes.c_uint)
def shot(self):
"""
Selects the shot to process for raw images that contain multiple
images.
:type: :class:`int`
:default: 0
:dcraw: ``-s``
:libraw: :class:`libraw.structs.libraw_output_params_t.shot_select`
"""
return None
[docs] @option(param='user_sat', ctype=ctypes.c_int)
def saturation(self):
"""
Determines the saturation level of the output image.
:type: :class:`int`
:default: None
:dcraw: ``-S``
:libraw: :class:`libraw.structs.libraw_output_params_t.user_sat`
"""
return None
[docs] @option(param='four_color_rgb', ctype=ctypes.c_int)
def rgbg_interpolation(self):
"""
Determines if we should use four channel RGB interpolation.
:type: :class:`boolean`
:default: False
:dcraw: ``-f``
:libraw: :class:`libraw.structs.libraw_output_params_t.four_color_rgb`
"""
return False
[docs] @option(param='threshold', ctype=ctypes.c_float)
def noise_threshold(self):
"""
Sets the threshold for noise reduction using wavelet denoising.
:type: :class:`float`
:default: None
:dcraw: ``-n``
:libraw: :class:`libraw.structs.libraw_output_params_t.threshold`
"""
return None
[docs] @option(param='half_size', ctype=ctypes.c_int)
def half_size(self):
"""
When developing the image, output it at 50% size. This makes developing
preview images much faster.
:type: :class:`boolean`
:default: False
:dcraw: ``-h``
:libraw: :class:`libraw.structs.libraw_output_params_t.half_size`
"""
return False
[docs] @option(param='user_black', ctype=ctypes.c_int)
def darkness(self):
"""
Raise the black level of a photo.
:type: :class:`int`
:default: None
:dcraw: ``-k``
:libraw: :class:`libraw.structs.libraw_output_params_t.user_black`
"""
return None
@option
def chromatic_aberration(self):
"""
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: :class:`double tuple`
:default: (1, 1)
:dcraw: ``-C``
:libraw: :class:`libraw.structs.libraw_output_params_t.aber`
"""
return (1, 1)
[docs] @chromatic_aberration.param_writer
def chromatic_aberration(self, params):
params.aber = (ctypes.c_double * 4)(*(
self.chromatic_aberration[0],
0, # TODO: What is this index used for?
self.chromatic_aberration[1],
0 # TODO: What is this index used for?
))
@option(param='output_bps', ctype=ctypes.c_int)
def bps(self):
"""
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: :class:`int`
:default: 8
:dcraw: ``-4``
:libraw: :class:`libraw.structs.libraw_output_params_t.output_bps`
"""
return 8
[docs] @bps.setter
def bps(self, value):
if value in (8, 16):
self._bps = value
else:
raise ValueError("BPS must be 8 or 16")
[docs] @option(param='cropbox', ctype=(ctypes.c_uint * 4))
def cropbox(self):
"""
Crops the image.
:type: :class:`4 float tuple`
:default: None
:dcraw: None
:libraw: :class:`libraw.structs.libraw_output_params_t.cropbox`
"""
return None
[docs] @option(param='gamm', ctype=(ctypes.c_double * 6))
def gamma(self):
"""
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: :class:`2 double tuple`
:default: None
:dcraw: ``-g``
:libraw: :class:`libraw.structs.libraw_output_params_t.gamm`
"""
return None
[docs] @option(param='interpolation', ctype=ctypes.c_uint)
def interpolation(self):
"""
Sets the interpolation algorithm.
:type: :class:`rawkit.options.interpolation`
:default: `ahd`
:dcraw: ``-q``
:libraw: :class:`libraw.structs.libraw_output_params_t.user_qual`
"""
return interpolation.ahd
[docs] @option(param='bright', ctype=ctypes.c_float)
def brightness(self):
"""
Sets the brightness level by dividing the white level by this value.
This is ignored if :class:`~auto_brightness` is ``True``.
:type: :class:`float`
:default: 1.0
:dcraw: ``-b``
:libraw: :class:`libraw.structs.libraw_output_params_t.bright`
"""
return None
[docs] @option(param='auto_bright_thr', ctype=ctypes.c_float)
def auto_brightness_threshold(self):
"""
The allowable percentage of clipped pixels when
:class:`~auto_brightness` is used.
:type: :class:`float`
:default: 0.001 (0.1%)
:dcraw: None
:libraw: :class:`libraw.structs.libraw_output_params_t.auto_bright_thr`
"""
return 0.001
@option
def auto_brightness(self):
"""
Set the brightness automatically based on the image histogram and the
:class:`~auto_brightness_threshold`.
:type: :class:`boolean`
:default: True
:dcraw: ``-W``
:libraw: :class:`libraw.structs.libraw_output_params_t.no_auto_bright`
"""
return True
[docs] @auto_brightness.param_writer
def auto_brightness(self, param):
param.no_auto_bright = ctypes.c_int(not self.auto_brightness)
[docs] @option(param='use_fuji_rotate', ctype=ctypes.c_int)
def auto_stretch(self):
"""
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: :class:`boolean`
:default: True
:dcraw: ``-j``
:libraw: :class:`libraw.structs.libraw_output_params_t.use_fuji_rotate`
"""
return True
@option
def rotation(self):
"""
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: :class:`int`
:default: None
:dcraw: ``-t``
:libraw: :class:`libraw.structs.libraw_output_params_t.user_flip`
"""
return None
@rotation.setter
def rotation(self, value):
if value is not None and value > 0:
value = ((value + 3600) % 360)
if value in (None, 0, 90, 180, 270):
self._rotation = value
else:
raise ValueError('Rotation must be None (use camera rotation) or '
'a multiple of 90')
[docs] @rotation.param_writer
def rotation(self, params):
params.user_flip = ctypes.c_int({
270: 5,
180: 3,
90: 6,
0: 0
}[self.rotation])
@option
def dark_frame(self):
"""
A dark frame in 16-bit PGM format. This may either be a path to an
existing file, or an instance of :class:`rawkit.raw.DarkFrame`.
:type: :class:`rawkit.raw.DarkFrame`
:class:`str`
:default: None
:dcraw: ``-K``
:libraw: :class:`libraw.structs.libraw_output_params_t.dark_frame`
"""
return None
@dark_frame.setter
def dark_frame(self, value):
self._dark_frame = value
[docs] @dark_frame.param_writer
def dark_frame(self, params):
try:
self.dark_frame.save()
params.dark_frame = ctypes.c_char_p(
self.dark_frame.name.encode('utf-8')
)
except AttributeError:
params.dark_frame = ctypes.c_char_p(
self.dark_frame.encode('utf-8')
)
[docs] @option(param='green_matching', ctype=ctypes.c_int)
def green_matching(self):
"""
Performs a second post-processing pass to correct for green channel
imbalance.
:type: :class:`boolean`
:default: False
:dcraw: None
:libraw: :class:`libraw.structs.libraw_output_params_t.green_matching`
"""
return False
[docs] @option(param='output_profile', ctype=ctypes.c_char_p)
def output_profile(self):
"""
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: :class:`string`
:default: None
:dcraw: ``-o``
``-p``
:libraw: :class:`libraw.structs.libraw_output_params_t.output_profile`
"""
return None
@option
def use_camera_profile(self):
"""
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: :class:`boolean`
:default: True
:dcraw: ``-o``
``-p``
:libraw: :class:`libraw.structs.libraw_output_params_t.camera_profile`
"""
return True
@use_camera_profile.setter
def use_camera_profile(self, value):
self._use_camera_profile = value
[docs] @use_camera_profile.param_writer
def use_camera_profile(self, params):
if self.use_camera_profile:
params.camera_profile = ctypes.c_char_p(b'embed')
else:
params.camera_profile = None
[docs] @option(param='bad_pixels', ctype=ctypes.c_char_p)
def bad_pixels_file(self):
"""
Points to a bad pixels map in dcraw format: ::
column row unix-timestamp\\n
:type: :class:`str`
:default: None
:dcraw: ``-P``
:libraw: :class:`libraw.structs.libraw_output_params_t.bad_pixels`
"""
return None
[docs] @option(param='adjust_maximum_thr', ctype=ctypes.c_float)
def adjust_maximum_threshold(self):
"""
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: :class:`float`
:default: 0.75
:dcraw: None
:libraw:
:class:`libraw.structs.libraw_output_params_t.adjust_maximum_thr`
"""
return 0
def _map_to_libraw_params(self, params):
"""
Internal method that writes rawkit options into the libraw options
struct with the proper C data types.
Args:
params (libraw.structs.libraw_output_params_t):
The output params struct to set.
"""
for slot in self.__slots__:
prop = slot[1:]
opt = getattr(Options, prop)
if type(opt) is option and getattr(self, prop) is not None:
opt.write_param(self, params)
# This generally isn't needed, except for testing.
return params
