Mask Editor is intended for interactive selection of good and bad regions on 2D image and preparation of output files with direct and inversed masks. It works as a basic graphical editor with specific input of the image and output for masks.

Content

User Interface

User interface of the Mask Editor works in a single window containing three panels; graphical window, left-hand, and bottom control bars. Content and functionality of these panels is described below. Most of control buttons have tool tip hints; when cursor stops on control button, a pop-up window with explanation of functionality of this button appears for a few seconds .

...

Mask Editor is developed as a part of the integrated data processing environment for XCS time correlation experiments. In this project the Mask Editor is integrated as one of the system GUIs. Also it can be executed as a stand-alone application named med. Stand-alone version of the Mask Editor can launched on any of psana or psexport node using command-line interface, for example, for all default parameters:

sit_setup
med

List of optional parameters

> med -h
Usage: med [options]

Optional input parameters.

Options:
  -h, --help            show this help message and exit
  -i IFNAME, --fname_imgifname=IFNAME
                        input image file name, default = ./roi-img
  -om OFNAMEMFNAME, --fname_figmfname=OFNAME
MFNAME
                        common path to I/O files with mask, default = ./roi-
   output png file name for current canvas                     mask
  -mo MFNAMEOFNAME, --path_maskofname=MFNAMEOFNAME
                        output  common path to I/O files with maskpng file name for current canvas, default =
                        ./fig.png
  -t TITLE, --title=TITLE
                        initial title of the garphical window, default = Mask
                        editor
  -x XC, --xc=XC        x coordinate of the center for Wedges, default = None
  -y YC, --yc=YC        y coordinate of the center for Wedges, default = None
  -p PICKER, --picker=PICKER
                        distance in pix, where object lineresponce canon bemouse,
 reaced by
                      default = mouse8
  -w LW, --lw=LW        object line width, default = 1
  -c COL, --color=COL   color of the form lines "b"-blue, "k"-black, etc.,
                        default = b
  -v, --verbose         allows print on console, default = True
  -q, --quiet           supress print on console, default = False

...

  -f, --fexmod          file exchange mode on/off (True/False), default = False

Data format for geometrical forms

Forms can be saved in file, loaded from file and displayed on image, printed on console monitor, and cleared/removed from image. This can be done using simple data representation for each form, which is quite self-explained in case of print or text-file format:

Form parameters for composition of the mask
Rectangle   48.00   50.00  262.00  380.00 1 b False False
Rectangle  987.00  853.00  255.00  380.00 1 w True False
Wedge  716.76  674.72  541.18  197.61 -171.39  174.59 1 b False False
Wedge  674.48  667.64  585.84  386.69  174.75  186.99 1 b False False
Circle  712.00  674.00  262.00 1 b False False
Circle 1068.00  180.00  112.00 1 b False False
Circle  191.00  898.00  117.00 1 b False False
Circle  752.00 1098.00   53.00 1 w True False
Line  689.79 1252.80  624.50  223.22 1 w True False
Line  829.99 1252.80  244.47  388.46 1 b False False
Line  836.67 1303.98  268.07  541.89 1 w True False
Line  692.02 1315.11  669.35  827.50 1 b False False
Polygon 1 w True False 10     400     373     620    ...
Polygon 1 b False False 6     329     674     683    ...   

File exchange mode

2014-06-12, CorAna V00-00-19, in release ana-0.11.6

In order to interactively communicate between Mask Editor and other application(s) Marcin Sikorski requested to introduce the file exchange mechanism for image and mask. It is assumed that external event processing application periodically supplies averaged image, Mask Editor can load it and use for interactive ROI mask correction, and submit in response the mask, which will be used by the external application. This asynchronous data exchange mechanism was implemented in CorAna.ArrFileExchange class. This algorithm uses numpy arrays with np.save(fname,arr) and arr=np.load(fname) methods. In order to get rid of collisions between reader and writer the "ring-buffer" (a.k.a. "round-robin") exchange mechanism is implemented. Data producer writes files with names enumerated in the ring buffer. During writing data is saved in the file with temporary name. When the file is written, it is renamed to indexed name. This eliminates probability of the read/write collision. Data consumer checks availability of the new data and loads numpy array  from the latest file if necessary.

Interface for class CorAna.ArrFileExchange

    #-----------------------
    # code in array producer
    #-----------------------
    afe = ArrFileExchange(prefix='./my-numpy-arr') # one call per object
    arr = ...                                      # supply array here
    afe.save_arr(arr)                              # as many times as you need

    #-----------------------
    # code in array consumer
    #-----------------------
    afe = ArrFileExchange(prefix='./my-numpy-arr') # one call per object
    arr = afe.get_arr_latest()                     # as many times as you need

    # optional method:
    status = afe.is_new_arr_available()            # returns True/False if the new array IS/IS NOT available
                                                   # since last call to arr = afe.get_arr_latest()

Two ArrFileExchange objects for image reader and mask writer are incorporated in the Mask Editor. File exchange mode in the med application can be launched by the command:

med -f -i work/my-roi-img -m work/my-roi-mask

assuming that path to the file directory work/ already exists. Options in this example provide functionality as follows;

• option -f turns on the file exchange mode,
• files with images are expected to have names work/my-roi-img-rbn-00#.npy and can be loaded by clicking on the GUI button "Load Image",
• and files with mask will be saved with names work/my-roi-mask-rbn-00#.npy by clicking on GUI button "Save Mask" or "Save Inv-M". 

External application may communicate with launched med through the code pattern shown below

from CorAna.ArrFileExchange import *
...
        # create reader/writer objects with file name prefixes 
        # exactly like in the med command line for opposite party:
        afe_rd = ArrFileExchange(prefix='work/my-roi-mask') 
        afe_wr = ArrFileExchange(prefix='work/my-roi-img')
        ...
	    # image writer
	    image = np.array(...)               # supply numpy array for image
        afe_wr.save_arr(image)              # image writer
        ...
	    # mask reader
        if afe_rd.is_new_arr_available() :  # check that the new data is available
            mask = afe_rd.get_arr_latest()  # mask reader             

Mask Editor can be tested with toy image producer application, for example, launch two applications from different xterm windows:

test_img_gen -n 50 -o work/roi-img;
med -f -i work/my-roi-img -m work/my-roi-mask;

then, click on buttons "Load Image", "Save Mask", or "Save Inv-M" in the MaskEditor GUI.

Image exchange with psana

The CorAna.ArrFileExchanges file exchange algorithm is used in psana module imgalgos.image_save_in_file to generate image files within ring buffer.

Other file browser application

In addition to med, there is a file/image browsing application plims, which options can be seen by the command

plims -h

[pyimgalgos.image_save_in_file]
source     = DetInfo(MecTargetChamber.0:Cspad2x2.3)
key_in     = cspad2x2_image
ofname     = ./roi-img
mode       = 3
delay_sec  = 1
print_bits = 255

Demonstration of features

...

• Input image
• Image with drawn forms on it
• Image for mask with forms on it
• Image for inversed mask with forms on it
• Help window
  

References

• imgalgos.image_save_in_file- ring-buffer image source in psana
• plims -h    - Image browsing application