core – Darkbridge core module

Darkbridge core module

The darkbridge.core module schedules operations to convert the sidecar files. Main tasks are filtering/checking the supported image files, parsing the Nikon sidecar files, transforming the metadata and writing the result in a XMP sidecar file compliant with Darktable. Furthermore, this module displays the sidecar content in a ‘human-readable’ way, and allows to search a metadata or image adjustment by name in a file tree structure.

This module is built around two set of features: the first one is the core scheduler (DarkBridge) to process the sidecar file, the second one is the display manager (DefaultDisplay).

Using core

For this short tutorial, we have a photo in NEF format named ‘full_XMP.IPTC.NEF’ in the folder named ‘images_samples’ and is associated sidecar file (‘images_samples/NKSC_PARAM/full_XMP.IPTC.NEF.nksc’). We create an instance of DarkBridge) with a level of verbosity set to 2 to have field names and contents.

>>> from darkbridge.core import DarkBridge
>>> bridge = DarkBridge(2, ["images_samples\full_XMP.IPTC.NEF"], False, None)

We can list the metadata and image adjustement with DarkBridge.list(). The following output has been truncated to fit in the page.

>>> bridge.list()
List metadata from '['images_samples\full_XMP.IPTC.NEF']'...
[1/1] Image full_XMP.IPTC.NEF
    Metadata
      * appname: NX Studio
      * appversion: 1.10 W
      * xmp:Rating: 5
      * xmp:Label: Rose
      * dc:title: [Description] Titre
      * dc:subject: ['Mot-clé #1', 'Mot-clé #2', 'Mot-clé #3']
      ...
      * Iptc4xmpExt:Event: ['[Description] Evénement']
    Adjustment
      * nikon::PictureControl
          * Export: b'NCP\x00\x00\x00\x00\x01\x00\x00\x00$0100STANDARD...'
          * SelectedPictureControl: 0
          * AutoContrast: 255
          * AutoSaturation: 255
          * SelectedPictureControlVersion2: 0
          * SavedPicConProcess: 1
          * PictureControl: 0
      ...
List metadata from '['images_samples\full_XMP.IPTC.NEF']' completed...

We can search if a metadata has been entered with DarkBridge.search_meta() (dc:subject here, that contains the keyword).

>>> bridge.search_meta("dc:subject")
Search 'dc:subject' in metadata from '['images_samples\full_XMP.IPTC.NEF']'...
[1/1] Image full_XMP.IPTC.NEF
    Matching
      * dc:subject: ['Mot-clé #1', 'Mot-clé #2', 'Mot-clé #3']
Found 1 images - Number of files: 1

We can search if an image adjustement is active with DarkBridge.search_processing() (PictureControl here).

>>> bridge.search_processing("PictureControl")
Search 'PictureControl' in metadata from '['images_samples\full_XMP.IPTC...
[1/1] Image full_XMP.IPTC.NEF
    Matching
      * nikon::PictureControl
          * Export: b'NCP\x00\x00\x00\x00\x01\x00\x00\x00$0100STANDARD...'
          * SelectedPictureControl: 0
          * AutoContrast: 255
          * AutoSaturation: 255
          * SelectedPictureControlVersion2: 0
          * SavedPicConProcess: 1
          * PictureControl: 0
Found 1 images - Number of files: 1

The output in the examples above are the default one made by the DefaultDisplay. You can create a new class derived from the BaseDisplay or DefaultDisplay to customize the output (adding some colors, see darkbridge.main_cli.CLIDisplay for an example).

About verbosity level…

The verbosity level impacts the leval of detail of each output. Verbosity is a positive integer number between 0 and 3. Any values greater than 3 (or 2 for search) is considered the maximum level (i.e. 3 for list, 2 for search).

Table 1 verbosity level for list output

Level

output content (based on :class:DefaultDisplay`) [1]

0

write image name and a set of indicators. Example:

1

write relevant metadata (i.e. non-empty) and active image adjustments.

2

write metadata’s content and image adjustment parameters

3

write all metadata and image’s adjustment whatever its status.
Table 2 verbosity level for convert output

Level

output content (based on :class:DefaultDisplay`) [1]

0

write image name processed. Example:

1

write image name, metadata and active image adjustement processed.

2

write image name, metadata content and active image adjustement’s parameters processed.

