manpages

rawpy(1)

RAWPY(1) rawpy RAWPY(1)

NAME

rawpy - rawpy Documentation

API REFERENCE

The main entry point to start working with RAW images is rawpy.imread(). It returns a rawpy.RawPy <#id0> object on which all further operations have to be performed.

rawpy.imread(pathOrFile: str | BinaryIO, shot_select: int = 0) -> RawPy <#id0>
Convenience function that creates a rawpy.RawPy <#id0> instance, opens the given file, and returns the rawpy.RawPy <#id0> instance for further processing.
Parameters
  • pathOrFile (str or file-like object) -- path or file object of RAW image that will be read
  • shot_select (int) -- select which image to extract from RAW files that contain multiple images (e.g., Dual Pixel RAW). Default is 0 for the first/main image.

Returns
RawPy instance with the opened RAW image
Return type
rawpy.RawPy <#id0>


Classes

RawPy class

class rawpy.RawPy
Load RAW images, work on their data, and create a postprocessed (demosaiced) image.

All operations are implemented using numpy arrays.

close(self) -> None
Release all resources and close the RAW image.

Consider using context managers for the same effect:

with rawpy.imread('image.nef') as raw:


  # work with raw object



extract_thumb(self) -> Thumbnail <#rawpy.Thumbnail>
Extracts and returns the thumbnail/preview image (whichever is bigger) of the opened RAW image as rawpy.Thumbnail <#rawpy.Thumbnail> object. For JPEG thumbnails, data is a bytes object and can be written as-is to file. For bitmap thumbnails, data is an ndarray of shape (h,w,c). If no image exists or the format is unsupported, an exception is raised.
Return type
rawpy.Thumbnail <#rawpy.Thumbnail>


