libcarna¶

Geometry Types¶

Each scene might contain multiple types of renderable objects. At least one could distinguish between polygonal and volumetric objects. Planes are certainly a third type: They are neither polygonal because they are infinitely extended, nor are they volumetric. It is up to the user to choose a more fine-grained taxonomy if required. Note that each renderer expects to be told which geometry type it should render. For example, by using two libcarna.cutting_planes renderers with different values for their geometry type, one could render multiple cutting planes with different windowing settings.

API¶

class libcarna.animate(*step_functions: list[Callable[[float], None]], n_frames: int = 25)¶

Bases: object

Create an animation that can be rendered.

Parameters:

*step_functions – List of functions that are called for each frame of the animation. Each function is called with a single argument t, which is a float in the range (0, 1]. The function should modify the scene in place. To obtain a smoothly looping animation, the scene should be in it’s initial state at t=1.
n_frames – Number of frames to be rendered.

bounce_local(axis: Literal['x', 'y', 'z'] | tuple[float, float, float] | list[float, float, float], amplitude: float = 1.0) → Callable[[float], None]¶

Create a step function for bouncing an object along a given axis.

Parameters:

spatial – The spatial object to be animated.
axis – The axis of the bounce. Can be ‘x’, ‘y’, ‘z’, or an arbitrary axis (vector with 3 components).
amplitude – The amplitude of the bounce (alias: amp).

render(r: renderer, *args, **kwargs) → Iterable[ndarray]¶

static rotate_local(spatial: Spatial, axis: Literal['x', 'y', 'z'] | tuple[float, float, float] | list[float, float, float] = 'y') → Callable[[float], None]¶

Create a step function for rotating an object’s local coordinate system.

Parameters:

spatial – The spatial object to be animated.
axis – The axis of rotation. Can be ‘x’, ‘y’, ‘z’, or an arbitrary axis (vector with 3 components).

swing_local(axis: Literal['x', 'y', 'z'] | tuple[float, float, float] | list[float, float, float] = 'y', amplitude: float = 45) → Callable[[float], None]¶

Create a step function for swinging an object’s local coordinate system.

Parameters:

spatial – The spatial object to be animated.
axis – The axis of rotation. Can be ‘x’, ‘y’, ‘z’, or an arbitrary axis (vector with 3 components).
amplitude – The amplitude of the swing in degrees (alias: amp).

libcarna.assertion_failure¶: alias of AssertionFailure

libcarna.camera(tag: str | None = None, *, parent: Node | None = None, **kwargs) → Camera¶

Create a carna.base.Camera object.

Parameters:

tag – An arbitrary string, that helps identifying the object.
parent – Parent node to attach the spatial to, or None.
**kwargs – Attributes to be set on the newly created object.

class libcarna.color(*args, **kwargs)¶: Bases: Color

libcarna.colormap¶: alias of ColorMap

Bases: CuttingPlanesStage

Renders cutting planes (cross sections) of volume geometries.

Parameters:

volume_geometry_type – Geometry type of volumes to be rendered.
plane_geometry_type – Geometry type of planes to be rendered.
cmap – Color map to use for the rendering. If None, the default color map is used.
clim – Color limits for the color map. If None, the full range of intensities [0, 1] is used (if cmap is str or None) or the limits of cmap are used (if cmap is a libcarna.base.ColorMap ).

Example

GEOMETRY_TYPE_VOLUME = 2
GEOMETRY_TYPE_PLANE = 3

# Create volume
data = libcarna.data.toy()

# Create scene
root = libcarna.node()

volume = libcarna.volume(
    GEOMETRY_TYPE_VOLUME,
    data,
    parent=root,
    spacing=(1, 1, 2),
)

zplane = libcarna.geometry(  # create z-plane
    GEOMETRY_TYPE_PLANE,
    parent=volume,
).plane(normal='z', distance=0)

for axis in ('-x', '+x'):  # create left and right planes
    libcarna.geometry(
        GEOMETRY_TYPE_PLANE,
        parent=volume,
    ).plane(normal=axis, dist=0.99 * volume.extent[0] / 2)

camera = libcarna.camera(
    parent=root,
).frustum(fov=90, z_near=1, z_far=500).translate(z=100)

# Create renderer
r = libcarna.renderer(800, 600, [
        libcarna.cutting_planes(
            volume_geometry_type=GEOMETRY_TYPE_VOLUME,
            plane_geometry_type=GEOMETRY_TYPE_PLANE,
            clim=(0.5, 1),
        ),
    ]
)

