Skip to content

statebuilder.base

Classes:

NumpyEncoder

Bases: JSONEncoder

Custom JSON encoder that handles numpy and pandas types.

Converts numpy scalars, arrays, and pandas Series to native Python types for JSON serialization.

Methods:

  • default –

    Override default method to handle numpy types.

default(obj)

Override default method to handle numpy types.

Parameters:

  • obj (any) –

    Object to serialize

Returns:

  • any –

    JSON-serializable representation of the object

ViewerState(target_site=None, target_url=None, layers=None, dimensions=None, *, position=None, scale_imagery=None, scale_3d=None, show_slices=None, selected_layer=None, selected_layer_visible=True, layout=None, title=None, show_axis_lines=None, show_scale_bar=None, show_default_annotations=None, cross_section_background_color=None, projection_background_color=None, hide_cross_section_background_3d=None, wire_frame=None, camera=None, extra=None, base_state=None, interactive=False, infer_coordinates=True, client=None, capabilities=None)

Parameters:

  • target_site (str, default: None ) –

    The target site for the viewer. If None, the default site will be used.

  • target_url (str, default: None ) –

    The target URL for the viewer. If None, the default URL will be used.

  • layers (list of Layer, default: None ) –

    The layers to add to the viewer.

  • dimensions (list or CoordSpace, default: None ) –

    The dimensions of the viewer. If None, the default dimensions will be used.

  • position (list or ndarray, default: None ) –

    The position of the viewer in 3D space. If None, the default position will be used.

  • scale_imagery (float, default: None ) –

    The scale factor for imagery layers. Default is 1.0.

  • scale_3d (float, default: None ) –

    The scale factor for 3D projections. Default is 50000.0.

  • show_slices (bool, default: None ) –

    Whether to show cross-sectional slices in the viewer. Default is False.

  • selected_layer (str, default: None ) –

    The name of the selected layer, whose settings panel is shown. If None, no layer is selected.

  • selected_layer_visible (bool, default: True ) –

    Whether the selected layer's panel is open. Default is True.

  • layout (str, Panel, or StackLayout, default: None ) –

    The panel layout of the viewer: a preset (default "xy-3d"), or rows and columns of Panels showing different layers. See set_layout.

  • title (str, default: None ) –

    Title shown in the browser tab.

  • show_axis_lines (bool, default: None ) –

    Whether to draw the red/green/blue axis lines. Neuroglancer's default is True.

  • show_scale_bar (bool, default: None ) –

    Whether to draw the scale bar. Neuroglancer's default is True.

  • show_default_annotations (bool, default: None ) –

    Whether to draw the default annotations, such as the outline of the cross-section plane in the 3d view. Neuroglancer's default is True.

  • cross_section_background_color (str or tuple, default: None ) –

    Background color of the 2d views, as a name, hex string, or RGB (0-1 or 0-255).

  • projection_background_color (str or tuple, default: None ) –

    Background color of the 3d view, as a name, hex string, or RGB (0-1 or 0-255).

  • hide_cross_section_background_3d (bool, default: None ) –

    Whether to hide the background of the cross-section plane where it appears in the 3d view.

  • wire_frame (bool, default: None ) –

    Whether to render meshes as wire frames.

  • camera (Camera, default: None ) –

    Zoom, orientation, and depth for the 2d and 3d views. Its scales take precedence over scale_imagery and scale_3d. See set_camera.

  • extra (dict, default: None ) –

    Raw Neuroglancer state JSON (camelCase keys) for options nglui does not wrap, deep-merged over the built state last so it wins over anything nglui sets. A value of None removes that key. For example, {"gpuMemoryLimit": 2_000_000_000}.

  • base_state (dict, default: None ) –

    The base state of the viewer. If None, the default state will be used. When given, its values for scale_imagery, scale_3d, show_slices, and layout are kept unless those are set explicitly.

  • interactive (bool, default: False ) –

    Whether the viewer is interactive. Default is False.

  • infer_coordinates (bool, default: True ) –

    Whether to infer resolution and position from the source information using CloudVolume. Default is True.

  • client (CAVEclient, default: None ) –

    A CAVE client to use for configuration. If provided, it will be used by default in functions that can accept it.

  • capabilities (str or Capabilities, default: None ) –

    What the target Neuroglancer deployment supports, which determines how annotation tags are encoded. Either a Capabilities or an alias such as "main" or "legacy". If None, nglui probes the target site and falls back to the conservative default when it cannot tell.

