This project was created by undergraduate computer science students, supervised by David-Elias Künstle and Felix Wichmann, as part of a practical software development course at the University of Tübingen. The final version of the students is marked as v1.0.

1. About the project
2. Features
3. Getting Started
4. Usage
5. Contributing
6. License
7. Sources

This is the repository for the teamproject course, summer term 2021, working on automating photography manipulation. The Plug-in is part of the teamproject of the University of Tübingen.

We are four female students at the University of Tübingen and we are all studying computer science.

• The special thing about our Plug-in is that you can select several images at once and import, export and edit them.
• exports selected images in a matrix-modification format
• processes the images using all possible combinations e.g. Contrast = [10,20], Saturation = [30,40]
  the following combinations will be applied on your selected photos:
  {[Contrast = 10, Saturation = 30],[Contrast = 10 , Saturation = 40], [Contrast = 20, Saturation = 30], [Contrast = 20 , Saturation = 40]}
• available settings:

• Exposure
• Contrast
• Highlights
• Shadows
• Whites
• Blacks
• Clarity
• Vibrance
• Saturation

• You need Adobe Lightroom Classic 10.3 with an access to the Creative Cloud.

• Download the whole project or only the folder lightroom_plugin.lrdevplugin(use green "Code"-Button). The folder itself can be anywhere on your computer.

• Create a new directory called "TheImageIterator" under the standard home directory.

  Home directory..

  • for Windows: C/Users/username/

  • for Mac OS: /Users/username/ (Shortcut: Command+Shift+H)

• Make sure to save the configuration file imageIteratorSettings.json under this folder.

• Add the Plug-in in Lightroom Classic: File -> Plug-in Manager... -> Add -> Select the folder of the plugin lightroom_plugin.lrdevplugin -> Done

• Choose the pictures you want to edit.

• Execute the Plug-in: Library -> Plug-in Extras -> The Image Iterator

• After opening the Plug-in you can see the path of your created configuration file under the standard home directory.

• Overview Develop settings displays all settings, that were initially added to the configuration file (see Config file) and the current content of the key "Settings" in the configuration file.

• If you need any help for using the Plug-in, press the SUPPORT-Button. The following window will pop up:

• Add settings by typing them into the text field and set (max. 3) different values for these. Press the ADD-Button afterwards.
• The added setting is now visible in Overview Develop settings
• Every new added setting and every new change of values for a setting will make the text color of Overview Develop settings red. If nothing has changed and the ADD-Button is used again the text color will turn black.

• Use the HELP-Button so see a list of all available settings.

CAUTION: If you add a setting and delete it afterwards in the configuration file, you have to RELOAD the Plug-in (File -> Plug-in Manager -> RELOAD-Button -> Done). Now you can execute the Plug-in again.

• You can reset the values of every setting to 0 by using the RESET-Button.
  

• After adding the preferred settings and values correctly, start the editing and exporting progress by using the SAVE AND EDIT-Button and by confirming the progress. A progress bar will appear in the upper left corner. A window will pop up after successfully editing and exporting every photograph. A folder named Exported Photos will be created in lightroom_plugin.lrdevplugin (first time using SAVE AND EDIT-Button) and there will be all edited photographs. For later use, all photographs will be stored in this folder. (Update: GIF not up to date, window to confirm the progress was changed). As shown, our UI creates arrays with the length of 3. If you want to edit your photos with arrays of a length greater than 3, you can use the configuration file.

• You have two options to cancel the progress:

1. By using the CANCEL PROGRESS AND EXIT-Button. The progress will immediately stop and the Plug-in will be closed.
2. By closing the Plug-in and by using the X at the right end of the progress bar.

• If you add an unavailable setting or an invalid text (as the following example "Helloworld") the following error will be generated:

• You can find all available settings in Features or by using the HELP-Button.

• If there is already an unavailable setting or an invalid text in the configuration file and you want to start the editing and exporting progress by using the SAVE AND EDIT-Button, the following error will be generated:

• Open the configuration file imageIteratorSettings.json, remove every setting that is not mentioned in the list of available settings and reload the Plug-in.

• Don't delete the Exported Photos folder. Remove the content only, otherwise the following error will occur:

• After resolving the errors, reload the Plug-in and start it again.

Example for configuration file imageIteratorSettings.json:

{ 
"export_format":"JPEG", 
"Settings":{ 
"Contrast":[ 
10, 
30, 
60
 ], 
"Highlights":[ 
-60, 
-10, 
35
 ]
 }
 }

If there is no directory under the standard home directory with the configuration file in it, or if the directory exists, but the configuration file is missing, the following error will occur:

