AgaveRenderer

class agave_pyclient.agave.AgaveRenderer(url='ws://localhost:1235/', mode='pathtrace')

AgaveRenderer communicates with AGAVE running in server mode to perform GPU volume rendering.

Parameters:

• url (str) – Full url to websocket server including port

• mode (str) – “pathtrace” or “raymarch” (pathtrace is default)

Examples

Connect to an already running local AGAVE server instance

>>> agaveclient = AgaveRenderer()

aperture(x: float)

Set the viewer camera aperture size.

Parameters:

x (float) – The aperture size. This is a number between 0 and 1. 0 means no defocusing will occur, like a pinhole camera. 1 means maximum defocus. Default is 0.

asset_path(name: str)

Sets a search path for volume files. NOT YET IMPLEMENTED.

Parameters:

name (str) – This name is the path where volume images are located.

auto_threshold(channel: int, method: int)

Automatically determine the intensity thresholds

Parameters:

• channel (int) – Which channel index, 0 based.

• method (int) – Allowed values: 0: Auto2 1: Auto 2: BestFit 3: ChimeraX emulation 4: between 0.5 percentile and 0.98 percentile

background_color(r: float, g: float, b: float)

Set the background color of the rendering

Parameters:

• r (float) – The red value between 0 and 1

• g (float) – The green value between 0 and 1

• b (float) – The blue value between 0 and 1

batch_render_rocker(number_of_frames=90, angle=30, direction=1, output_name='frame', first_frame=0)

Loop to render a rocker sequence, an oscillating partial rotation about the vertical axis. Other commands must have been previously issued to load the data and set all the viewing parameters.

Parameters:

• number_of_frames (int) – How many images to generate

• angle (float) – Max angle to rock back and forth, in degrees

• direction (int) – rotate to the left or to the right

• output_name (str) – a full path prefix. The file names will have the frame numbers automatically appended

• first_frame (int) – an offset for the frame indices in the saved file names

batch_render_turntable(number_of_frames=90, direction=1, output_name='frame', first_frame=0)

Loop to render a turntable sequence, a 360 degree rotation about the vertical axis. Other commands must have been previously issued to load the data and set all the viewing parameters.

Parameters:

• number_of_frames (int) – How many images to generate

• direction (int) – rotate to the left or to the right, +1 or -1

• output_name (str) – a full path prefix. The file names will have the frame numbers automatically appended

• first_frame (int) – an offset for the frame indices in the saved file names

bounding_box_color(r: float, g: float, b: float)

Set the color for the bounding box display

Parameters:

• r (float) – the red value, from 0 to 1

• g (float) – the green value, from 0 to 1

• b (float) – the blue value, from 0 to 1

camera_projection(projection_type: int, x: float)

Set the viewer camera projection type, along with a relevant parameter.

Parameters:

• projection_type (int) – 0 for Perspective, 1 for Orthographic. Default: 0

• x (float) – If Perspective, then this is the vertical Field of View angle in degrees. If Orthographic, then this is the orthographic scale dimension. Default: 55.0 degrees. (default Orthographic scale is 0.5)

density(x: float)

Set the scattering density.

Parameters:

x (float) – The scattering density, 0-100. Higher values will make the volume seem more opaque. Default is 8.5, which is relatively transparent.

enable_channel(channel: int, enabled: int)

Show or hide a given channel

Parameters:

• channel (int) – Which channel index, 0 based.

• enabled (int) – 0 to hide, 1 to show

exposure(x: float)

Set the exposure level

Parameters:

x (float) – The exposure level between 0 and 1. Default is 0.75. Higher numbers are brighter.

eye(x: float, y: float, z: float)

Set the viewer camera position. Default is (500,500,500).

Parameters:

• x (float) – The x coordinate

• y (float) – The y coordinate

• z (float) – The z coordinate

focaldist(x: float)

Set the viewer camera focal distance

Parameters:

x (float) – The focal distance. Has no effect if aperture is 0.

frame_scene()

Automatically set camera parameters so that the volume fills the view. Useful when you have insufficient information to position the camera accurately.

light_color(index: int, r: float, g: float, b: float)

Set the color of an area light. Overdrive the values higher than 1 to increase the light’s intensity.

Parameters:

• index (int) – Which light to set. Currently unused as there is only one area light.

• r (float) – The red value between 0 and 1

• g (float) – The green value between 0 and 1

• b (float) – The blue value between 0 and 1

light_pos(index: int, r: float, theta: float, phi: float)

Set the position of an area light, in spherical coordinates

Parameters:

• index (int) – Which light to set. Currently unused as there is only one area light.

• r (float) – The radius, as distance from the center of the volume