Methods:

  • add_annotation_layer –

    Add an annotation layer, either local or with precomputed annotation source

  • add_annotation_source –

    Add a precomputed annotation source to the viewer.

  • add_boxes –

    Add bounding box annotations to an existing annotation layer or create a new one.

  • add_ellipsoids –

    Add ellipsoid annotations to an existing annotation layer or create a new one.

  • add_image_layer –

    Add an image layer to the viewer.

  • add_layer –

    Add a layer to the viewer.

  • add_layers_from_client –

    Configure the viewer with information from a CaveClient.

  • add_lines –

    Add lines to an existing annotation layer or create a new one.

  • add_points –

    Add points to an existing annotation layer or create a new one.

  • add_polylines –

    Add points to an existing annotation layer or create a new one.

  • add_raw_layer –

    Add a layer based on a raw state dictionary. Useful when copying existing layers, but offers limited customization.

  • add_segment_properties –

    Upload segment properties and add to the layer.

  • add_segmentation_layer –

    Add a segmentation layer to the viewer.

  • add_segments –

    Add segments directly to an existing segmentation layer.

  • add_segments_from_data –

    Add segments from a DataFrame or DataMap to an existing segmentation layer.

  • add_tool_palette –

    Add a tool palette, or update the placement of one with the same name.

  • add_tools –

    Bind tools to keys, and optionally show them in a tool palette.

  • get_layer –

    Get a layer by name.

  • map –

    Apply a datamap to the viewer state to freeze the state of the viewer.

  • set_camera –

    Set the zoom, orientation, and depth of the 2d and 3d views.

  • set_layout –

    Set the panel layout: a preset, or rows and columns of Panels.

  • set_panels –

    Open, close, or place Neuroglancer's side panels.

  • set_selected_layer –

    Select a layer, showing its settings in the selected-layer panel.

  • set_viewer_properties –

    Set various properties of the viewer state.

  • to_browser –

    Open the viewer state URL in a web browser.

  • to_clipboard –

    Copy the viewer state URL to the system clipboard.

  • to_dict –

    Return a dictionary representation of the viewer state.

  • to_json_string –

    Return a JSON string representation of the viewer state.

  • to_link –

    Return an HTML link representation of the viewer state.

  • to_link_shortener –

    Shorten the URL using the CAVE link shortener service.

  • to_url –

    Return a URL representation of the viewer state.

  • with_datamap –

    Context manager to apply datamaps.

Attributes:

camera property writable

The camera settings that have been set explicitly.

capabilities property writable

Capabilities of the target deployment, if explicitly set.

extra property writable

Raw Neuroglancer state JSON merged over the built state last.

Read-only; assign a new dict, or use set_viewer_properties(extra=...) to merge into it, so the cached state is rebuilt.

panels property

Side panel settings, keyed by panel name.

scale_3d property writable

Zoom of the 3d view; the camera's projection_scale.

scale_imagery property writable

Zoom of the 2d views; the camera's cross_section_scale.

tool_palettes property

Tool palettes, keyed by name.

tools property

Tools added with add_tools.

viewer property

Get the Neuroglancer viewer object.

add_annotation_layer(name='annotation', source=None, resolution=None, tags=None, linked_segmentation=True, shader=None, capabilities=None, **kwargs)

Add an annotation layer, either local or with precomputed annotation source

Parameters:

  • name (str, default: 'annotation' ) –

    Layer name, by default "annotation"

  • source (Optional[str], default: None ) –

    Cloud annotation source path, if using. By default None

  • resolution (Optional[Union[list, ndarray]], default: None ) –

    Layer resolution, only used by local annotation layers. By default None, where it is inferred from the viewer.

  • tags (Optional[list], default: None ) –

    Ordered list of tags, by default None.

  • linked_segmentation (Union[str, bool], default: True ) –

    If True, will link to the first segmentation layer found in the viewer. If False, will not link to any segmentation layer. If a string is provided, it will be used as the name of the segmentation layer to link to.

  • capabilities (str or Capabilities, default: None ) –

    Override how this layer's tags are encoded, regardless of what the viewer state resolved. See ViewerState for details.

  • **kwargs (dict, default: {} ) –

    Additional keyword arguments to pass to the annotation layer constructor.

Returns:

  • Self –

    The viewer state object with the added annotation layer.

add_annotation_source(source, name='annotation', linked_segmentation=True, shader=None)

Add a precomputed annotation source to the viewer.

Parameters:

  • source (str) –

    The source path for the annotation layer.

  • name (str, default: 'annotation' ) –

    The name of the annotation layer, by default "annotation".

  • shader (Optional[str], default: None ) –

    The shader to use for the annotation layer, by default None.

Returns:

  • Self –

    The viewer state object with the added annotation layer.

add_boxes(data=None, name='annotation', point_a_column=None, point_b_column=None, segment_column=None, description_column=None, tag_column=None, tag_bools=None, data_resolution=None, tags=None, linked_segmentation=True, shader=None, color=None, swap_visible_segments_on_move='auto', **layer_kwargs)

Add bounding box annotations to an existing annotation layer or create a new one.

