API documentation ================= pyunraw ####### The module pyunraw contains three attributes version and one class PyUnraw. **Attributes** .. * :ref:`version ` * :ref:`__version__ ` * :ref:`__dcraw_version__ ` **Documentation** .. _version: .. attribute:: version A tuple containing the three components of the version number: major, minor, micro. .. _version__: .. attribute:: __version__ The version of the module as a string (major.minor.micro). .. _dcraw_version__: .. attribute:: __dcraw_version__ A tuple containing the two components of the version number: major, minor. .. class:: pyunraw.PyUnraw **Instance Attributes** .. * :ref:`filename ` * :ref:`out_filename ` * :ref:`data ` * :ref:`is_raw ` * :ref:`profile ` * :ref:`has_preview ` **Instance Methods** .. * :func:`__init__(filename="") <__init__>` * :func:`apply_new_profile(profile) ` * :func:`clean_artifacts(passes) ` * :func:`find_white_balance(x=0, y=0, w=0, h=0) ` * :func:`fix_dead_pixels(fname="") ` * :func:`get_file_properties() ` * :func:`get_preview(dest="") ` * :func:`get_unraw_parameters() ` * :func:`ignore_white_balance() ` * :func:`quick_unraw(dest="") ` * :func:`read_profile(fname) ` * :func:`reset_profile() ` * :func:`rotate_fuji(rotate) ` * :func:`save_profile(fname, pickle_=False) ` * :func:`set_black_layer(filename=None) ` * :func:`set_brightness(factor) ` * :func:`set_color_space(space) ` * :func:`set_darkness(level) ` * :func:`set_gamma_curve(power, toe_sloop=0) ` * :func:`set_highlights(level) ` * :func:`set_ICC_profile(profile, output="") ` * :func:`set_interpolation_method(method) ` * :func:`set_noise_threshold(threshold) ` * :func:`set_orientation(orientation) ` * :func:`set_output_format(use_tiff=True) ` * :func:`set_saturation(level) ` * :func:`set_source_file(path) ` * :func:`set_white_balance(red, green, blue, green1=0) ` * :func:`stretch_red_blue_layers(red, blue) ` * :func:`unraw(index=0, dest="") ` * :func:`unraw_dark(filename, dest="") ` * :func:`validate(filename) ` * :func:`write_sixteen_bits(apply_, linear=False) ` **Documentation** .. _filename_: .. attribute:: filename The complete path of the raw file. .. _out_filename_: .. attribute:: out_filename The complete path of the decoded image file. .. _data_: .. attribute:: data A dictionnary which contains the properties of the raw image. .. _is_raw_: .. attribute:: is_raw True if the file can be decoded with dcraw, otherwise False. .. _profile_: .. attribute:: profile A dictionnary which contains the user's decoding parameters. .. _has_preview_: .. attribute:: has_preview True if the raw file contains at least one preview. **Methods** .. function:: __init__(filename="") Initialise the class PyUnraw with the raw file name. Argument: * *filename* The path/name.ext of the raw file, optionnal Raises: * *ValueError* if the file doesn't exists * *TypeError* if the file is clearly identified as a non-raw format, (jpeg, tiff, ppm, ...). See: :func:`validate(filename) ` .. function:: apply_new_profile(profile) Apply a decoding parameters profile. Argument: * *profile* A dictionnary with the decoding custom parameters .. function:: clean_artifacts(passes) Set the number of passes for the artifacts cleaning. Argument: * *passes* The number of passes .. function:: find_white_balance(x=0, y=0, w=0, h=0) Use a rectangular area to compute the white balance. The parameters calculated will be applyed automatically. Use PyUnraw.find_white_balance() to cancel this method. Arguments: * *x* The left side of the area * *y* The top side of the area * *w* The width of the area * *h* The height of the area .. function:: fix_dead_pixels(fname="") Fix the dead pixels given with the file fname. Argument: * *fname* Absolute path of the file .. function:: get_file_properties() Return the image properties as a dictionnary, same as the attribute PyUnraw.data. .. function:: get_preview(dest="") Extract a preview embeded into the raw file. The attribute PyUnraw.has_preview define if there's at least one preview in the raw file. After writing the preview on disk, the attribute PyUnraw.preview define the file name or None if the process failed. If there's more than one preview into the file, dcraw extract the first one found. If you want to choose the preview consider `py3exiv2 `_. Argument: * *dest* Absolute path of destination file. If not provided, the name of the preview is build with the name of the file source and the suffix `_thumb` i.e. DSC0786.NEF --> DSC0786_thumb.jpg .. function:: get_unraw_parameters() Return all the parameters (default and custom) used for the demosaication as python dictionnary. .. function:: ignore_white_balance() Use a fixed white level, ignoring the camera parameters. .. function:: quick_unraw(dest="") Decode a half-size middle-quality of the raw image. This only usefull to see a preview of the image when the (old) camera doesn't include a thumbnail into the file. If some custom parameters are already fixed, the profile is cleared and will be restaured after the demosaication. New in version 1.2 Argument: * *dest* Destination file name whitout extension Return the path of the file created .. function:: read_profile(fname) Read a profile from a file. The file must be pickled or write as a json file. The new profile is applied immediately. Argument: * *fname* Absolute path of the file .. function:: reset_profile() Reset all parameters to the default values. The profile dictionnary will be emptyed. .. function:: rotate_fuji(rotate) Rotate the decoded image to 45°. For Fuji Super CCD cameras where the image are tilted 45 degrees. Argument: * *rotate* Boolean: True, apply the rotation (default) False, keep the image tilted 45 degrees .. function:: save_profile(fname, pickle_=False) Save the profile on disk. Arguments: * *fname* Absolute path of the file to save the profile * *pickle_* Boolean: If False (default) the profile will be saved as a json file, if True it will be pickled .. function:: set_black_layer(filename=None) Set the name of the dark frame. If the file is already a .pgm file, the file is checked for validity. If the file is yet a raw file it will be converted into a valid .pgm Argument: * *filename* Absolute path of the file Raises: * *PgmSizeError* if the size of the frame is not the same size of the source file * *PgmEncodingError* if the .pgm is not encoded in 16 bits .. function:: set_brightness(factor) Divide the white level by this number, 1.0 by default. Argument: * *factor* The value to divide the white level .. function:: set_color_space(space) Define the output color space. This cancel a previously ICC profile defined. Use PyUnraw.set_color_space(1) to reset to default value (sRGB D65). Argument: * *space* Index of the color space: * 0 : Raw color (unique to each camera) * 1 : sRGB D65 (default) * 2 : Adobe RGB (1998) D65 * 3 : Wide Gamut RGB D65 * 4 : Kodak ProPhoto RGB D65 * 5 : XYZ * 6 : ACES .. function:: set_darkness(level) Set the level of darkness. Argument: * *level* The level of darkness .. function:: set_gamma_curve(power, toe_sloop=0) Set the gamma curve values. Use PyUnraw.set_gamma_curve(0) to reset to the default values BT.709 (2.222 4.5). Arguments: * *power* The value of the power * *toe_sloop* The value of the sloop .. function:: set_highlights(level) Set the highlights level. Use PyUnraw.set_highlights(0) to reset the parameter. Argument: * *level* The level of highlights, the value must be in range(10): * 0 : Clip all highlights to solid white (default) * 1 : Leave highlights unclipped in various shades of pink * 2 : Blend clipped and unclipped values together for a gradual fade to white * 3~9 : Reconstruct highlights. Low numbers favor whites; high numbers favor colors. Try 5 as a compromise .. function:: set_ICC_profile(profile, output="") Apply an ICC profile to the image. The ICC profile can be embeded into the camera, that can be checked with PyUnraw.data["embeded_icc"]. Arguments: * *profile* The ICC profile: * False : Don't apply an ICC profile * True : Apply the embeded ICC profile * Absolute path of "camera.icm" * *output* "path/camera.icm": File name to write the embeded ICC profile .. function:: set_interpolation_method(method) Set the interpolation method. Argument: * *method* The index of the method: * 0 : Use high-speed, low-quality bilinear interpolation * 1 : Use Variable Number of Gradients (VNG) interpolation * 2 : Use Patterned Pixel Grouping (PPG) interpolation * 3 : Use Adaptive Homogeneity-Directed (AHD) interpolation (default) * 4 : Interpolate RGB as four colors * 5 : Show the raw data as a grayscale image with no interpolation * 6 : Same as #5, but with the original unscaled pixel values * 7 : Same as #6, but masked pixels are not cropped * 8 : Output a half-size color image. Twice as fast as #0 .. function:: set_noise_threshold(threshold) Fix the noise threshold limit. The best value should be somewhere between 100 and 1000. Use PyUnraw.set_noise_threshold(0) to reset the parameter. Argument: * *threshold* The value of the threshold limit .. function:: set_orientation(orientation) Set the orientation of the decoded image. Argument: * *orientation* Integer which define the orientation. The integer must be in (-1, 0, 3, 5, 6, 90, 180, 270): * -1 : apply the orientation found into the metadata * 0 : no rotation (Default) * 3 or 180 : rotate 180° * 5 or 270 : rotate 270° * 6 or 90 : rotate 90° .. function:: set_output_format(use_tiff=True) Use the tiff format with metadata instead of ppm, pgm or pam. Argument: * *use_tiff* Boolean: Use tiff format if True (default), otherwise, depending of the source file, the format pgm, ppm or pam will be choosed .. function:: set_saturation(level) Set the level of saturation. Argument: * *level* The level of saturation .. function:: set_source_file(path) Set a new RAW source file. This doesn't reset the unrawing parameters previously fixed. This method is intended to unraw a list of raw files with the same parameters. Argument: * *filename* Absolute path of RAW source file .. function:: set_white_balance(red, green, blue, green1=0) Set the value of the white balance. To reset the white balance to the default values use 0 for each value. Arguments: * *red* The red value * *green* The green value * *blue* The blue value * *green1* The second green value, if 0 the value of green will be used .. function:: stretch_red_blue_layers(red, blue=0) Fix the chromatic aberration. Stretch the raw red and blue layers by the given factors, typically 0.999 to 1.001. Use PyUnraw.stretch_red_blue_layers(0) to reset to default values. Arguments: * *red* The red factor * *blue* The blue factor .. function:: unraw(index=0, dest="") Run the demosaication process. Arguments: * *index* The index of the image or "all" if there's more than one image into the file * *dest* The absolute file name for the image decoded. If a file with the same name already exists, it will be overwritten Raises: * *IndexError* if index >= raw.data["image_count"] .. function:: unraw_dark(filename, dest="") Decode a raw image as a dark. Arguments: * *filename* Absolute path of raw file * *dest* Absolute path of destination, if not provided the pgm file will be named wit the raw file name Returns the path of the pgm file or None if failed .. function:: validate(filename) Returns True if the file is a valid RAW image supported by dcraw. Argument: * *path* Absolute path of the file .. function:: write_sixteen_bits(apply_, linear=False) Write sixteen bits per sample. Arguments: * *apply_* Boolean: apply 16 bits if True * *linear* Boolean: apply 16 bits linear if True