README.md



Welcome to pyLIMI
Both Carl Zeiss' Smartzoom 5 and Leica's LAS light microscopes generate
extensive metadata during image recording. This software extracts and
combines this metadata with user-provided information, such as project
numbers and sample data, to create metadata files for recorded images
in JSON format.

Installation

To install the application, clone the repository to your local
computer using the command
git clone git@gitlab.rhrk.uni-kl.de:ivw-rdm-tools/pyLIMI.git,
or by downloading from
this HTML page.
Open your terminal, such as Anaconda prompt.
Navigate to the base directory of the application, for example, pyLIMI or pyLIMI-main.
Install the necessary requirements by running python -m pip install -r requirements.txt.


Research data management (RDM) subprocess
This section outlines the steps required to use pyLIMI for recording images
with IVW's Leica and SmartZoom microscopes. It functions as a subprocess of the
image recording process and cannot be used independently.
Metadata template

pyLIMI generates metadata files for all recorded images in accordance with the
IVW research data management handbook. To achieve this, it retrieves data from
three distinct sources and consolidates it into a unified metadata file for
each image. Initially, it imports a metadata template file (template).
pyLIMI's latest release always includes the most up-to-date recommended
version of a metadata template for light microscopic images recorded with
SZ5 or LAS.
If this built-in template does meet your requirements, you can supply a path
to a custom template when running pyLIMI's individual components.
The userdata folder

Next, create a new or edit an existing folder called userdata anywhere on
your (local) filesystem. This folder should contains user-defined metadata
that will be included into the metadata files of the microscopic images when running
create_metadata_files.py. For this, all .meta.json files in this folder will be
included in the .meta.json files of the microscopic images.


Example for data in the userdata subfolder.
The content of these files must be valid JSON and will be used as value of a key that is equal to the name of the file
without the .meta.json extension. For example, the content of the file "creators.meta.json"
will be used as the value for the "creators" key, and the content
of the file "sample.meta.json" will be used as the value for the "sample" key in the template:

For this process, the following rules apply:

The userdata directory can be empty, in which case no additional files will injected into the template.
Files with other extensions will be ignored.
Files names only serve as first-level keys. If nested documents should be inserted, pre-compile them and store them in the corresponding document.
The metadata within this folder will be included in each image that is processed during a run.
If images need different user-defined metadata, put them in separate folders an run create_metadata_files.py multiple times, modifying the metadata in metadata in-between.
If a file name represents a key that is already present in the template, its value will be overwritten without asking or warning.
If a file name represents a key that is not already present in the template, it will be created.

Extract metadata (and auto-extract tif images from czi images)

After updating the userdata folder, run the following command, e.g.
in an Anaconda shell:
python create_metadata_files.py -d image_folder -u userdata [-t templates]
Replace image_folder by the path to the folder to which you have
exported the SZ5 job/the LAS images of a given sample. Replace userdata
with the path to the folder where your user-defined metadata is located.
As an option, you can define the template folder with the -t templates option.
When left away, pyLIMI will use its built-in template.
For example, on Windows, run (use quotes for paths that include blanks!):
python create_metadata_files.py -d "D:/Daten/JohnDoe/1021501000/Probe 1" -u D:/Daten/JohnDoe/userdata
Although individual hierarchies of a path are separated by a backslash, i.e. "" on the Windows prompt,
pyLIMI will also accept folder paths in which components are separated by (forward) slashes, i.e. "/".
create_metadata_files.py will then search for images to process
in the specified folder. This can be czi-images or regular tif-files,
depending on whether the Smartzoom or the LAS microscope is used.
In the case of czi-files, tif images will be extracted.
The script will not only process images which are located directly in the
specified folder, but it will also iterate through any subdirectories,
to infinite depth. Therefore, do not process any folders that contain symbolic
links to directories, as this will result in an infinite loop.
Compress tif images

By default, LAS saves tif images uncompressed, which frequently
results in very high consumption of storage space. Therefore,
pyLIMI provides the compress_tif_images.py script which activates
LZW compression for all tif images in a specified folder.
LZW compression is lossless and therefore does not interfere
with bit-wise numerical analysis of the images. Applying it
universally is therefore a safe operation with respect to later
image analysis. It is therefore applied in-place, i.e. it will
modify the actual images instead of creating a compressed copy
(which would actually defeat the purpose of saving storage space).
Run the following command in order to compress tif files. Replace folder
with the absolute or relative path to your image folder. Remember
to enclose paths that contain blanks in quotes.
python compress_tif_images.py -d folder
Again, compress_tif_images.py will operate on any tif images
it finds in the specified folder and iterate any subfolder it
finds, again down to infinite depth. As create_metadata_files.py
extracts tif images from czi images, this allows for the convenient
compression of a large number of images in one run when specifying
a high level folder.
Derive jpg copies and imprint scalebar

