Skip to content

scene

ngtools.scene

A neuroglancer scene with a programmatic interface.

ViewerState

Bases: Wraps(ViewerState)

Smart ng.ViewerState that knows default values set in the frontend.

Attributes:

Name Type Description
title str, default=None

Window title
dimensions CoordinateSpace

All "global" dimensions.
relative_display_scales dict[str, float]

???
display_dimensions list[str]

The 2 or 3 dimensions that are displayed in the cross section. Their order matters, as they map to the red, green and blue axes.
position LinkedType[vector[float]]

Position in the "global frame". This vector must have as many values as there are dimensions.
velocity dict[str, DimensionPlaybackVelocity]

???
cross_section_orientation vector[float], default=(0, 0, 0, 1)

Orientation of the cross-sections in the "displayed global frame". It is a quaternion ordered as [i, j, k, r].
cross_section_scale float, default=1

Zoom level of the cross-sections.
cross_section_depth float

???
projection_scale float

Zoom level of the 3D window.
projection_depth float

???
projection_orientation vector[float], default=[0, 0, 0, 1]

Orientation of the 3D window in the "displayed global frame". It is a quaternion ordered as [i, j, k, r].
show_slices bool, default=True

Whether to display orthogonal cross sections in the 3D window.
wire_frame bool, default=False

Whether to display mesh wire frames in the 3D window.
enable_adaptive_downsampling bool, default=True

???
show_scale_bar bool, default=True

Whether to show the scale bar.
show_default_annotations bool, default=True

???
gpu_memory_limit int

Maximum GPU usage.
system_memory_limit int

Maximum CPU usage.
concurrent_downloads int

Maximum number of concurrent downloads.
prefetch bool, default=True

Prefetch chunks.
layers Layers

List of (named) registered layers.
layout StackLayout | LayerGroupViewer | DataPanelLayout | str

If a string, can be one of {"xy", "yz", "xz", "xy-3d", "yz-3d", "xz-3d", "4panel", "3d"}.
cross_section_background_color str, default="black"

Background color of cross-sections.
projection_background_color str, default="black"

Background color of 3D window.
selected_layer SelectedLayerState

With fields * layer : str, default=layers[0].name Selected layer * visible : bool, default=False Whether the right panel is visible. * size : int Width of the right panel, in voxels.
statistics StatisticsDisplayState

With fields * visible : bool, default=False Whether the statistics panel is visible. * size : int Height of the panel, in voxels.
help_panel HelpPanelState

With fields * visible : bool, default=False Whether the help panel is visible. * size : int Width of the panel, in voxels. * flex : float, default=1.0 Relative height of the panel.
layer_list_panel LayerListPanelState

With fields * visible : bool, default=False Whether the layer list panel is visible. * size : int Width of the panel, in voxels. * flex : float, default=1.0 Relative height of the panel.
partial_viewport vector[float], default=[0, 0, 1, 1]

Top-left and bottom-right corner of the visible portion of the viewer, where [0, 0, 1, 1] corresponds to the entire viewer.
tool_bindings dict[str, Tool | str]

User-specific key bindings.

spatial_dimensions property 

spatial_dimensions

All spatial dimensions (with meter-like unit).

time_dimensions property 

time_dimensions

All time dimensions (with second-like unit).

Scene 

Scene(*args, **kwargs)

Bases: ViewerState

A neuroglancer scene with a programmatic interface.

Other Parameters:

Name Type Description
stdout TextIO | str

Output stream.
stderr TextIO | str

Error stream.
level (debug, info, warning, error, any)

Level of printing. * If None: no printing * If "error": print errors * If "warning": print errors and warnings * If "info": print errors, warnings and infos * If "debug": print errors, warnings, infos and debug messages. * If "any: print any message.

spatial_dimensions property 

spatial_dimensions

All spatial dimensions (with meter-like unit).

time_dimensions property 

time_dimensions

All time dimensions (with second-like unit).

load 

load(uri=None, transform=None, shader=None, inv=False, **kwargs)

Load file(s).

Parameters:

Name Type Description Default
uri str | list[str] | dict[str, str]