The normal vector of the planes does not have to necessarily align with the axes.

In this example, we have a z-plane and a pair of x-planes. The x-planes are positioned on the left and right faces of the volume. Their distances to the center of the volume calculates as the width of the volume divided by 2. In addition, a factor of 0.99 is used to position the planes just about inside the volume (otherwise, rounding errors might cause rendering artifacts on some hardware).

For a more information-rich visualization of the volume, we will make the z-plane bounce between the front and back faces of the volume. The amplitude is calculated as the depth of the volume divided by 2.

# Define animation
animation = libcarna.animate(
    libcarna.animate.bounce_local(
        zplane,
        axis='z',
        amplitude=volume.extent[2] / 2,
    ),
    n_frames=50,
)

# Render animation
frames = list(animation.render(r, camera))

The example yields this animation:

_images/test_integration.CuttingPlanesStage.test__animated.png

replicate()¶: Replicate the cutting planes renderer.

class libcarna.drr(geometry_type: int, *, sample_rate: int = 200, water_attenuation: float = 0.004999999888241291, base_intensity: float = 1.0, lower_threshold: int = -400, upper_threshold: int = 400, upper_multiplier: float = 1.5, render_inverse: bool = False)¶

Bases: DRRStage

Renders Digitally Reconstructed Radiographs (DRR) of volume geometries.

Parameters:

geometry_type – Geometry type to be rendered.
sample_rate – Sample rate for volume rendering (alias: sr). Larger values result in higher quality and less artifacts, but slower rendering.
water_attenuation – Water attenuation (alias: waterat).
base_intensity – Base intensity (alias: baseint).
lower_threshold – Lower threshold in Hounsfield Units (alias: lothres).
upper_threshold – Upper threshold in Hounsfield Units (alias: upthres).
upper_multiplier – Upper multiplier (alias: upmulti).
render_inverse – If True, the image is rendered as gray-white on black background (alias: inverse). Otherwise, the image is rendered as gray-black on white background.

Example

GEOMETRY_TYPE_VOLUME = 2

# Create volume
data = libcarna.data.toy()

# Create scene
root = libcarna.node()

libcarna.volume(
    GEOMETRY_TYPE_VOLUME,
    data,
    parent=root,
    spacing=(1, 1, 2),
)

camera = libcarna.camera(
    parent=root,
).frustum(fov=90, z_near=1, z_far=500).translate(z=100)

# Create renderer
r = libcarna.renderer(
    800, 600, [
        libcarna.drr(
            GEOMETRY_TYPE_VOLUME, sr=800, inverse=True,
            lothres=0, upthres=1000, upmulti=3,
        ),
    ],
    bgcolor=libcarna.color.WHITE_NO_ALPHA,
)

Rendering the scene as an animation:

_images/test_integration.DRRStage.test__animated.png

replicate()¶: Replicate the DRR renderer.

Bases: DVRStage

Performs Direct Volume Rendering (DVR) of volume geometries.

Parameters:

geometry_type – Geometry type to be rendered.
cmap – Color map to use for the DVR. If None, the default color map is used.
clim – Color limits for the color map. If None, the full range of intensities [0, 1] is used (if cmap is str or None) or the limits of cmap are used (if cmap is a libcarna.base.ColorMap ).
sample_rate – Sample rate for volume rendering (alias: sr). Larger values result in higher quality and less artifacts, but slower rendering.
translucency – Translucency value for the DVR, that is used on top of the translucency from the color map (alias: transl). A value of 1 means that the overall translucency is doubled. Larger values result in more translucency.
diffuse_light – Diffuse light value for the volume rendering. Larger values result in more diffuse light (alias: diffuse). Ambient light is one minus diffuse light.

Example

GEOMETRY_TYPE_VOLUME = 2

# Create volume
data = libcarna.data.toy()

# Create scene
root = libcarna.node()

libcarna.volume(
    GEOMETRY_TYPE_VOLUME,
    data,
    parent=root,
    spacing=(1, 1, 2),
    normals=True,
)

camera = libcarna.camera(
    parent=root,
).frustum(fov=90, z_near=1, z_far=500).translate(z=100)

# Create renderer
dvr = libcarna.dvr(
    GEOMETRY_TYPE_VOLUME, sr=800, transl=0.1, diffuse=0.8,
)
dvr.cmap.clear()
dvr.cmap.linear_segment(
    0.7, 1.0,
    libcarna.color(0, 150, 255, 150),
    libcarna.color(255, 0, 255, 255),
)
r = libcarna.renderer(800, 600, [dvr])

