Tutorial

This tutorial is meant to give you a quick overview of what pyunraw allows you to do. You can just read it through or follow it interactively, in which case you will need to have pyunraw installed. It doesn’t cover all the possibilities offered by pyunraw, only a basic subset of them. For complete reference, see the API documentation.

First we import pyunraw:

>>> import pyunraw

We can read the version of the module:

>>> pyunraw.version
(1, 0, 0)

With pyunraw.__version__ we will get the version as string and, with pyunraw.__dcraw_version__, this is the version of dcraw which is returned as tuple.

We then instanciate PyUnraw with an image and read his properties:

>>> raw = pyunraw.PyUnraw("_DSC2849.NEF")
>>> for key, value in raw.data.items():
...     print(" %-20s%s" %(key, str(value)))
...
 camera              Nikon
 model               D5000
 time                1507263878
 ISO                 250
 image_count         1
 owner
 shutter             30.0
 aperture            9.0
 focal               62.0
 embeded_icc         0
 white_balance       (2.00850820541, 0.92519360780, 1.0760494470596313, 0.0)
 multipliers         (421.0, 256.0, 496.0, 256.0)
 image_size          (4310, 2868)
 output_size         (4310, 2868)
 color_count         3
 bits_per_sample     12
 preview             1
 date_time           2017-10-06 06:24:38
 color_space         1
 icc_profil          None
 white_adjust        None
 template_wb         None
 color_matrice       True

The key image_count is the number of raw image found into the file, in this case: 1.

We can check if the file is a valid raw file:

>>> raw.is_raw
True

Before we adjust some demosaicing parameters, we need to see the image decoded with the parameters provided by the camera:

>>> raw.unraw(0, "_DSC2849_1")
Scaling with darkness 0, saturation 3840, and
multipliers 2.170906 1.000000 1.163053 1.000000
AHD interpolation...
Converting to sRGB colorspace...
>>> raw.out_filename
'_DSC2849_1.tiff'

The attribute raw.out_filename returns the name of the file created.

The default format is Tiff, if we prefer let dcraw to decide the type of the file, we have to use:

>>> raw.set_output_format(False)

After seeing the image produced, we can, now, change one or more parameters and re-run the demosaicing:

>>> raw.set_gamma_curve(2.4, 12.9)
>>> raw.set_interpolation_method(1)
>>> raw.unraw(0, "_DSC2849_2")

If we don’t change the output file name, the last one will be overwritten.

Profile

The custom parameters are permanent, if we want to make a new demosaication without a parameter already fixed we have to cancel it:

>>> raw.set_gamma_curve(0)   # reset to default (BT.709)
>>> raw.set_interpolation_method(3)
>>> raw.unraw(0, "_DSC2849_3")

Now, if we want to proceed with an new raw image, we have two choices. Create a new instance of PyUnraw or just change the source raw file name:

>>> raw = pyunraw.PyUnraw("_DSC2850.NEF")
>>> # or
>>> raw.set_source_file("_DSC2850.NEF")

In the first case, all customs parameters are reset to the default values, in the other case, the new image can be decoded immediately with the same parameters as the last one.

pyunraw keep a demosaicing profile into a dictionnary which contains the custom parameters. We can get this profile:

>>> raw.profile
{'gamma': [2.4, 12.9], 'interpolation': 1}

The profile can be saved on disk with raw.save_profile("profile_1.jsn") or loaded from disk with raw.read_profile("profile_1.jsn"). The profile loaded will be applied immediatelly.

We can also provide a dictionnary with raw.apply_new_profile(profile) or reset all parameters to the default values with raw.reset_profile().

After demosaication, we can get all parameters, default and custom, used for this image:

>>> p = raw.get_unraw_parameters()
>>> for k, v in p.items():
...     print(" %24s : %s" %(k, str(v)))
...
         White balance : (0.0, 0.0, 0.0, 0.0)
           Auto bright : 1
           Gamma curve : (0.4166666567325592, 12.899999618530273)
  Chromatic aberration : (1.0, 1.0)
           Color space : 1
           ICC embeded : 0
             File .icm : None
       Noise threshold : 0.0
            Highlights : 0
               Quality : 1
         Document mode : 0
             Half size : 0
        Four color RGB : 0
       Clean artifacts : 0
              Darkness : -1
            Saturation : -1
            Brightness : 1.0
               16 bits : 8
        16 bits linear : 0
            Embeded WB : 0

Workflow

pyunraw is NOT thread safe. That means we can decode one image into a thread but we can’t run several process in the same time. We have to wait the end of a thread before run the next one.

If we need to sort raw files and non-raw files, we have the method validade(filename):

>>> # we can instanciate PyUnraw without file name
>>> raw = pyunraw.PyUnraw()
>>> for f in list_of_files:
...     if raw.validate(f):
...         # use f as raw file

Differences with dcraw

The default output format is Tiff, see: set_output_format(use_tiff=True)

The images taken in portrait orientation are not rotated, see: set_orientation(orientation).

Change the access and modification times with the datetime of the image is not implemented, Python os.stats() and os.utime() can do that.