Tools#

The tools the viewer offers an agent, with the descriptions the agent is given. Each is one of the viewer’s actions, the same method the window and Python call, so load here is Viewer.load in Python. The arguments are sent as JSON: enums as their text ("volumes"), positions as lists of numbers in world coordinates (mm, RAS+), and items by the ids scene gives. Paths are on the computer the viewer runs on.

add_mask(item_id, mask_id, role='include')

Adds a mask to the regions a tractogram’s streamlines are filtered by.

With the filter on (OptionName.REGION_FILTER, on by default), only the streamlines that pass through every include region, through no exclude region and stay within every within region are drawn; a point is inside a mask when it lies in a voxel whose value rounds to a non-zero integer. A streamline passes through a region when one of its points is inside it, and stays within it when all of them are. The subset and the points per streamline then apply to the streamlines kept.

Parameters:

  • item_id – The tractogram’s id.

  • mask_id – The mask: a volume or an overlay with one volume, on any grid, one of item_choices.

  • role – RegionRole.INCLUDE to keep the streamlines that pass through it, EXCLUDE to drop them, WITHIN to keep only those that stay within it.

Raises:

  • ValueError – If there is no item with either id.

  • TypeError – If role is not a RegionRole.

  • OptionError – If the item is not a tractogram or the mask is not one it can be filtered by.

add_sphere(item_id, radius, centre=None, role='include')

Adds a sphere to the regions a tractogram’s streamlines are filtered by.

As add_mask; a point is inside the sphere when it is at most radius from the centre.

Parameters:

  • item_id – The tractogram’s id.

  • radius – The sphere’s radius in mm, positive.

  • centre – Its centre in world coordinates, mm; the cursor if None.

  • role – RegionRole.INCLUDE to keep the streamlines that pass through it, EXCLUDE to drop them, WITHIN to keep only those that stay within it.

Raises:

  • ValueError – If there is no item with that id.

  • OptionError – If the item is not a tractogram, the centre or the radius is not a finite number, or the radius is not positive.

clear_regions(item_id)

Removes every region a tractogram is filtered by, so all are drawn.

Parameters:

item_id – The tractogram.

Raises:
data_choices(item_id, name)

The names an option that names some of an item’s data can take.

For OptionName.COLOUR_BY: the surface’s values per vertex, one number per vertex each, such as “curv” or “thickness”.

Parameters:

  • item_id – The item whose option it is.

  • name – An option that names some of the item’s data.

Returns:

The names, in the data’s order; None, for no data, is always allowed.

Raises:

  • TypeError – If item_id or name is of the wrong type.

  • ValueError – If there is no item with that id.

  • OptionError – If the item has no such option, or it names no data.

item_choices(item_id, name)

The items an option that names an item can name, for one item.

For OptionName.MODULATE: the other volumes and overlays that are 3D and on the same grid (shape and affine) as the item. For OptionName.VALUES_VOLUME, and the masks a tractogram is filtered by (INCLUDE_MASKS, EXCLUDE_MASKS, WITHIN_MASKS): the volumes and overlays with one volume (3D, or 4D with a single volume), on any grid.

Parameters:

  • item_id – The item whose option it is.

  • name – An option that names an item, such as OptionName.MODULATE.

Returns:

The items, in Layers order.

Raises:

  • TypeError – If item_id or name is of the wrong type.

  • ValueError – If there is no item with that id.

  • OptionError – If the item has no such option, or it names no item.

kept_streamlines(item_id)

How many of a tractogram’s streamlines its regions keep.

Counted over the streamlines loaded, before the subset is taken.

Parameters:

item_id – The tractogram.

Returns:

The number of streamlines kept.

Raises:
labels(item_id)

The labels in an overlay’s shown volume, as a parcellation holds them.

The surfaces of the 3D view are chosen among these (SURFACE_LABELS).

Parameters:

item_id – An overlay’s id.

Returns:

The values other than 0 in the volume at the overlay’s volume index, in scaled units rounded to whole numbers, sorted; none for an image with more distinct values than a parcellation can show (8192).

Raises:

ValueError – If there is no item with that id, or it is not an overlay.

load(path, category, max_streamlines=1000000, transforms=None, reference=None, inverse=False, interpolation=None, format=None, warp_type=None, fsl_input_path=None, fsl_reference_path=None)

Reads a file into a new item of category, as add adds it.