postprocess(self, params: Params <#rawpy.Params> | None = None, **kw) -> NDArray[np.uint8]
Postprocess the currently loaded RAW image and return the new resulting image as numpy array.
Parameters
  • params (rawpy.Params <#rawpy.Params>) -- The parameters to use for postprocessing.
  • **kw --

    Alternative way to provide postprocessing parameters. The keywords are used to construct a rawpy.Params <#rawpy.Params> instance. If keywords are given, then params must be omitted.


Return type
ndarray of shape (h,w,c)


raw_color(self, int row, int column) -> int
Return color index for the given coordinates relative to the full RAW size. Only usable for flat RAW images (see raw_type property).

raw_value(self, int row, int column) -> ushort
Return RAW value at given position relative to the full RAW image. Only usable for flat RAW images (see raw_type property).

raw_value_visible(self, int row, int column) -> ushort
Return RAW value at given position relative to visible area of image. Only usable for flat RAW images (see raw_type property).

set_unpack_params(self, int shot_select: int = 0) -> None
Set parameters that affect RAW image unpacking.

This should be called after opening a file and before unpacking.

Note:

This is a low-level method. When using rawpy.imread() <#rawpy.imread>, unpack parameters can be provided directly.


Parameters
shot_select (int) -- select which image to extract from RAW files that contain multiple images (e.g., Dual Pixel RAW). Default is 0 for the first/main image.


auto_whitebalance
RawPy.auto_whitebalance: Optional[List[float]]

White balance coefficients used during postprocessing.

This property returns the actual white balance multipliers that were used during postprocessing, regardless of the white balance mode: whether from camera settings, auto white balance calculation, user-specified values, or daylight balance.

This property must be accessed after calling postprocess() or dcraw_process() to get the coefficients that were actually applied. If accessed before postprocessing, it returns None.

This corresponds to LibRaw's imgdata.color.pre_mul[] array after processing, which contains the white balance multipliers applied to the raw sensor data.

Return type
list of length 4, or None if postprocessing hasn't been called yet


black_level_per_channel
RawPy.black_level_per_channel: List[int]

Per-channel black level correction.

Return type
list of length 4


camera_white_level_per_channel
RawPy.camera_white_level_per_channel: Optional[List[int]]

Per-channel saturation levels read from raw file metadata, if it exists. Otherwise None.

Return type
list of length 4, or None if metadata missing


camera_whitebalance
RawPy.camera_whitebalance: List[float]

White balance coefficients (as shot). Either read from file or calculated.

Return type
list of length 4


color_desc
RawPy.color_desc: bytes

String description of colors numbered from 0 to 3 (RGBG,RGBE,GMCY, or GBTG). Note that same letters may not refer strictly to the same color. There are cameras with two different greens for example.


color_matrix
RawPy.color_matrix: NDArray[np.float32]

Color matrix, read from file for some cameras, calculated for others.

Return type
ndarray of shape (3,4)


daylight_whitebalance
RawPy.daylight_whitebalance: List[float]

White balance coefficients for daylight (daylight balance). Either read from file, or calculated on the basis of file data, or taken from hardcoded constants.

Return type
list of length 4


lens
RawPy.lens: Lens

num_colors
RawPy.num_colors: int

Number of colors. Note that e.g. for RGBG this can be 3 or 4, depending on the camera model, as some use two different greens.


other
RawPy.other: Other

raw_colors
RawPy.raw_colors: NDArray[np.uint8]

An array of color indices for each pixel in the RAW image. Equivalent to calling raw_color(y,x) for each pixel. Only usable for flat RAW images (see raw_type property).

Return type
ndarray of shape (h,w)


raw_colors_visible
RawPy.raw_colors_visible: NDArray[np.uint8]

Like raw_colors but without margin.

Return type
ndarray of shape (hv,wv)


raw_image
RawPy.raw_image: NDArray[np.uint16]

View of RAW image. Includes margin.

For Bayer images, a 2D ndarray is returned. For Foveon and other RGB-type images, a 3D ndarray is returned. Note that there may be 4 color channels, where the 4th channel can be blank (zeros).

Modifying the returned array directly influences the result of calling postprocess().

Warning:

The returned numpy array can only be accessed while this RawPy instance is not closed yet, that is, within a with block or before calling close(). If you need to work on the array after closing the RawPy instance, make sure to create a copy of it with raw_image = raw.raw_image.copy().


Return type
ndarray of shape (h,w[,c])


raw_image_visible
RawPy.raw_image_visible: NDArray[np.uint16]

Like raw_image but without margin.

Return type
ndarray of shape (hv,wv[,c])


raw_pattern
RawPy.raw_pattern: Optional[NDArray[np.uint8]]

The smallest possible Bayer pattern of this image.

Return type
ndarray, or None if not a flat RAW image


raw_type
RawPy.raw_type: RawType

Return the RAW type.

Return type
rawpy.RawType <#rawpy.RawType>


rgb_xyz_matrix
RawPy.rgb_xyz_matrix: NDArray[np.float32]

Camera RGB - XYZ conversion matrix. This matrix is constant (different for different models). Last row is zero for RGB cameras and non-zero for different color models (CMYG and so on).

Return type
ndarray of shape (4,3)


sizes
RawPy.sizes: ImageSizes

Return a rawpy.ImageSizes <#rawpy.ImageSizes> instance with size information of the RAW image and postprocessed image.


tone_curve
RawPy.tone_curve: NDArray[np.uint16]

Camera tone curve, read from file for Nikon, Sony and some other cameras.

Return type
ndarray of length 65536


white_level
RawPy.white_level: int

Level at which the raw pixel value is considered to be saturated.



Additional low-level methods:

class rawpy.RawPy
Load RAW images, work on their data, and create a postprocessed (demosaiced) image.

All operations are implemented using numpy arrays.

dcraw_make_mem_image(self)
Return the postprocessed image (see dcraw_process()) as numpy array.

Note:

This is a low-level method, consider using postprocess() instead.


Return type
ndarray of shape (h,w,c)


dcraw_make_mem_thumb(self)
Return the thumbnail/preview image (see unpack_thumb()) as rawpy.Thumbnail <#rawpy.Thumbnail> object. For JPEG thumbnails, data is a bytes object and can be written as-is to file. For bitmap thumbnails, data is an ndarray of shape (h,w,c). If no image exists or the format is unsupported, an exception is raised.

Note:

This is a low-level method, consider using extract_thumb() instead.


Return type
rawpy.Thumbnail <#rawpy.Thumbnail>


dcraw_process(self, params: Params <#rawpy.Params> | None = None, **kw) -> None
Postprocess the currently loaded RAW image.

Note:

This is a low-level method, consider using postprocess() instead.


Parameters
  • params (rawpy.Params <#rawpy.Params>) -- The parameters to use for postprocessing.
  • **kw --

    Alternative way to provide postprocessing parameters. The keywords are used to construct a rawpy.Params <#rawpy.Params> instance. If keywords are given, then params must be omitted.




open_buffer(self, fileobj: BinaryIO) -> None
Opens the given RAW image file-like object. Should be followed by a call to unpack().

Note:

This is a low-level method, consider using rawpy.imread() <#rawpy.imread> instead.


Parameters
fileobj (file) -- The file-like object.


open_file(self, str path: str) -> None
Opens the given RAW image file. Should be followed by a call to unpack().

Note:

This is a low-level method, consider using rawpy.imread() <#rawpy.imread> instead.


Parameters
path (str) -- The path to the RAW image.


unpack(self) -> None
Unpacks/decodes the opened RAW image.

Note:

This is a low-level method, consider using rawpy.imread() <#rawpy.imread> instead.



unpack_thumb(self) -> None
Unpacks/decodes the thumbnail/preview image, whichever is bigger.

Note:

This is a low-level method, consider using extract_thumb() instead.




Params class

class rawpy.Params(self, demosaic_algorithm: Optional[DemosaicAlgorithm] = None, bool half_size: bool = False, bool four_color_rgb: bool = False, int dcb_iterations: int = 0, bool dcb_enhance: bool = False, fbdd_noise_reduction: FBDDNoiseReductionMode = FBDDNoiseReductionMode.Off, float noise_thr: Optional[float] = None, int median_filter_passes: int = 0, bool use_camera_wb: bool = False, bool use_auto_wb: bool = False, list user_wb: Optional[List[float]] = None, output_color: ColorSpace = ColorSpace.sRGB, int output_bps: int = 8, int user_flip: Optional[int] = None, int user_black: Optional[int] = None, list user_cblack: Optional[List[int]] = None, int user_sat: Optional[int] = None, bool no_auto_bright: bool = False, float auto_bright_thr: Optional[float] = None, double adjust_maximum_thr: float = 0.75, double bright: float = 1.0, highlight_mode: Union[HighlightMode, int] = HighlightMode.Clip, float exp_shift: Optional[float] = None, double exp_preserve_highlights: float = 0.0, bool no_auto_scale: bool = False, tuple gamma: Optional[Tuple[float, float]] = None, tuple chromatic_aberration: Optional[Tuple[float, float]] = None, str bad_pixels_path: Optional[str] = None)
A class that handles postprocessing parameters.

If use_camera_wb and use_auto_wb are False and user_wb is None, then daylight white balance correction is used. If both use_camera_wb and use_auto_wb are True, then use_auto_wb has priority.

Parameters
  • demosaic_algorithm (rawpy.DemosaicAlgorithm <#rawpy.DemosaicAlgorithm>) -- default is AHD
  • half_size (bool) -- outputs image in half size by reducing each 2x2 block to one pixel instead of interpolating
  • four_color_rgb (bool) -- whether to use separate interpolations for two green channels
  • dcb_iterations (int) -- number of DCB correction passes, requires DCB demosaicing algorithm
  • dcb_enhance (bool) -- DCB interpolation with enhanced interpolated colors
  • fbdd_noise_reduction (rawpy.FBDDNoiseReductionMode <#rawpy.FBDDNoiseReductionMode>) -- controls FBDD noise reduction before demosaicing
  • noise_thr (float) -- threshold for wavelet denoising (default disabled)
  • median_filter_passes (int) -- number of median filter passes after demosaicing to reduce color artifacts
  • use_camera_wb (bool) -- whether to use the as-shot white balance values
  • use_auto_wb (bool) -- whether to try automatically calculating the white balance
  • user_wb (list) -- list of length 4 with white balance multipliers for each color
  • output_color (rawpy.ColorSpace <#rawpy.ColorSpace>) -- output color space
  • output_bps (int) -- 8 or 16
  • user_flip (int) -- 0=none, 3=180, 5=90CCW, 6=90CW, default is to use image orientation from the RAW image if available
  • user_black (int) -- custom black level
  • user_cblack (list) -- list of length 4 with per-channel corrections to user_black. These are offsets applied on top of user_black for [R, G, B, G2] channels.
  • user_sat (int) -- saturation adjustment (custom white level)
  • no_auto_scale (bool) -- Whether to disable pixel value scaling
  • no_auto_bright (bool) -- whether to disable automatic increase of brightness
  • auto_bright_thr (float) -- ratio of clipped pixels when automatic brighness increase is used (see no_auto_bright). Default is 0.01 (1%).
  • adjust_maximum_thr (float) -- see libraw docs
  • bright (float) -- brightness scaling
  • highlight_mode (rawpy.HighlightMode <#rawpy.HighlightMode> | int) -- highlight mode
  • exp_shift (float) -- exposure shift in linear scale. Usable range from 0.25 (2-stop darken) to 8.0 (3-stop lighter).
  • exp_preserve_highlights (float) -- preserve highlights when lightening the image with exp_shift. From 0.0 to 1.0 (full preservation).
  • gamma (tuple) -- pair (power,slope), default is (2.222, 4.5) for rec. BT.709
  • chromatic_aberration (tuple) -- pair (red_scale, blue_scale), default is (1,1), corrects chromatic aberration by scaling the red and blue channels
  • bad_pixels_path (str) -- path to dcraw bad pixels file. Each bad pixel will be corrected using the mean of the neighbor pixels. See the rawpy.enhance <#module-rawpy.enhance> module for alternative repair algorithms, e.g. using the median.



Exceptions

NotSupportedError

rawpy.NotSupportedError is raised if a feature of LibRaw is used that was not enabled during the LibRaw library build, for example demosaic algorithms that are part of the GPL2/GPL3 packs.

class rawpy.NotSupportedError(self, message, min_version=None)

LibRawError

rawpy.LibRawError is the base type of rawpy.LibRawFatalError and rawpy.LibRawNonFatalError and can be used to catch any LibRaw errors.

class rawpy.LibRawError

LibRawFatalError

class rawpy.LibRawFatalError

The following error types are subtypes of rawpy.LibRawFatalError:

class rawpy.LibRawUnsufficientMemoryError

class rawpy.LibRawDataError

class rawpy.LibRawIOError

class rawpy.LibRawCancelledByCallbackError

class rawpy.LibRawBadCropError

class rawpy.LibRawTooBigError

class rawpy.LibRawMemPoolOverflowError

LibRawNonFatalError

class rawpy.LibRawNonFatalError

The following error types are subtypes of rawpy.LibRawNonFatalError:

class rawpy.LibRawUnspecifiedError

class rawpy.LibRawFileUnsupportedError

class rawpy.LibRawRequestForNonexistentImageError

class rawpy.LibRawOutOfOrderCallError

class rawpy.LibRawNoThumbnailError

class rawpy.LibRawUnsupportedThumbnailError

class rawpy.LibRawInputClosedError

class rawpy.LibRawNotImplementedError

Enumerations

RawType

class rawpy.RawType(*values)
RAW image type.
Flat = 0

Stack = 1


ThumbFormat

class rawpy.ThumbFormat(*values)
Thumbnail/preview image type.
BITMAP = 2

JPEG = 1


DemosaicAlgorithm

class rawpy.DemosaicAlgorithm(*values)
Identifiers for demosaic algorithms.
AAHD = 12

AFD = 6

AHD = 3

AMAZE = 10

DCB = 4

DHT = 11

LINEAR = 0

LMMSE = 9

MODIFIED_AHD = 5

PPG = 2

VCD = 7

VCD_MODIFIED_AHD = 8

VNG = 1

checkSupported(self)
Like isSupported but raises an exception for the False case.

property isSupported
Return True if the demosaic algorithm is supported, False if it is not, and None if the support status is unknown. The latter is returned if LibRaw < 0.15.4 is used or if it was compiled without cmake.

The necessary information is read from the libraw_config.h header which is only written with cmake builds >= 0.15.4.



ColorSpace

class rawpy.ColorSpace(*values)
Color spaces.
ACES = 6

Adobe = 2

P3D65 = 7

ProPhoto = 4

Rec2020 = 8

Wide = 3

XYZ = 5

raw = 0

sRGB = 1


HighlightMode

class rawpy.HighlightMode(*values)
Highlight modes.
Blend = 2

Clip = 0

Ignore = 1

classmethod Reconstruct(self, level)
Parameters
level (int) -- 3 to 9, low numbers favor whites, high numbers favor colors


ReconstructDefault = 5


FBDDNoiseReductionMode

class rawpy.FBDDNoiseReductionMode(*values)
FBDD noise reduction modes.
Full = 2

Light = 1

Off = 0


Named Tuples

ImageSizes

class rawpy.ImageSizes(raw_height, raw_width, height, width, top_margin, left_margin, iheight, iwidth, pixel_aspect, flip, crop_left_margin, crop_top_margin, crop_width, crop_height)
Create new instance of ImageSizes(raw_height, raw_width, height, width, top_margin, left_margin, iheight, iwidth, pixel_aspect, flip, crop_left_margin, crop_top_margin, crop_width, crop_height)

Thumbnail

class rawpy.Thumbnail(format, data)
Create new instance of Thumbnail(format, data)

Other

class rawpy.Other(iso_speed, shutter_speed, aperture, focal_length, timestamp, shot_order, artist)
Create new instance of Other(iso_speed, shutter_speed, aperture, focal_length, timestamp, shot_order, artist)

Lens

class rawpy.Lens(model, make, min_focal, max_focal)
Create new instance of Lens(model, make, min_focal, max_focal)

Modules

enhance module

rawpy.enhance.find_bad_pixels(paths, find_hot=True, find_dead=True, confirm_ratio=0.9)
Find and return coordinates of hot/dead pixels in the given RAW images.

The probability that a detected bad pixel is really a bad pixel gets higher the more input images are given. The images should be taken around the same time, that is, each image must contain the same bad pixels. Also, there should be movement between the images to avoid the false detection of bad pixels in non-moving high-contrast areas.

Parameters
  • paths (iterable of str) -- paths to RAW images shot with the same camera
  • find_hot (bool) -- whether to find hot pixels
  • find_dead (bool) -- whether to find dead pixels
  • confirm_ratio (float) -- ratio of how many out of all given images must contain a bad pixel to confirm it as such

Returns
coordinates of confirmed bad pixels
Return type
ndarray of shape (n,2) with y,x coordinates relative to visible RAW size


rawpy.enhance.repair_bad_pixels(raw, coords, method='median')
Repair bad pixels in the given RAW image.

Note that the function works in-place on the RAW image data. It has to be called before postprocessing the image.

Parameters
  • raw (rawpy.RawPy <#id0>) -- the RAW image to repair
  • coords (array-like) -- coordinates of bad pixels to repair, array of shape (n,2) with y,x coordinates relative to visible RAW size
  • method (str) -- currently only 'median' is supported



rawpy.enhance.save_dcraw_bad_pixels(path, bad_pixels)
Save the given bad pixel coordinates in dcraw file format <http://www.cybercom.net/~dcoffin/dcraw/.badpixels>.

Note that timestamps cannot be set and will be written as zero.

Parameters
  • path (str) -- path of the badpixels file that will be written
  • bad_pixels (array-like) -- array of shape (n,2) with y,x coordinates relative to visible image area



•
Index <>

Author

Maik Riechert

Copyright

2014, Maik Riechert

May 11, 2026 0.27.0