• theta (float) – The polar angle

• phi (float) – The azimuthal angle

light_size(index: int, x: float, y: float)

Set the size dimensions of a rectangular area light.

Parameters:

• index (int) – Which light to set. Currently unused as there is only one area light.

• x (float) – The width dimension of the area light

• y (float) – The height dimension of the area light

load_data(path: str, scene: int = 0, multiresolution_level: int = 0, time: int = 0, channels: List[int] = [], region: List[int] = [])

Completely specify volume data to load

Parameters:

• path (str) – URL or directory or file path to the data. The path must be locally accessible from the AGAVE server.

• scene (int) – zero-based index to select the scene, for multi-scene files. Defaults to 0

• multiresolution_level (int) – zero-based index to select the multiresolution level. Defaults to 0

• time (int) – zero-based index to select the time sample. Defaults to 0

• channels (List[int]) – zero-based indices to select the channels. Defaults to all channels

• region (List[int]) – 6 integers specifying the region to load. Defaults to the entire volume. Any list length other than 0 or 6 is an error.

load_ome_tif(name: str)

DEPRECATED. Use load_data

load_volume_from_file(path: str, scene: int, time: int)

DEPRECATED. Use load_data

mat_diffuse(channel: int, r: float, g: float, b: float, a: float)

Set the diffuse color of a channel

Parameters:

• channel (int) – Which channel index, 0 based.

• r (float) – The red value between 0 and 1

• g (float) – The green value between 0 and 1

• b (float) – The blue value between 0 and 1

• a (float) – The alpha value between 0 and 1 (currently unused)

mat_emissive(channel: int, r: float, g: float, b: float, a: float)

Set the emissive color of a channel (defaults to black, for no emission)

Parameters:

• channel (int) – Which channel index, 0 based.

• r (float) – The red value between 0 and 1

• g (float) – The green value between 0 and 1

• b (float) – The blue value between 0 and 1

• a (float) – The alpha value between 0 and 1 (currently unused)

mat_glossiness(channel: int, glossiness: float)

Set the channel’s glossiness.

Parameters:

• channel (int) – Which channel index, 0 based.

• glossiness (float) – Sets the shininess, a number between 0 and 100.

mat_opacity(channel: int, opacity: float)

Set channel opacity. This is a multiplier against all intensity values in the channel.

Parameters:

• channel (int) – Which channel index, 0 based.

• opacity (float) – A multiplier between 0 and 1. Default is 1

mat_specular(channel: int, r: float, g: float, b: float, a: float)

Set the specular color of a channel (defaults to black, for no specular response)

Parameters:

• channel (int) – Which channel index, 0 based.

• r (float) – The red value between 0 and 1

• g (float) – The green value between 0 and 1

• b (float) – The blue value between 0 and 1

• a (float) – The alpha value between 0 and 1 (currently unused)

orbit_camera(theta: float, phi: float)

Rotate the camera around the volume by angle deltas

Parameters:

• theta (float) – polar angle in degrees

• phi (float) – azimuthal angle in degrees

redraw()

Tell the server to process all commands and return an image, and then save the image. This function will block and wait for the image to be returned. The image returned will be saved automatically using the session_name. TODO: a timeout is not yet implemented.

render_iterations(x: int)

Set the number of paths per pixel to accumulate.

Parameters:

x (int) – How many paths per pixel. The more paths, the less noise in the image.

session(name: str)

Set the current session name. Use the full path to the name of the output image here.

Parameters:

name (str) – This name is the full path to the output image, ending in .png or .jpg. Make sure the directory has already been created.

set_clip_region(minx: float, maxx: float, miny: float, maxy: float, minz: float, maxz: float)

Set the axis aligned region of interest of the volume. All axis values are relative, where 0 is one extent of the volume and 1 is the opposite extent. For example, (0,1, 0,1, 0,0.5) will select the lower half of the volume’s z slices.

Parameters:

• minx (float) – The lower x extent between 0 and 1

• maxx (float) – The higher x extent between 0 and 1

• miny (float) – The lower y extent between 0 and 1

• maxy (float) – The higher y extent between 0 and 1

• minz (float) – The lower z extent between 0 and 1

• maxz (float) – The higher z extent between 0 and 1

set_control_points(channel: int, data: List[float])

Set intensity thresholds based on a piecewise linear transfer function.

Parameters:

• channel (int) – Which channel index, 0 based.

• data (List[float]) – An array of values. 5 floats per control point. first is position (0-1), next four are rgba (all 0-1). Only alpha is currently used as the remapped intensity value. All others are linearly interpolated.

set_flip_axis(x: int, y: int, z: int)

