Warning, /documentation/digikam-doc/batch_queue/custom_script.rst is written in an unsupported language. File is not indexed.
0001 .. meta:: 0002 :description: digiKam Custom Script from Batch Queue Manager 0003 :keywords: digiKam, documentation, user manual, photo management, open source, free, learn, easy, batch, custom, script 0004 0005 .. metadata-placeholder 0006 0007 :authors: - digiKam Team 0008 0009 :license: see Credits and License page for details (https://docs.digikam.org/en/credits_license.html) 0010 0011 .. _custom_script: 0012 0013 Custom Script 0014 ============= 0015 0016 .. contents:: 0017 0018 Overview 0019 -------- 0020 0021 The batch Queue Manager allows to customize a **Workflow** with a specific plugin dedicated to run a script and process your images with external tools as `ImageMagick <https://imagemagick.org/>`_ or `ExifTool <https://en.wikipedia.org/wiki/ExifTool>`_ for example. 0022 0023 The Tool is named **Custom Script**, available in **Base Tools** list, and **Custom Tools** category. The goal is to pass to a script source code written by the user in the plugin, a series of environment variables handled in the code and re-routed for a custom usage with delegate command line programs installed on your computer. 0024 0025 .. figure:: images/bqm_custom_script.webp 0026 :alt: 0027 :align: center 0028 0029 The Batch Queue Manager Including a Custom Script in a Workflow 0030 0031 The tool provides these options: 0032 0033 - **Output Image Type**: this value allows to setup the expected type of image format to use at the output of your script. The default is **Same as input**, but you can set **JPEG**, **PNG**, or **TIFF**. Take a care that JPEG is a lossy compression format, only support 8-bit color depth, and does not supports transparency. 0034 0035 - **Shell Script**: this text edit field allows to enter the source code of your shell script. Under **Linux** and **macOS**, `Bash script <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_ is supported. Under **Windows** `Batch script <https://en.wikipedia.org/wiki/Batch_file>`_ is supported. 0036 0037 The keywords that you can use in your script code are listed below. The tool will replace all occurrences of keywords in script at run time before shell execution. Take a care that keywords are case sensitive. 0038 0039 - **$INPUT** for workflow input filename (with special characters escaped). 0040 0041 - **$OUTPUT** for workflow output filename (with special characters escaped). 0042 0043 .. important:: 0044 0045 A new file is always expected on **$OUTPUT**. With a script programs that do not create a new file (e.g. changing metadata with ExifTool) you must first copy **$INPUT** to **$OUTPUT** with a command appropriate to the operating system and then make the changes to **$OUTPUT**. 0046 0047 The environment variables that you can use in your script code are listed below: 0048 0049 - **TITLE**: to handle digiKam **Title** item properties from database. 0050 0051 - **COMMENTS**: to handle digiKam **Caption** item properties from database. 0052 0053 - **COLORLABEL**: to handle digiKam **Color Label** item properties from database. 0054 0055 - **PICKLABEL**: to handle digiKam **Pick Label** item properties from database. 0056 0057 - **RATING**: to handle digiKam **Rating** item properties from database. 0058 0059 - **TAGSPATH**: to handle digiKam **Tags** item properties from database. 0060 0061 .. note:: 0062 0063 Under Linux and macOS, environment variables can be accessed in script with **$** as prefix of variable names (for example **$INPUT**). The interpreter used to run the script is **/bin/bash**. 0064 0065 Under Windows, environment variables can be accessed in script with **%** as prefix and suffix of variable names (for example **%INPUT%**). The interpreter used to run the script is **cmd.exe**. 0066 0067 0068 Return Value 0069 ------------ 0070 0071 By convention, a **Bash script** under Linux and macOS, 0 is returned on success or an integer in the range 1-255 for something else. Use **exit < error_code >** to pass the return value on the workflow. 0072 0073 Under Windows, a **Batch script** returns 0 on success and another value for something else, but the value is a signed integer, so a negative value is possible. Use **EXIT /B < error_code >** to pass the return value on the workflow. 0074 0075 The Batch Queue Manager handles the value returned by your script. If zero is returned, the workflow continue as expected, else the workflow is broken and Batch Queue Manager stop the process. 0076 0077 Examples 0078 -------- 0079 0080 Proof of Concept 0081 ~~~~~~~~~~~~~~~~ 0082 0083 This First example that you can see below, ...do nothing special. It will print on the console the input/output file names and item properties passed from batch queue manager to the script and copy input file to output file (this stage is required else Batch Queue Manager returns an error as the target file does not exist). The script returns the value from the file copy command, this one is parsed by the Batch Queue Manager to check the workflow stream. 0084 0085 .. code-block:: bash 0086 0087 echo "INPUT FILE: $INPUT" 0088 echo "OUTPUT FILE: $OUTPUT" 0089 0090 echo "TITLE: $TITLE" 0091 echo "COMMENT: $COMMENT" 0092 echo "COLORLABEL: $COLORLABEL" 0093 echo "PICKLABEL: $PICKLABEL" 0094 echo "RATING: $RATING" 0095 echo "TAGSPATH: $TAGSPATH" 0096 0097 cp "$INPUT" "$OUTPUT" 0098 exit $? 0099 0100 If you have started digiKam from a terminal and enabled the debug traces on :ref:`Setup/Miscs/System dialog page <system_settings>`, you will see something like this: 0101 0102 .. code-block:: text 0103 0104 digikam.general: Action Thread run 1 new jobs 0105 digikam.general: Tool : index= 1 :: name= "UserScript" :: group= Digikam::BatchTool::CustomTool :: wurl= QUrl("file:///mnt/data/Images/SALAGOU") 0106 digikam.general: path: "/mnt/data/Images/SALAGOU/BatchTool-EpEjEz-9e1c7a12.digikamtempfile.JPG" 0107 digikam.general: Tool: "User Shell Script" 0108 digikam.general: Input url: QUrl("file:///mnt/data/Images/SALAGOU/DSC08833.JPG") 0109 digikam.general: Output url: QUrl("file:///mnt/data/Images/SALAGOU/BatchTool-EpEjEz-9e1c7a12.digikamtempfile.JPG") 0110 digikam.dplugin.bqm: Script stdout "INPUT FILE: /mnt/data/Images/SALAGOU/DSC08833.JPG\nOUTPUT FILE: /mnt/data/Images/SALAGOU/BatchTool-EpEjEz-9e1c7a12.digikamtempfile.JPG\nTITLE: Salagou Trip\nCOMMENT: \nCOLORLABEL: 5\nPICKLABEL: 3\nRATING: 3\nTAGSPATH: Places;Places/France;Places/France/Salagou Lake\n" 0111 digikam.dplugin.bqm: Script stderr "" 0112 digikam.dplugin.bqm: Script exit code: 0 0113 0114 The digiKam information taken from the database are: 0115 0116 - Item processed is **/mnt/data/Images/SALAGOU/DSC08833.JPG**. 0117 - Target filename is **/mnt/data/Images/SALAGOU/BatchTool-EpEjEz-9e1c7a12.digikamtempfile.JPG** (a temporary file generated by Batch Queue Manager). 0118 - Item Title is **Salagou Trip**. 0119 - Item Comment is null. 0120 - Item Color Label is **5** (Green). 0121 - Item Pick Label is **3** (Accepted). 0122 - Item Rating is **3 stars**. 0123 - Item Tags are **Places**, **Places/France**, **Places/France/Salagou Lake**. 0124 0125 Add a Watermark with ImageMagick 0126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 0127 0128 The second example below is more complex and uses **ImageMagick** command like tool to add a multiline text superimposed over pictures to create a visible watermark on the center of images. 0129 0130 .. code-block:: bash 0131 0132 watermark="This image is\ncopyrighted and\navailable with\nlimited usage" 0133 0134 in_file="$INPUT" 0135 out_file="$OUTPUT" 0136 0137 convert -size 2000x1000 xc:none -gravity center \ 0138 -stroke yellow -pointsize 120 -font Courier-BoldOblique -strokewidth 3 -annotate +100+100 "${watermark}" \ 0139 -blur 0x25 -level 0%,50% \ 0140 -fill white -stroke none -annotate +100+100 "${watermark}" \ 0141 "${in_file}" +swap -gravity center -geometry +0-3 \ 0142 -composite "${out_file}" 0143 0144 .. note:: 0145 0146 In this example, there is no explicit **exit** call to return a value to the Workflow. Bash uses the last called method as the returned value from the script, here the ImageMagick command line tool **convert**. 0147 0148 This give a result like below. 0149 0150 .. figure:: images/bqm_imagemagick_watermark.webp 0151 :alt: 0152 :align: center 0153 0154 The result of the Script Using ImageMagick to Apply a Watermark