Paths or URL, eventually prepended with "type" and "format" protocols. Ex: "labels://nifti://http://cloud.com/path/to/nii.gz" If a dictionary, maps layer names to file names.

 None
transform array_like | list[float] | str | None

Affine transform to apply to the loaded volume.

 None
inv bool

Invert the transform before applying it.

 False

Other Parameters:

Name Type Description
name str | list[str]

Alternative way of providing layer names. If used, uri cannot be a dict.

unload 

unload(layer=None)

Unload layers.

Parameters:

Name Type Description Default
layer str or list[str]

Layer(s) to unload

 None

rename 

rename(src, dst)

Rename a layer.

Parameters:

Name Type Description Default
src str

Current name

 required
dst str

New name

 required

world_axes 

world_axes(axes=None, **kwargs)

Map native model axes ("x", "y", "z", "t") to neuroanatomical or arbitrary names.

Parameters:

Name Type Description Default
axes dict[str, str] | list[str] | str | None

Mapping from native to user names. If None, simply return current mapping.

 None

Other Parameters:

Name Type Description
src str | list[str]

Native/New axes names. If used, axes cannot be used.
dst str | list[str]

Native/New axes names. If used, axes cannot be used.

Returns:

Name Type Description
axes dict[str, str]

Mapping from native to user names.

rename_axes 

rename_axes(axes=None, layer=None, **kwargs)

Rename world axes.

Parameters:

Name Type Description Default
axes str | list[str] | dict[str]