Parameters:

  • data (DataFrame, default: None ) –

    The DataFrame containing the bounding box annotations.

  • name (str, default: 'annotation' ) –

    The name of the annotation layer, by default "annotation".

  • point_a_column (str, default: None ) –

    The column name for the start point coordinates of the box.

  • point_b_column (str, default: None ) –

    The column name for the end point coordinates of the box.

  • segment_column (Optional[str], default: None ) –

    The name of the column containing linked segment IDs, by default None.

  • description_column (Optional[str], default: None ) –

    The name of the column containing descriptions, by default None.

  • tag_column (Optional[str], default: None ) –

    The name of a column containing tags, by default None.

  • tag_bools (Optional[list], default: None ) –

    A list of column names indicating tags as booleans, by default None.

  • data_resolution (Optional[list], default: None ) –

    The resolution of the data, by default None.

  • tags (Optional[list], default: None ) –

    A list of tags to add to the annotation layer, by default None.

  • linked_segmentation (str or bool, default: True ) –

    The name of the segmentation layer to link to, by default None. If True, will link to the first segmentation layer found in the viewer. If False, will not link to any segmentation layer.

  • shader (Optional[str], default: None ) –

    The shader to use for the annotation layer, by default None.

  • color (Optional[str], default: None ) –

    The color to use for the bounding boxes, by default None.

  • swap_visible_segments_on_move (bool or 'auto', default: 'auto' ) –

    If True, will swap the visibility of segments when moving boxes. If "auto" (default), will swap only when segment_column is provided.

  • **layer_kwargs (Any, default: {} ) –

    Further options for the annotation layer when this call creates it, such as active_tool, shader_controls, filter_by_segmentation, tools, or extra. See AnnotationLayer. Passing any when the layer already exists raises, rather than silently ignoring them.

Returns:

  • Self –

    The viewer state object with the added bounding boxes.

add_ellipsoids(data=None, name='annotation', center_column=None, radii_column=None, segment_column=None, description_column=None, tag_column=None, tag_bools=None, data_resolution=None, tags=None, linked_segmentation=True, shader=None, color=None, swap_visible_segments_on_move='auto', **layer_kwargs)

Add ellipsoid annotations to an existing annotation layer or create a new one.

Parameters:

  • data (DataFrame, default: None ) –

    The DataFrame containing the ellipsoid annotations.

  • name (str, default: 'annotation' ) –

    The name of the annotation layer, by default "annotation".

  • center_column (str, default: None ) –

    The column name for the ellipsoid center coordinates.

  • radii_column (str, default: None ) –

    The column name for the ellipsoid radii.

  • segment_column (Optional[str], default: None ) –

    The name of the column containing linked segment IDs, by default None.

  • description_column (Optional[str], default: None ) –

    The name of the column containing descriptions, by default None.

  • tag_column (Optional[str], default: None ) –

    The name of a column containing tags, by default None.

  • tag_bools (Optional[list], default: None ) –

    A list of column names indicating tags as booleans, by default None.

  • data_resolution (Optional[list], default: None ) –

    The resolution of the data, by default None.

  • tags (Optional[list], default: None ) –

    A list of tags to add to the annotation layer, by default None.

  • linked_segmentation (str or bool, default: True ) –

    The name of the segmentation layer to link to, by default None. If True, will link to the first segmentation layer found in the viewer. If False, will not link to any segmentation layer.

  • shader (Optional[str], default: None ) –

    The shader to use for the annotation layer, by default None.

  • color (Optional[str], default: None ) –

    The color to use for the ellipsoids, by default None.

  • swap_visible_segments_on_move (bool or 'auto', default: 'auto' ) –

    If True, will swap the visibility of segments when moving ellipsoids. If "auto" (default), will swap only when segment_column is provided.

  • **layer_kwargs (Any, default: {} ) –

    Further options for the annotation layer when this call creates it, such as active_tool, shader_controls, filter_by_segmentation, tools, or extra. See AnnotationLayer. Passing any when the layer already exists raises, rather than silently ignoring them.

Returns:

  • Self –

    The viewer state object with the added ellipsoids.

add_image_layer(source, name='imagery', resolution=None, **kwargs)

Add an image layer to the viewer.

Parameters:

  • source (str) –

    The source path for the image layer.

  • name (str, default: 'imagery' ) –

    The name of the image layer, by default "imagery".

  • resolution (Optional[Union[list, ndarray]], default: None ) –

    The resolution of the image layer. If None, the viewer's current resolution will be used or it will be inferred from the source (if cloud-volume is installed).

  • **kwargs (dict, default: {} ) –

    Additional keyword arguments to pass to the image layer constructor.

add_layer(layers, selected=False)

Add a layer to the viewer.

Parameters:

  • layers (Layer or list of Layer) –

    The layer(s) to add to the viewer.

add_layers_from_client(client=None, imagery=True, segmentation=True, skeleton_source=True, resolution=True, target_url=False, selected_alpha=None, alpha_3d=None, mesh_silhouette=None, imagery_kws=None, segmentation_kws=None)

Configure the viewer with information from a CaveClient. Can set the target URL, viewer resolution, and add image and segmentation layers.

Parameters:

  • client (CAVEclient, default: None ) –

    The client to use for configuration. If None, will use the client set in the viewer state if allowed.

  • imagery (Union[bool, str], default: True ) –

    Whether to add an image layer, by default True. If a string is provided, it will be used as the name of the layer.

  • segmentation (Union[bool, str], default: True ) –

    Whether to add a segmentation layer, by default True If a string is provided, it will be used as the name of the layer.

  • skeleton_source (bool, default: True ) –

    Whether to try to add a skeleton source for the segmentation layer, if provided, by default True

  • resolution (bool, default: True ) –

    Whether to infer viewer resolution from the client info, by default True

  • target_url (bool, default: False ) –

    Whether to set the neuroglancer URL from the client, by default False

  • selected_alpha (Optional[float], default: None ) –

    The alpha value for the segmentation layer, by default None.

  • alpha_3d (Optional[float], default: None ) –

    The alpha value for 3D meshes, by default None.

  • mesh_silhouette (Optional[float], default: None ) –

    The mesh silhouette value, by default None.

  • imagery_kws (Optional[dict], default: None ) –

    Additional keyword arguments to pass to the image layer constructor.

  • segmentation_kws (Optional[dict], default: None ) –

    Additional keyword arguments to pass to the segmentation layer constructor.P

