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 :doc:`api`.

First we import *pyunraw*::

  >>> import pyunraw

We can read the version of the module::

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

With :ref:`pyunraw.__version__ <version__>` we will get the version as string and, with :ref:`pyunraw.__dcraw_version__ <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 :ref:`raw.out_filename <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 :func:`raw.save_profile("profile_1.jsn") <save_profile>` or loaded from disk with :func:`raw.read_profile("profile_1.jsn") <read_profile>`. The profile loaded will be applied immediatelly.

We can also provide a dictionnary with :func:`raw.apply_new_profile(profile) <apply_new_profile>` or reset all parameters to the default values with :func:`raw.reset_profile() <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 :func:`validade(filename) <validade>`::

   >>> # 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: :func:`set_output_format(use_tiff=True) <set_output_format>`

The images taken in portrait orientation are not rotated, see: :func:`set_orientation(orientation) <set_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.