A dictionary that maps old names to new names, or a known neurospace (e.g., "xyz",["x", "y", "z"],"ras",["right", "anterior", "posterior"]`)

 None
layer str | list[str] | None

Layers to rename. By default, all.

 None

Other Parameters:

Name Type Description
src str | list[str]

Old/New axes names. If used, axes cannot be used.
dst str | list[str]

Old/New axes names. If used, axes cannot be used.

Returns:

Name Type Description
axes dict[str]

Mapping from old names to new names

space 

space(mode='radio', layer=None)

Rotate the view such that the cross-sections are aligned with the voxel axes of a layer. Also, switch between radiological and neurological orientation.

Parameters:

Name Type Description Default
mode Literal['radio', 'neuro']

Neurological (patient's point of view) or radiological (facing the patient) orientation.

 'radio'
layer str | None

Name of a layer or "world".

 None

display 

display(dimensions=None)

Change displayed dimensions and/or change neurospace.

Parameters:

Name Type Description Default
dimensions str or list[str]

The three dimensions to display. Each dimension can be one of:

  • "left" or "right"
  • "posterior" or "anterior"
  • "inferior" or "superior"

Otherwise, dimensions can be native axis names of the loaded data, such as "x", "y", "z".

A compact representation ("RAS", or "zyx") can also be provided.

 None

transform 

transform(transform=None, layer=None, inv=False, reset=False, *, mov=None, fix=None)

Apply an affine transform.

Parameters:

Name Type Description Default
transform list[float] or ndarray or fileobj

Affine transform (RAS+)

 None
layer str or list[str]

Layer(s) to transform

 None
inv bool

Invert the transform

 False
reset bool

Reset the default transform prior to applying the new transform.

 False

Other Parameters:

Name Type Description
mov str

Moving/Floating image (required by some affine formats)
fix str

Fixed/Reference image (required by some affine formats)

save_transform 

save_transform(output=None, layer=None, format=None)

Save transform from default space to current space.

Parameters:

Name Type Description Default
output [list of] str | None

Output filename(s).

 None
layer [list of] str | none

Layer(s) for which to save the transform(s).

 None
format str | None

Format hint.

 None

Returns:

Name Type Description
transform [list of] ng.CoordinateSpaceTransform

Estimated transform(s).

channel_mode 

channel_mode(mode, layer=None, dimension='c')

Change the mode (local or intensity) of an axis.

Parameters:

Name Type Description Default
mode (local, channel, 'global')

How to interpret this dimension:

  • "local": enables a switch/slider to change which channel is displayed (e.g., time).
  • "channel": enables the joint use of all channels to display a single intensity/color (e.g., RGB).
  • "global": enables the display of this axis in the cross-view.
 "local"
layer [list of] str

Names of layers to process

 None
dimension [list of] str

Names of dimensions to process

 'c'

move 

move(coord=0, dimensions=None, unit=None, absolute=False, **kwargs)

Change cursor position.

Parameters:

Name Type Description Default
coord [list of] float | dict[str, float]

New position. If a dictionary, maps axes to values.

 0
dimensions [list of] str

Axis of each coordinate. Can be a compact name like 'RAS'. Cannot be used when coord is a dict. Default: Currently displayed axes.

 None
unit str

Units of the coordinates. Default: Unit of current axes.

 None
absolute bool

Move to absolute position, rather than relative to current.

 False

Other Parameters:

Name Type Description
reset bool

Reset position to default

Returns:

Name Type Description
coord list[float]

Current cursor position.

zoom 

zoom(factor=2.0, reset=False)

Zoom by some factor.

Parameters:

Name Type Description Default
factor float

Zoom factor

 2.0
reset bool

Reset zoom level to default

 False

Returns:

Name Type Description
scale float

Current zoom level

unzoom 

unzoom(factor=2.0, reset=False)

Unzoom by some factor.

Parameters:

Name Type Description Default
factor float

Unzoom factor

 2.0
reset bool

Reset zoom level to default

 False

Returns:

Name Type Description
scale float

Current zoom level

shader 

shader(shader, layer=None, layer_type=None, **kwargs)

Apply a shader (that is, a colormap or lookup table).

Parameters:

Name Type Description Default
shader str

A known shader name (from ngtools.shaders), or some user-defined shader code, or a LUT file.

 required
layer str or list[str]

Apply the shader to these layers. Default: all layers.

 None
layer_type str or list[str]

Apply the shader to these layer types. Default: all layers.

 None

change_layout 

change_layout(layout=None, stack=None, layer=None, *, flex=1, append=None, assign=None, insert=None, remove=None)

Change layout.

Append/Assign/Insert/Remove

The requested (stack of) layout(s) can be inserted into existing layouts.

Arguments must be an integer or list of integer, that are used to navigate through the existing nested stacks of layouts.

Only one of {append, assign, insert, remove} can be used.

Parameters:

Name Type Description Default
layout [list of] {"xy", "yz", "xz", "xy-3d", "yz-3d", "xz-3d", "4panel", "3d"}

Layout(s) to set or insert. If list, stack must be set.

 None
stack (row, column)

Insert a stack of layouts. If input layout is a list and append is not used, default is "row".

 "row"
layer [list of] str

Set of layers to include in the layout. By default, all layers are included (even future ones).

 None

Other Parameters:

Name Type Description
flex float

???
append bool or [list of] int or str

Append the layout to an existing stack.
assign int or [list of] int or str

Assign the layout into an existing stack.
insert int or [list of] int or str

Insert the layout into an existing stack.
remove int or [list of] int or str

Remove the layout from an existing stack.

Returns:

Name Type Description
layout object

Current JSON layout

zorder 

zorder(layer, steps=None, **kwargs)

Move or reorder layers.

In neuroglancer, layers are listed in the order they are loaded, with the latest layer appearing on top of the other ones in the scene. Counter-intuitively, the latest/topmost layer is listed at the bottom of the layer list, while the earliest/bottommost layer is listed at the top of the layer list. In this function, we list layers in their expected z-order, top to bottom.

Parameters:

Name Type Description Default
layer str or list[str]

Name of layers to move. If steps=None, layers are given the provided order. Else, the selected layers are moved by steps steps.

 required
steps int

Number of steps to take. Positive steps move layers towards the top and negative steps move layers towards the bottom.

 None

state 

state(load=None, save=None, url=False, instance=None, print=True, **kwargs)

Print or save or load the viewer's JSON state.

Parameters:

Name Type Description Default
load str

Load state from JSON file, or JSON string (or URL if url=True).

 None
save str

Save state to JSON file

 None
url bool

Print/load/save a JSON URL rather than a JSON object

 False
instance (neuroglancer, linc)

Neuroglancer instance to use in the URL.

 "ng"
print bool

print the JSON object or URL

 True

Returns:

Name Type Description
state dict

JSON state

autolog 

autolog(func)

Decorate a function to automatically log its usage.