AgaveRenderer

class agave_pyclient.agave.AgaveRenderer(url: str = 'ws://localhost:1235/', mode: str = 'pathtrace', agave_path: str | None = None, auto_launch: bool = True, launch_retries: int = 10, launch_retry_delay: float = 1.0)

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

• agave_path (Optional[str]) – Path to an AGAVE executable to launch if no running server is found. If None, a standard install location will be searched for via guess_agave_path(). Ignored when auto_launch is False.

• auto_launch (bool) – If True (default), and no AGAVE instance can be reached at url, attempt to launch one locally. If False, only connect to an already running instance and raise on failure.

• launch_retries (int) – Number of times to retry connecting after launching AGAVE.

• launch_retry_delay (float) – Seconds to wait between connection retries after launching AGAVE.

Examples

Connect to a running local AGAVE server, launching one if necessary:

>>> agaveclient = AgaveRenderer()

Connect only — do not auto-launch:

>>> agaveclient = AgaveRenderer(auto_launch=False)

Launch a specific AGAVE executable:

>>> agaveclient = AgaveRenderer(agave_path="/path/to/agave")

Notes

Connection precedence (highest to lowest):

1. An AGAVE server already listening at url is always used first, regardless of the other arguments. agave_path and auto_launch are ignored when the initial connect succeeds.

2. If no server responds and auto_launch is False, the connection error is re-raised immediately. agave_path is not consulted.

3. If no server responds and auto_launch is True, an AGAVE executable is located using:

   1. agave_path if explicitly provided, else

   2. guess_agave_path() (PATH, then standard install locations for the current OS).

   The executable is launched with --server --port=<port> where <port> is parsed from url, then the connection is retried up to launch_retries times spaced launch_retry_delay seconds apart.

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)

close() → None

Close the websocket and any AGAVE process started by this client.

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_data_and_get_info(path: str, scene: int = 0, multiresolution_level: int = 0, time: int = 0, channels: List[int] = [], region: List[int] = []) → dict

Load a volume and return the server’s metadata response as a dict.

Same arguments as load_data(), but this variant immediately flushes the command buffer to the server, waits for the JSON text frame the server sends back, and returns the parsed dictionary.

The returned dict contains at least the following keys (see LoadDataCommand::execute in renderlib/command.cpp):

• commandId : int, id of the LOAD_DATA command

• x, y, z, c, t : int, image extents

• pixel_size_x/y/z : float, physical voxel size

• channel_names : list[str]

• channel_min_intensity: list[int], one value per channel

• channel_max_intensity: list[int], one value per channel

• volume_dimensions : nested dict mirroring the C++ VolumeDimensions struct

Note: any other commands queued in the buffer prior to calling this method will be flushed at the same time.

Returns:

Parsed JSON metadata for the loaded volume.

Return type:

dict

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_plane(x: float, y: float, z: float, d: float)

Set the clip plane equation. The xyz vector must be normalized.

Parameters:

• x (float) – The x component of the normal

• y (float) – The y component of the normal

• z (float) – The z component of the normal

• d (float) – The distance from the origin

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_color_ramp(channel: int, name: str, data: List[float])

Set intensity thresholds based on a piecewise linear transfer function.

Parameters:

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

• name (str) – The name of the color ramp

• data (List[float]) – An array of values. 5 floats per control point. first is position (0-1), next four are rgba (all 0-1). Currently alpha will be ignored. To guarantee correct behavior, the first control point should be at 0.0 and the last at 1.0.

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_min_max_threshold(channel: int, min_val: int, max_val: int)

Set the minimum and maximum intensity thresholds for a channel.

Parameters:

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

• min_val (int) – The minimum intensity value.

• max_val (int) – The maximum intensity value.

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_skylight_rotation(x: float, y: float, z: float, w: float)

Set the orientation of the sphere (sky) light as a quaternion. The quaternion rotates the default direction (0, 0, 1) to the desired sky-light direction and also encodes the roll of the sphere around that direction, which determines where the top/middle/bottom color bands appear relative to the volume.

Parameters:

• x (float) – Quaternion x component.

• y (float) – Quaternion y component.

• z (float) – Quaternion z component.

• w (float) – Quaternion w component.

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_time_stamp_format(format: int)

Set the timestamp display format

Parameters:

format (int) – 0 for HH:MM:SS, 1 for time units

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

show_time_stamp(on: int)

Turn timestamp display on or off

Parameters:

on (int) – 0 to hide timestamps, 1 to show them

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