yt.visualization.volume_rendering.scene module¶

class yt.visualization.volume_rendering.scene.Scene[source]¶

Bases: object

A virtual landscape for a volume rendering.

The Scene class is meant to be the primary container for the new volume rendering framework. A single scene may contain several Camera and RenderSource instances, and is the primary driver behind creating a volume rendering.

This sets up the basics needed to add sources and cameras. This does very little setup, and requires additional input to do anything useful.

Examples

This example shows how to create an empty scene and add a VolumeSource and a Camera.

>>> import yt
>>> from yt.visualization.volume_rendering.api import (
...     Camera, Scene, create_volume_source)
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
>>> sc = Scene()
>>> source = create_volume_source(ds.all_data(), "density")
>>> sc.add_source(source)
>>> cam = sc.add_camera()
>>> im = sc.render()

Alternatively, you can use the create_scene function to set up defaults and then modify the Scene later:

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> # Modify camera, sources, etc...
>>> im = sc.render()

add_camera(data_source=None, lens_type='plane-parallel', auto=False)[source]¶

Add a new camera to the Scene.

The camera is defined by a position (the location of the camera in the simulation domain,), a focus (the point at which the camera is pointed), a width (the width of the snapshot that will be taken, a resolution (the number of pixels in the image), and a north_vector (the “up” direction in the resulting image). A camera can use a variety of different Lens objects.

If the scene already has a camera associated with it, this function will create a new camera and discard the old one.

Parameters:

data_source (AMR3DData or Dataset, optional) – This is the source to be rendered, which can be any arbitrary yt data object or dataset.
lens_type (string, optional) – This specifies the type of lens to use for rendering. Current options are ‘plane-parallel’, ‘perspective’, and ‘fisheye’. See yt.visualization.volume_rendering.lens.Lens for details. Default: ‘plane-parallel’
auto (boolean) – If True, build smart defaults using the data source extent. This can be time-consuming to iterate over the entire dataset to find the positional bounds. Default: False

Examples

In this example, the camera is set using defaults that are chosen to be reasonable for the argument Dataset.

>>> import yt
>>> from yt.visualization.volume_rendering.api import Camera, Scene
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
>>> sc = Scene()
>>> sc.add_camera()

Here, we set the camera properties manually:

>>> import yt
>>> from yt.visualization.volume_rendering.api import Camera, Scene
>>> sc = Scene()
>>> cam = sc.add_camera()
>>> cam.position = np.array([0.5, 0.5, -1.0])
>>> cam.focus = np.array([0.5, 0.5, 0.0])
>>> cam.north_vector = np.array([1.0, 0.0, 0.0])

Finally, we create a camera with a non-default lens:

>>> import yt
>>> from yt.visualization.volume_rendering.api import Camera
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
>>> sc = Scene()
>>> sc.add_camera(ds, lens_type="perspective")

add_source(render_source, keyname=None)[source]¶

Add a render source to the scene.

This will autodetect the type of source.

Parameters:

render_source – yt.visualization.volume_rendering.render_source.RenderSource A source to contribute to the volume rendering scene.
keyname (string (optional)) – The dictionary key used to reference the source in the sources dictionary.

annotate_axes(colors=None, alpha=1.0, *, thickness=1)[source]¶

Modifies this scene by drawing the coordinate axes. This adds a new CoordinateVectorSource to the scene and returns the modified scene object.

Parameters:

colors (array-like of shape (3,4), optional) – The RGBA values to use to draw the x, y, and z vectors. The default is [[1, 0, 0, alpha], [0, 1, 0, alpha], [0, 0, 1, alpha]] where alpha is set by the parameter below. If colors is set then alpha is ignored.
alpha (float, optional) – The opacity of the vectors.
thickness (int, optional) – The line thickness

Examples

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> sc.annotate_axes(alpha=0.5)
>>> im = sc.render()

annotate_domain(ds, color=None)[source]¶

Modifies this scene by drawing the edges of the computational domain. This adds a new BoxSource to the scene corresponding to the domain boundaries and returns the modified scene object.

Parameters:

ds (yt.data_objects.static_output.Dataset) – This is the dataset object corresponding to the simulation being rendered. Used to get the domain bounds.
color (array_like of shape (4,), optional) – The RGBA value to use to draw the domain boundaries. Default is black with an alpha of 1.0.

Examples

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> sc.annotate_domain(ds)
>>> im = sc.render()

annotate_grids(data_source, alpha=0.3, cmap=None, min_level=None, max_level=None)[source]¶

Modifies this scene by drawing the edges of the AMR grids. This adds a new GridSource to the scene that represents the AMR grid and returns the resulting Scene object.

Parameters:

data_source (DataContainer) – The data container that will be used to identify grids to draw.
alpha (float) – The opacity of the grids to draw.
cmap (color map name) – The color map to use to map resolution levels to color.
min_level (int, optional) – Minimum level to draw
max_level (int, optional) – Maximum level to draw

Examples

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> sc.annotate_grids(ds.all_data())
>>> im = sc.render()

annotate_mesh_lines(color=None, alpha=1.0)[source]¶

Modifies this Scene by drawing the mesh line boundaries on all MeshSources.

Parameters:

color (array_like of shape (4,), optional) – The RGBA value to use to draw the mesh lines. Default is black with an alpha of 1.0.
alpha (float, optional) – The opacity of the mesh lines. Default is 255 (solid).

property arr¶

Converts an array into a yt.units.yt_array.YTArray

The returned YTArray will be dimensionless by default, but can be cast to arbitrary units using the units keyword argument.

Parameters:

input_array (Iterable) – A tuple, list, or array to attach units to
units (String unit specification, unit symbol object, or astropy units object) – The units of the array. Powers must be specified using python syntax (cm**3, not cm^3).
dtype (string or NumPy dtype object) – The dtype of the returned array data

Examples

>>> a = sc.arr([1, 2, 3], "cm")
>>> b = sc.arr([4, 5, 6], "m")
>>> a + b
YTArray([ 401.,  502.,  603.]) cm
>>> b + a
YTArray([ 4.01,  5.02,  6.03]) m

Arrays returned by this function know about the scene’s unit system

>>> a = sc.arr(np.ones(5), "unitary")
>>> a.in_units("Mpc")
YTArray([ 1.00010449,  1.00010449,  1.00010449,  1.00010449,
         1.00010449]) Mpc

property camera¶

The camera property.

This is the default camera that will be used when rendering. Can be set manually, but Camera type will be checked for validity.

composite(camera=None)[source]¶

Create a composite image of the current scene.

First iterate over the opaque sources and set the ZBuffer. Then iterate over the transparent sources, rendering from the value of the zbuffer to the front of the box. Typically this function is accessed through the .render() command.

Parameters:: camera (Camera, optional) – If specified, use a specific Camera to render the scene.
Returns:: im – ImageArray instance of the current rendering image.
Return type:: ImageArray

Examples

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> # Modify camera, sources, etc...
>>> im = sc.composite()

get_camera()[source]¶: Get the camera currently used by this scene.

get_source(source_num=0)[source]¶: Returns the volume rendering source indexed by source_num

property opaque_sources¶: Iterate over opaque RenderSource objects, returning a tuple of (key, source)

property quan¶

Converts an scalar into a yt.units.yt_array.YTQuantity

The returned YTQuantity will be dimensionless by default, but can be cast to arbitrary units using the units keyword argument.

Parameters:

input_scalar (an integer or floating point scalar) – The scalar to attach units to
units (String unit specification, unit symbol object, or astropy) – units
input_units (deprecated in favor of 'units') – The units of the quantity. Powers must be specified using python syntax (cm**3, not cm^3).
dtype (string or NumPy dtype object) – The dtype of the array data.

Examples

>>> a = sc.quan(1, "cm")
>>> b = sc.quan(2, "m")
>>> a + b
201.0 cm
>>> b + a
2.01 m

Quantities created this way automatically know about the unit system of the scene

>>> a = ds.quan(5, "unitary")
>>> a.in_cgs()
1.543e+25 cm

render(camera=None)[source]¶

Render all sources in the Scene.

Use the current state of the Scene object to render all sources currently in the scene. Returns the image array. If you want to save the output to a file, call the save() function.

Parameters:

camera (Camera, optional) – If specified, use a different Camera to render the scene.

Returns:

A yt.data_objects.image_array.ImageArray instance containing
the current rendering image.

Examples

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> # Modify camera, sources, etc...
>>> im = sc.render()
>>> sc.save(sigma_clip=4.0, render=False)

Altneratively, if you do not need the image array, you can just call save as follows.

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> # Modify camera, sources, etc...
>>> sc.save(sigma_clip=4.0)

save(fname: str | None = None, sigma_clip: float | None = None, render: bool = True)[source]¶

Saves a rendered image of the Scene to disk.

Once you have created a scene, this saves an image array to disk with an optional filename. This function calls render() to generate an image array, unless the render parameter is set to False, in which case the most recently rendered scene is used if it exists.

Parameters:

fname (string, optional) –
If specified, save the rendering as to the file “fname”. If unspecified, it creates a default based on the dataset filename. The file format is inferred from the filename’s suffix. Supported formats depend on which version of matplotlib is installed.

Default: None
sigma_clip (float, optional) –
Image values greater than this number times the standard deviation plus the mean of the image will be clipped before saving. Useful for enhancing images as it gets rid of rare high pixel values. Default: None

floor(vals > std_dev*sigma_clip + mean)
render (boolean, optional) – If True, will always render the scene before saving. If False, will use results of previous render if it exists. Default: True

Return type:

Nothing

Examples

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> # Modify camera, sources, etc...
>>> sc.save("test.png", sigma_clip=4)

When saving multiple images without modifying the scene (camera, sources,etc.), render=False can be used to avoid re-rendering. This is useful for generating images at a range of sigma_clip values:

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> # save with different sigma clipping values
>>> sc.save("raw.png")  # The initial render call happens here
>>> sc.save("clipped_2.png", sigma_clip=2, render=False)
>>> sc.save("clipped_4.png", sigma_clip=4, render=False)

save_annotated(fname: str | None = None, label_fmt: str | None = None, text_annotate=None, dpi: int = 100, sigma_clip: float | None = None, render: bool = True, tf_rect: list[float] | None = None, *, label_fontsize: float | str = 10)[source]¶

Saves the most recently rendered image of the Scene to disk, including an image of the transfer function and and user-defined text.

Once you have created a scene and rendered that scene to an image array, this saves that image array to disk with an optional filename. If an image has not yet been rendered for the current scene object, it forces one and writes it out.

Parameters:

fname (string, optional) – If specified, save the rendering as a bitmap to the file “fname”. If unspecified, it creates a default based on the dataset filename. Default: None
sigma_clip (float, optional) –
Image values greater than this number times the standard deviation plus the mean of the image will be clipped before saving. Useful for enhancing images as it gets rid of rare high pixel values. Default: None

floor(vals > std_dev*sigma_clip + mean)
dpi (integer, optional) – By default, the resulting image will be the same size as the camera parameters. If you supply a dpi, then the image will be scaled accordingly (from the default 100 dpi)
label_fmt (str, optional) – A format specifier (e.g., label_fmt=”%.2g”) to use in formatting the data values that label the transfer function colorbar.
label_fontsize (float or string, optional) – The fontsize used to display the numbers on the transfer function colorbar. This can be any matplotlib font size specification, e.g., “large” or 12. (default: 10)
text_annotate (list of iterables) –
Any text that you wish to display on the image. This should be an list containing a tuple of coordinates (in normalized figure coordinates), the text to display, and, optionally, a dictionary of keyword/value pairs to pass through to the matplotlib text() function.

Each item in the main list is a separate string to write.
render (boolean, optional) – If True, will render the scene before saving. If False, will use results of previous render if it exists. Default: True
tf_rect (sequence of floats, optional) – A rectangle that defines the location of the transfer function legend. This is only used for the case where there are multiple volume sources with associated transfer functions. tf_rect is of the form [x0, y0, width, height], in figure coordinates.

Return type:

Nothing

Examples

>>> sc.save_annotated(
...     "fig.png",
...     text_annotate=[
...         [
...             (0.05, 0.05),
...             f"t = {ds.current_time.d}",
...             dict(horizontalalignment="left"),
...         ],
...         [
...             (0.5, 0.95),
...             "simulation title",
...             dict(color="y", fontsize="24", horizontalalignment="center"),
...         ],
...     ],
... )

set_camera(camera)[source]¶: Set the camera to be used by this scene.

show(sigma_clip=None)[source]¶

This will send the most recently rendered image to the IPython notebook.

If yt is being run from within an IPython session, and it is able to determine this, this function will send the current image of this Scene to the notebook for display. If there is no current image, it will run the render() method on this Scene before sending the result to the notebook.

If yt can’t determine if it’s inside an IPython session, this will raise YTNotInsideNotebook.

Examples

>>> import yt
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

>>> sc = yt.create_scene(ds)
>>> sc.show()

property transparent_sources¶: Iterate over transparent RenderSource objects, returning a tuple of (key, source)

property unit_registry¶