Introduction

This user guide presents a broad view of all concepts needed to use TRIOSlib. All code examples presented can be found at the docs/examples folder.

Image sets

The image processing task we would like to solve is defined by a set of input-output images. For instance, if the task to be solved is staff removal, the following pair of images coudl be used for training. We would like to estimate an image transform that takes as input the image on the left and produces an output as close as possile to the image on the right.

Figure 1 : Input-output image pair for staff removal

The trios.Imageset class represents this set of input-output images and resembles a list of tuples. Each element of trios.Imageset contains the path to an input image, the path to the desired output and the path to a binary mask that indicates which pixels should be processed. The following example illustrates the usage of the trios.Imageset class to create sets of input-output images.

import trios
import trios.shortcuts.persistence as p

if __name__ == '__main__':
    # Imageset can be defined directly in code, like below
    images = trios.Imageset([
        ('input.png', 'output.png', None),
        ('input2.png', 'output2.png', 'mask.png')
    ])
    # Definitions in code can be put in a module and imported like regular
    # Python code.


    # It can also be saved to a gziped file using the persistence
    p.save_gzip(images, 'imageset.gz')

    # And loaded back
    images2 = p.load_gzip('imageset.gz')
    assert images[0] == images2[0]
    assert images[1] == images2[1]
    assert len(images) == len(images2)

    # Or saved to a text-only format using the read and write methods.
    images.write('imageset-text.txt')

    images3 = trios.Imageset.read('imageset-text.txt')
    assert images[0] == images3[0]
    assert images[1] == images3[1]
    assert len(images) == len(images3)

Windows

Image operators built with TRIOS are local image transforms that analyse a small neighborhood window around each point to determine its value in the output image. TRIOS uses 2D numpy arrays of unsigned 8bit ints to store windows. A point is inside the window if its value not 0 (we typically use 1). Thus, the size (number of points) of a window win is np.sum(win != 0).

The follow example illustrates the use of the module trios.shortcuts.window to create simple window shapes. More interesting shapes can be built using slice notation.

import numpy as np
import trios.shortcuts.window as trios_win

if __name__ == '__main__': 
    # We can use the trios.shortcuts.window module to create windows.abs
    rect5x5 = trios_win.square(5)
    # The show method plots a window using matplotlib. Black dots
    # represent points inside the window.
    trios_win.show(rect5x5, 'rect5x5.png')

    # We can create rectangular shapes as well
    rect9x7 = trios_win.rectangle(7, 9)
    trios_win.show(rect9x7, 'rect9x7.png')

    # Windows are just numpy 2D arrays of unsigned 8bit ints.
    # We can use array slices to create new shapes.
    cross = np.zeros((5, 5), np.uint8)
    cross[2,:] = cross[:, 2] = 1
    trios_win.show(cross, 'cross5x5.png')

Square \(5\times 5\)	Rectangle \(9\times 7\)	Cross \(5\times 5\)

WOperators

Local image transforms (or image operators) estimated by TRIOS are called WOperators and are represented by the trios.WOperator class. In the following pages we will learn how to use instances of this class to transform images and how to estimate new local transformations.