Here is what I learned from a frustrating situation with a paper that I submitted to a journal, where the author instructions allowed a LaTex submission but the editorial reality was different. This can work quite well and it is a much better solution than loading a PDF into your favorite word processor or Acrobat Pro, but expect to do some manual formatting after the conversion.

• have pandoc and citeproc installed on your system
• convert vector figures into PNG files
• become familiar with how styles work in your word processor (I am using Libre Office)
• get a csl file (citation style language) of the journal, or one that is close enough
• forcefully insert a section called “References” in your LaTex document because otherwise it will not be there in the docx file
• if you use math symbols, expect them to be some special type of object in the office document (example: $\dagger$)
• use the commands below to convert
• check for more complicated in-text citations like (some fact; Author 1999) and correct them if necessary
• check if there are problems with the author name disambiguation (author first names popping up in in-text citations) and correct by hand if necessary

There are approaches: 1) conversion without a reference document 2) conversion with a reference document

Without a reference document

pandoc -f latex -t  docx  --bibliography=your_bibfile.bib --citeproc --csl=journalname.csl -o name_of_office_document.docx name_of_tex_file.tex 

This is the simplest method. You simply change the weird default style to your needs in the word processor. However, if you find that you might have to change something in the LaTex code, you may have to repeat many manual steps.

With a reference document

pandoc -f latex -t  docx  --bibliography=your_bibfile.bib --citeproc --csl=journalname.csl --reference-doc=style_reference_document.docx -o name_of_office_document.docx name_of_tex_file.tex 

This approach has the benefit of being able to make changes in the LaTex file without having to repeat the formatting steps in the word processor. The downside is that your reference document might break certain things like reference formatting, if it is not how pandoc expects it to be.

If things are breaking, copy from the converted version without the reference document and inspect the style names. This might be especially important for tables.

Important: the bibliography style should be named “Bibliography” (not “Bibliography 1” as Libre Office names it).

If tables don’t render, check if they render in the converted version without the reference document.

Background

Stitching together images taken with a macro photography setup is not a trivial task. With some setups it is possible to use programs that are designed for microscopic images (very low distortion) like the Grid/Collection Stitching plugin for ImageJ/Fiji or the Montage all images in this layer function in TrakEM2. However, as soon as there is noticeable distortion in the images, there will be artefacts if you attempt to blend the aligned images to a panoramic image. Most panorama creators take into account the distiortion of the images. However, they also assume that the panorama was recorded by tilting the camera, which is not how one would record a panorama in macro photography. In macro photographic setups often a microscope table with X-Y drives or (motorized) X-Y stages are used to translate the photographed object. If the panorama creating sotware is unaware of this difference in recording, the alignment can fail or the stitched image might contain severe artifacts (which may not even be noticed). Fortunately, there is an open source program called Hugin that is capable of creating large panoramas and allows to precisely specify how the final image will be created, estimating and taking into account the distortion of the images and the translation movement. Hugin is forever free of charge and runs on all relevant modern operating systems such as Linux, Windows and MacOS.

Workflow using Hugin

1) All images should be of the same dimension. This sounds trivial but depending on the focus-merging software and settings, image dimensions can vary from image to image by a few pixels. If it is not possible to get the input images to be of the same size, you have to account for that later – depending on the images and the overlap it is possible that you will not get good results.

2) Make sure you have at least the 2022 version of Hugin (available as a flatpak). Under Interface in the top menu select Expert (you will need the expert settings later on).

3) Navigate to the Photos tab (if you are not already there).

4) Import your images by clicking the Add images... button and selecting all images that should contribute to the panorama.

5) Enter your camera and lens data. For the camera data you have to enter the crop factor of the camera sensor (relative to a full frame sensor), so for example 1.5 for a Nikon DX (APS-C) sensor. Note that this will change the HFOV (Horizontal Field Of View) value.

If you could not determine the focal length, e.g. because you did not use a standard lens or lost the information which lens you used, click Cancel and it will fill in default values, which can be very detrimental for your stitching results if not recalculated later (see below).

6) Under Feature matching click Create control points. Use the default option ‘Hugin’s CPFind’. You can inspect and manually edit the control points under the Control Points tab (useful for blurry images or images with large out of focus areas).

Check the number of control points and get a feeling for it.

7) Under Optimize select Custom parameters. Note that a new tab Optimzer appears.

8) Go to the the tab Optimzer.

Under Image orientation:

