fsleyes_widgets.utils.layout

Utility functions for calculating canvas sizes and laying them out.

This module implements a simple layout manager, for laying out canvases and associated orientation labels. It is used primarily by the render application, for off-screen rendering.

You can use the following classes to define a layout:

Bitmap	A class which encapsulates a RGBA bitmap, assumed to be a numpy.uint8 array of shape \(height \times width \times 4\)).
Space	A class which represents empty space of a specific width/height.
HBox	A class which contains items to be laid out horizontally.
VBox	A class which contains items to be laid out vertically.

And the following functions to generate layouts and bitmaps:

buildOrthoLayout	Builds a layout containing the given canvas bitmaps, label bitmaps, and colour bar bitmap.
buildCanvasBox	Builds a layout containing the given canvas bitmap, and orientation labels (if showLabels is True).
padBitmap	Pads the given bitmap with zeros along the secondary axis (specified with the vert parameter), so that it fits in the given width/height.
layoutToBitmap	Recursively turns the given layout object into a bitmap.

A few functions are also provided for calculating the display size, in pixels, of one or more canvases which are displaying a defined coordinate system. The canvas sizes are calculated so that their aspect ratio, relative to the respective horizontal/vertical display axes, are maintained, and that the canvases are sized proportionally with respect to each other. The following size calculation functions are available:

calcSizes	Convenience function which, based upon whether the layout argument is 'horizontal', 'vertical', or 'grid', respectively calls one of:
calcGridSizes	Calculates the size of three canvases so that they are laid out in a grid, i.e.:
calcHorizontalSizes	Calculates the size of up to three canvases so they are laid out horizontally.
calcVerticalSizes	Calculates the size of up to three canvases so they are laid out vertically.
calcPixWidth	Given the dimensions of a space to be displayed, and the available height in pixels, calculates the required pixel width.
calcPixHeight	Given the dimensions of a space to be displayed, and the available width in pixels, calculates the required pixel height.

class fsleyes_widgets.utils.layout.Bitmap(bitmap)

Bases: object

A class which encapsulates a RGBA bitmap, assumed to be a numpy.uint8 array of shape \(height \times width \times 4\)).

Warning

Note the unusual array shape - height is the first axis, and width the second!

A Bitmap instance has the following attributes:

• bitmap: The bitmap data

• width: Bitmap width in pixels

• height: Bitmap height in pixels

Create a Bitmap.

Parameters:

bitmap – numpy array containing the bitmap data.

class fsleyes_widgets.utils.layout.Space(width, height)

Bases: object

A class which represents empty space of a specific width/height.

A Space instance has the following attributes:

• width: Width in pixels.

• height: Height in pixels.

Creat a Space.

Parameters:

• width – Width in pixels.

• height – Height in pixels.

class fsleyes_widgets.utils.layout.HBox(items=None)

Bases: object

A class which contains items to be laid out horizontally.

After creation, new items should be added via the append() method.

A HBox instance has the following attributes:

• width: Total width in pixels.

• height: Total height in pixels.

• items: List of items in this HBox.

Create a HBox.

Parameters:

items – List of items contained in this HBox.

append(item)

Append a new item to this HBox.

class fsleyes_widgets.utils.layout.VBox(items=None)

Bases: object

A class which contains items to be laid out vertically.

After creation, new items can be added via the append() method.

A VBox instance has the following attributes:

• width: Total width in pixels.

• height: Total height in pixels.

• items: List of items in this VBox.

Create a VBox.

Parameters:

items – List of items contained in this VBox.

append(item)

Append a new item to this VBox.

fsleyes_widgets.utils.layout.padBitmap(bitmap, width, height, vert, bgColour)

Pads the given bitmap with zeros along the secondary axis (specified with the vert parameter), so that it fits in the given width/height.

Parameters:

• bitmap – A numpy.array of size \(x \times y \times 4\) containing a RGBA bitmap.

• width – Desired width in pixels.

• height – Desired height in pixels.

• vert – If vert is True, the bitmap is padded horizontally to fit width. Otherwise, the bitmap is padded vertically to fit height.

• bgColour – Background colour to use for padding. Must be a (r, g, b, a) tuple with each channel in the range [0 - 255].

