Imaging

Assign and Retrieve Colors

Methods of CellContainer

Description

assign_colors_to_cells()

Assigns unique colors to cells.

counter_to_cell_identifier()

Converts an integer counter to a cell

get_color()

Obtains the color assigned to the cell

get_cell_from_color()

Given a color, determines the CellIdentifier

counter_to_color()

Maps an integer counter uniquely to a color value

color_to_counter()

Inverse of counter_to_color()
Generating Images

Function

Description

render_pv_image()

Renders an image image purely generated by pyvista

render_mask()

Creates masks usable for cell-segmentation

render_image()

Renders a complete near-realistic image.

store_all_images()

Creates and stores images in files.
class RenderSettings(resolution: int = 1280, diffuse: float = 0.5, ambient: float = 0.5, specular: float = 0.5, specular_power: float = 10.0, metallic: float = 1.0, noise: int = 50, bg_brightness: int = 100, cell_brightness: int = 30, ssao_radius: int = 50, kernel_size: int = 30, pbr: bool = True, lighting: bool = True, render_mask: bool = False)

Bases: object

This class contains all settings to render images with pyvista <https://docs.pyvista.org/>_ and `opencv <https://opencv.org>_ to create near-realistic microscopic images. Many of the values will be given directly to pyvistas :meth:`pyvista.plotter.add_mesh function. Others are used by cv2.

prepare_for_masks()

Prepares all render settings such that the image generated is a mask.

ambient: float = 0.5

Value between 0 and 1.

bg_brightness: int = 100

Background brightness

cell_brightness: int = 30

Brightness of the individual cells

diffuse: float = 0.5

Value Between 0 and 1.

kernel_size: int = 30

Smoothing kernel size

lighting: bool = True
metallic: float = 1.0

Value between 0 and 1

noise: int = 50

RGB values per pixel

pbr: bool = True

Enable physics-based rendering

render_mask: bool = False
resolution: int = 1280

Resolution of the generated image

specular: float = 0.5

Value between 0 and 1.

specular_power: float = 10.0

Value between 0 and 250.

ssao_radius: int = 50

Radius for ssao scattering

render_image(cells: dict[CellIdentifier, tuple[RodAgent, CellIdentifier | None]], domain_size: float, render_settings: RenderSettings | None = None, filename: str | Path | None = None) → ndarray

Aims to create a near-realistic microscopic image with the given cells. This function internally uses the render_pv_image() function but changes some of the

Parameters:
Returns:

See render_pv_image().

Return type:

np.ndarray

render_mask(cells: dict[CellIdentifier, tuple[RodAgent, CellIdentifier | None]], colors: dict[CellIdentifier, list[int]], domain_size: float, render_settings: RenderSettings | None = None, filename: str | Path | None = None) → ndarray

Creates an image containing masks of the given cells. This function internally uses the render_pv_image() function and RenderSettings.prepare_for_masks() method.

Parameters:
Returns:

See render_pv_image().

Return type:

np.ndarray

render_pv_image(cells: dict[CellIdentifier, tuple[RodAgent, CellIdentifier | None]], render_settings: RenderSettings, domain_size: float, colors: dict[CellIdentifier, list[int]] | None = None, filename: str | Path | None = None) → ndarray

Creates a 3D render of the given cells.

Parameters:

  • cells – A iterable which contains all cells at a specific iteration.

  • render_settings (RenderSettings) – Contains all settings to specify how to render image.

  • domain_size (float) – The domain size as specified in Configuration.

  • colors (dict) – A dictionary mapping a CellIdentifier to a color. If not given use color from render_settings.

  • filename – Name of the file in which to save the image. If not specified, do not save.

Returns:

An array of shape (resolution, resolution, 3) which contains the rendered

pixels.

Return type:

np.ndarray

store_all_images(cell_container: CellContainer, domain_size: float, render_settings: RenderSettings | None = None, save_dir: str | Path = 'out', render_raw_pv: bool = False, show_progressbar: bool | int = False, store_config: Configuration | None = None, use_hash: bool = True)

Combines multiple functions and renders images to files for a complete simulation result. This function calls the render_image(), render_pv_image() and render_mask() functions to create multiple images.

Parameters:

  • cell_container – See cr_mech_coli.simulation.run_simulation().

  • domain_size (float) – See render_pv_image().

  • render_settings (RenderSettings) – See render_pv_image().

  • save_dir – Path of the directory where to save all images.

  • render_raw_pv (bool) – Additionaly render the intermediate image before applying effects from cv2.

  • show_progressbar (bool) – Shows a progressbar of how many iterations have been rendered.

  • store_config (bool) – Store config as json string in directory.

  • use_hash (bool) – Use a hash generated from the Configuration class as subfolder of save_dir to store results in. This option can only be used together with the store_config option.

Returns:

See render_pv_image().

Return type:

np.ndarray

counter_to_color(counter)

Converts an integer counter between 0 and 251^3-1 to an RGB value. The reason why 251 was chosen is due to the fact that it is the highest prime number which is below 255. This will yield a Field of numbers \(\mathbb{Z}/251 \mathbb{Z}\) and thus we will be able to determine an exact inverse function. This system is bettern known as modular arithmetic.

To calculate artistic color values we multiply the counter by 157*163*173 which are three prime numbers roughyl in the middle of 255. The new numbers can be calculated via

>>> new_counter = counter * 157 * 163 * 173
>>> c1, mod = divmod(new_counter, 251**2)
>>> c2, mod = divmod(mod, 251)
>>> c3      = mod
Parameters:

  • counter (int) – Counter between 0 and 251^3-1

  • artistic (bool) – Enables artistic to provide larger differences between single steps instead of simple incremental one.

Returns:

A list with exactly 3 entries containing the calculated color.

Return type:

list[int]

color_to_counter(color)

Converts a given color back to the counter value.

The is the inverse of the counter_to_color() function. The formulae can be calculated with the Extended Euclidean Algorithm. The multiplicative inverse (mod 251) of the numbers of 157, 163 and 173 are:

>>> assert (12590168 * 157) % 251**3 == 1
>>> assert (13775961 * 163) % 251**3 == 1
>>> assert (12157008 * 173) % 251**3 == 1

Thus the formula to calculate the counter from a given color is:

>>> counter = color[0] * 251**2 + color[1] * 251 + color[2]
>>> counter = (counter * 12590168) % 251**3
>>> counter = (counter * 13775961) % 251**3
>>> counter = (counter * 12157008) % 251**3