GraphRLM: Graph Run-Length Matrices for Unsupervised Segmentation of Histopathological Images

The source codes and executable jar file are provided in the links below.

NOTE: The following source codes and executable are provided for research purposes only. The authors have no responsibility for any consequences of use of these source codes and the executable. If you use any part of these codes, please cite the following papers.

  • If you use the code for segmentation:
    A.B. Tosun and C.Gunduz-Demir, "Graph run-length matrices for histopathological image segmentation," IEEE Transactions on Medical Imaging, 30(3):721-732, 2011. PDF
     
  • If you use the code for the circle-fit algorithm:
    A.B. Tosun, M. Kandemir, C. Sokmensuer, and C. Gunduz-Demir, "Object-oriented texture analysis for the unsupervised segmentation of biopsy images for cancer detection," Pattern Recognition, 42(6):1104-1112, 2009. PDF

Please contant Akif Burak Tosun for further questions.

Source code

This project is written in the Java programming language and the source codes can be found here: GraphRLM.zip.

You may use these codes for the unsupervised segmentation based on graph run-length matrices. You may also use them to obtain the output of the circle-fit algorithm (using the createCircularObjects() function in the Runlength class).

IMPORTANT: For a given image, the program writes four files into its runnning folder. The names of these files are the name of the original image file followed by "_c3", "_objects", "_circle_map", and "_runlength_features" strings, respectively:

    "_c3": The map of the quantized pixels (labeled with 0, 1 and 2). The image pixels are quantized using the k-means algorithm (k = 3). The first line of this file is a header and keeps the dimensions of the pixel map.
    "_objects": The id map of the circular objects. The pixels of each object are marked on the map with the id of this object. Ids are given to the objects from 1 to N. The background (non-object pixels) are marked with 0. Likewise, the first line of this file keeps the dimensions of the id map.
    "_circle_map": The type map of the circular objects. There may exist three different object types within an image. These are nucleus, stroma, and lumen objects. The pixels of these objects are marked on the map with 0, 1, and 2, respectively. In this file, label 6 is used to mark the background (non-object pixels). Likewise, the first line of this file keeps the dimensions of the type map.
    "_runlength_features": The feature values extracted for each object. This file contains the dimensions in its first line; the first value is the number of the objects in an image and the second value is the dimension of the feature vector defined for an object (in our work, the feature dimension is 16). In this file, the i-th line after the first one corresponds to the run-length features of the object with an id of i.
Note that these files are created for the first time when the quantized pixels, objects, and features are computed. The contents of these files can be used for different purposes. Our program uses their contents to make its calculations faster in the subsequent runs for the same image (for a given image, the program does not compute these values again if their files are already in the running folder). Also note that writing into these files make the execution slower for the first time. Thus, if you run the program just once for a given image, you may comment these file operations from the source code.

Executable jar

This executable jar file can be found here: GraphRLM.jar. In order to run this file, you should have Java installed on your computer.

You can call this program from the command line as follows:

    java -jar GraphRLM.jar <fname> <r_min> <r_strel> <win_size> <dist_thr> <comp_thr>
The parameters of this program are:
    fname: The name of the image file. It should not include the extension of the file. Note that only JPG files are compatible. Thus the ".jpg" extension is appended by the program.
    r_min: The minimum radius of the circular objects. Note that for histopathological images taken with a 5x microscope objective lens and 1920x2560 image resolution, we set this value to 9 considering the smallest nucleus object in the image. You should change this value according to your images.
    r_strel: The radius of the structuring element used by the dilation operation. You may obtain better circular objects, if you apply the dilation operation of the quantized pixels. The value of this parameter should be selected considering the image resolution and image domain. We set this value to 2 in our experiments.
    win_size: The window size that determines the size of a region on which texture descriptors are defined. The algorithm uses this parameter in its run-length matrix calculation step (Section II-B of the first paper).
    dist_thr: The distance threshold used in the seed determination and region growing steps (Section III of the first paper). This parameter determines at what similarity level the objects form a single seed and controls the region growing step.
    comp_thr: The component size threshold used to eliminate small sized components in the seed determination step.

This program produces a JPG file that includes the segmentation results. The results for sample histopathological images are given below. These images are taken using a 5x microscope objective lens and have 1920x2560 resolution. We obtained the results with the following parameter values: r_min = 9, r_strel = 2, win_size = 96, dist_thr = 1.25, and comp_thr = 100.