Obj.MPP: Object/pattern detection using a Marked Point Process¶

This documentation describes the usage of the Obj.MPP tools whose source code is available on a GitLab repository.

What does Obj.MPP do?¶

In Images¶

Looking for disk-like objects (other shapes available):


Image with a region of interest (ROI) identified by the green rectangle.	Disk-like objects found by Obj.MPP inside the ROI (“inside” in the sense “disk center is inside”).
Image source: К562_(Light_microscopy), Creative Commons Attribution-Share Alike 4.0 International (https://creativecommons.org/licenses/by-sa/4.0/deed.en)

In a Few Words¶

Obj.MPP implements the detection of parametric objects (or patterns) in a signal based on a quality measure using a Marked Point Process (MPP).

Detecting an object in a signal amounts to finding a position p (a point) paired with a set of parameters m (called marks here [1]), the quality measure of which being above some threshold.
The detection task amounts to finding all such objects in the signal.

Parametric object: An n-dimensional region defined by a finite set of parameters, typically real numbers. For example, a disk (n=2, position=center, mark(s)=radius). See Standard Object Types.
Signal: A mapping between an n-dimensional position and a d-dimensional vector. For example, a 2-dimensional grayscale image (n=2, d=1).
Quality measure: A way to compute a real number measuring how well a given parametric object fits the signal at a given position. For example, object brightness compared to the surrounding area (i.e., object contrast). See Standard Quality Measures.

Footnotes

[1]	Hence the “marked point” terminology.

Bibliographic References¶

Detecting and quantifying stress granules in tissues of multicellular organisms with the Obj.MPP analysis tool; de Graeve, Debreuve, Rahmoun, Ecsedi, Bahri, Hubstenberger, Descombes, Besse; Traffic (Wiley, ISSN: 1398-9219, ESSN: 1600-0854); 20(9), 697-711, 2019

DOI: 10.1111/tra.12678

Citation: BibTeX and EndNote

Multiple birth and cut algorithm for multiple object detection; Gamal Eldin, Descombes, Charpiat, Zerubia; JMPT (ISSN: 0976-4127, ESSN: 0976-4135); 2012

DOI: 10.1.1.661.9041

Citation: BibTeX and EndNote

Installation¶

Follow the instructions on the Installation and Requirements page.

Documentation Sections¶

For Users = Software users willing to:
- detect objects…
  using mpp_detector_cli.py (command line interface)
  
  or mpp_detector_gi.py (graphical interface)
  
  and the provided object type and object quality definitions
For Developers = Library users willing to:
- add the Obj.MPP object detection capability in some piece of software…
  using the core module mpp.py
  
  and the provided object type and object quality definitions
For Customizers = Library hackers willing to:
- modify mpp.py
- add new object type and object quality definitions
For Reviewers = Code checkers willing to:
- understand the structure of Obj.MPP
- hunt for bugs
- imagine structure, code readability, code conventions, code conformity, performance improvements

Typical browsing route for users:

Sitemap¶

Obj.MPP Installation¶

Installation¶

Using Tools¶

The Obj.MPP project is published on the Python Package Index (PyPI) at: https://pypi.org/project/obj.mpp. It requires version 3.8, or newer, of the interpreter. It should be installable from Python distribution platforms or Integrated Development Environments (IDEs). Otherwise, it can be installed from a command-line console:

For all users, after acquiring administrative rights:
- First installation: pip3 install obj.mpp
- Installation update: pip3 install --upgrade obj.mpp
For the current user (no administrative rights required):
- First installation: pip3 install --user obj.mpp
- Installation update: pip3 install --user --upgrade obj.mpp

Note

The command pip3 was mentioned above to emphasize that Obj.MPP requires major version 3 of Python. If pip defaults to this version, it can of course be used instead.

Manually¶

To install Obj.MPP manually anywhere in a non-system location, download the project available in the source code repository, for example as a ZIP archive. Check that all the requirements are met (see Section Requirements). Then follow the instructions Obj.MPP for Users.

Requirements¶

The standalone distribution of mpp_detector_cli.py for Windows (see Windows section) requires Windows PowerShell. Recent versions of Windows normally come with PowerShell pre-installed. If not, instructions to install it can easily be found.

To use the Obj.MPP tools in an OS-independent way (see OS-independent section), the requirements are:

the latest Python language interpreter of major version 3 (see note on Python version)
the following Python packages (the mentioned versions are the ones used for development)
- pillow
- PyQt5
- colorama
- imageio
- matplotlib
- networkx
- numpy
- scikit_image
- scipy
a console (a.k.a. terminal) application on Linux or MacOS (console application also usable on Windows, but not required)

Note

For sure, pre-3.6 Python versions are not recent enough. The Obj.MPP tools might work with pre-latest versions though. However, the source code is regularly “upgraded” to benefit from new features of the language.

Obj.MPP for Users¶

Usage: OS-independent¶

General Instructions¶

The steps to use the Obj.MPP tools are:

download the project available in the source code repository, for example as a ZIP archive
decompress the archive
open a console (a terminal application on Linux or MacOS, or the command prompt on Windows [1])
move to the folder containing mpp_detector_cli.py [2]
run one of the following commands (see Detailed usage):
- python3 mpp_detector_cli.py path_to_an_INI_configuration_file
- python3 mpp_detector_gi.py
- python3 mpp_quality_chooser.py

Note

The use of python3 as the Python interpreter command is a way to emphasize that the Obj.MPP tools must be interpreted using version 3 of the Python language. Actual interpreter command name might be different depending on OS configuration.

The script mpp_detector_cli.py is the command-line version of Obj.MPP. It allows “more advanced” users to write their own INI configuration file [3], and then launch the detection algorithm with this INI file as input.

The script mpp_detector_gi.py is the graphical version of Obj.MPP and exposes only a subset of the configuration parameters that mpp_detector_cli.py accepts. It is more targeted toward regular users.

The script mpp_quality_chooser.py is a graphical tool allowing to infer good configuration parameters regarding object parameters and object quality. It is potentially useful in either case.

Detailed Usage¶

Footnotes

[1]	Other options might be available, like Cygwin on Windows.

[2]

[3]	E.g., by getting inspiration from `resource/twoD/microscopy-circle.ini` or by checking the full specification in `brick/data/config/specification.py`.

Obj.MPP for Developers¶

This section targets developers, that is, library clients willing to:

add the Obj.MPP object detection capability in some piece of software…
- using the core module mpp.py
- and the provided object type and object quality definitions

Obj.MPP for Customizers¶

This section targets customizers, that is, library hackers willing to:

modify mpp.py
add new object type and object quality definitions

Obj.MPP for Reviewers¶

This section targets reviewers, that is, code checkers willing to:

understand the structure of Obj.MPP
hunt for bugs
imagine structure, code readability, code conventions, code conformity, performance improvements

Signal Loading Diagram¶

The following diagram presents how signals are loaded and processed in mpp_detector_cli.py.

Using mpp_detector_cli.py¶

The command mpp_detector_cli.py takes a configuration file as argument. All configuration parameters can also be overwritten by adding arguments in the form --section-parameter value, for example --mpp-n_iterations 1000 to set the parameter n_iterations in section mpp to 1000. Note that any space in the section name must be replaced with the underscore character, for example object_ranges for section object ranges. For details about the configuration file, please refer to

Using mpp_detector_cli.bat¶

To be done.

Using mpp_detector_gi.py¶

Note

The GRAPHICAL INTERFACE VERSION of Obj.MPP is CURRENTLY UNDERGOING an OVERHAUL. It is PREFERABLE to TURN to the COMMAND-LINE VERSION.

The main steps of the graphical interface usage for object detection are identified in the screenshot below.

Using mpp_quality_chooser.py¶

The main steps of the graphical interface usage for

quality measure selection and
tuning of object mark ranges

are identified in the screenshot below.

Configuration File¶

Example Configuration¶

Configuration files follow the INI format. Sections are introduced by [section name]. In a section, parameters are defined by parameter_name = value. Comments start with the hash character # and end with the end of the line. Below are examples of the main sections.

General detection section:

[mpp]
n_iterations            = 1000 # Number of detection iterations
n_births_per_iteration  = 50   # Number of object proposals per iteration

Section about constraints on detected objects. Currently, only one constraint is implemented: non-overlapping between any 2 objects, with some tolerance:

[constraints]
overlap_tolerance       = 20.0 # Accepts up to 20% in overlapping between 2 objects

Detection refinement section (can be safely removed):

[refinement]
age_for_refinement      = 40
n_refinement_attempts   = 40
refinement_fraction     = 0.2

When an object has not been replaced by a better overlapping one for age_for_refinement number of iterations, n_refinement_attempts slight variations of it are generated (how “slight” the variations are is defined by refinement_fraction), the best of which replaces the object if better.

Execution feedback:

[feedback]
status_period           = 2 # Period of reporting of current detection state

Sections about the a priori on the objects of interest:

[object]
object_type             = circle # Idealized shape of objects of interest

# Section of the ranges of the object mark(s)
[object ranges]
radius_rng              = (20, 35, 0.5) # Range of the mark "radius": min value, max value, and precision

Section about the object quality measure:

[quality]
object_quality          = dark_on_bright_gradient # Python "function" to compute the quality measure
min_quality             = 0.75                    # Minimal quality measure of detected objects

Section about the signal to look for objects in:

[signal]
signal_loading_function = SingleChannelOfImage # Python function able to load the signal file
signal_path             = microscopy.png       # Name of signal file

# Section of the parameters of the signal loading function (if any)
[signal loading prm]
channel                 = gray

# Section of the parameter(s) of the signal transformation function
[signal processing prm]
unitary                 = False

The quality measure computation might operate on a transformation of the loaded signal. This transformation might take tunable parameters, which are then specified in the signal processing prm section. Actually, to each quality measure corresponds a signal transformation, be it the no-op.

Section about how the detected objects are presented and/or stored:

[output]
console                 = True

result_output_function  = OutputObjectsOnSingleChannelBackground

Generic Configurations¶

More details about available sections and parameters: Generic Configurations.

Generic Configurations¶

The values set for mandatory parameters are just examples. They should be adapted to the problem at hand. The values set for the other parameters are their default values.

Sections that are empty in the minimal and basic configurations must really be adapted to the problem at hand since the default values of their parameters are surely inappropriate. Additional empty sections in the full configuration are dedicated to optional parameters of the chosen quality measure, its corresponding signal transformation, and the way the detection result is reported.

Minimal¶

[mpp]
n_iterations   = 100    # Mandatory

[object]
object_type    = circle # Mandatory

[object ranges]
# To be set in accordance with the chosen object type

[quality]
object_quality = bright_on_dark_contrast # Mandatory
min_quality    = 0.2                     # Mandatory

[signal]
signal_path    = some_image.png # Mandatory

Basic¶

[mpp]
n_iterations   = 100    # Mandatory

[object]
object_type    = circle # Mandatory

[object ranges]
# To be set in accordance with the chosen object type

[units]

[quality]
object_quality = bright_on_dark_contrast # Mandatory
min_quality    = 0.2                     # Mandatory

[signal]
signal_path    = some_image.png # Mandatory

[output]
output_path    = None
marks_output   = False
mkpt_output    = False
contour_output = False
region_output  = False

Full¶

[mpp]
n_iterations            = 100 # Mandatory
n_births_per_iteration  = 20
seed                    = None
n_parallel_workers      = 0
use_history             = False
fixed_history           = False

[refinement]
age_for_refinement      = None
n_refinement_attempts   = 10
refinement_fraction     = 0.1

[feedback]
status_period           = 2

[object]
object_type             = circle # Mandatory
center_rng              = None
only_uncropped          = True

[object ranges]
# To be set in accordance with the chosen object type

[units]

[quality]
object_quality          = bright_on_dark_contrast # Mandatory
min_quality             = 0.2                     # Mandatory

[quality prm]

[incitations]
area_weight = 0.0

[constraints]
overlap_tolerance       = 20.0

[signal]
signal_path             = some_image.png # Mandatory
vmap_path               = None
signal_loading_function = signal_loading:RawImage

[signal loading prm]

[signal processing prm]

[output]
console                 = True
output_path             = None
marks_output            = False
mkpt_output             = False
contour_output          = False
region_output           = False
result_output_function  = None

[output prm]

Standard Object Types¶

Specifying an Object Type¶

The desired object type is specified in the [object] section of a configuration file using the object_type parameter, for example object_type = circle (see Configuration File).

2-Dimensional Objects¶

Current standard object types are:

circle, ellipse, rectangle, square, superquadric.

See Section Marks Details for details about the respective marks of the object types.

3-Dimensional Objects¶

Current standard object types are:

ellipsoid.

See Section Marks Details for details about the respective marks of the object types.

Marks Details¶

Note

The mark ranges in a configuration file are named with the name of the mark followed by the suffix “_rng”, for example radius_rng for the mark radius.

The desired mark ranges are specified in the [object ranges] section of a configuration file (see Configuration File). To specify a mark range, use one of the following statements

MARK_NAME_rng = (min_desired_value, max_desired_value)
MARK_NAME_rng = (min_desired_value, max_desired_value, value_precision)
Examples: radius_rng = (0, 10) and radius_rng = (0, 10, 2)

If no precision is given, then the detection algorithm will generate random mark values uniformly in the given interval at machine precision. Otherwise, the random values will be uniformly drawn among the values in the given interval that can be written min_desired_value + k * value_precision where k is an integer.

The following table describes the marks of the standard object types. Some values might be rounded. Yet, one can identify typical multiples or fractions of \(\pi\). Very large or tiny numbers will often correspond to limit values of the floating point representation used in the code.

Object	Mark	Type	Valid Range	Default Range	Default Precision

2-Dimensional Objects

`circle`	`radius`	float	]0.0, 1.8e+308]	None	0.5