• Leave one image totally unchecked (Anchor image from the Photos tab, its position does not need to be optimzed)
• For all other images select only X(TrX) and Y(TrY) to be optimized. This is unless you need to account for (accidental) tilting that might have occurred while capturing (e.g. handheld camera, movement of the specimen by hand leading to rotation)

Under Lens Parameters check a and b. If you were not able to determine the focal length then you also need to check Hfov (v).

9) Click Optimize now!. The checked box Only use control points between activated images refers to settings from a different menu (all images are activated by default).

10) Go to the Stitcher tab and select the Projection to Rectilinear.

11) You can inspect your unblended stitching results now by clicking the iconized button Preview panorama or Preview panorama (OpenGL). This will open another window with the Simple interface. Use the sliders and the mouse wheel to zoom in and out.

12) Go back to the Stitcher tab and click the buttons Calcuate Field of View and Calculate Optimal Size. You may also click Fit Crop to Images. This will remove unoccupied image space; yet, it can also cut off areas of your panorama that stick out from a rectangluar arrangement. You can always crop the image later in a raster graphics editor like GIMP.

You can leave all remainder settings at their default values.

Click Stitch!

13) Before Hugin blends together your panorama, you need to save the stitching project, so that the command line programs that do the heavy lifting can read the information they require.

14) You will also be asked to provide a file name. Make sure to also append the desired file extension (.tif for the default Stitcher settings)

15) Hugin will then try to run your project and constantly tell you what it is currrently doing. Hugin may also open another where your project will appear as one job in a batch processing queue. Ignore the batch processing window – do not close it!

16) Note that the resulting panoramic images, especially when not automatically cropped, can have very large pixel dimensions. Because of this, it may be best to either use a powerful raster graphics editor like GIMP to open it and to crop it to the desired dimensions or to use a image viewer that is designed for large images like vipsdisp to open it.

Why should you care?

While most people can differentiate colours well, there is a surprisingly large portion of the population that consists of people with impairments regarding the differentiation of colours Wikipedia. Often this is referred to as colour blindness; however, most people with these conditons are not achromatic and do see different colours. The most prevalent type of colour vision deficiency affects up to 6% of the male population (colour vision deficiencies are much less prevalent in females). Therefore, if your figures are being viewed by a few hundred people, the chances are high that there is a part of your audience that has trouble differentiating colours.

What can we do about it?

Not using colours at all would be a waste of opportunities. One would throw a powerful toolset over board, that could have been used to communicate ones findings in a more intuitive way than in grayscale figures. Thankfully, colour vision deficiencies can be simulated in order to understand what colour combinations are most problematic and which colour combinations are fine fro most people.

Technical solutions

There is a variety of programs available to simulate the most common forms of colour vision impairment. Here are some of the solutions that I tried and and which worked out for me. Note that this selection is biased towards software that is free and available to use in Linux.

• Color Oracle: This is a Java based application available for Linux, MacOS and Windows. Note that for this you need a suitable Java runtime environment and a system tray. The software creates a still view of the entire screen that disappears with the next mouse click or keyboard button push.

• Daltonize python library: This is a python library that allows to convert image files. It can be used to integrate colour deficiency checking into your workflow by writing a shell script and executing it with a keyboard shortcut. No desktop environment is necessary for this. Here is how I use it on my laptop that currently runs the Qtile window manager.

#!/bin/bash
# This is based on the free and open programs scrot (screencapture), daltonize (deuteranopia filter) and feh (imageviewer)
# https://github.com/joergdietrich/daltonize
# Daltonize must not be used commercialy!

scrot ~/Pictures/deuter.png -o -q 100
daltonize ~/Pictures/deuter.png ~/Pictures/deuter.png -s 
feh ~/Pictures/deuter.png -F

• Custom Hot Corners - Extended (Gnome extension): This is an extension for the Gnome desktop environment that allows you to render a window with converted colours, so that you can actually work as if you were impaired. This allows you to tweak the colours without having to go back and forth as often as you would have to with the other two solutions presented above. If Gnome is your desktop environmaent of choice, this is probably the best solution out there. The extension serves as a frontend for the Gnome Universal Access tools and different functions can be grouped into custom menus, which then can be launched with keyboard shortcuts.

Why the command line?

