# yt.visualization.volume_rendering.transfer_functions module¶

class yt.visualization.volume_rendering.transfer_functions.ColorTransferFunction(x_bounds, nbins=256, grey_opacity=False)[source]

A complete set of transfer functions for standard color-mapping.

This is the best and easiest way to set up volume rendering. It creates field tables for all three colors, their alphas, and has support for sampling color maps and adding independent color values at all locations. It will correctly set up the MultiVariateTransferFunction.

Parameters
• x_bounds (tuple of floats) – The min and max for the transfer function. Values below or above these values are discarded.

• nbins (int) – How many bins to calculate; in between, linear interpolation is used, so low values are typically fine.

• grey_opacity (bool) – Should opacity be calculated on a channel-by-channel basis, or overall? Useful for opaque renderings.

add_field_table(table, field_id, weight_field_id=- 1, weight_table_id=- 1)

This accepts a table describing integration.

A “field table” is a tabulated set of values that govern the integration through a given field. These are defined not only by the transmission coefficient, interpolated from the table itself, but the field_id that describes which of several fields the integration coefficient is to be calculated from.

Parameters
• table (TransferFunction) – The integration table to be added to the set of tables used during the integration.

• field_id (int) – Each volume has an associated set of fields. This identifies which of those fields will be used to calculate the integration coefficient from this table.

• weight_field_id (int, optional) – If specified, the value of the field this identifies will be multiplied against the integration coefficient.

• weight_table_id (int, optional) – If specified, the value from the table this identifies will be multiplied against the integration coefficient.

Notes

This can be rather complicated. It’s recommended that if you are interested in manipulating this in detail that you examine the source code, specifically the function FIT_get_value in yt/_amr_utils/VolumeIntegrator.pyx.

Examples

This example shows how to link a new transfer function against field 0. Note that this by itself does not link a channel for integration against a field. This is because the weighting system does not mandate that all tables contribute to a channel, only that they contribute a value which may be used by other field tables.

>>> mv = MultiVariateTransferFunction()
>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-7.0, 0.01, 1.0)

add_gaussian(location, width, height)[source]

Add a Gaussian distribution to the transfer function.

Typically, when rendering isocontours, a Guassian distribution is the easiest way to draw out features. The spread provides a softness. The values are calculated as $$f(x) = h \exp{-(x-x_0)^2 / w}$$.

Parameters
• location (float) – The centroid of the Gaussian ($$x_0$$ in the above equation.)

• width (float) – The relative width ($$w$$ in the above equation.)

• height (list of 4 float) – The peak height ($$h$$ in the above equation.) Note that while values greater 1.0 will be accepted, the values of the transmission function are clipped at 1.0. This must be a list, and it is in the order of (red, green, blue, alpha).

Examples

This adds a red spike.

>>> tf = ColorTransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-9.0, 0.01, [1.0, 0.0, 0.0, 1.0])

add_layers(N, w=None, mi=None, ma=None, alpha=None, colormap='gist_stern', col_bounds=None)[source]

Add a set of Gaussians based on an existing colormap.

Constructing pleasing Gaussians in a transfer function can pose some challenges, so this function will add several evenly-spaced Gaussians whose colors are taken from a colormap scaled between the bounds of the transfer function. For each Gaussian to be added, ColorTransferFunction.sample_colormap is called.

Parameters
• N (int) – How many Gaussians to add

• w (float) – The relative width of each Gaussian. If not included, it is calculated as 0.001 * (max_val - min_val) / N

• mi (float, optional) – If only a subset of the data range is to have the Gaussians added, this is the minimum for that subset

• ma (float, optional) – If only a subset of the data range is to have the Gaussians added, this is the maximum for that subset

• alpha (list of floats, optional) – The alpha value height for each Gaussian. If not supplied, it is set as 1.0 everywhere.

• colormap (string, optional) – An acceptable colormap. See either yt.visualization.color_maps or https://scipy-cookbook.readthedocs.io/items/Matplotlib_Show_colormaps.html .

