`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 images adjustements objects based the above string with the factory function create_nine_edits().

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

We can list the image ajustements declarated in the XMP property, create_nine_edits() returning a dictionary of image adjustments objects with the image adjustment name as key.

>>> 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 adjustement functions

darkbridge.sidecar.nik_adjustment.create_nine_edits(element: Element) → dict

Return the list of image adjustments

Parameters:: element – XML element containing the NineEdits property.
Returns:: Dictionary of image adjustments with the image adjustment name as key. The value is an instance of the image adjustment class (NikWhiteBalance, NikPictureControl or NikBaseAdjustment for example). See class documentation to have more details.
Raises:: NikAdjustmentError – Generic error, the NikAdjustmentError.message details the error.

Image adjustment objects

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

parse()

Parse the image adjustment XML element.

This method parses an XML element as an image’s adjustment block and populate attributes (active and params).

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

Raises:: NikAdjustmentError – Generic error, the NikAdjustmentError.message details the error.

_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 parameters 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_integer(element: Element)

Set integer parameter.

An integer may a decimal number or a boolean if its value is true or false.

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

_set_param_bool(element: Element)

Set boolean parameter.

As the NineEdits XML format is not documented, some type may be overloaded (boolean and integer for exemple).

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

_set_param_double(element: Element)

Set double parameter.

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

_set_param_data(element: Element)

Set data parameter.

Data is an unspecified text string

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

_set_param_binary(element: Element)

Set binary parameter.

Binary string encoded in base64 (seems similar to Export type parameters)

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

_set_default(element: Element)

Default setter for parameter.

Simple parameter is a simple tag, its type is guessed from its value. As the method is the default setter, it checks that the parameter is a simple one. If not a warning is logged.

Parameters:: element – Element containing the parameter.
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.

_set_param_point(element: Element)

Set point parameter.

Point parameter is a 2D coordinates (x and y). Please note that data structure is not the same than points.

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.

The ….

Returns:: /todo something .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Bases: NikBaseAdjustment

Nikon::NXHistory image’s adjustment class

Nikon::NXHistory is not strictly an image adjustment, it is an ordered list whose entries are tagged vith historystep. Each entry (aka. step) is an unitary image adjustment to apply to the image. For example, cropping an image should be done after image processing modifying the image size as lens correction or perspective controls). The list is stored in a dictionary with name historystep:XXX as key where XX is the step index (from 1 to 999).

The step parameters are in a dictionary with parameter name as key. The value type is set according to its explicit or implicit type.

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

_set_param_history_step(element: Element)

Set history step parameter.

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

_set_hs_filter(element: Element)

Set history step filter parameter.

This parameter is the image adjustment to apply.

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

_set_hs_adjustment_data(element: Element)

Set history step adjustmentData parameter.

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

_set_hs_default(element: Element)

Default setter for history step parameter.

Simple parameter is a simple tag, its type is guessed from its value.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

nik_adjustment – Handle Nikon adjustments

Using nk_adjustment