yt.visualization.volume_rendering.transfer_functions module¶

class
yt.visualization.volume_rendering.transfer_functions.
ColorTransferFunction
(x_bounds, nbins=256, grey_opacity=False)[source]¶ Bases:
yt.visualization.volume_rendering.transfer_functions.MultiVariateTransferFunction
A complete set of transfer functions for standard colormapping.
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 channelbychannel 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) >>> mv.add_field_table(tf, 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{(xx_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 evenlyspaced 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://scipycookbook.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.
See also
ColorTransferFunction.sample_colormap()
Single Gaussian adder
Examples
>>> tf = ColorTransferFunction((10.0, 5.0)) >>> tf.add_layers(8)

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])

link_channels
(table_id, channels=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
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.add_field_table(tf, 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://scipycookbook.readthedocs.io/items/Matplotlib_Show_colormaps.html .
scale_func (function(
value
,minval
,maxval
), optional) – A userdefined 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.add_layers(8) >>> 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{(xx_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://scipycookbook.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.
See also
ColorTransferFunction.add_layers()
Manyatatime adder
Examples
>>> tf = ColorTransferFunction((10.0, 5.0)) >>> tf.sample_colormap(7.0, 0.01, colormap="arbre")

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, densityweighted emission that produces colors based on the temperature of the fluid.
 Parameters
grey_opacity (bool) – Should opacity be calculated on a channelbychannel 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) >>> mv.add_field_table(tf, 0)

link_channels
(table_id, channels=0)[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
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.add_field_table(tf, 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]¶ Bases:
yt.visualization.volume_rendering.transfer_functions.MultiVariateTransferFunction
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 unitfree, 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) >>> mv.add_field_table(tf, 0)

link_channels
(table_id, channels=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
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.add_field_table(tf, 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]¶ Bases:
yt.visualization.volume_rendering.transfer_functions.MultiVariateTransferFunction
A transfer function that defines a simple projection.
To generate an interpolated, offaxis 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) >>> mv.add_field_table(tf, 0)

link_channels
(table_id, channels=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
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.add_field_table(tf, 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_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{(xx_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 xvalues 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)

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")