fsleyes_widgets.utils.layout.layoutToBitmap(layout, bgColour=None)

Recursively turns the given layout object into a bitmap.

Parameters:

• layout – A Bitmap, Space, HBox or VBox instance.

• bgColour – Background colour used to fill in empty space. Must be a (r, g, b, a) tuple with channel values in the range [0, 255]. Defaults to transparent.

Returns:

a numpy.uint8 array of size \(height \times width \times 4\).

fsleyes_widgets.utils.layout.buildCanvasBox(canvasBmp, labelBmps, showLabels, labelSize)

Builds a layout containing the given canvas bitmap, and orientation labels (if showLabels is True).

Parameters:

• canvasBmp – A numpy.uint8 array containing a bitmap.

• labelBmps – Only used if showLabels is True. numpy.uint8 arrays containing label bitmaps. Must be a dictionary of {side : numpy.uint8} mappings, and must have keys top, bottom, left and right.

• showLabels – If True, the orientation labels provided in labelBmps are added to the layout.

• labelSize – Label sizes - the left/right label widths, and top/bottom label heights are padded to this size using Space objects.

Returns:

A Bitmap or VBox instance.

fsleyes_widgets.utils.layout.buildOrthoLayout(canvasBmps, labelBmps, layout, showLabels, labelSize)

Builds a layout containing the given canvas bitmaps, label bitmaps, and colour bar bitmap.

Parameters:

• canvasBmps – A list of numpy.uint8 arrays containing the canvas bitmaps to be laid out.

• layout – One of 'horizontal', 'vertical', or 'grid'.

See the buildCanvasBox() for details on the other parameters.

Returns:

A HBox or VBox describing the layout.

fsleyes_widgets.utils.layout.calcSizes(layout, canvasaxes, bounds, width, height)

Convenience function which, based upon whether the layout argument is 'horizontal', 'vertical', or 'grid', respectively calls one of:

• calcHorizontalSizes()

• calcVerticalSizes()

• calcGridSizes()

Parameters:

• layout – String specifying the layout type.

• canvsaxes – A list of tuples, one for each canvas to be laid out. Each tuple contains two values, (i, j), where i is an index, into bounds, specifying the canvas width, and j is an index into bounds, specifying the canvas height, in the display coordinate system.

• bounds – A list of three values specifying the size of the display space.

• width – Maximum width in pixels.

• height – Maximum height in pixels.

Returns:

A list of (width, height) tuples, one for each canvas, each specifying the canvas width and height in pixels.

fsleyes_widgets.utils.layout.calcGridSizes(canvasaxes, bounds, width, height)

Calculates the size of three canvases so that they are laid out in a grid, i.e.:

0 1

2

It is assumed that the canvasaxes parameters are ordered such that adjacent canvases share common axes in the world coordinate system. In other words, in the above diagram, the horizontal axes of canvases 0 and 2 are equal, and the vertical axes of canvases 0 and 1 must be equal.

Note

If less than three canvases are specified, they are passed to the calcHorizontalLayout() function.

See calcSizes() for details on the arguments.

fsleyes_widgets.utils.layout.calcVerticalSizes(canvasaxes, bounds, width, height)

Calculates the size of up to three canvases so they are laid out vertically.

See calcSizes() for details on the arguments.

fsleyes_widgets.utils.layout.calcHorizontalSizes(canvasaxes, bounds, width, height)

Calculates the size of up to three canvases so they are laid out horizontally.

See calcSizes() for details on the arguments.

fsleyes_widgets.utils.layout.calcPixWidth(wldWidth, wldHeight, pixHeight)

Given the dimensions of a space to be displayed, and the available height in pixels, calculates the required pixel width.

Parameters:

• wldWidth – Width of the display coordinate system

• wldHeight – Height of the display coordinate system

• pixHeight – Available height in pixels.

Returns:

The required width in pixels.

fsleyes_widgets.utils.layout.calcPixHeight(wldWidth, wldHeight, pixWidth)

Given the dimensions of a space to be displayed, and the available width in pixels, calculates the required pixel height.

Parameters:

• wldWidth – Width of the display coordinate system

• wldHeight – Height of the display coordinate system

• pixWidth – Available width in pixels.

Returns:

The required height in pixels.