porescene.config module

Configuration objects that control how a PoreNetwork and its images are rendered.

This module bundles the settings used throughout porescene:

• PropertyConfiguration – visualization of a single property.

• ImageConfiguration – resolution of the rendered images.

• VideoConfiguration – frame settings for rendered videos.

• SceneConfiguration – overall scene, material and property settings.

• AxesConfiguration – coordinate axes, ticks and labels.

class porescene.config.AxesConfiguration(extent, tick_interval=None, unit_display='MICRO', num_ticks=6)

Bases: object

Settings for the coordinate axes, ticks and labels of a scene.

classmethod from_dict(extent, data)

Creates an AxesConfiguration from a dictionary.

Ticks and axis labels are derived from extent (the size of the volume) together with the optional tick_interval and unit_display keys; the remaining keys override the derived values.

Return type:

Self

property enable_labels_ticks: tuple[bool, bool, bool]

Toggle to show/hide the labels of the major axis ticks.

When set to None, an axis is labelled only if it carries ticks – either the ones calibrated from extent or ones assigned explicitly. An axis whose ticks were cleared falls back to the evenly spaced ticks of num_ticks, which carry no calibrated values, so it is drawn with bare ticks rather than misleading numbers.

property enable_ticks: tuple[bool, bool, bool]

Toggle to show/hide major axis ticks.

property enable_ticks_minor: tuple[bool, bool, bool]

Toggle to show/hide minor axis ticks.

property extent: ndarray

Physical extent of the domain along x, y and z, in meters.

property factor: tuple[float, float, float]

Factor to scale axis labels.

property font_family: Path | None

Font family for axis labels specified as Path to TTF file.

property font_size_labels: float

Axis label font-size.

property font_size_ticks: float

Tick label font-size.

property indent_ticks: bool

Whether tick labels are indented.

property label_x: str

x-axis label.

property label_y: str

y-axis label.

property label_z: str

z-axis label.

property line_width: float

Axis line width.

property num_ticks: int

Number of major ticks aimed for along the longest axis.

Sizes the derived tick_interval, and is met only approximately there, since the interval is rounded to a value the ticks read well at. For an axis whose ticks were cleared, the count is instead exact: the ticks are spread evenly between value_start and value_end, and are drawn without labels unless enable_labels_ticks says otherwise. Values below 2 are raised to 2, since a single tick has no spacing to place minor ticks by.

property num_ticks_minor: int

Number of minor ticks drawn between two adjacent major ticks.

When set to None, a suitable number is derived from the spacing of the major ticks, following the convention of matplotlib’s AutoMinorLocator: a major step whose leading digit is 1 or 5 – such as 100 or 50 – is divided into 5 intervals, giving 4 minor ticks, while any other step is divided into 4 intervals, giving 3 minor ticks. This keeps the minor ticks on round values instead of, say, splitting a step of 20 into fifths of 4. Falls back to 4 when the major tick spacing is still unknown.

property position_tick_x: Sequence[float]

Normalized positions (0-1) of the x-axis ticks.

Derived from ticks_x and extent unless set explicitly.

property position_tick_y: Sequence[float]

Normalized positions (0-1) of the y-axis ticks.

Derived from ticks_y and extent unless set explicitly.

property position_tick_z: Sequence[float]

Normalized positions (0-1) of the z-axis ticks.

Derived from ticks_z and extent unless set explicitly.

property precision: tuple[int, int, int]

Precision of axis labels. Applies after scaling.

property spacing: float

Gap kept around the axes, in scene units.

Offsets the axis lines from the volume and the tick labels from the outer end of their ticks, so neither sits flush against what it belongs to.

property tick_interval: float

Spacing between major ticks, in the displayed unit.

Unless given at construction, the interval is derived from extent: it is the value from the 1-2-5-10 series that puts roughly num_ticks ticks on the longest axis. All three axes share it, so the ticks stay to scale and a shorter axis simply carries fewer of them.

property tick_length: float

Tick length.

property ticks_x: Sequence[float]

Tick values shown along the x-axis.

Falls back to evenly spaced ticks, see num_ticks.

property ticks_y: Sequence[float]

Tick values shown along the y-axis.

Falls back to evenly spaced ticks, see num_ticks.

