Scene configuration

Instead of hard-coding every render setting in Python, PoreScene reads the parts of a scene that you tend to stay constant between figures – image resolution, axis calibration, and per-property styling – from a single JSON file. Keeping these values in a plain text file makes a figure reproducible and easy to adjust: change a number, re-run the script, and the same scene renders with the new setting.

The file is grouped into sections, each of which maps onto one of PoreScene’s configuration objects (see porescene.config). Every key is optional – any key you leave out falls back to the built-in default – so a minimal config file is perfectly valid, and you only add the keys you actually want to override.

Loading the configuration

A configuration file is loaded with Scene.from_json. Besides the path to the JSON file, it takes the physical domain dimensions dims as (x, y, z) in meters – these calibrate the axes to the real size of the sample, while the JSON only controls how that calibration is displayed:

from pathlib import Path

from porescene.scene import Scene

# physical domain size in meters (x, y, z)
dims = (100e-06, 100e-06, 100e-06)

# build a scene from the JSON configuration
sc = Scene.from_json(dims, Path.cwd() / "data" / "porescene.json")

Individual settings can still be overridden afterwards on the returned scene, for example sc.config_scene.enable_cylinders = False.

Example configuration

The following porescene.json sets a 4096 × 4096 px image, calibrates the axes to micrometers, and declares a single diameter property. It is a good starting point to copy and adapt:

{
    "axes": {
        "font_size_labels": 1,
        "font_size_ticks": 0.6,
        "font_family": "Inter",
        "enable_ticks": [true, true, true],
        "enable_ticks_minor": true,
        "num_ticks_minor": 3,
        "line_width": 0.04,
        "tick_length": 0.15,
        "tick_interval": 20,
        "precision": [2, 2, 2],
        "spacing": 0.06,
        "unit_display": "MICRO"
    },
    "image": {
        "width": 4096,
        "height": 4096
    },
    "properties": [
        {
            "id": "diameter",
            "heading": "Diameter [µm]",
            "factor": 2e6
        }
    ]
}

The remaining sections describe every key in detail.

image

Controls the resolution of the rendered image, mapping onto ImageConfiguration. Both values are given in pixels.

Key	Type	Default	Description
width	int	4096	Image width in pixels.
height	int	4096	Image height in pixels.

axes

Controls the to-scale axes drawn around the scene, mapping onto AxesConfiguration. The axes are calibrated from the physical dims passed to Scene.from_json; the keys below only govern how that calibration is displayed – the shown unit, tick spacing, precision, and geometry.

Lengths such as line_width, tick_length, and spacing are expressed in scene units, where the longest edge of the model is normalized to a length of 10. Per-axis keys accept either a single value (applied to all three axes) or a three-element list ordered [x, y, z].

Key	Type	Default	Description
unit_display	str	"MICRO"	Metric prefix used for the displayed tick values and axis labels, e.g. "MICRO" → µm, "MILLI" → mm, "NANO" → nm. Must be one of the names of UnitPrefixMetric (uppercase).
tick_interval	number	auto	Spacing between major ticks, in the displayed unit. With unit_display: "MICRO" a value of 20 places a major tick every 20 µm. If omitted, the spacing is derived from dims: the value from the 1-2-5-10 series that puts roughly num_ticks ticks on the longest axis. All three axes share one spacing, so the ticks stay to scale and a shorter axis carries fewer of them.
precision	int or list[int]	[0, 0, 0]	Number of decimal places on the tick labels, per axis. Applied after the values are scaled into the displayed unit.
enable_ticks	bool or list[bool]	[true, true, true]	Show or hide the major ticks, per axis.
enable_ticks_minor	bool or list[bool]	[true, true, true]	Show or hide the minor ticks between major ticks, per axis.
enable_labels_ticks	bool or list[bool]	auto	Show or hide the labels of the major ticks, per axis. If omitted, an axis is labelled only when its ticks are calibrated, i.e. when they come from dims and tick_interval or from an explicit ticks_x/ticks_y/ticks_z. An axis falling back to num_ticks is drawn with bare ticks.
num_ticks	int	6	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. Ignored when tick_interval is given, except for an axis that has no ticks at all, where exactly this many are spread evenly over the full axis length. Minimum 2.
num_ticks_minor	int	auto	Number of minor ticks drawn between two adjacent major ticks. If omitted, the number is derived from the major tick spacing so that the minor ticks fall on round values: a step whose leading digit is 1 or 5 (e.g. 100 or 50) is split into 5 intervals, giving 4 minor ticks, any other step into 4 intervals, giving 3 minor ticks.
font_size_labels	float	0.6	Font size of the axis labels, in scene units.
font_size_ticks	float	0.5	Font size of the tick labels, in scene units.
line_width	float	0.04	Thickness of the axis lines, in scene units.
spacing	float	0.06	Gap kept around the axes, in scene units. Offsets the axis lines from the model’s bounding box and the tick labels from the outer end of their ticks.
tick_length	float	0.2	Length of the tick marks, in scene units.
label_x, label_y, label_z	str	auto	Axis label text. If omitted, a label is generated automatically from unit_display, e.g. "x [µm]".
ticks_x, ticks_y, ticks_z	list[number]	auto	Explicit major-tick positions, in the displayed unit. If omitted, ticks are generated from dims and tick_interval.

Note

The tick values and axis labels are derived from the dims you pass to Scene.from_json (in meters) together with unit_display and tick_interval. To change the shown unit, adjust unit_display – do not rescale dims, which must always stay in meters.

properties

Each entry in the properties list describes one scalar property of the pore network that can be mapped to color – for example diameter, radius, or coordination_number – and mirrors the fields of PropertyConfiguration.

Key	Type	Description
id	str	Name of the property. Must match the property stored on the PoreNetwork.
heading	str	Title shown above the colorbar, typically including the unit, e.g. "Diameter [µm]".
factor	float	Multiplier applied to the raw property values before they are displayed on the colorbar, e.g. 2e6 to turn a radius in meters into a diameter in micrometers. This affects the overlay only, not the rendered geometry.

Note

The color mapping itself – the palette or list of colors, the gradient type, alignment, and orientation – is currently defined in Python by constructing a PropertyConfiguration and adding it with sc.config_scene.add_property(...). See the examples for complete, runnable scripts that build and color a property overlay.