3

write image name, metadata and image’s adjustment parameters processed whatever its status
Table 3 verbosity level for search output

Level

output content (based on :class:DefaultDisplay`) [1]

0

write the number of image files matching search criterias Example:

1

write image name, metadata and/or active image adjustments matching search criterias.

2

write image name, metadata’s content and image adjustment parameters matching search criterias.

3

ignored

Notes

Reference

Display objects

class darkbridge.core.BaseDisplay

Bases: object

Base class for managing display of image’s metadata.

This class is an abstract class used by DarkBridge to display metadata, processing module, progress status during an operation (DarkBridge.convert(), DarkBridge.list()). As it is an absract class, a concrete class should be defined by overriding one or more following methods:

start_convert(filenames: list[str], recursive: bool, dry_run: bool, force: bool, verbosity: int, total: int)

Display the conversion launching.

Parameters:
show_convert(index: int, path: Path, nksc: NikonSideCar)

Display a sidecar content after conversion.

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

complete_convert(index: int)

Display the conversion completion.

Parameters:

index – Index of the last image files. The index cannot be greater than _total parameter.

start_list(filenames: list[str], recursive: bool, verbosity: int, total: int)

Display the listing launching.

Parameters:

  • filenames – List of images _filenames (see DarkBridge)

  • recursive – True make a _recursive search (see DarkBridge)

  • verbosity – level of verbosity for the command output. The level should be 0 to 3 (see About verbosity level… for more details)

  • total – Number of image files in the processing pipe.

show_meta(index: int, path: Path, nksc: NikonSideCar)

Display sidecar contents.

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

complete_list(index: int)

Display the listing completion.

Parameters:

index – Index of the last image files. The index cannot be greater than _total parameter.

Display the searching launching.

Parameters:

  • filenames – List of images _filenames (see DarkBridge)

  • recursive – True make a _recursive search (see DarkBridge)

  • pattern – Substring to find in metadata field names.

  • verbosity – level of verbosity for the command output. The level should be 0 to 3 (see About verbosity level… for more details)

  • total – Number of image files in the processing pipe.

show_findings(index: int, path: Path, nksc: NikonSideCar, findings: dict)

Display the result of a search (unitary)

This method is called when the finding should be displayed.

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

  • findings – Dictionnary of metadata or image’s adjustment matching the pattern.

Display the searching completion.

Parameters:

  • index – Index of the last image files. The index cannot be greater than _total parameter.

  • matching – Number of image’s files where metadata or processing name match the pattern

ignore(path: Path)

Indicate that an image’s file is ignored.

An image’s files is ignored when it is not a supported image file or no sidecar file exists.

Parameters:

path – Path of the current image file.

class darkbridge.core.DefaultDisplay

Bases: BaseDisplay

Concrete class for managing display of image’s metadata.

This concrete class implements the default behavior for displaying image’s metadata. The display is simply based on standard output.

start_convert(filenames: list[str], recursive: bool, dry_run: bool, force: bool, verbosity: int, total: int)

Display the conversion launching.

Parameters:
show_convert(index: int, path: Path, nksc: NikonSideCar)

Display a sidecar content after conversion.

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

complete_convert(index: int)

Display the conversion completion.

Parameters:

index – Index of the last image files. The index cannot be greater than _total parameter.

start_list(filenames: list[str], recursive: bool, verbosity: int, total: int)

Display the listing launching.

Parameters:

  • filenames – List of images _filenames (see DarkBridge)

  • recursive – True make a _recursive search (see DarkBridge)

  • verbosity – level of verbosity for the command output. The level should be 0 to 3 (see About verbosity level… for more details)

  • total – Number of image files in the processing pipe.

show_meta(index: int, path: Path, nksc: NikonSideCar)

Display sidecar contents.

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

complete_list(index: int)

Display the listing completion.

Parameters:

index – Index of the last image files. The index cannot be greater than _total parameter.

Display the searching launching.

Parameters:

  • filenames – List of images _filenames (see DarkBridge)

  • recursive – True make a _recursive search (see DarkBridge)

  • pattern – Substring to find in metadata field names.

  • verbosity – level of verbosity for the command output. The level should be 0 to 3 (see About verbosity level… for more details)

  • total – Number of image files in the processing pipe.

show_findings(index: int, path: Path, nksc: NikonSideCar, findings: dict)

Display the result of a search (unitary)

This method is called when the finding should be displayed.

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

  • findings – Dictionnary of metadata or image’s adjustment matching the pattern.

Display the searching completion.

Parameters:

  • index – Index of the last image files. The index cannot be greater than _total parameter.

  • matching – Number of image’s files where metadata or processing name match the pattern

ignore(path: Path)

Indicate that an image’s file is ignored.

An image’s files is ignored when it is not a supported image file or no sidecar file exists.

Parameters:

path – Path of the current image file.

_show_meta_v0(index: int, path: Path, nksc: NikonSideCar)

Display an overview of sidecar contents (verbosity 0).

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

_show_meta_v1(index: int, path: Path, nksc: NikonSideCar)

Display sidecar contents (verbosity 1).

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

_show_meta_v2(index: int, path: Path, nksc: NikonSideCar)

Display sidecar contents (verbosity 2).

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

_show_meta_v3(index: int, path: Path, nksc: NikonSideCar)

Display sidecar contents (verbosity 3).

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

_show_findings_v1(index: int, path: Path, nksc: NikonSideCar, findings: dict)

Display the result of a search (verbosity 1).

This method is called when the finding should be displayed.

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

  • findings – Dictionnary of metadata or image’s adjustment matching the pattern.

_show_findings_v2(index: int, path: Path, nksc: NikonSideCar, findings: dict)

Display the result of a search (verbosity 2).

This method is called when the finding should be displayed.

Parameters:

  • index – Index of the current image files. The index cannot be greater than _total parameter.

  • path – Path of the current image file.

  • nksc – Object containing the metadata and processing data of the current image.

  • findings – Dictionnary of metadata or image’s adjustment matching the pattern.

_dump_data(data: bytes, prefix: str)

Dump an obscure data structure.

This method returns a human-readable representation of an obscure data (unknown or obfuscated data structure). The representation is a common one based on standard hexacimal dump (left part with bytes expressed in hexadecimal and right part as character if possible.

Parameters:

  • data – Obscure data expressed as binary array.

  • prefix – String starting output lines to indent the output if needed

Scheduler object

class darkbridge.core.DarkBridge

Bases: object

Convert sidecar files from Nikon NX Studio (._nksc) in sidecar files compliant with Darktable.

Parameters:

  • verbosity – level of verbosity for the command output. The level should be 0 to 3 (see About verbosity level… for more details).

  • pathname – List of pathname of images files list based on patterns as defined by Path.glob() function (see Pattern language for more details)

  • recursive – True make a _recursive search of images files in subfolders.

_append_path()

Add the path in the list of files to process.

Only supported images files with a sidecar file are considered.

Parameters:

path – filesystem path of the image file to add.

_build_filelist() → int

Build the images files list based on patterns as defined in glob.glob function.

The method returns a list of unique image files. If the selection pattern covers the same directory, the files are included only once.

Returns:

Number of filesystem path of image files to process

convert(dry_run: bool, force: bool) → bool

Entry point to launch conversions to Darktable sidecar files

This method searches sidecar files in the required folders (and subfolders if _recursive is True), reads the metadata and create or modify the sidecar files in XMP format at the same level as the original image file.

Parameters:

  • dry_run – True runs in preview mode without any sidecar writing.

  • force – True overwrites existing sidecar files without prompting for confirmation.

Returns:

True if the execution went well. In case of failure, an error is written on console.

list() → bool

Entry point to launch metadata listing.

This method searches sidecar files in the required folders (and subfolders if _recursive is True), reads the metadata and list metadata for each file.

Returns:

True if the execution went well. In case of failure, an error is written on console.

search_meta(pattern: str) → bool

Entry point to search a pattern in metadata

This method searches sidecar files in the required folders (and subfolders if _recursive is True), reads the metadata and indicate if the pattern is found in metada.

Parameters:

pattern – Substring to find in metadata field names.

Returns:

True if the execution went well. In case of failure, an error is written on console.

search_processing(pattern: str) → bool

Entry point to search a pattern in processing

This method searches sidecar files in the required folders (and subfolders if _recursive is True), reads the metadata and indicate if the pattern is found in active processings.

Parameters:

pattern – Substring to find in processing names.

Returns:

True if the execution went well. In case of failure, an error is written on console.