property ticks_z: Sequence[float]

Tick values shown along the z-axis.

Falls back to evenly spaced ticks, see num_ticks.

property value_end: Sequence[float]

Tick value at the end of each axis (x, y, z).

property value_start: Sequence[float]

Tick value at the start of each axis (x, y, z).

class porescene.config.ImageConfiguration

Bases: object

Settings for the resolution of the rendered images.

classmethod from_dict(data)

Creates an ImageConfiguration from a dictionary.

Only the width and height keys are read; other keys are ignored.

Return type:

Self

property aspect_ratio: float

Image aspect ratio.

property height: int

Height of the image in px.

property resolution: list[int]

Image resolution in px [width,height].

property width: int

Width of the image in px.

class porescene.config.PropertyConfiguration(name, colors=(), /, gradient_class=<class 'porescene.color.gradient.SmoothGradient'>, heading=None, subheading=None, text=(), align=CompassDirection.NORTH, orientation=Orientation.HORIZONTAL, precision=0, min=None, max=None, use_global_boundaries=False, factor=1.0, func_transform=<function PropertyConfiguration.<lambda>>, fit=True, color_nan=None, color_below=None, color_above=None)

Bases: object

Settings for the visualization of a specific property of the system.

property align: CompassDirection

Point of alignment of the layout image.

property color_above: Color | None

Color of values above the range.

See also Gradient.color_above.

property color_below: Color | None

Color of values below the range.

See also Gradient.color_below.

property color_nan: Color | None

Color of NaN values.

See also Gradient.color_nan.

property colors: list[Color]

Colors of the gradient to visualize the property.

See also Gradient.colors.

property factor: float

A factor to scale the values of a property on overlays. Does not apply to anything rendering or model related.

property fit: bool

If True, the gradient truncates all values in specified range.

property func_transform: Callable

A transformation function to scale the values of a property on overlays. Does not apply to anything rendering or model related.

property heading: str | None

Heading of the layout image.

property max: float | None

Maximum of the property.

property min: float | None

Minimum of the property.

property name: str

Name of the property.

property orientation: Orientation

Orientation of the layout image. There are two types available: vertical (‘V’) and horizontal (‘H’).

property precision: int

Precision of the gradient boundaries on a layout.

property subheading: str | None

Subheading of the layout image.

property text: list[str]

Text lines on the layout image.

property use_global_boundaries: bool

Whether to use colorbar limits across all states or per state.

class porescene.config.SceneConfiguration(enable_spheres=True, enable_cylinders=True, enable_clusters=True, enable_axes=True, enable_solid=True, enable_void=False, versions_solid=None, versions_void=None, material_spheres='PLASTIC_ROUGH', material_cylinders='PLASTIC_ROUGH', material_clusters='PLASTIC_ROUGH', material_solid='SOLID_DEFAULT', material_void='ICE', palette=None)

Bases: object

Settings for the visualization of a PoreNetwork.

add_property(prop)

Add the PropertyConfiguration for a property of the pnm.

get_property(name)

Returns the PropertyConfiguration for given name.

Return type:

PropertyConfiguration

property enable_axes: bool

Toggle to enable/disable scalebars in plots.

property enable_clusters: bool

Toggle to enable/disable clusters in plots.

property enable_cylinders: bool

Toggle to enable/disable cylinders in plots.

property enable_solid: bool

Toggle to enable/disable the solid structure in plots.

property enable_spheres: bool

Toggle to enable/disable spheres in plots.

property enable_void: bool

Toggle to enable/disable the void structure in plots.

property material_clusters: str

Returns the material type to render the clusters with.

property material_cylinders: str

Returns the material type to render the throats with.

property material_solid: str

Returns the material type to render the solid with.

property material_spheres: str

Returns the material type to render the pores with.

property material_void: str

Returns the material type to render the void with.

property palette: Palette

Color palette used to render the network.

property versions_solid: list[Path]

Clipping versions of the solid structure to render.

property versions_void: list[Path]

Clipping versions of the void structure to render.

class porescene.config.VideoConfiguration

Bases: object

Settings for the frames of a rendered video.

property frames_fps: int

Frames per second of the video.

property frames_solid: int

Type of solid to display in generated frames.

property frames_speed: int

Number of steps between two frames of the video.