• col_bounds (array_like, optional) – Limits ([min, max]) the values over which the colormap spans to these values. Useful for sampling an entire colormap over a range smaller than the transfer function bounds.

Examples

>>> tf = ColorTransferFunction((-10.0, -5.0))

add_step(start, stop, value)[source]

Adds a step function to the transfer function.

This accepts a start and a stop, and then in between those points the transfer function is set to the maximum of the transfer function and the value.

Parameters
• start (float) – This is the beginning of the step function; must be within domain of the transfer function.

• stop (float) – This is the ending of the step function; must be within domain of the transfer function.

• value (list of 4 floats) – The value the transfer function will be set to between start and stop. Note that the transfer function will actually be set to max(y, value) where y is the existing value of the transfer function. This must be a list, and it is in the order of (red, green, blue, alpha).

Examples

This adds a step function that will produce a white value at > -6.0.

>>> tf = ColorTransferFunction((-10.0, -5.0))
>>> tf.add_step(-6.0, -5.0, [1.0, 1.0, 1.0, 1.0])

clear()[source]
get_colormap_image(height, width)[source]

Link an image channel to a field table.

Once a field table has been added, it can be linked against a channel (any one of the six – red, green, blue, red absorption, green absorption, blue absorption) and then the value calculated for that field table will be added to the integration for that channel. Not all tables must be linked against channels.

Parameters
• table_id (int) – The 0-indexed table to link.

• channels (int or list of ints) – The channel or channels to link with this table’s calculated value.

Examples

This example shows how to link a new transfer function against field 0, and then link that table against all three RGB channels. Typically an absorption (or ‘alpha’) channel is also linked.

>>> mv = MultiVariateTransferFunction()
>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-7.0, 0.01, 1.0)
>>> mv.link_channels(0, [0, 1, 2])

map_to_colormap(mi, ma, scale=1.0, colormap='gist_stern', scale_func=None)[source]

Map a range of values to a full colormap.

Given a minimum and maximum value in the TransferFunction, map a full colormap over that range at an alpha level of scale. Optionally specify a scale_func function that modifies the alpha as a function of the transfer function value.

Parameters
• mi (float) – The start of the TransferFunction to map the colormap

• ma (float) – The end of the TransferFunction to map the colormap

• scale (float, optional) – The alpha value to be used for the height of the transfer function. Larger values will be more opaque.

• colormap (string, optional) – An acceptable colormap. See either yt.visualization.color_maps or https://scipy-cookbook.readthedocs.io/items/Matplotlib_Show_colormaps.html .

• scale_func (function(value, minval, maxval), optional) – A user-defined function that can be used to scale the alpha channel as a function of the TransferFunction field values. Function maps value to somewhere between minval and maxval.

Examples

>>> def linramp(vals, minval, maxval):
...     return (vals - vals.min()) / (vals.max() - vals.min())
>>> tf = ColorTransferFunction((-10.0, -5.0))
>>> tf.map_to_colormap(-8.0, -6.0, scale=10.0, colormap="arbre")
>>> tf.map_to_colormap(
...     -6.0, -5.0, scale=10.0, colormap="arbre", scale_func=linramp
... )

plot(filename)[source]

Save an image file of the transfer function.

This function loads up matplotlib, plots all of the constituent transfer functions and saves.

Parameters

filename (string) – The file to save out the plot as.

Examples

>>> tf = ColorTransferFunction((-10.0, -5.0))
>>> tf.plot("sample.png")

sample_colormap(v, w, alpha=None, colormap='gist_stern', col_bounds=None)[source]

Add a Gaussian based on an existing colormap.

Constructing pleasing Gaussians in a transfer function can pose some challenges, so this function will add a single Gaussian whose colors are taken from a colormap scaled between the bounds of the transfer function. As with TransferFunction.add_gaussian, the value is calculated as $$f(x) = h \exp{-(x-x_0)^2 / w}$$ but with the height for each color calculated from the colormap.

Parameters
• v (float) – The value at which the Gaussian is to be added.

• w (float) – The relative width ($$w$$ in the above equation.)

• alpha (float, optional) – The alpha value height for the Gaussian