Returns:

  • Self –

    The updated viewer state object.

add_lines(data=None, name='annotation', point_a_column=None, point_b_column=None, segment_column=None, description_column=None, tag_column=None, tag_bools=None, data_resolution=None, tags=None, linked_segmentation=True, shader=None, color=None, swap_visible_segments_on_move='auto', **layer_kwargs)

Add lines to an existing annotation layer or create a new one.

Parameters:

  • data (DataFrame, default: None ) –

    The DataFrame containing the line annotations or a tuple of (start_points, end_points) as Nx3 arrays.

  • name (str, default: 'annotation' ) –

    The name of the annotation layer, by default "annotation".

  • point_a_column (str, default: None ) –

    The column name for the start point coordinates. If you have a split point representation in the format {prefix}_x, {prefix}_y, {prefix}_z, you can specify this with "prefix" only and the suffixes will be ignored. If you provide a list, they will be used explicitly as the x,y, and z columns.

  • point_b_column (str, default: None ) –

    The column name for the end point coordinates, formatted similarly as point_a_column.

  • segment_column (Optional[str], default: None ) –

    The name of the column containing linked segment IDs, by default None.

  • description_column (Optional[str], default: None ) –

    The name of the column containing descriptions, by default None.

  • tag_column (Optional[str], default: None ) –

    The name of a column containing tags, by default None.

  • tag_bools (Optional[list], default: None ) –

    A list of column names indicating tags as booleans, by default None.

  • data_resolution (Optional[list], default: None ) –

    The resolution of the data, by default None.

  • tags (Optional[list], default: None ) –

    A list of tags to add to the annotation layer, by default None.

  • linked_segmentation (str or bool, default: True ) –

    The name of the segmentation layer to link to, by default None. If True, will link to the first segmentation layer found in the viewer. If False, will not link to any segmentation layer.

  • shader (Optional[str], default: None ) –

    The shader to use for the annotation layer, by default None.

  • color (Optional[str], default: None ) –

    The color to use for the lines, by default None.

  • swap_visible_segments_on_move (bool or 'auto', default: 'auto' ) –

    If True, will swap the visibility of segments when moving lines. If "auto" (default), will swap only when segment_column is provided.

  • **layer_kwargs (Any, default: {} ) –

    Further options for the annotation layer when this call creates it, such as active_tool, shader_controls, filter_by_segmentation, tools, or extra. See AnnotationLayer. Passing any when the layer already exists raises, rather than silently ignoring them.

Returns:

  • Self –

    The viewer state object with the added lines.

add_points(data=None, name='annotation', point_column=None, segment_column=None, description_column=None, tag_column=None, tag_bools=None, data_resolution=None, tags=None, linked_segmentation=True, shader=None, color=None, swap_visible_segments_on_move='auto', **layer_kwargs)

Add points to an existing annotation layer or create a new one.

Parameters:

  • data (Union[list, ndarray, DataFrame], default: None ) –

    The data to add to the annotation layer.

  • name (str, default: 'annotation' ) –

    The name of the annotation layer, by default "annotation".

  • point_column (Optional[Union[str, list]] = None,, default: None ) –

    The name of the column containing point coordinates, by default None. If you have a split point representation in the format {prefix}_x, {prefix}_y, {prefix}_z, you can specify this with "prefix" only and the suffixes will be ignored. If you provide a list, they will be used explicitly as the x,y, and z columns. None is needed if the data is an array, but is required if the data is a DataFrame.

  • segment_column (Optional[str], default: None ) –

    The name of the column containing linked segment IDs, by default None.

  • description_column (Optional[str], default: None ) –

    The name of the column containing descriptions, by default None. If None, no descriptions will be added.

  • tag_column (Optional[str], default: None ) –

    The name of a column containing tags, by default None.

  • tag_bools (Optional[list], default: None ) –

    A list of column names indicating tags as booleans, by default None.

  • data_resolution (Optional[list], default: None ) –

    The resolution of the data, by default None. If None, the viewer's current resolution will be used.

  • tags (Optional[list], default: None ) –

    A list of tags to add to the annotation layer, by default None. If None, tags will be inferred from the data, if any tag columns are provided.

  • linked_segmentation (str or bool, default: True ) –

    The name of the segmentation layer to link to, by default None. If True, will link to the first segmentation layer found in the viewer. If False, will not link to any segmentation layer.

  • shader (Optional[str], default: None ) –

    The shader to use for the annotation layer, by default None. If None, the default shader will be used.

  • swap_visible_segments_on_move (Union[bool, Literal['auto']], default: 'auto' ) –

    If True, will swap the visibility of segments when moving points. If "auto" (default), will swap only when segment_column is provided.

  • **layer_kwargs (Any, default: {} ) –

    Further options for the annotation layer when this call creates it, such as active_tool, shader_controls, filter_by_segmentation, tools, or extra. See AnnotationLayer. Passing any when the layer already exists raises, rather than silently ignoring them.