Frequently, microscopic images should be used in presentations, reports
or scientific papers. For these purposes they usually require a scalebar.
Both the Smartzoom 5 software and LAS provide manual procedures which
insert a scalebar directly into a recorded image. When images are also
intended for numerical analysis, this is however not always feasible as
the scalebar overwrites the original pixel values where it is inserted
into the image. Multiple solutions exist for this issue, one being
multilayered images where the scalebar is stored in a separate overlay,
this preserving the actual pixel values at its location. When displayed,
the scalebar is then merged into the base layer of the image. Another
solution leaves the base image unmodified and instead inserts the scalebar
into a duplicate of the image. Both Smartzoom 5 and LAS provide manual
processes to produce such duplicates. However, especially with large numbers
of images, this requires multiple additional clicks and is error-prone as
it is easily forgotten.
To alleviate this issue, pyLIMI provides the derive_jpg_images.py script,
which creates duplicates of tif images in jpg format and automatically inserts
a scalebar into them.  Being jpg images, they will be significantly smaller
than the tif images created by both the SZ5 software and LAS.
Also, as the scale bar is dynamically generated based on the metadata,
that is extracted by create_metadata_files.py, the need to manually save
a copy that includes a scale bar is removed. Note that having created
.meta.json files with create_metadata_files.py is therefore a prerequisite
for running derive_jpg_images.py.
To run the script, execute the following command:
python derive_jpg_images.py -d image_folder -u userdata [-t template]
Replace image_folder by the relative or absolute path to your image directory. Remember
to enclose paths that contain blanks in quotes and userdata with the path to where
your user-defined metadata is located. As an option, you can define the template
folder with the -t template option. When left away, pyLIMI will use its built-in
template.
Important notice: As jpg images are compressed in a way which trades
fidelity of pixel values for reduction of storage space, these images are not
suitable for bit-wise numerical analysis
Batch processing

You can run
create_metadata_files.py,

compress_tif_images, and

derive_jpg_images
sequentially with one single command:
python batch_process.py -d image_folder -u userdata [-t template]
End of the RDM subprocess

After having completed this subprocess, return to the main workflows for
recording images with either SZ5 or LAS.

Workflow for recording images with the Smartzoom 5 microscope
The workflow for recording images with the Zeiss Smartzoom 5 microscope is as follows:

Start

Switch on the microscope's computer, log in and start the SZ5 software.
Create new job


