Virtual Orientation Tool for FIJI (VOTj)

This tool is designed to center and align objects of interest both horizontally and vertically from their base orientation. It requires an input image and a corresponding mask that defines the object of interest within the image. This tool is adapted at aligning a single object in each image, and this alignment can seamlessly propagate across multiple channels in the case of multichannel images. It offers compatibility across a wide range of image types, including 2D, 3D, 4D, and 5D data.

For detailed information and usage instructions,please refer to our publication: https://www.micropublication.org/journals/biology/micropub-biology-001221

The source code is available on GitHub: https://github.com/sankeert1999/Virtual-Orientation-Tools-VOTj

A video tutorial is available on YouTube https://youtu.be/WHeDhn1Mnpc

• How does it work ?

  The tool primarily serves to determine the orientation of a given object, aligning it with the horizontal or vertical axis, and optionally centering the object. The process begins by detecting the object of interest from the provided binary mask, followed by identifying its center. To establish the object's orientation, the tool employs Principal Component Analysis (PCA) on the contour of the detected object.

  This process yields two principal components, representing the eigenvectors that capture the data variance.The tool calculates the angle between these eigenvectors using the tanh function, providing the initial orientation angle. To ensure alignment within the [-90, 90] range and accommodate small rotations, an additional step transforms the obtained angles into the final angle for alignment. For users choosing to orient the object vertically, an extra transformation step determines the respective alignment angle. Refer to the table below for a detailed calculation of the alignment angle. Once the center and angle are established, the tool facilitates user-defined transformations, such as rotation or rotation with centering, etc. Notably, the tool accounts for object polarity, deduced from the mask. After alignment, a final step applies a flip operation to adjust object polarity based on user preferences.

  

  

VOTj Modes

The Virtual Orientation Tool for Fiji (VOTj) offers two distinct modes:

• Single Mode

  In this mode, users can orient a single image at a time. This mode provides two suboptions.

  • VOTj Direct User Input

    In this specific operational mode of the VOTj tool, the user is prompted to select an input image (the image to be aligned) and an associated mask (2D or 3D stack) that corresponds to the input image.

  The tool then proceeds to generate the output image after collecting essential alignment information from the user.GUI configuration overview

  

  • VOTj Annotation Assisted Alignment

    In this specific operational mode of the VOTj tool, the user is prompted to annotate the object of interest and based on these annotations the input image is aligned.

  • Selecting the input image

    

  • Selecting the annotation mode

    User would be prompted with a window to select the annotation mode (only for images with dimensionality > 3). There are two annoation mode Single-Slice-Annotation and Multi-Slice-Annotation.

    • Single-Slice-Annotation

      This option lets you annotate a single slice (e.g of a Z-stack or multi-channel image) and the tool will align the full stack based on this single annotation.

    • Multi-Slice Annotation

      Multi-Slice-Annotation, on the other hand, allows you to annotate multiple slices, typically suited for timelapse where each timepoint is aligned separately (with any number of Z-slices and channels).A single slice in each timepoint is annotated (you choose which timepoint and Z-slice to use). The "substacks" (Z and/or multi-channel) at each timepoint are then aligned separately based on this timepoint-specific annotation.

    These two annotation modes provide you with the flexibility to align images efficiently based on your specific image characteristics and alignment requirements. In essence, through annotation, you create a mask file that guides the alignment process.

    To better understand how to design your mask according to your input,consult the following table,which outlines the different mask files expected by the tool for various input image scenarios.

    

  • Selecting appropriate Slice/Stack for annotation

    After selecting the appropriate annotation mode, the user will be prompted to choose the image or stack for annotation. Depending on whether you've chosen Single-Slice-Annotation or Multi-Slice-Annotation, the tool will guide you accordingly. For instance, if you have a Z-stack and opt for Single-Slice-Annotation mode, you will be prompted to select the specific Z slice you wish to annotate.

    

  • Annotating the object of interest

    Once you've selected the image for annotation, the tool will present the image or stack for annotation, and the paintbrush tool will be automatically activated with a white color. To adjust the brush width, simply double-click on the paintbrush tool icon. It's important to note that drawing on the image before confirming the width will make the annotation permanent and irreversible. Here are some tips for effective annotation:

    • When marking the object of interest, ensure it covers the orientation you want to align.
    • Try to position the annotation somewhat centered on the object of interest.
    • For multi-slice annotation, aim for a consistent drawing that doesn't drastically change across the stack, particularly at the centers."
    • To account for the polarity in the annoation refer here Alignment with object pointing to.

    

  • Configuring the VOTj panel

    Now, the user is prompted to select the alignment operation they need for their image.GUI configuration overview

    