Returns:

  • Self –

    The viewer state object with the added points.

add_polylines(data=None, name='annotation', points_column=None, segment_column=None, description_column=None, tag_column=None, tag_bools=None, data_resolution=None, tags=None, linked_segmentation=True, shader=None, color=None, swap_visible_segments_on_move='auto', **layer_kwargs)

Add points to an existing annotation layer or create a new one.

Parameters:

  • data (Union[list, ndarray, DataFrame], default: None ) –

    The data to add to the annotation layer.

  • name (str, default: 'annotation' ) –

    The name of the annotation layer, by default "annotation".

  • points_column (Optional[Union[str, list]] = None,, default: None ) –

    The name of the column containing lists of point coordinates, by default None. None is needed if the data is an array, but is required if the data is a DataFrame. Because the data is a list of 3d points, this cannot be a split prefix.

  • segment_column (Optional[str], default: None ) –

    The name of the column containing linked segment IDs, by default None.

  • description_column (Optional[str], default: None ) –

    The name of the column containing descriptions, by default None. If None, no descriptions will be added.

  • tag_column (Optional[str], default: None ) –

    The name of a column containing tags, by default None.

  • tag_bools (Optional[list], default: None ) –

    A list of column names indicating tags as booleans, by default None.

  • data_resolution (Optional[list], default: None ) –

    The resolution of the data, by default None. If None, the viewer's current resolution will be used.

  • tags (Optional[list], default: None ) –

    A list of tags to add to the annotation layer, by default None. If None, tags will be inferred from the data, if any tag columns are provided.

  • linked_segmentation (str or bool, default: True ) –

    The name of the segmentation layer to link to, by default None. If True, will link to the first segmentation layer found in the viewer. If False, will not link to any segmentation layer.

  • shader (Optional[str], default: None ) –

    The shader to use for the annotation layer, by default None. If None, the default shader will be used.

  • swap_visible_segments_on_move (Union[bool, Literal['auto']], default: 'auto' ) –

    If True, will swap the visibility of segments when moving points. If "auto" (default), will swap only when segment_column is provided.

  • **layer_kwargs (Any, default: {} ) –

    Further options for the annotation layer when this call creates it, such as active_tool, shader_controls, filter_by_segmentation, tools, or extra. See AnnotationLayer. Passing any when the layer already exists raises, rather than silently ignoring them.

Returns:

  • Self –

    The viewer state object with the added points.

add_raw_layer(data, name=None, visible=None, archived=None, source_remap=None)

Add a layer based on a raw state dictionary. Useful when copying existing layers, but offers limited customization.

Parameters:

  • data (dict) –

    The raw state dictionary for the layer.

  • name (str, default: None ) –

    The new name of the layer, if you want to change it.

  • visible (bool, default: None ) –

    Whether the layer is visible, if you want to change it.

  • archived (bool, default: None ) –

    Whether the layer is archived, if you want to change it.

  • source_remap (Optional[dict], default: None ) –

    A dictionary mapping source cloudpaths to new cloudpaths, for example to update the layer's data source without changing anything else.

Returns:

  • Self –

    The updated viewer state object.

add_segment_properties(data, id_column='pt_root_id', client=None, label_column=None, description_column=None, string_columns=None, number_columns=None, tag_value_columns=None, tag_bool_columns=None, tag_descriptions=None, allow_disambiguation=True, label_separator='_', label_format_map=None, prepend_col_name=False, random_columns=None, random_column_prefix=None, dry_run=False, name=None)

Upload segment properties and add to the layer. If you already have a segment properties cloud path, use add_source to add it to the layer.

Parameters:

  • data (DataFrame) –

    The DataFrame containing the segment properties.

  • id_column (str, default: 'pt_root_id' ) –

    The column name for the segment IDs. Default is 'pt_root_id'.

  • client (CAVEclient, default: None ) –

    The CAVEclient object needed to upload .

  • label_column (str or list, default: None ) –

    The column name(s) for the segment labels. Default is None.

  • description_column (str, default: None ) –

    The column name for the segment descriptions. Default is None.

  • string_columns (list, default: None ) –

    The column names for string properties. Default is None.

  • number_columns (list, default: None ) –

    The column names for number properties. Default is None.

  • tag_value_columns (list, default: None ) –

    The column names for tag value properties. Default is None.

  • tag_bool_columns (list, default: None ) –

    The column names for tag boolean properties. Default is None.

  • tag_descriptions (list, default: None ) –

    The descriptions for the tags. Default is None.

  • allow_disambiguation (bool, default: True ) –

    Whether to allow disambiguation of segment IDs. Default is True.

  • label_separator (str, default: '_' ) –

    The separator for label formatting. Default is "_".

  • label_format_map (str, default: None ) –

    The format map for labels. Default is None.

  • prepend_col_name (bool, default: False ) –

    Whether to prepend the column name to the label. Default is False.

  • random_columns (Optional[int], default: None ) –

    Number of random columns to add. Default is None.

  • random_column_prefix (str, default: None ) –

    Name prefix of the random columns. Default is None.

  • dry_run (bool, default: False ) –

    If dry run is true, build but do not actually upload and instead use a placeholder source text. Default is False.

  • name (Optional[str], default: None ) –

    Layer name. Must be specified if there is more than one segmentation layer in the state.