Creating a new job with the Smartzoom 5 software.
Create a new job (1) and give the new job a name that identifies the pictured sample (2).
The job's name will later be used as the name for the folder in which all images
that get recorded for this sample will be stored. Therefore, do not use any information
for creating the job name that only applies to a subset of the images (e.g. 'sample 1, top'
when you will also record images from the sample's bottom). Also, do not investigate
different samples in one job.
Put the sample on the microscope stage.
Record overview image

At the beginning of each job, the SZ5 software assumes users to record a special type
of image, called 'overview image'. This image is meant to give the viewer a general overview
of the recorded sample at a low magnification. It is only intended to provide context for
any recorded detail images. While it is possible not to record such an overview image,
pyLIMI works best when such an image is present. Therefore, record such an image by clicking
on "OK" (3) and proceed.
Record images

Currently, pyLIMI supports single images and xy-stitched images. Nagivate to the next image's
region of interest, adjust all recoding parameters and record an image of one these types.
Image recording loop

For the current sample, continue recording images of the supported types in sequence
until all desired images have been recorded. While doing so do not export any single images.
pyLIMI will later export all recorded images from the exported czi job files.
Optionally, it will also create derivatives of all images that contain a scale bar.
Save and export job

Having recorded all images for a given sample, save the job (4, 5):


Saving and exporting a job with Smartzoom 5.
Next, export your job. For this, first click on the home button in the top-left corner of the screen
and then choose "Archiv" (6) from the menu:


Choose "Archiv" to switch to archive mode.
Next, select your job from the job list (7), click on the options menu (8)
and then choose "Exportieren" (9):


Select a job for export.
In the pop-up menu, choose "Jedes IPS einzeln" (10) to export each image into a seperate file.
When prompted for a file format, choose "czi" (11a). Then click on the three-dot button (11b)
to choose the destination folder for the export operation and click on "OK" (12):


Export to separate files and choosing a destination for the export.
It is highly recommended to use the same destination folder for exporting all jobs in one session.
At this location, the SZ5 software will create a separte folder for each job, that has the same name as the job.
Following this procedure for a set of 4 samples results in the situation depicted below:


Example of a folder that contains four jobs,
each of which representing a separate SZ5 job.
Each of these folder will then contain the overview image and the recorded sequence of
images. Images of a job do not receive individual names but are automatically named by
the SZ5 software by combining the job's name and a sequential index:


Example of a sample subfolder that contains the job's overview image and
a series of two different images. File names are auto-generated by the SZ5-software
based on a name convention scheme.
RDM subproccess

Now, execute the pyLIMI's RDM subprocess. Proceed to next sample after completing it.
Next sample

If applicable, change the sample and repeat this process until all samples have been
investigated.
Transfer data to storage location

After investigating all samples, transfer all data its respective storage location,
e.g. the project folder of the respective project.

Workflow for recording images with Leica's LAS software


Workflow for recording images with the Leica Application Suite (LAS).
Start

First, switch on the microscope's control unit and wait 20 seconds.
Then, switch on the microscope's personal computer, login and start
the Leica Application Suite (LAS).
Position sample, select image folder

Put the (next) sample on the microscope's stage. Then, select the folder where LAS should save all recorded images for this sample (1, 2).
Use a name that describes the pictured sample best, e.g. "Probe 1":

Selecting image folder for a specific sample.  
Record single image

On the left control panel select "Kamera" (3), adjust your image, and click on "Bild aufnehmen" (4):


Record single image with LAS.
When prompted for the image name, choose a name that best describes
the recorded image, e.g. "top". The image will be then be stored in the pre-selected image folder.
Info: Additionally, LAS will export and save a series of metadata files.
These contain auxiliary information about the images,
e.g. magnification, number of pixels in x and y direction
etc. You will not be asked to enter a storage location
for these metadata files. Instead, they will be stored
in a subfolder of the image folder called .Metadata,
which is a hidden folder in most operating systems due to
its leading dot.
Example: Assume you have recorded images of a sample
you call 'sample_1'. You have named the two images 'top'
and 'left'. Your image folder might then look like this:


Content of img/sample_1/


Content of img/sample_1/.Metadata/
The naming convention for relating single images with their respective LAS metadata
files therefore is:
relative/path/to/dir/filename.tif <-> relative/path/to/dir/.Metadata/filename.ext
where ext is any ofanx, cal.xml, eax, sbx, snr, thb.

LAS and pyLIMI both use this convention, so do not change any file names after
recording and do not move any file to another folder without also moving the
corresponding .Metadata folder.
If you want to split a collection of images that you have stored into a joint folder, use
your operating system's file explorer for this and proceed as follows:

backup the source folder so that you can restore the original state in case you make any mistakes
select a subset of the images in your source folder and the .Metadata subfolder

copy your selection to a new destination
delete the copied subset of pictures in your source folder, but keep the .Metadata subfolder
copy more subsets to other locations, always including the .Metadata subfolder, then delete only copied images
after having copied all images to their respective destinations delete the source folder

Record multi-step image

LAS allows for the recording of laterally stitched images, so called multi-step images:


Exemple of a 2x2-multi-step image recorded with LAS
For recording such an image, select "S" in the left panel (5):


Recording a laterally stitched image with LAS
Then, expand the options section (6) and tick "Mosaikbild erstellen" (7).
Optionally, tick "Einzelbilder speichern" for also saving the individual images
that make up the stitched image (7). Next, provide a folder name in which the
stitched image, its component images and all metadata will be saved in (8). LAS
will then create a subfolder in the pre-selected sample folder (10):


Auto-generated subfolder for stitched image
When recording a multi-step image LAS will not only store the stitched image
as a tif inside the specified subfolder, but also the individual component images (if ticked),
and the corrsponding metadata required by pyLIMI.
RDM subproccess

Now, execute pyLIMI's RDM subprocess. Proceed to next sample after completing it.
Next sample

If applicable, change the sample and repeat this process until all samples have been
investigated.
Transfer data to storage location

After investigating all samples, transfer all data its respective storage location,
e.g. the project folder of the respective project.

Support
Send any requests for support or bug reports to andreas.gebhard@ivw.uni-kl.de.

Creators
Andreas Gebhard 

lead programming
workflow design
documentation

Martin Detzel 

programming: metadata extraction for LAS

Marc Hein 

domain knowledge
testing
user training

Kevin Chen 

programming: PKDE connector


Credits
This software uses the following third party software according to their
respective licenses:

ImageMagick is an open-source image processing library by ImageMagick Studio LLC. It provides the image manipulation functionality for including scale bars in microscopic image. For more information about ImageMagick, visit https://imagemagick.org/.


Rights and license
pyLIMI is the result of the authors' work as employees of
Leibniz-Institut für Verbundwerkstoffe GmbH (IVW), located in Kaiserslautern,
Germany. IVW holds all rights to pyLIMI.
pyLIMI is released under the MIT license.
ImageMagick, which is bundled with pyLIMI, is subject to its own license,
detailed in bin/windows/LICENSE.txt and here.
All other dependencies, including Python and all required Python libraries,
are governed by their respective licenses.
Neither IVW nor the authors claim any rights on any dependency of pyLIMI.

Citation
Please cite as: Andreas Gebhard, Martin Detzel, Marc Hein, Kevin Chen (2024): pyLIMI,
https://gitlab.rhrk.uni-kl.de/ivw-rdm-tools/pyLIMI

Disclaimer
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, title,
and non-infringement. In no event shall the copyright holders or
anyone distributing the software be liable for any damages or
other liability, whether in contract, tort, or otherwise,
arising from, out of, or in connection with the software or
the use or other dealings in the software.