• Batch Mode

  Batch Mode allows users to batch process an entire folder of images. This mode provides three suboptions.

  • VOTj Batch Direct User Input

    This operational mode is a batch format of the VOTj Direct User Input mode

    The GUI initiates by requesting input configuration, where users specify the input image and its corresponding mask folder details. It is essential that the filenames of masks match those of the input images to avoid errors.

  The subsequent steps include configuring object alignment settings,additional options and finally output configuration. In the output configuration, users specify the destination folder for saving output images and choose the desired image format.

  

  • VOTj Batch Custom Macro

    This operational mode allows users to process a folder of images, using a custom macro to generate masks for each input image and further orienting them. The GUI begins by prompting input configuration, where users specify image folder details and the macro folder. The macro should generate masks, with the final mask as the active image window.

  Followed by configuring object alignment settings,additional options and finally output configuration.Users can save output images to a specified folder and opt to save corresponding masks in a "Mask_VOTj" subfolder. Users also have the flexibility to choose image and mask formats.

  

  • VOTj Batch Annotation Assisted Alignment

    This operational mode is a batch format of the VOTj Annotation Assisted Alignment.

  The GUI initiates by requesting input configuration, where users specify the input image. The subsequent steps include configuring object alignment settings,additional options and finally output configuration.Users can save output images to a specified folder and opt to save corresponding masks in a "Mask_VOTj" subfolder. Users also have the flexibility to choose image and mask formats. Following GUI configuration, proceed with the annotation procedure for each image, mirroring the process in VOTj Annotation Assisted Alignment.

  

VOTj GUI Overview

• Input Configuration

  • Select the image

    Input image to be aligned (compatibile across a wide range of image types, including 2D, 3D, 4D, and 5D data.)

  • Select the mask

    Corresponding mask file for the input image representing the object of interest within the image. The table below outlines the various scenarios in which this tool is compatible and the corresponding mask file expectations for the respective input files.

\* Slices of a Z-stack should typically be aligned with the same transformation, as they were normally acquired with the same orientation. The option to align slices separately is rather here to adress the fact that timelapse are sometimes recognized as Z-stack in ImageJ. So you can still align each timepoint separately in that case with the tool, without having to swap dimensions first.

• Object alignment settings

  • Tasks

    After selecting the corresponding images the next step is to selecte the task which you want to perform with this tool.

    

  • Move object to image-center

    This task involves recognizing the object of interest, and calculates its center, followed by aligning it to the image center.

  • Align object to desired orientation

    This task involves recognizing the object of interest, determines its center and base orientation, and then calculates the necessary rotation angle to align it with either the horizontal or vertical axis, as prompted by the user. The image is then rotated accordingly.

  • Center object and then align to orientation

    This task involves recognizing the object of interest, calculating its center, aligning the image to the center, determining the base orientation of the object, and calculating the rotation angle required to align it with the horizontal or vertical axis, as specified by the user. Subsequently, the image is rotated to achieve this alignment.

  • Orientation

    Desired orientation for aligning the object of interest.

  • Horizontal

  • Vertical

    

    An illustrative image demonstrating the same sample object centered and aligned in two distinct orientations.

  • Center of rotation

    Users have the option to specify the rotation center. This feature proves valuable in scenarios when the task is rotation. However, when the task is centering rotation becomes unnecessary, rendering this option redundant. Similarly, in cases of when the task is centering+rotation, where the object's center is aligned with the image center as the initial step, this option becomes redundant as well.

  • Object center

  • Image center

  • Alignment with object pointing to

    This enables the user to configure the polarity of object of interest, allowing users to define the object's pointing direction. For asymmetrical objects, like a fish with a distinct head and tail, users can specify the desired orientation. For instance, while annotating, marking the head specifically introduces asymmetry in the mask (see the below figure), and the tool aligns the object accordingly with the polarity.

  • Any

  • Left (for horizontal)/Top (for vertical)

  • Right (for horizontal)/Bottom (for vertical)

    

  • Fill background with

    This enables the user to customize the background color by choosing from three options: black, white, and mean. The background color is applied to the alignment operation, and the user's selected color determines the background hue. The "mean" option utilizes the mean intensity of the image to fill the background, offering a unique approach to color customization based on the overall image intensity.

  • Black

  • White

  • Mean

    

• Additional options

  • Enlarge image

    User have the option to enalrge the output image, enlarging the image serves the purpose by minimizing potential loss of critical information around the surrounding area near object of interest.

    

  • Log File Output

    Users can choose to generate a log file, including the center coordinates and orientation angle of the detected object.The orientation angle is the smallest angle needed to align the object with the user-defined axis, whether vertical or horizontal. This feature provides users with detailed insights into the processing results for enhanced analysis and documentation.

• Output configuration

  Exclusive for batch mode

  • Save processed images/masks to

    Users are prompted to provide the corresponding directory information indicating where they would like to save the output files generated.

  • Save images in format

    Users can choose the desired image format for saving the output image, with available options including TIFF (tif, tiff), JPEG (jpg, jpeg), PNG (png), and BMP (bmp).

  • Save mask file

    Users can simply check or uncheck a checkbox to indicate their preference for saving the mask file. If selected, the masks are stored in a folder named Mask_VOTj within the specified output directory in the option Save processed images/masks to.

  • Save masks in format

    Users can choose the desired image format for saving the masks, with available options including TIFF (tif, tiff), JPEG (jpg, jpeg), PNG (png), and BMP (bmp).