Flip the volume data on any axis

Parameters:

• x (int) – -1 to flip, 1 to not flip

• y (int) – -1 to flip, 1 to not flip

• z (int) – -1 to flip, 1 to not flip

set_interpolation(x: int)

Set the volume sampling interpolation mode

Parameters:

x (int) – 0 for nearest, 1 for linear

set_isovalue_threshold(channel: int, isovalue: float, isorange: float)

Set intensity thresholds based on values around an isovalue.

Parameters:

• channel (int) – Which channel index, 0 based.

• isovalue (float) – The value to center at maximum intensity, between 0 and 1

• isorange (float) – A range around the isovalue to keep at constant intensity, between 0 and 1. Typically small, to select for a single isovalue.

set_percentile_threshold(channel: int, pct_low: float, pct_high: float)

Set intensity thresholds based on percentiles of pixels to clip min and max intensity

Parameters:

• channel (int) – Which channel index, 0 based.

• pct_low (float) – The low percentile to remap to 0(min) intensity

• pct_high (float) – The high percentile to remap to 1(max) intensity

set_primary_ray_step_size(step_size: float)

Set primary ray step size. This is an accuracy versus speed tradeoff. Low values are more accurate. High values will render faster. Primary rays are the rays that are cast from the camera out into the volume.

Parameters:

step_size (float) – A value in voxels. Default is 4. Minimum sensible value is 1.

set_resolution(x: int, y: int)

Set the image resolution in pixels.

Parameters:

• x (int) – x resolution in pixels

• y (int) – y resolution in pixels

set_secondary_ray_step_size(step_size: float)

Set secondary ray step size. This is an accuracy versus speed tradeoff. Low values are more accurate. High values will render faster. The secondary rays are rays which are cast toward lights after they have scattered within the volume.

Parameters:

step_size (float) – A value in voxels. Default is 4. Minimum sensible value is 1.

set_time(time: int)

Load a time from the current volume file

Parameters:

time (int) – zero-based index to select the time sample. Defaults to 0

set_voxel_scale(x: float, y: float, z: float)

Set the relative scale of the pixels in the volume. Typically this is filled in with the physical pixel dimensions from the microscope metadata. Often the x and y scale will differ from the z scale. Defaults to (1,1,1)

Parameters:

• x (float) – x scale

• y (float) – y scale

• z (float) – z scale

set_window_level(channel: int, window: float, level: float)

Set intensity threshold for a given channel based on Window/Level

Parameters:

• channel (int) – Which channel index, 0 based.

• window (float) – Width of the window, from 0-1.

• level (float) – Intensity level mapped to middle of window, from 0-1

show_bounding_box(on: int)

Turn bounding box display on or off

Parameters:

on (int) – 0 to hide bounding box, 1 to show it

show_scale_bar(on: int)

Turn scale bar display on or off

Parameters:

on (int) – 0 to hide scale bar, 1 to show it

skylight_bottom_color(r: float, g: float, b: float)

Set the “south pole” color of the sky sphere

Parameters:

• r (float) – The red value between 0 and 1

• g (float) – The green value between 0 and 1

• b (float) – The blue value between 0 and 1

skylight_middle_color(r: float, g: float, b: float)

Set the “equator” color of the sky sphere

Parameters:

• r (float) – The red value between 0 and 1

• g (float) – The green value between 0 and 1

• b (float) – The blue value between 0 and 1

skylight_top_color(r: float, g: float, b: float)

Set the “north pole” color of the sky sphere

Parameters:

• r (float) – The red value between 0 and 1

• g (float) – The green value between 0 and 1

• b (float) – The blue value between 0 and 1

stream_mode(x: int)

Turn stream mode on or off. Stream mode will send an image back to the client on each iteration up to some server-defined amount. This mode is useful for interactive client-server applications but not for batch-mode offline rendering.

Parameters:

x (int) – 0 for off, 1 for on. Default is off.

target(x: float, y: float, z: float)

Set the viewer target position. This is a point toward which we are looking. Default is (0,0,0).

Parameters:

• x (float) – The x coordinate

• y (float) – The y coordinate

• z (float) – The z coordinate

trackball_camera(theta: float, phi: float)

Rotate the camera around the volume by angle deltas

Parameters:

• theta (float) – vertical screen angle in degrees

• phi (float) – horizontal screen angle in degrees

up(x: float, y: float, z: float)

Set the viewer camera up direction. This is a vector which should be nearly perpendicular to the view direction (target-eye), and defines the “roll” amount for the camera. Default is (0,0,1).

Parameters:

• x (float) – The x coordinate

• y (float) – The y coordinate

• z (float) – The z coordinate