Returns:

  • Self –

add_segmentation_layer(source, name='segmentation', resolution=None, segments=None, **kwargs)

Add a segmentation layer to the viewer.

Parameters:

  • source (str) –

    The source path for the segmentation layer.

  • name (str, default: 'segmentation' ) –

    The name of the segmentation layer, by default "segmentation".

  • resolution (Optional[Union[list, ndarray]], default: None ) –

    The resolution of the segmentation layer. If None, the viewer's current resolution will be used or it will be inferred from the source (if cloud-volume is installed).

  • segments (Optional[list], default: None ) –

    A list of segments to set as selected in the segmentation layer.

  • **kwargs (dict, default: {} ) –

    Additional keyword arguments to pass to the segmentation layer constructor.

add_segments(segments, visible=None, segment_colors=None, name=None)

Add segments directly to an existing segmentation layer. By default, it will use the first segmentation layer found in the viewer, otherwise you must specify a layer name.

Parameters:

  • segments (list or dict or VisibleSegments) –

    The segments to add. If a dict, the keys are the segment IDs and the values are the boolean visibility.

  • visible (Optional[Union[list, ndarray]], default: None ) –

    The visibility of the segments, assumed to be True if not provided. Should be the same length as segments, and segments should be a list of the same length.

  • segment_colors (Union[str, list, dict], default: None ) –

    The color(s) to assign to the segments. If a string or list, all segments will be assigned the same color. A list is assumed to be a color tuple. If a dict, the keys are segment IDs and the values are colors.

  • name (Optional[str], default: None ) –

    The name of the segmentation layer to add segments to. If None, it will use the first segmentation layer found in the viewer.

Returns:

  • The viewer state object with the added segments. –

add_segments_from_data(data, segment_column, visible_column=None, color_column=None, name=None)

Add segments from a DataFrame or DataMap to an existing segmentation layer. By default, it will use the first segmentation layer found in the viewer, otherwise you must specify a layer name.

Parameters:

  • data (Union[DataFrame, DataMap]) –

    The data containing segment information or a datamap to be filled in later

  • segment_column (str) –

    The name of the column containing segment IDs in the DataFrame.

  • visible_column (str, default: None ) –

    The name of the column containing visibility information in the DataFrame. If not provided, all segments will be considered visible.

  • color_column (str, default: None ) –

    The name of the column containing color information for the segments.

  • name (Optional[str], default: None ) –

    The name of the segmentation layer to add segments to. If None, it will use the first segmentation layer found in the viewer.

add_tool_palette(palette)

Add a tool palette, or update the placement of one with the same name.

Tools listed in palette are shown in it but not bound to keys; use add_tools to bind them as well.

Parameters:

Returns:

add_tools(*tools, palette=None)

Bind tools to keys, and optionally show them in a tool palette.

Keys are allocated across the whole viewer when the state is built, since Neuroglancer has one key namespace for every layer: a tool's explicit key must be free, and tools with key=None get the next free letter.

Parameters:

  • *tools (Tool, default: () ) –

    Tools from nglui.statebuilder.tools. Layer tools need layer set, as a layer name or object. Use key=False for a palette-only tool.

  • palette (str or ToolPalette, default: None ) –

    A palette to also show these tools in, by name or as a ToolPalette for placement. Tools are added to an existing palette of that name.

Returns:

Examples:

>>> from nglui.statebuilder import tools
>>> vs.add_tools(
...     tools.SelectSegments(layer="seg", key="S"),
...     tools.MeshSilhouette(layer="seg"),
...     palette=tools.ToolPalette("Review", side="right"),
... )

get_layer(name)

Get a layer by name.

Parameters:

  • name (str) –

    The name of the layer to get.

Returns:

  • Layer –

    The layer with the specified name.

map(datamap, inplace=False)

Apply a datamap to the viewer state to freeze the state of the viewer. Must be used if any layers use a datamap. By default, this will return a new viewer state with the datamap applied without changing the current object.

Parameters:

  • datamap (dict) –

    A dictionary mapping layer names to their corresponding datamaps.

  • inplace (bool, default: False ) –

    If True, apply the datamap in place and return the modified viewer state. If False, return a new viewer state with the datamap applied.

Returns:

  • Self –

    A new ViewerState object with the datamap applied.

set_camera(camera=None, *, cross_section_scale=None, cross_section_orientation=None, cross_section_depth=None, projection_scale=None, projection_orientation=None, projection_depth=None)

Set the zoom, orientation, and depth of the 2d and 3d views.

Only the values given are changed; the rest keep their current settings.