The file is read before the method returns. Volumes, overlays, FODs and peaks are NIfTI (.nii, .nii.gz) or MRtrix (.mif, .mif.gz, .mih) images; tractograms are TCK, TRK or VTK files; surfaces are GIfTI (.gii) or FreeSurfer surfaces (such as lh.white). For a FreeSurfer surface, lh.curv in its folder is read as its values “curv”, and ../label/lh.cortex.label as its cortex, when they exist.

Parameters:

  • path – The file to read.

  • category – Where the item goes: Category.VOLUMES, OVERLAYS (masks, maps, parcellations), TRACTOGRAMS, FODS, PEAKS (from lar peaks) or SURFACES.

  • max_streamlines – A tractogram with more streamlines keeps a random subset of this size; the same file always gives the same subset. None keeps all. Ignored for images.

  • transforms – Bring the item into another space through a registration computed by ANTs, FSL or MRtrix3: its transform files, listed as antsApplyTransforms lists them (an affine, a warp, or a warp and the inverse warp its tool wrote as “warp,inverse_warp”). The files are those that resample an image into the reference space; tractograms and surfaces are brought into the same space. FODs cannot be brought through a registration. None loads the file as it is.

  • reference – With transforms: an image of the reference space, whose grid images are resampled onto (needed for images).

  • inverse – With transforms: go the other way, from the reference space into the space the transforms bring images from.

  • interpolation – With transforms, for images: “nearest”, “linear” or “cubic”; None is linear for volumes and nearest for overlays and peaks (whose directions are reoriented).

  • format – With transforms: the tool that wrote them, “ants”, “fsl” or “mrtrix”; None guesses from the files (a 4D NIfTI warp can be FSL’s or MRtrix3’s, so it needs format).

  • warp_type – With transforms: the warp fields’ type, “deformation” (the default) or “displacement” for MRtrix3, “relative” (the default) or “absolute” for FSL; checked against the fields’ values.

  • fsl_input_path – With FSL transforms: the input image of the FLIRT or FNIRT run; defaults to the item when it is an image (to the reference with inverse). Tractograms and surfaces need it.

  • fsl_reference_path – With FSL transforms: the run’s reference image; defaults to reference (to the item with inverse). Tractograms and surfaces need it with inverse.

Returns:

The new item; its id names it in the other actions.

Raises:

  • TypeError – If category is not a Category.

  • ValueError – If the file’s extension is not one the category reads, the file cannot be read as that format, an FOD’s number of coefficients fits no SH layout, or the registration cannot be applied (a transform file it cannot read, an image without a reference, an FOD).

  • OSError – If the file cannot be opened.

load_matlab(path, preset, reference=None, variables=None, tractogram_id=None, max_streamlines=1000000)

Reads what a MATLAB .mat file holds into new items, as chosen.

The presets read MRIToolkit’s results. TENSOR_FIT (a DTI or DKI fit) adds FA, MD and the eigenvalues as volumes, the first eigenvector as a volume with DTI colours modulated by the FA, and the DWI. FOD_FIT (a GRL or mFOD result) adds its FODs (SH, MRtrix basis) and its fractions and residuals as volumes. TRACTOGRAPHY adds the tracts as a tractogram. MANUAL reads the variables named in variables (paths as in read_matlab, such as “FA”, “DT{1}” or “GRL_Results.FOD”) each as its LoadAs: an image (MRIToolkit’s layout) as a volume, overlay, FODs or peaks; a cell of (N, 3) points as a tractogram; a struct with vertices and faces as a surface; or a cell of one value per point as the values tractogram_id is coloured by. A choice that does not fit its variable’s shape is refused. The file is read before the method returns; sessions reopen the items from the same variables.

Parameters:

  • path – The .mat file.

  • preset – MatlabPreset.TENSOR_FIT, FOD_FIT, TRACTOGRAPHY or MANUAL.

  • reference – The grid of files that store none (FOD results, tracts, and images of files without a header): the MRIToolkit fit (.mat) they came from, or a NIfTI or MIF file of its image.

  • variables – For MANUAL, what to read each variable as.

  • tractogram_id – The tractogram item coloured by a variable read as LoadAs.POINT_VALUES.

  • max_streamlines – As in load.

Returns:

The new items, in the order added.

Raises:

  • ValueError – If the preset does not fit the file, a reference is needed and not given, or a variable cannot be read as chosen.

  • OSError – If a file cannot be opened.

load_session(path, max_streamlines=1000000)

Replaces the scene with the one a session file holds.