• colormap (string, optional) – An acceptable colormap. See either yt.visualization.color_maps or https://scipy-cookbook.readthedocs.io/items/Matplotlib_Show_colormaps.html .

• col_bounds (array_like, optional) – Limits ([min, max]) the values over which the colormap spans to these values. Useful for sampling an entire colormap over a range smaller than the transfer function bounds.

Examples

>>> tf = ColorTransferFunction((-10.0, -5.0))
>>> tf.sample_colormap(-7.0, 0.01, colormap="arbre")

show(ax=None)[source]

Display an image of the transfer function

This function loads up matplotlib and displays the current transfer function.

Examples

>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-9.0, 0.01, 1.0)
>>> tf.show()

vert_cbar(resolution, log_scale, ax, label=None, label_fmt=None)[source]

Display an image of the transfer function

This function loads up matplotlib and displays the current transfer function.

Examples

>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-9.0, 0.01, 1.0)
>>> tf.show()

class yt.visualization.volume_rendering.transfer_functions.MultiVariateTransferFunction(grey_opacity=False)[source]

Bases: object

This object constructs a set of field tables that allow for multiple field variables to control the integration through a volume.

The integration through a volume typically only utilizes a single field variable (for instance, Density) to set up and control the values returned at the end of the integration. For things like isocontours, this is fine. However, more complicated schema are possible by using this object. For instance, density-weighted emission that produces colors based on the temperature of the fluid.

Parameters

grey_opacity (bool) – Should opacity be calculated on a channel-by-channel basis, or overall? Useful for opaque renderings. Default: False

add_field_table(table, field_id, weight_field_id=- 1, weight_table_id=- 1)[source]

This accepts a table describing integration.

A “field table” is a tabulated set of values that govern the integration through a given field. These are defined not only by the transmission coefficient, interpolated from the table itself, but the field_id that describes which of several fields the integration coefficient is to be calculated from.

Parameters
• table (TransferFunction) – The integration table to be added to the set of tables used during the integration.

• field_id (int) – Each volume has an associated set of fields. This identifies which of those fields will be used to calculate the integration coefficient from this table.

• weight_field_id (int, optional) – If specified, the value of the field this identifies will be multiplied against the integration coefficient.

• weight_table_id (int, optional) – If specified, the value from the table this identifies will be multiplied against the integration coefficient.

Notes

This can be rather complicated. It’s recommended that if you are interested in manipulating this in detail that you examine the source code, specifically the function FIT_get_value in yt/_amr_utils/VolumeIntegrator.pyx.

Examples

This example shows how to link a new transfer function against field 0. Note that this by itself does not link a channel for integration against a field. This is because the weighting system does not mandate that all tables contribute to a channel, only that they contribute a value which may be used by other field tables.

>>> mv = MultiVariateTransferFunction()
>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-7.0, 0.01, 1.0)


Link an image channel to a field table.

Once a field table has been added, it can be linked against a channel (any one of the six – red, green, blue, red absorption, green absorption, blue absorption) and then the value calculated for that field table will be added to the integration for that channel. Not all tables must be linked against channels.

Parameters
• table_id (int) – The 0-indexed table to link.

• channels (int or list of ints) – The channel or channels to link with this table’s calculated value.

Examples

This example shows how to link a new transfer function against field 0, and then link that table against all three RGB channels. Typically an absorption (or ‘alpha’) channel is also linked.

>>> mv = MultiVariateTransferFunction()
>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-7.0, 0.01, 1.0)
>>> mv.link_channels(0, [0, 1, 2])

class yt.visualization.volume_rendering.transfer_functions.PlanckTransferFunction(T_bounds, rho_bounds, nbins=256, red='R', green='V', blue='B', anorm=1000000.0)[source]

This sets up a planck function for multivariate emission and absorption. We assume that the emission is black body, which is then convolved with appropriate Johnson filters for red, green and blue. T_bounds and rho_bounds define the limits of tabulated emission and absorption functions. anorm is a “fudge factor” that defines the somewhat arbitrary normalization to the scattering approximation: because everything is done largely unit-free, and is really not terribly accurate anyway, feel free to adjust this to change the relative amount of reddening. Maybe in some future version this will be unitful.