There are many programs available to perform the task of merging multiple images into a single image with everything in focus. Some of the most widely used programs are proprietary (e.g. Helicon Focus or Zerene Stacker). There are also many programs that are free/free and open that can do the same task in a similar quality as the proprietary programs. Probably the most widely used free and open focus merging program is CombineZP (formerly CombineZ5 and CombineZM), which was the program that I used most often in the past years, because it is free and open and it produces high quality results. But what if you have to merge a lot of stacks and you don’t want to spend an afternoon clicking through menus and waiting for the program to finish each job? A good solution to this is to use focus merging programs in a batch mode. CombineZP for example comes with a companion program (CZBatch), that does exactly that. But CombineZP has its glitches and a lot of windows tend to pop up even if you use it in batch mode (practically making your computer unusable until the program finishes). Still, CombineZP is easy to use, consistently produces high quality results and, though designed for Windows, it can run on UNIX systems like GNU/Linux with the help of WINE and derivative programs like Winebotteler. This way for many people CombineZP will continue to be the best solution in the open source realm.

But what if you want to speed up your workflow by using a powerful server instead of your laptop or perform actions that are not included in your focus merging program without exporting and importing files by hand? What if you want to focus merge images automatically as soon as your digital microscope finished taking the pictures? Or what if you simply want your focus merging to be done quietly in a terminal window while you are doing something else? If you are able to move your focus merging workflow to the command line all of this (and a lot more) is possible. Also, if there are new methods for focus merging, in most cases they will be available as command line programs before (if ever) someone writes a graphical user interface (GUI) for them.

What programs to use?

Even though CombineZP seems to have command line functionality, I avoided using it so far because it is a Windows program and the errors which I can run into might be really hard to fix on on my Linux systems.

Hugin and Enfuse

One way is to use enfuse from Enfuse/Enblend. However, enfuse can only perform the focus merging process but not the image alignment. For the image alignment another program is needed. For this we can use align_image_stack from the software suite Hugin. Both programs are easily available on most Linux distributions via the inbuilt package managers and can also be installed on other UNIX systems such as MacOS (not tested personally).

# for Debian/Ubuntu (based) distributions:
sudo apt install hugin enfuse 

Instructions on how to install these programs on MacOS are available on the respective websites linked above.

The alignment

Hugin has a graphical user interface (GUI), but it can as well be used from the command line. For the alignment we only need the function align_image_stack. The program align_image_stack from Hugin takes the names of the images which have to be aligned as the first argument (arguments come after the name of the program and are separated by spaces). To export the aligned images as image files we need to put the option -a followed optionally by the prefix (the name that the aligned images should have). The argument -m tells the program to resize the images. This is needed when the magnification is slightly different between the images (happens in many optical setups). The argument -i tells the program to optimize the image center shift. --use-given-order tells the program to not use the darkest image as the first in the stack. This seems to be a weird default but hugin is often used to do align for HDR (high dynamic range) images, where this makes sense. With the argument -c you can specify the number of reference points used during the alignment. The default value was too small for my large DSLR camera images so I increased the number to 20.

align_image_stack image_1 image_2 image_3 \
                        -a aligned_ -m -i \
                        --use-given-order \
                        -c 20

Writing or pasting in names of files is of course very inefficient. The below command takes all images beginning with the letters IMG (case sensitive!) which are in the current directory (folder) as input of the program. The backslash sign only acts as a line break and allows to write oneliners on multiple lines to increase the readability.

align_image_stack IMG* \
                -a aligned_ \
                -m -i \
                --use-given-order \
                -c 20

Depending on your hardware it might make sense to use the GPU with the argument -gpu to speed up the alignment process (haven’t tried it yet).

The focus merging

The program enfuse can not only merge focus stacks but also stacks of images with different illumination (HDR). The default values of the program are not suitable for focus merging. Enfuse takes the names of the images which have to be aligned as the first argument. The options --hard-mask --contrast-weight --exopsure-weight and --saturation-weight have to be set as below for enfuse to be useful for focus merging.

enfuse aligned_* --hard-mask \
                --contrast-weight 1 \
                --exposure-weight 0 \
                --saturation-weight 0 \
                --contrast-window 7 \
                --contrast-edge-scale=0.3 \
                --contrast-min-curvature=-0.5% \
                -o merfoc_enf.tif

The above command takes all images beginning with aligned_ as input and outputs (argument -o) a single image with the name merfoc.tif The other arguments are optional and the values given here are based on my judgement of the results from my images. Different images may need different settings. The meaning of the settings can be researched in the documentation of enfuse, which is very vast and detailed.

focus-stack

The program focus-stack by Petteri Aimonen can do both, the alignment and the focus merging. Also, even with the default settings it produces very good results. And it is fast. However, the installation is a bit more complex because it not available through package managers and has to be built from the source code. It depends on OpenCV, which has to be installed beforehand. It uses an algorithm developed by Forster et al. 2004, which is also built into an ImageJ plugin.