Each file is looked for at its path from the session file’s folder, then at its absolute path, and read before the method returns, as load reads it. A file that is missing or cannot be read, and an option or a view-state field that is no longer allowed, are reported (and logged), and the rest of the session still opens.

Parameters:

  • path – A session file written by save_session.

  • max_streamlines – A tractogram with more streamlines keeps a random subset of this size, as in load; None keeps all.

Returns:

The items opened and the problems met, one sentence each.

Raises:

  • SessionError – If the file is not a session, or was saved by a newer Larmor; the scene is then unchanged.

  • OSError – If the session file cannot be read.

move_cursor(position)

Moves the cursor, and so the crosshair and the slices, to a position.

Parameters:

position – The world position (x, y, z) in mm, RAS+. It may lie outside the images.

Raises:

ValueError – If position is not three finite numbers.

pan(view, right, up)

Moves what a 2D view shows, as a drag does.

Parameters:

  • view – ViewKind.AXIAL, CORONAL or SAGITTAL.

  • right – How far the view’s centre moves towards the screen’s right, in mm (negative: left).

  • up – How far it moves towards the screen’s top, in mm (negative: down).

Raises:

  • TypeError – If view is not a ViewKind.

  • ValueError – If view is the 3D view, or right or up is not a finite number.

readout()

What the crosshair reports, as the 2D views show it.

Returns:

The cursor’s position (mm, RAS+) and, with a main volume, its name, the nearest voxel (i, j, k, with the volume index for a 4D image) and the value there in scaled units, interpolated if the volume is shown interpolated; voxel and value are None outside its grid.

record_rotation(path, size=[800, 800], scale=1.0, speed=30.0, duration=12.0, fps=30, overlay=None, transparent=False)

Records the 3D view turning, off screen, as an animated WebP or GIF.

The scene turns about the screen’s up axis, starting from the 3D view’s camera, which is left as it is: with a window open, its 3D view does not move. The frames are written as they are drawn, so a long video of large frames does not fill the memory (a GIF keeps each frame as 8-bit colour until the end).

Parameters:

  • path – The file to write: .webp or .gif. An existing file is replaced once the video is complete, and kept if it is cancelled.

  • size – The 3D view’s width and height in logical pixels.

  • scale – Pixels per logical pixel in the frames.

  • speed – Degrees the scene turns per second, towards the screen’s right; negative turns it to the left.

  • duration – Seconds of video; the default, at the default speed, is one full turn.

  • fps – Frames per second, a whole number; a GIF takes at most 50 (it stores frame times in hundredths of a second, so at 30 its frames last 30 or 40 ms, 33.3 ms on average).

  • overlay – Whether to draw the information overlay; None follows toggle_overlay’s switch.

  • transparent – Whether the background is transparent; needs WebP.

  • on_progress – Called after each frame with the number of frames drawn and their total, for example to show progress; it returns True to go on, or False to cancel.

Returns:

The path written, or None if on_progress cancelled the video.

Raises:

  • ViewerUnavailableError – If the viewer’s dependencies are not installed.

  • TypeError – If overlay or transparent is not a bool, speed or duration is not a real number, or fps is not a whole number.

  • ValueError – If size or scale is not positive, the frames are larger than the GPU draws, the extension is neither .webp nor .gif (or is .gif with a transparent background or fps above 50), speed is not finite, duration is not positive, or fps is not positive.

  • OSError – If the file cannot be written.

remove(target)

Removes an item, or every item of a category.

When the main volume is removed, the next volume in Layers order becomes the main volume, and is shown if the removed one was. The views keep their field of view.

Parameters:

target – An item’s id, or a Category to remove all its items.

Raises:

  • TypeError – If target is neither an item id nor a Category.

  • ValueError – If there is no item with that id.

reset_camera(view)

Shows a view’s whole field of view again, at zoom 1 and centred.

The 3D view also returns to its starting direction.

Parameters:

view – The view to reset.

Raises:

TypeError – If view is not a ViewKind.

rotate_camera(right, up)

Turns the 3D view’s scene, as a drag in that view does.

The turn is about the camera’s own axes, so it never locks up when looking straight down.

Parameters:

  • right – Degrees to turn the scene towards the screen’s right (about the screen’s up axis).

  • up – Degrees to turn it towards the screen’s top (about the screen’s right axis).

Raises:

ValueError – If right or up is not a finite number.

save_session(path)

Saves the items and the state of the views to a session file.