Parameters:

  • camera (Camera, default: None ) –

    A camera whose set fields are applied, for reusing one view across states.

  • cross_section_scale (float, default: None ) –

    Zoom of the 2d views. Same as scale_imagery.

  • cross_section_orientation (str or sequence of float, default: None ) –

    Orientation of the 2d views, as a plane name ("xy", "xz", "yz") or an [x, y, z, w] quaternion.

  • cross_section_depth (float, default: None ) –

    Depth of field of the 2d views.

  • projection_scale (float, default: None ) –

    Zoom of the 3d view. Same as scale_3d.

  • projection_orientation (str or sequence of float, default: None ) –

    Orientation of the 3d view, as a plane name or quaternion.

  • projection_depth (float, default: None ) –

    Depth of the 3d view's clipping volume.

Returns:

Examples:

>>> vs.set_camera(projection_orientation="xz", projection_scale=5000)

set_layout(layout)

Set the panel layout: a preset, or rows and columns of Panels.

Parameters:

  • layout (str, Panel, or StackLayout) –

    A preset such as "xy-3d" or "4panel", which shows every layer in every view; or a Panel or row/column of panels, each showing its own layers with its own view type and optionally its own camera.

Returns:

Examples:

>>> from nglui.statebuilder import Panel, row
>>> vs.set_layout(row(Panel([img, seg], layout="xy"), Panel([seg], layout="3d")))

set_panels(*, layer_list_panel=None, statistics_panel=None, help_panel=None, selected_layer_panel=None)

Open, close, or place Neuroglancer's side panels.

Each panel takes a SidePanel, a dict of its fields, or a bool as shorthand for SidePanel(visible=...). Only the panels and fields given are changed.

Parameters:

  • layer_list_panel (bool, SidePanel, or dict, default: None ) –

    The panel listing all layers.

  • statistics_panel (bool, SidePanel, or dict, default: None ) –

    The chunk-download statistics panel.

  • help_panel (bool, SidePanel, or dict, default: None ) –

    The keyboard and mouse bindings help panel.

  • selected_layer_panel (bool, SidePanel, or dict, default: None ) –

    The panel for the selected layer's settings. Which layer it shows is set with set_selected_layer; visible here takes precedence over it.

Returns:

Examples:

>>> vs.set_panels(
...     layer_list_panel=True,
...     selected_layer_panel=SidePanel(side="right", size=500),
... )

set_selected_layer(selected_layer, visible=True)

Select a layer, showing its settings in the selected-layer panel.

Parameters:

  • selected_layer (str or Layer) –

    The layer, by name or object.

  • visible (bool, default: True ) –

    Whether the panel is open. Default is True. Place the panel with set_panels(selected_layer_panel=SidePanel(...)).

Returns:

set_viewer_properties(position=None, dimensions=None, scale_imagery=None, scale_3d=None, show_slices=None, selected_layer=None, selected_layer_visible=None, layout=None, title=None, show_axis_lines=None, show_scale_bar=None, show_default_annotations=None, cross_section_background_color=None, projection_background_color=None, hide_cross_section_background_3d=None, wire_frame=None, camera=None, extra=None, base_state=None, interactive=None, infer_coordinates=None)

Set various properties of the viewer state.

This function allows you to configure the viewer's position, dimensions, scale, layout, and other properties. Any property not explicitly set will remain unchanged.

Parameters:

  • position (list or ndarray, default: None ) –

    The position of the viewer in 3D space.

  • dimensions (list or ndarray, default: None ) –

    The dimensions of the viewer's coordinate space. Can be either a list of 3 values treated as nanometer resolution or a CoordSpace object with more detailed options.

  • scale_imagery (float, default: None ) –

    The scale factor for imagery layers.

  • scale_3d (float, default: None ) –

    The scale factor for 3D projections.

  • show_slices (bool, default: None ) –

    Whether to show cross-sectional slices in the viewer.

  • selected_layer (str or ImageLayer, default: None ) –

    The name of the selected layer or the layer object itself.

  • selected_layer_visible (bool, default: None ) –

    Whether the selected layer is visible.

  • layout (str, Panel, or StackLayout, default: None ) –

    The panel layout of the viewer; see set_layout.

  • title (optional, default: None ) –

    Presentation options; see the ViewerState constructor.

  • show_axis_lines (optional, default: None ) –

    Presentation options; see the ViewerState constructor.

  • show_scale_bar (optional, default: None ) –

    Presentation options; see the ViewerState constructor.

  • show_default_annotations (optional, default: None ) –

    Presentation options; see the ViewerState constructor.

  • cross_section_background_color (optional, default: None ) –

    Background colors; see the ViewerState constructor.

  • projection_background_color (optional, default: None ) –

    Background colors; see the ViewerState constructor.

  • hide_cross_section_background_3d (bool, default: None ) –

    Presentation options; see the ViewerState constructor.

  • wire_frame (bool, default: None ) –

    Presentation options; see the ViewerState constructor.

  • camera (Camera, default: None ) –

    Camera settings to apply; see set_camera.

  • extra (dict, default: None ) –

    Raw Neuroglancer state JSON, deep-merged into any existing extra.

  • base_state (dict, default: None ) –

    The base state of the viewer.

  • interactive (bool, default: None ) –

    Whether the viewer is interactive.

  • infer_coordinates (bool, default: None ) –

    Whether to infer resolution and position from the source information. If True, the viewer will attempt to extract this information from the info provided by the source if not provided explicitly.