focus-stack image_1 image_2 image_3 --output=/}_merfoc_fs.tif

Efficiently using the command line programs

To not repeat these commands for each stack the commands can be wrapped into a shell script, which can act like a program on the command line. For this scripts to work properly, the image files of each stack must be in their own folders (and checked and for eventual 90 degree rotations!). The folders should be inside an ideally empty folder (text files etc. are unproblematic but images could get overwritten accidentally). This way, preparing the files is the same as for CZBatch. All of the scripts have in common that they search for folders and sequentially go into them and perform the alignment followed by the focus merging. The original images remain as they are before running the scripts and the merged images are placed in the parent directory (where the stack-folders are located). The name of the output image is defined by the names of the stack folders and the suffix is specified in the script.

focus-stack inside a script (merfoc_fs.sh)

#!/bin/bash
# This line needs to be in all bash shell scripts to tell the computer what to do with it (use bash to execute it)

# use a for loop to repeat the process for all folders in that directory
for d in ./*/
do
        # go into each folder
        cd "$d"

        # find image files and store them inside a variable
        images=$(find *.[Jj][Pp][Gg] *.[Jj][Pp][Ee][Gg] *.[Pp][Nn][Gg] *.[Tt][Ii][Ff] *.[Tt][Ii][Ff][Ff])

        # use a command line program that does the alignment and the focus merging in one go
        # the program takes the image file variable as the input
        focus-stack $images --output=${PWD##*/}_merfoc_fs.tif
        # the output image has the name of the folder as a prefix

        # to store the resulting in focus images of all focus stacks in one place they are moved up one directory
        mv *_merfoc_fs.tif ..

        # go out of each folder
        cd ..
done

Hugin and Enfuse inside a script (merfoc_enf.sh)

#!/bin/bash

# use a for loop to repeat the process for all folders in that directory
for d in ./*/
do
        # go into each folder
        cd "$d"

        # find image files and store them inside a variable
        images=$(find *.[Jj][Pp][Gg] *.[Jj][Pp][Ee][Gg] *.[Pp][Nn][Gg] *.[Tt][Ii][Ff] *.[Tt][Ii][Ff][Ff])

        # use a command line program that does the alignment
        # the program takes the image file variable as the input
        # the output images should be named in a way that they are easily searchable
        align_image_stack $images -a aligned_ -m -i --use-given-order -c 20

        # use a command line program that does the focus merging
        # using the asterisk the program searches for the aligned images as input images
        enfuse aligned_* --hard-mask \
                --contrast-weight 1 \
                --exposure-weight 0 \
                --saturation-weight 0 \
                --contrast-window 7 \
                --contrast-edge-scale=0.3 \
                --contrast-min-curvature=-0.5% \
                -o ${PWD##*/}_merfoc_enf.tif

        # after the focus merging the aligned images can be deleted
        rm aligned*

        # to store the resulting in focus images of all focus stacks in one place they are moved up one directory
        mv *_merfoc_enf.tif ..

        # go out of each folder
        cd ..
done

The script explained here can also be found as downloadable files in this repository. To start the script you have to give the file the permission to be executed as a program (right click on the script in your file manager and change the permissions or do so on the command line chmod +x merfoc.sh). You also need to know where the script is or link it to a place where your operating system searches for executables. Go into the directory where your folders with the stacks are and type on the commandline:

/path/to/merfoc.sh

Practical example: Reducing artefacts around fluorescent fibers when photographing with UV light (merfoc_fluo.sh)

When merging focus stacks of images from UV light photography there are often artefacts around dust fibers. Some dust fibers strongly glow in blue colour when exposed to UV light. When a focus stack is merged this can result in artefects which are much larger than the fiber itself. By removing the blue colour channel before the focus merging, these artefacts can be minimized. The convert function of the software suite Image Magick can do that when given the specific arguments.

convert image_1 -colorspace RGB \
                       -channel B \
                       -evaluate set 0 +channel \
                       -colorspace Gray \
                       image_1_redgreen.tif 

Image Magick is in general a great tool to convert and manipulate images fast and on the command line, that everyone should have on their system. This additional step can of course also be put into a shell script to be conveniently usable when handling a large number of stacks.

#!/bin/bash