The file is JSON (.lar.json is the usual extension). It holds each item’s category, name, file (its absolute path and its path from the session file’s folder, so a project folder can be moved) and options, and the view state: cursor, cameras, main volume, selection, maximised view, convention and the overlay and crosshair switches. The application’s settings are not saved. Items added from Python without a file cannot be saved and are left out, with a warning in the log.

Parameters:

path – The session file to write; an existing file is replaced.

Returns:

The names of the items left out, in Layers order.

Raises:

  • OSError – If the file cannot be written.

  • ValueError – If an option holds a value JSON cannot store, such as an infinite number.

scene()

The items in the scene, in Layers order (id, category, name, source file, number of volumes, value range and options), and the state of the views (cursor, main volume, selection, cameras, …). Other tools name items by these ids.

screenshot(view, path, size=[800, 800], scale=1.0, overlay=None, transparent=False)

Draws one view, or all of them, off screen, as the window shows them.

Needs no window and no Qt, only the viewer’s drawing library (pygfx) and a GPU or a software renderer. With a window open, the image is drawn separately, at the given size, and the window is not changed. To draw many images of one scene, an OffscreenRenderer (in larmor.viewer.render.offscreen) is faster: it is set up once.

Parameters:

  • view – The view to draw, or None for the whole window’s layout: the maximised view if there is one, else the four views in the window’s 2 x 2 grid (axial, coronal; sagittal, 3D), with a thin grey line between them.

  • path – The image file to write; its extension sets the format (.png, .jpg, .tif, …). An existing file is replaced.

  • size – Each view’s width and height in logical pixels, the units of the window’s views; text and lines keep their size in them.

  • scale – Pixels per logical pixel in the image, for example 2 for twice the resolution with the same layout.

  • overlay – Whether to draw the information overlay (text, labels and colour bars); None follows toggle_overlay’s switch, which the screenshot leaves as it is.

  • transparent – Whether the background is transparent (an RGBA image) rather than the views’ background colour; needs PNG or TIFF.

Returns:

The path written. The image is RGB, or RGBA if transparent; each view in it is size times scale pixels.

Raises:

  • ViewerUnavailableError – If the viewer’s dependencies are not installed.

  • TypeError – If view is neither a ViewKind nor None, or overlay or transparent is not a bool.

  • ValueError – If size or scale is not positive, the image is larger than the GPU draws, or the extension is not an image format (or is JPEG with a transparent background).

  • OSError – If the file cannot be written.

screenshot_views(path, size=[800, 800], scale=1.0, overlay=None, transparent=False)

Draws the three 2D views off screen, each into its own file.

The images are those screenshot draws of each 2D view, drawn with one renderer, so they are faster than three screenshots.

Parameters:

  • path – The name the files are made from, the view’s name added to its stem: “fig.png” gives “fig_axial.png”, “fig_coronal.png” and “fig_sagittal.png”. Existing files are replaced.

  • size – Each view’s width and height in logical pixels.

  • scale – Pixels per logical pixel in the images.

  • overlay – Whether to draw the information overlay; None follows toggle_overlay’s switch, which is left as it is.

  • transparent – Whether the background is transparent (RGBA images); needs PNG or TIFF.

Returns:

The paths written – axial, coronal, sagittal.

Raises:
select(target)

Selects an item or a category, as a click in Layers does.

The selection is what the Options panel shows, and the image the left and right arrows step through.

Parameters:

target – An item’s id, a Category, or None to select nothing.

Raises:

  • TypeError – If target is neither an item id nor a Category.

  • ValueError – If there is no item with that id.

select_view(view)

Makes a view the selected one, as a click in it does; shortcuts act there.

Parameters:

view – The view.

Raises:

TypeError – If view is not a ViewKind.

set(target, name, value)

Changes one option of an item, or of every item of a category.

Showing a volume makes it the main volume and hides the others; setting the Volumes category’s visibility shows or hides the main volume only. A new volume index drops the surface labels its volume does not hold. Minimum, maximum and threshold are in the image’s scaled units. DTI colours need a 4D image with 3 volumes (a direction’s x, y and z), and the image that modulates them must be one of item_choices. A surface’s values to colour by must be one of data_choices; a new one also sets the colormap and range: for “curv” and “sulc” white to black from -0.3 to 0.3, for others the image default over the values’ range. A tractogram’s TSF file (VALUES_FILE) must hold a value per point of its streamlines, and its sampled volume (VALUES_VOLUME) must be one of item_choices; setting either clears the other, colours the tractogram by value and sets the range to the values’ (for a volume, its data’s).