add_field_table(table, field_id, weight_field_id=- 1, weight_table_id=- 1)

This accepts a table describing integration.

A “field table” is a tabulated set of values that govern the integration through a given field. These are defined not only by the transmission coefficient, interpolated from the table itself, but the field_id that describes which of several fields the integration coefficient is to be calculated from.

Parameters
• table (TransferFunction) – The integration table to be added to the set of tables used during the integration.

• field_id (int) – Each volume has an associated set of fields. This identifies which of those fields will be used to calculate the integration coefficient from this table.

• weight_field_id (int, optional) – If specified, the value of the field this identifies will be multiplied against the integration coefficient.

• weight_table_id (int, optional) – If specified, the value from the table this identifies will be multiplied against the integration coefficient.

Notes

This can be rather complicated. It’s recommended that if you are interested in manipulating this in detail that you examine the source code, specifically the function FIT_get_value in yt/_amr_utils/VolumeIntegrator.pyx.

Examples

This example shows how to link a new transfer function against field 0. Note that this by itself does not link a channel for integration against a field. This is because the weighting system does not mandate that all tables contribute to a channel, only that they contribute a value which may be used by other field tables.

>>> mv = MultiVariateTransferFunction()
>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-7.0, 0.01, 1.0)


Link an image channel to a field table.

Once a field table has been added, it can be linked against a channel (any one of the six – red, green, blue, red absorption, green absorption, blue absorption) and then the value calculated for that field table will be added to the integration for that channel. Not all tables must be linked against channels.

Parameters
• table_id (int) – The 0-indexed table to link.

• channels (int or list of ints) – The channel or channels to link with this table’s calculated value.

Examples

This example shows how to link a new transfer function against field 0, and then link that table against all three RGB channels. Typically an absorption (or ‘alpha’) channel is also linked.

>>> mv = MultiVariateTransferFunction()
>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-7.0, 0.01, 1.0)
>>> mv.link_channels(0, [0, 1, 2])

class yt.visualization.volume_rendering.transfer_functions.ProjectionTransferFunction(x_bounds=- 1e+60, 1e+60, n_fields=1)[source]

A transfer function that defines a simple projection.

To generate an interpolated, off-axis projection through a dataset, this transfer function should be used. It will create a very simple table that merely sums along each ray. Note that the end product will need to be scaled by the total width through which the rays were cast, a piece of information inaccessible to the transfer function.

Parameters
• x_bounds (tuple of floats, optional) – If any of your values lie outside this range, they will be truncated.

• n_fields (int, optional) – How many fields we’re going to project and pass through

Notes

When you use this transfer function, you may need to explicitly disable logging of fields.

add_field_table(table, field_id, weight_field_id=- 1, weight_table_id=- 1)

This accepts a table describing integration.

A “field table” is a tabulated set of values that govern the integration through a given field. These are defined not only by the transmission coefficient, interpolated from the table itself, but the field_id that describes which of several fields the integration coefficient is to be calculated from.

Parameters
• table (TransferFunction) – The integration table to be added to the set of tables used during the integration.

• field_id (int) – Each volume has an associated set of fields. This identifies which of those fields will be used to calculate the integration coefficient from this table.

• weight_field_id (int, optional) – If specified, the value of the field this identifies will be multiplied against the integration coefficient.

• weight_table_id (int, optional) – If specified, the value from the table this identifies will be multiplied against the integration coefficient.

Notes

This can be rather complicated. It’s recommended that if you are interested in manipulating this in detail that you examine the source code, specifically the function FIT_get_value in yt/_amr_utils/VolumeIntegrator.pyx.

Examples

This example shows how to link a new transfer function against field 0. Note that this by itself does not link a channel for integration against a field. This is because the weighting system does not mandate that all tables contribute to a channel, only that they contribute a value which may be used by other field tables.

>>> mv = MultiVariateTransferFunction()
>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-7.0, 0.01, 1.0)


Link an image channel to a field table.