# use a for loop to repeat the process for all folders in that directory
for d in ./*/
do
        # go into each folder
        cd "$d"


        # repeat the image manipulation (removing blue channel and desaturation) for all image files in the folder
        # give the output images an easily findable name
        shopt -s nullglob
        for i in *.[Jj][Pp][Gg] *.[Jj][Pp][Ee][Gg] *.[Pp][Nn][Gg] *.[Tt][Ii][Ff] *.[Tt][Ii][Ff][Ff]
        do
                convert $i -colorspace RGB \
                       -channel B \
                       -evaluate set 0 +channel \
                       -colorspace Gray \
                       redgreen_$i.tif 
        done

        # perform the alignment on the manipulated images
        align_image_stack redgreen*.tif -a aligned_ -m -i --use-given-order -c 20


        # remove the not aligned manipulated images
        rm redgreen*

        # perform the focus merging
        enfuse aligned_* --hard-mask \
                --contrast-weight 1 \
                --exposure-weight 0 \
                --saturation-weight 0 \
                --contrast-window 7 \
                --contrast-edge-scale=0.3 \
                --contrast-min-curvature=-0.5% \
                -o ${PWD##*/}_merfoc_fluo.tif

        # remove the aligned manipulated images
        rm aligned*

        # move the resulting in focus image up one directory
        mv *_merfoc_fluo.tif ..

        # go out of each folder
        cd ..
done

Step 1

Draw the outline using the Bezier tool. Then draw the midline according to what you see in the base image.

Step 2

Then rotate the outline and the midline, so that the midline is horuzontal (the ends of the midline should be at the same level).

Step 3

Vertically mirror the midline (by pressing “v”) and move the mirrored midline up or down so that the lines are tangents of each other.

Step 4

Then select the Bezier tool and adjust its mode to be “Bend from clipboard”. With the bezier tool try to redraw the mirrored midline as precisely as possible. For the end points to correctly align, the snapping behaviour of Inkscape can be used. Another shape should appear by releasing the Bezier tool with a right click.

Step 5

Remove everything but the new shape.

Step 6

Do not forget to set the mode of the Bezier tool back to “none” when you are done. Otherwise you will regret it later.

Purpose

When imaging amber specimens under high magnifications in an inverse microscope (especially using oil immersion), the adjustable focal plane can be limited to an unfortunate amount and the specimen may lie so deep in the resin that the adjustable focal plane does not cover the whole specimen (Figure 1). However, this limit of the focal plane can be created by the design of the microscope rather than by the sheer physical distance between the lens of the objective and the amber piece. To overcome this limitation, a deeper window can be created that is not restricted by the position of the microscope table (Figure 2).

What is needed?

• regular sized plastic petri dish
• smaller plastic petri dish that fits through the opening of the microscopy table
• extra large cover slips (more than are actually needed, tend to break)
• silicone and a dispenser for it
• a multipurpose rotary tool with cutting and grinding attachments
• diamond pen (for carving or writing on glass)
• a thin permanent marker
• a piece of regular printer paper

Step 1

Place the smaller petri dish on the larger one and draw the outline of the smaller one onto the larger one. Then draw a smaller circle inside the outline (just enough smaller to leave a margin for the smaller one to be placed onto the larger petri dish, see later pictures). Then cut along the smaller circle with the rotary tool and remove the burr afterwards using the grinding attachment of the rotary tool.

Step 2

If your cover slips are smaller than the diameter of the smaller petri dish, mark the size of the cover slip onto the small petri dish. Draw a circle on the bottom of the petri dish (smaller than the smallest side of the cover slip). Use the rotary tool to cut out a hole into the bottom of the petri dish (along the circle), remove the burr. By now you should have a small and a large petri dish with each a circular hole in the bottom.

Step 3

Use the permanent marker to draw a circle that is larger than the hole in the smaller petri dish but smaller than the outline of the same petri dish. Place the cover slip on a piece of paper (not on a paper towel!). Scratch along the circular marking. Check the result by looking at the reflection pattern. Gently break the glass along the scratches. You may need a few attempts for this. The cover slip should now fit on the bottom of the petri dish without overlapping.

Step 4

Glue the cover slip onto the underside of the bottom of the smaller petri dish using the silicone. For this , apply a ring of silicone and press the cover slip gently on top of it, so that a broad contact emerges between the cover slip and the silicone. Remove superstitious silicone without getting silicone onto the critical area of the cover slip.

Step 5

Apply a ring of silicone on the underside of the larger petri dish next to the opening and then place the small petri dish onto it. Seal the connection between the two petri dishes (you may need to apply more silicone). Let the whole object dry over night and test whether it is really waterproof or small leakages have to be sealed with silicone.