Parameters:

  • target – An item’s id, or a Category to change all its items.

  • name – The option, such as OptionName.COLORMAP.

  • value – The new value, of the option’s type: a bool, a number, a Colormap, a path for a lookup table (”” for the built-in colours) or a TSF file (”” for none), label numbers for SURFACE_LABELS, which must be among the overlay’s labels, or another item’s id (or None) for an option that names an item, such as OptionName.MODULATE or VALUES_VOLUME, or a name (or None) for OptionName.COLOUR_BY. A tractogram’s INCLUDE_MASKS, EXCLUDE_MASKS and WITHIN_MASKS are items’ ids, each one of item_choices, and INCLUDE_SPHERES, EXCLUDE_SPHERES and WITHIN_SPHERES are (x, y, z, radius) in world coordinates, mm.

Raises:

  • TypeError – If target or name is of the wrong type.

  • OptionError – If the items have no such option, the value is outside the option’s range or choices, the option (such as the volume index) is set per item and target is a category, DTI colours are asked of an image without 3 volumes, the item named is not one the option can name, a surface has no such values, or a TSF file cannot be read or does not match the tractogram.

  • ValueError – If there is no item with that id.

set_camera(view, preset)

Moves the 3D view’s camera to a standard position, keeping its zoom.

Parameters:

  • view – ViewKind.THREE_D, the only view with camera positions.

  • preset – Axial (from above), coronal (from the front) or sagittal (from the subject’s right).

Raises:

  • TypeError – If view is not a ViewKind or preset not a CameraPreset.

  • ValueError – If view is a 2D view.

set_convention(convention)

Shows the subject’s right on the screen’s right or on its left.

Each 2D view stays centred on the same place.

Parameters:

convention – Convention.RAS (neurological, right on the right) or Convention.LAS (radiological, right on the left).

Raises:

TypeError – If convention is not a Convention.

set_default(category, name, value)

Sets the value an option starts with on the items added to a category.

Items already in the scene keep their value. The Settings panel uses it for the default interpolation of new images.

Parameters:

  • category – The category whose new items start with the value.

  • name – The option.

  • value – Its starting value, checked as set checks it.

Raises:

  • TypeError – If category or name is not its enum.

  • OptionError – If the category has no such option, the option is set per item, or the value is not allowed.

step_slice(view, n)

Moves a 2D view’s slice by n steps along the view’s axis.

A step is the reference grid’s voxel size along the world axis closest to the view’s (x for sagittal, y for coronal, z for axial), or 1 mm with no grid. Positive n moves towards right, anterior or superior.

Parameters:

  • view – ViewKind.AXIAL, CORONAL or SAGITTAL.

  • n – The number of steps, negative to go back.

Raises:
step_volume(n)

Moves a 4D image’s volume index by n, as the left and right arrows do.

The image is the selected one if it is 4D, else the main volume. The index stops at the first and the last volume; without a main volume, nothing happens.

Parameters:

n – The number of volumes, negative to go back.

Raises:

TypeError – If n is not a whole number.

toggle_crosshair()

Shows or hides the crosshair in the 2D views.

toggle_maximised(view)

Makes a view fill the window, or, if it already does, shows all four.

The view filling the window is also selected, so the shortcuts act on it.

Parameters:

view – The view.

Raises:

TypeError – If view is not a ViewKind.

toggle_overlay()

Shows or hides the text and colour bars drawn over the views.

The text is the orientation letters at the edges and the crosshair’s readout.

view_centre(view)

The world position at the centre of a 2D view, in its slice plane.

Parameters:

view – ViewKind.AXIAL, CORONAL or SAGITTAL.

Returns:

The position (x, y, z) in mm, RAS+.

Raises:
zoom(view, factor, about=None)

Zooms a view in or out, keeping a point where it is on the screen.

The zoom stays within ZOOM_RANGE (0.25 to 64 times the field of view at zoom 1). The 3D view always zooms about its centre.

Parameters:

  • view – The view to zoom.

  • factor – How much to multiply the zoom by: above 1 zooms in, below 1 zooms out.

  • about – The world position (mm) that stays in place, such as the point under the mouse; the view’s centre if None. Not allowed for the 3D view.

Raises:

  • TypeError – If view is not a ViewKind.

  • ValueError – If factor is not a positive number, about is not three finite numbers, or about is given for the 3D view.