Once a field table has been added, it can be linked against a channel (any one of the six – red, green, blue, red absorption, green absorption, blue absorption) and then the value calculated for that field table will be added to the integration for that channel. Not all tables must be linked against channels.

Parameters
• table_id (int) – The 0-indexed table to link.

• channels (int or list of ints) – The channel or channels to link with this table’s calculated value.

Examples

This example shows how to link a new transfer function against field 0, and then link that table against all three RGB channels. Typically an absorption (or ‘alpha’) channel is also linked.

>>> mv = MultiVariateTransferFunction()
>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-7.0, 0.01, 1.0)
>>> mv.link_channels(0, [0, 1, 2])

class yt.visualization.volume_rendering.transfer_functions.TransferFunction(x_bounds, nbins=256)[source]

Bases: object

A transfer function governs the transmission of emission and absorption through a volume.

Transfer functions are defined by boundaries, bins, and the value that governs transmission through that bin. This is scaled between 0 and 1. When integrating through a volume the value through a given cell is defined by the value calculated in the transfer function.

Parameters
• x_bounds (tuple of floats) – The min and max for the transfer function. Values below or above these values are discarded.

• nbins (int) – How many bins to calculate; in between, linear interpolation is used, so low values are typically fine.

Notes

Typically, raw transfer functions are not generated unless particular and specific control over the integration is desired. Usually either color transfer functions, where the color values are calculated from color tables, or multivariate transfer functions are used.

add_filtered_planck(wavelength, trans)[source]
add_gaussian(location, width, height)[source]

Add a Gaussian distribution to the transfer function.

Typically, when rendering isocontours, a Gaussian distribution is the easiest way to draw out features. The spread provides a softness. The values are calculated as $$f(x) = h \exp{-(x-x_0)^2 / w}$$.

Parameters
• location (float) – The centroid of the Gaussian ($$x_0$$ in the above equation.)

• width (float) – The relative width ($$w$$ in the above equation.)

• height (float) – The peak height ($$h$$ in the above equation.) Note that while values greater 1.0 will be accepted, the values of the transmission function are clipped at 1.0.

Examples

>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-9.0, 0.01, 1.0)

add_line(start, stop)[source]

Add a line between two points to the transmission function.

This will accept a starting point in (x,y) and an ending point in (x,y) and set the values of the transmission function between those x-values to be along the line connecting the y values.

Parameters
• start (tuple of floats) – (x0, y0), the starting point. x0 is between the bounds of the transfer function and y0 must be between 0.0 and 1.0.

• stop (tuple of floats) – (x1, y1), the ending point. x1 is between the bounds of the transfer function and y1 must be between 0.0 and 1.0.

Examples

This will set the transfer function to be linear from 0.0 to 1.0, across the bounds of the function.

>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_line((-10.0, 0.0), (-5.0, 1.0))

add_step(start, stop, value)[source]

Adds a step function to the transfer function.

This accepts a start and a stop, and then in between those points the transfer function is set to the maximum of the transfer function and the value.

Parameters
• start (float) – This is the beginning of the step function; must be within domain of the transfer function.

• stop (float) – This is the ending of the step function; must be within domain of the transfer function.

• value (float) – The value the transfer function will be set to between start and stop. Note that the transfer function will actually be set to max(y, value) where y is the existing value of the transfer function.

Examples

Note that in this example, we have added a step function, but the Gaussian that already exists will “win” where it exceeds 0.5.

>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-7.0, 0.01, 1.0)
>>> tf.add_step(-8.0, -6.0, 0.5)

clear()[source]
plot(filename)[source]

Save an image file of the transfer function.

This function loads up matplotlib, plots the transfer function and saves.

Parameters

filename (string) – The file to save out the plot as.

Examples

>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-9.0, 0.01, 1.0)
>>> tf.plot("sample.png")

show()[source]

Display an image of the transfer function

This function loads up matplotlib and displays the current transfer function.

Examples

>>> tf = TransferFunction((-10.0, -5.0))
>>> tf.add_gaussian(-9.0, 0.01, 1.0)
>>> tf.show()