Returns:

  • self –

    The updated viewer state object.

to_browser(target_url=None, target_site=None, shorten=False, client=None, new=2, autoraise=True, browser=None)

Open the viewer state URL in a web browser.

Parameters:

  • target_url (str, default: None ) –

    The base URL to use for the Neuroglancer state. If not provided, the default server URL will be used.

  • target_site (str, default: None ) –

    The target site for the URL, based on the keys in site_utils.NEUROGLANCER_SITES. If not provided, the default server URL will be used.

  • shorten (Union[bool, Literal['if_long']], default: False ) –

    If True, the URL will be shortened using the CAVE link shortener service. If "if_long", the URL will only be shortened if it exceeds a certain length.

  • client (Optional[CAVEclient], default: None ) –

    The CAVE client to use for shortening the URL. If not provided, the URL will not be shortened.

  • new (int, default: 2 ) –

    If new is 0, the url is opened in the same browser window if possible. If new is 1, a new browser window is opened if possible. If new is 2, a new browser page (“tab”) is opened if possible. Note that not all browsers support all values of new, and some may ignore this parameter.

  • autoraise (bool, default: True ) –

    If True, the browser window will be raised to the front when opened. Note that under many window managers this will occur regardless of the setting of this variable.

  • browser (Optional[str], default: None ) –

    The name of the browser to use. If None, the system default browser will be used. Note that the browser name needs to be registered on your system, see webbrowser.register for more details.

See Also

webbrowser.open : Opens a URL in the web browser.

Returns:

  • str –

    The URL representation of the viewer state that has also been opened in the browser.

to_clipboard(target_url=None, target_site=None, shorten=False, client=None)

Copy the viewer state URL to the system clipboard.

Parameters:

  • target_url (str, default: None ) –

    The base URL to use for the Neuroglancer state. If not provided, the default server URL will be used.

  • target_site (str, default: None ) –

    The target site for the URL, based on the keys in site_utils.NEUROGLANCER_SITES. If not provided, the default server URL will be used.

  • shorten (Union[bool, Literal['if_long']], default: False ) –

    If True, the URL will be shortened using the CAVE link shortener service. If "if_long", the URL will only be shortened if it exceeds a certain length.

  • client (Optional[CAVEclient], default: None ) –

    The CAVE client to use for shortening the URL. If not provided, the URL will not be shortened.

Returns:

  • str –

    The URL representation of the viewer state that has also been copied to the clipboard.

to_dict()

Return a dictionary representation of the viewer state.

Returns:

  • dict –

    A dictionary representation of the viewer state.

to_json_string(indent=2, compact=False)

Return a JSON string representation of the viewer state.

Parameters:

  • indent (int, default: 2 ) –

    The number of spaces to use for indentation in the JSON string. Default is 2.

  • compact (bool, default: False ) –

    If True, the JSON string will be compact with no extra whitespace or newlines. Default is False.

Returns:

  • str –

    A JSON string representation of the viewer state.

Return an HTML link representation of the viewer state.

Parameters:

  • target_url (str, default: None ) –

    The base URL to use for the Neuroglancer state. If not provided, the default server URL will be used.

  • target_site (str, default: None ) –

    The target site for the URL, based on the keys in site_utils.NEUROGLANCER_SITES. If not provided, the default server URL will be used.

  • link_text (str, default: 'Neuroglancer Link' ) –

    The text to display for the HTML link.

  • shorten (Union[bool, Literal['if_long']], default: False ) –

    If True, the URL will be shortened using the CAVE link shortener service. If "if_long", the URL will only be shortened if it exceeds a certain length.

  • client (Optional[CAVEclient], default: None ) –

    The CAVE client to use for shortening the URL. If not provided, the URL will not be shortened.

Returns:

  • HTML –

    An HTML link representation of the viewer state.

Shorten the URL using the CAVE link shortener service.

Parameters:

  • client (CAVEclient, default: None ) –

    The CAVE client to use for shortening the URL.

  • target_url (str, default: None ) –

    The base URL to use for the Neuroglancer state. If not provided, the default server URL will be used.

  • target_site (str, default: None ) –

    The target site for the URL, based on the keys in site_utils.NEUROGLANCER_SITES. If not provided, the default server URL will be used.

Returns:

  • str –

    A shortened URL representation of the viewer state.

to_url(target_url=None, target_site=None, shorten=False, client=None)

Return a URL representation of the viewer state.

Parameters:

  • target_url (str, default: None ) –

    The base URL to use for the Neuroglancer state. If not provided, the default server URL will be used.

  • target_site (str, default: None ) –

    The target site for the URL, based on the keys in site_utils.NEUROGLANCER . If not provided, the default server URL will be used.

  • shorten (Union[bool, Literal['if_long']], default: False ) –

    If True, the URL will be shortened using the CAVE link shortener service. If "if_long", the URL will only be shortened if it exceeds a certain length.

  • client (Optional[CAVEclient], default: None ) –

    The CAVE client to use for shortening the URL. If not provided, the URL will not be shortened.

Returns:

  • str –

    A URL representation of the viewer state.

with_datamap(datamap)

Context manager to apply datamaps.