`nik_adjustment` – Handle Nikon adjustments

Handle Nikon adjustments

The sidecar.nik_adjustment module implements handlers for the Nikon image adjustments stored in Nikon sidecar files.file. The article named “Inside Nikon Sidecar file” details the data structure and tags used by Nikon.

Each image adjustments, as declarated in the observed sidecar file have its own class to later implement the convert Nikon parameters to Darktable module parameters if it possible. Nevertheless, all these classes are derived from the base class NikBaseAdjustment. This base class offers the interface contract and a set of common methods for decoding parameters expressed as XMP properties.

Using `nk_adjustment`

For this short tutorial, we have a dummy content of nine:NineEdits XMP property used as sample.

Listing 1 dummy nine:NineEdits XMP property

 <userData>
     <filter id="nikon::NoiseReduction">
         <active>true</active>
         <parameters>
             <integer name="NoiseReduction.version">13</integer>
             <integer name="NoiseReduction.endableMore">0</integer>
         </parameters>
     </filter>
     <filter id="nikon::transform">
         <active>true</active>
         <parameters>
             <integer name="Rotation">0</integer>
             <integer name="PreRotation">0</integer>
             <bool name="Flip">false</bool>
         </parameters>
     </filter>
     <filter id="nikon::DLightingHQ">
         <active>false</active>
         <parameters>
             <shadowAdjustment>50</shadowAdjustment>
             <highlightAdjustment>1</highlightAdjustment>
             <colorBoost>60</colorBoost>
         </parameters>
     </filter>
 </userData>

We use a linearized form of the XMP property expressed as a string.

>>> prop = ('<userData><filter id="nikon::NoiseReduction"><active>true</active>'
...         '<parameters><integer name="NoiseReduction.version">13</integer>'
...         '<integer name="NoiseReduction.endableMore">0</integer></parameters>'
...         '</filter><filter id="nikon::transform"><active>true</active>'
...         '<parameters><integer name="Rotation">0</integer>'
...         '<integer name="PreRotation">0</integer><bool name="Flip">false</bool>'
...         '</parameters></filter><filter id="nikon::DLightingHQ"><active>false'
...         '</active><parameters><shadowAdjustment>50</shadowAdjustment>'
...         '<highlightAdjustment>1</highlightAdjustment><colorBoost>60'
...         '</colorBoost></parameters></filter></userData>')

We create an instance of NineEdits with the above string.

>>> from sidecar.nik_adjustment import NineEdits
>>> from xml.etree import ElementTree
>>> tree = ElementTree.fromstring(prop)
>>> procs = NineEdits(tree).adjustments

We can list the image ajustements declarated in the XMP property.

>>> procs
{'nikon::NoiseReduction': NikNoiseReduction object: active=True, 'nikon::transform': Niktransform object: active=True, 'nikon::DLightingHQ': NikDLightingHQ object: active=False}

We can access to the status (active or not) and its parameters for each image ajustement by using its shortname as key.

>>> procs['nikon::NoiseReduction']
NikNoiseReduction object: active=True
>>> procs['nikon::NoiseReduction'].active
True
>>> procs['nikon::NoiseReduction'].params
{'NoiseReduction.version': 13.0, 'NoiseReduction.endableMore': 0.0}

Reference

Exception

exception darkbridge.sidecar.nik_adjustment.NikAdjustmentError(message: str | None = '')

Bases: Exception

Base class for image’s adjustment parser exceptions.

Parameters:: message – (optional) Human readable string describing the exception.

message

Human readable string describing the exception.

Type:: str | None

Image adjustment objects

class darkbridge.sidecar.nik_adjustment.NineEdits(element: Element)

Bases: object

Nikon NineEdits (aka adjustments) container

Parameters:: element – XML element containing the NineEdits property.
Raises:: NikAdjustmentError – Generic error, the NikAdjustmentError.message details the error.

active: True indicate that the filter will be applied on the image associated to the sidecar files when opening in NX Studio.

params: filter’s parameters as a dictionnary.

class darkbridge.sidecar.nik_adjustment.NikBaseAdjustment(element: Element)

Bases: object

Base class for Nikon image’s adjustment class

Parameters:: element – XML element containing the metadata.
Raises:: NikAdjustmentError – Generic error, the NikAdjustmentError.message details the error.

active

True indicate that the image’s adjustments will be applied on the image associated to the sidecar files when opening in NX Studio.

Type:: bool

params

image’s adjustment parameters as a dictionnary.

Type:: dict

_set_params(element: Element)

Set image’s adjustment parameters.

This method parses an XML element as a image’s adjustment parameters block and store it in the parameters’ dictionary params according to its explicit or implicit type. As image’s adjustment parameterq are not documented (Nikon proprietary format), the method is permissive and not checks the data set.

The article named “Inside Nikon Sidecar file” details the data structure and tags used by Nikon.

Particular use cases

Parameters:: element – Element containing the parameter block.
Raises:: NikAdjustmentError – Generic error, the NikAdjustmentError.message details the error.

_set_param_dtstamp(element: Element)

Set datetime stamp parameter.

dateAndTime parameter is a date and a time expressed in a block with year, month, day, hour, minute and second xml tag. The date 1900-1-1 00:00:00 seems to be default value.

Parameters:: element – Element containing the parameter.
Raises:: NikAdjustmentError – Generic error, the NikAdjustmentError.message details the error.

_set_param_export(element: Element)

Set export parameter.

Export parameter is a binary string expressed as a set of two elements: ExportData and ExportDataSize. ExportData is a binary string encoded in Base64. ExportDataSize is the length of the encoded string.

Parameters:: element – Element containing the parameter.
Raises:: NikAdjustmentError – Generic error, the NikAdjustmentError.message details the error.

_set_param_map(element: Element)

Set map parameter.

Map parameter is a binary string expressed as a set of two elements: mapdata and mapsize. mapdata is a binary string encoded in Base64. mapsize is the length of the encoded string. This parameter contains data used by the dust off adjustment.

Parameters:: element – Element containing the parameter.
Raises:: NikAdjustmentError – Generic error, the NikAdjustmentError.message details the error.

_set_param_points(element: Element)

Set points parameter.

Points parameter is a set of 2D coordinates (x and y).

Parameters:: element – Element containing the parameter.
Raises:: NikAdjustmentError – Generic error, the NikAdjustmentError.message details the error.

is_dt_ready()

Return if this image’s adjustment may be used in Darktable.

The ….

Returns:: True if this image’s adjustment may be used in Darktable.

get_dt_module()

Return the image’s adjustment parameters for Darktable.