Rendering the scene as an animation:

_images/test_integration.DVRStage.test__animated.png

replicate()¶: Replicate the DVR.

libcarna.egl_context¶: alias of EGLContext

libcarna.frame_renderer¶: alias of FrameRenderer

libcarna.frame_renderer_helper¶: alias of FrameRendererHelper

libcarna.geometry(geometry_type: int, tag: str | None = None, *, parent: Node | None = None, mesh: GeometryFeature | None = None, material: Material | None = None, **kwargs) → Geometry¶

Create a carna.base.Geometry object.

Parameters:

geometry_type – The type of the geometry.
tag – An arbitrary string, that helps identifying the object.
parent – Parent node to attach the spatial to, or None.
mesh – A mesh to be attached to this geometry object.
material – A material to be attached to this geometry object.
**kwargs – Attributes to be set on the newly created object.

libcarna.geometry_feature¶: alias of GeometryFeature

libcarna.gl_context¶: alias of GLContext

libcarna.imshow(array: ndarray | Iterable[ndarray], *colorbars, fps: float = 25, format: str = 'auto') → Any¶

Display an image or a sequence of images in a Jupyter notebook.

Parameters:

array – The image or sequence of images to display. Can be a 3D NumPy array (RGB image) or 4D NumPy array (stack of RGB images), or an iterable of 3D arrays (sequence of RGB images).
colorbars – Optional colorbars to display alongside the image.
fps – The frames per second for the animation. Default is 25.
format – The format to use for displaying the image. Can be ‘apng’ or ‘h264’. Default is ‘auto’, which will use ‘apng’ for single images, and ‘h264’ for image stacks or sequences.

libcarna.libcarna_exception¶: alias of LibCarnaException

libcarna.logging(enabled: bool = True) → None¶

class libcarna.mask_renderer(geometry_type: int, *, sample_rate: int = 200, color: ~libcarna._color.color = <libcarna.base.Color object>, filling: bool = False)¶

Bases: MaskRenderingStage

Renders 3D masks as either unshaded areas or borders.

Parameters:

geometry_type – Geometry type to be rendered.
sample_rate – Sample rate for volume rendering (alias: sr). Larger values result in higher quality and less artifacts, but slower rendering.
color – Color to use for the mask (alias: c).
filling – If True, the mask is filled (alias: fill). If False, only the borders are rendered.

Example

GEOMETRY_TYPE_VOLUME = 2

# Create volume
data = (libcarna.data.toy() > 0.68)

# Create scene
root = libcarna.node()

libcarna.volume(
    GEOMETRY_TYPE_VOLUME,
    data,
    parent=root,
    spacing=(1, 1, 2),
)

camera = libcarna.camera(
    parent=root,
).frustum(fov=90, z_near=1, z_far=500).translate(z=100)

# Create renderer
r = libcarna.renderer(800, 600, [
        libcarna.mask_renderer(GEOMETRY_TYPE_VOLUME),
    ]
)

Rendering the scene as an animation:

_images/test_integration.MaskRenderingStage.test__animated.png

replicate()¶: Replicate the mask renderer.

libcarna.material(shader_name: str = 'solid', lw: float = 1, **kwargs) → Material¶

Create a libcarna.base.Material object.

Parameters:

shader_name – The shader to be used for rendering.
lw – The width of the lines in pixels, if the material is used for drawing lines.
**kwargs – Uniform shader parameters.

libcarna.mesh_renderer¶: alias of MeshRenderingStage

libcarna.meshes¶: alias of MeshFactory

class libcarna.mip(geometry_type: int, *, cmap: str | None = None, clim: tuple[float | None, float | None] | None = None, sample_rate: int = 200)¶

Bases: MIPStage

Renders Maximum Intensity Projections (MIP) of volume geometries.

Parameters:

geometry_type – Geometry type to be rendered.
cmap – Color map to use for the MIP. If None, the default color map is used.
clim – Color limits for the color map. If None, the full range of intensities [0, 1] is used (if cmap is str or None) or the limits of cmap are used (if cmap is a libcarna.base.ColorMap ).
sample_rate – Sample rate for volume rendering (alias: sr). Larger values result in higher quality and less artifacts, but slower rendering.

Example

GEOMETRY_TYPE_VOLUME = 2

# Create data
data = libcarna.data.toy()

# Create scene
root = libcarna.node()