`ellipse`	`semi_minor_axis`	float	]0.0, 1.8e+308]	None	0.5
	`major_minor_ratio`	float	[1.0, 1.8e+308]	(1.0, 2.0)	None
	`angle`	float	[0.0, 3.14[	(0.0, 3.14)	0.0436

`rectangle`	`semi_minor_axis`	float	]0.0, 1.8e+308]	None	0.5
	`major_minor_ratio`	float	[1.0, 1.8e+308]	(1.0, 2.0)	None
	`angle`	float	[0.0, 3.14[	(0.0, 3.14)	0.0436

`square`	`half_side`	float	]0.0, 1.8e+308]	None	0.5
	`angle`	float	[0.0, 1.57[	(0.0, 1.57)	0.0218

`superquadric`	`semi_minor_axis`	float	]0.0, 1.8e+308]	None	0.5
	`major_minor_ratio`	float	[1.0, 1.8e+308]	(1.0, 2.0)	None
	`minor_exponent`	float	]0.0, 1.8e+308]	None	None
	`major_exponent`	float	]0.0, 1.8e+308]	None	None
	`angle`	float	[0.0, 3.14[	(0.0, 3.14)	0.0436

3-Dimensional Objects

`ellipsoid`	`semi_minor_axis`	float	]0.0, 1.8e+308]	None	0.5
	`major_minor_ratio`	float	[1.0, 1.8e+308]	(1.0, 2.0)	None
	`third_minor_ratio`	float	]0.0, 1.8e+308]	(1.0, 1.0)	None
	`rc_angle`	float	[0.0, 3.14[	(0.0, 3.14)	0.0436
	`rd_angle`	float	[0.0, 6.28[	(0.0, 6.28)	0.0873

Standard Quality Measures and Associated Signal Transformations¶

Quality Measures¶

The desired quality measure is specified in the [quality] section of a configuration file using the object_quality parameter, for example object_quality = bright_on_dark_contrast. The minimum quality value an object must have to be considered acceptable is specified using the min_quality parameter in the same section, for example min_quality = 1 (see Configuration File).

Current standard quality measures are:

contour, bright_on_dark_contrast, dark_on_bright_contrast, bright_on_dark_gradient, dark_on_bright_gradient.

Note

Although quality measures might be described as “Python functions” in the documentation, they are in fact Python classes. The full name of these classes are obtained by suffixing the names used in the documentation by “_t”. For example, bright_on_dark_contrast_t for bright_on_dark_contrast.

The contour quality aggregates the signal along the contour of the object. The supported aggregation functions are: mean, stddev (standard deviation), variance, median, min, and max. The associated parameter is named measure. Its default value is mean.

The contrast-based qualities measure how far apart the average signal value inside the object and the average in its neighborhood are.

The gradient-based qualities measure how aligned the gradient of the signal along the object contour and the contour normal are. The parameters of these quality measures are:

bright_on_dark_contrast
- ring_thickness_ext: thickness of the outside ring used to compute object contrast.
- ring_thickness_int: thickness of the inside ring used to compute object contrast. By default, use full object interior.
- normalized: set to True or False to choose whether to normalize the contrast by the square root of the product of the standard deviations in the outside and inside rings.
bright_on_dark_gradient
- max_hole_size: gradient and normal can be consecutively misaligned for at most this length.
The dark-on-bright counterparts have the same parameters.

The desired quality parameters are specified in the optional [quality prm] section of a configuration file, for example ring_thickness_ext = 3 (see Configuration File). However, note that all these parameters have default values (which explains why the [quality prm] section is optional).

For details about the respective parameters of the quality measures, see Section Parameters of Quality Measures

Parameters of Quality Measures¶

The following table describes the parameters of the standard quality measures. Some values might be rounded. The value inf represents a value larger than any other one.

Quality	Parameter	Type	Default Value

`contour`	`measure`	measure_e	measure_e.MEAN

`bright_on_dark_contrast`	`ring_thickness_ext`	int	1
	`ring_thickness_int`	int	inf
	`normalized`	bool	False

`dark_on_bright_contrast`	`ring_thickness_ext`	int	1
	`ring_thickness_int`	int	inf
	`normalized`	bool	False

`bright_on_dark_gradient`	`max_hole_size`	float	1.0

`dark_on_bright_gradient`	`max_hole_size`	float	1.0

Signal Transformations¶

The signal transformation associated with a quality measure is never explicit in a configuration file since it is hardcoded. For the sake of information, the transformation-quality associations are:

Contour quality measure: the signal is used as is.
Contrast-based quality measures: the signal is used as is.
Gradient-based quality measures: the transformation computes the gradient of the signal. It has an optional parameters: unitary. If True, the signal gradient will be normalized. In other words, the quality measures will not depend on the gradient norm, but only its direction.