It's important that the structure is preserved.

{ "export_format":"JPEG", "Settings":{}}

If there is no Settings key or no export_format, the Plug-in won't work and the following error messages will appear:

• Missing keys:

• Missing values for "Settings":

Of course you can add more keys, but don't delete the existing ones. Otherwise we cannot guarantee that the Plug-in will work.

You can add more settings in the key Settings. If you want to modify the configuration file, you have to write the settings in lower case (except the first letter in upper case). The added settings should look like this "Settingname":[x,y,z] .

• The programming language of our project is Lua.
• Read the Lightroom Classic SDK guide. (You don't have to read each chapter). We would recommend reading the first two chapters of the SDK.
• Try to program your own small "Hello World" Plug-in using the SDK.

• Info.lua: This file describes your Plug-in e.g. the Lightroom Version, the title of your Plug-in and more
• Main file or as we call it "the UI file": in our case this file is called LibraryMenuItemPluginUI.lua It is called by the Info.lua file as the main script. This is where the magic happens. This file implements the whole User Interface of our Plug-in as well as a few functions. (Those are interacting with UI-objects, for example the text-fields.)

• In our case, the most important file is the configuration file called imageIteratorSettings.json. You can save the settings in the configuration file or use our UI for modifying the configuration file. The configuration file contains the settings for editing and other infomation. We implemented export_format and our Settings for editing. If you want to save for example the metadata, you have to implement functions in the Plug-in. In short, the configuration file contains information for the processing.

• Because the imageIteratorSettings.json file is a JSON-file, we use json.lua for decoding and encoding between JSON and Lua. It's an external JSON library for Lua. Here is the License for the json.lua file: (You can find it in json.lua as well.)

-- Copyright (c) 2020 rxi -- -- Permission is hereby granted, free of charge, to any person obtaining a copy of -- this software and associated documentation files (the "Software"), to deal in -- the Software without restriction, including without limitation the rights to -- use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies -- of the Software, and to permit persons to whom the Software is furnished to do -- so, subject to the following conditions: -- -- The above copyright notice and this permission notice shall be included in all -- copies or substantial portions of the Software. -- -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -- SOFTWARE. --

All external sources used in our Plug-in are listed at the end of this README.

• AdjustConfigurationFile.lua is the interface between LibraryMenuItemPluginUI.lua and the configuration file. It checks whether the configuration file exists, reads the configuration file, writes into the configuration file and so on. For the last two tasks, json.lua is absolutely necessary.

• DevelopSettingsCombinations.lua is an external code as well. Click here for getting to the source. Because it is code from Stack Overflow, it is licensed under the CC BY-SA 4.0 license. Here is the source of the Public Network Terms of Service. We extend the code for our usage with some functions based on it. This file gets the settings from the configuration file and creates a new table with all possible combinations from the settings of our configuration file. The code is well commented, so you should be able to read the comments for understanding each function.

• ExportPhotos.lua is a very short file with the duty to export our images.

The easiest way for importing images into our Plug-in is to import them into the Lightroom Classic Catalog and select them.

local catalog = LrApplication.activeCatalog()
local targetPhotos = catalog.targetPhotos

In this code, the targetPhotos are the selected photos in the catalog. Now you can work with them. It's that simple.

ExportPhotos.lua is responsible for the export of our images. You don't have to implement an ExportServiceProvider.

function ExportPhotos.processRenderedPhotos(photos, folderName)

gets the images and the foldername for export. This function creates an exportsession where you can change the settings for the export e.g. the format. We used

LR_export_destinationPathSuffix = folderName

for exporting in different folders. Each time the function function ExportPhotos.processRenderedPhotos(photos, folderName) is called, the photos will be exported in the associated folders. If you want to export all of the images into one folder, then you have to change the variable folderName into a string.

We use the function photo:quickDevelopAdjustImage(settingName, size) from the class LrPhoto for editing our images. The following settings are available for editing with this function : Features

You can find more settings in the Namespace LrDevelopController. The settings that we have not listed, can not be used within the photo:quickDevelopAdjustImage(settingName, size). If you want more available settings, you have to implement the whole Develop Controller. Our UI creates arrays with the length of 3. If you want to edit your photos with arrays of a length greater than 3, you can use the configuration file. If the UI should create array of length of n elements, you have to implement this.

Distributed under the MIT License.

1. JSON Library for Lua Accessed: May 20, 2021
2. Sample pictures for testing the Plug-in Accessed: May 22, 2021
3. Code from Stack Overflow for finding all possible combinations of arrays recursively
4. Split function for strings