libcarna.volume(
    GEOMETRY_TYPE_VOLUME,
    data,
    parent=root,
    spacing=(1, 1, 2),
)

camera = libcarna.camera(
    parent=root,
).frustum(fov=90, z_near=1, z_far=500).translate(z=100)

# Create renderer
r = libcarna.renderer(800, 600, [
        libcarna.mip(GEOMETRY_TYPE_VOLUME, cmap='jet'),
    ]
)

Rendering the scene as an animation:

_images/test_integration.MIPStage.test__animated.png

replicate()¶: Replicate the MIP stage.

libcarna.node(tag: str | None = None, *, parent: Node | None = None, **kwargs) → Node¶

Create a carna.base.Node object, that other spatial objects can be added to.

Parameters:

tag – An arbitrary string, that helps identifying the object.
parent – Parent node to attach the spatial to, or None.
**kwargs – Attributes to be set on the newly created object.

libcarna.normalize_hounsfield_units(data, rel_mode_width=0.33)¶: Normalize data to Hounsfield Units (HU) using a heuristic histogram method.

class libcarna.opaque_renderer(geometry_type: int)¶

Bases: OpaqueRenderingStage

Renders opaque geometries (meshes).

Parameters:: geometry_type – Geometry type to be rendered.

Example

GEOMETRY_TYPE_OPAQUE = 1

# Create mesh
box = libcarna.meshes.create_box(40, 40, 40)

# Create scene
root = libcarna.node()

libcarna.geometry(
    GEOMETRY_TYPE_OPAQUE,
    parent=root,
    mesh=box,
    material=libcarna.material('solid', color='#ff0000'),
).translate(-10, -10, -40)

libcarna.geometry(
    GEOMETRY_TYPE_OPAQUE,
    parent=root,
    mesh=box,
    material=libcarna.material('solid', color='#00ff00'),
).translate(+10, +10, +40)

camera = libcarna.camera(
    parent=root,
).frustum(fov=90, z_near=1, z_far=1e3).translate(z=250)

# Create renderer
r = libcarna.renderer(800, 600, [
        libcarna.opaque_renderer(GEOMETRY_TYPE_OPAQUE),
    ]
)

Rendering the scene as an animation:

_images/test_integration.OpaqueRenderingStage.test__animated.png

replicate()¶: Replicate the opaque renderer.

libcarna.render_stage¶: alias of RenderStage

class libcarna.renderer(width: int, height: int, stages: ~typing.Iterable[~libcarna.base.RenderStage], background_color: ~libcarna._color.color = <libcarna.base.Color object>, gl_context: ~libcarna.base.GLContext | None = None)¶

Bases: object

Create a renderer, that conveniently combines a frame_renderer and a surface.

Parameters:

width – Horizontal rendering resolution.
height – Vertical rendering resolution.
stages – List of stages to be added to the frame renderer.
background_color – Background color of the surface (aliases: bgcolor, bgc).
gl_context – OpenGL context to be used for rendering (alias: ctx). If None, a new egl_context will be created.

gl_context: GLContext¶: OpenGL context used for rendering.

height: int¶: Vertical rendering resolution.

render(camera: Camera, root: Node | None = None) → ndarray¶: Render scene root from camera point of view to a NumPy array.

width: int¶: Horizontal rendering resolution.

libcarna.spatial¶: alias of Spatial

libcarna.surface¶: alias of Surface

libcarna.volume(geometry_type: int, array: ndarray, tag: str | None = None, *, units: Literal['raw', 'hu'] = 'raw', parent: Node | None = None, normals: bool = False, spacing: ndarray | None = None, extent: ndarray | None = None, **kwargs) → Node¶

Create a renderable representation of 3D data using the specified geometry_type, that can be put anywhere in the scene graph. The 3D volume is centered in the returned node.

Parameters:

geometry_type – The type of the geometry.
array – 3D data to be rendered.
tag – An arbitrary string, that helps identifying the created node.
units – The units of the data. If ‘hu’, the data is assumed to be in Hounsfield Units (HU).
parent – Parent node to attach the volume to, or None.
normals – Governs normal mapping (if True, the 3D normal map will be pre-computed for the volume).
spacing – Specifies the spacing between two adjacent voxel centers. Mutually exclusive with extent.
extent – Specifies the spatial size of the whole volume. Mutually exclusive with spacing.
**kwargs – Attributes to be set on the created node.

libcarna.volume_renderer¶: alias of VolumeRenderingStage

libcarna¶

Geometry Types¶

API¶

libcarna-python

Navigation

Related Topics