fsleyes_props.properties_types

Definitions for different property types.

This module provides a number of PropertyBase subclasses which define properties of different types. These classes are intended to be added as attributes of a HasProperties class definition.

Object	A property which encapsulates any value.
Boolean	A property which encapsulates a bool value.
Number	Base class for the Int and Real classes.
Int	A Number which encapsulates an integer.
Real	A Number which encapsulates a floating point number.
Percentage	A Real property which represents a percentage.
String	A property which encapsulates a string.
Choice	A property which may only be set to one of a set of predefined values.
FilePath	A property which represents a file or directory path.
List	A property which represents a list of items, of another property type.
Colour	A property which represents a RGBA colour, stored as four floating point values in the range 0.0 - 1.0.
ColourMap	A property which encapsulates a matplotlib.colors.Colormap.
Bounds	A property which represents numeric bounds in any number of dimensions, as long as that number is no more than 4.
Point	A property which represents a point in some n-dimensional (up to 4) space.
Array	A property which represents a numpy array.

class fsleyes_props.properties_types.Object(**kwargs)

Bases: PropertyBase

A property which encapsulates any value.

Create a Object property. If an equalityFunc is not provided, any writes to this property will be treated as if the value has changed (and any listeners will be notified).

class fsleyes_props.properties_types.Boolean(**kwargs)

Bases: PropertyBase

A property which encapsulates a bool value.

Create a Boolean property.

If the default kwarg is not provided, a default value of False is used.

cast(instance, attributes, value)

Overrides PropertyBase.cast(). Casts the given value to a bool.

class fsleyes_props.properties_types.Number(minval=None, maxval=None, clamped=False, **kwargs)

Bases: PropertyBase

Base class for the Int and Real classes.

A property which represents a number. Don’t use/subclass this, use/subclass one of Int or Real.

Define a Number property.

Parameters:

• minval – Minimum valid value

• maxval – Maximum valid value

• clamped – If True, the value will be clamped to its min/max bounds.

• kwargs – Passed through to PropertyBase.__init__(). If a default value is not provided, it is set to something sensible.

validate(instance, attributes, value)

Overrides PropertyBase.validate(). Validates the given number.

Calls the PropertyBase.validate() method. Then, if the minval and/or maxval attributes have been set, and the given value is not within those values, a ValueError is raised.

Parameters:

• instance – The owning HasProperties instance (or None for unbound property values).

• attributes – Dictionary containing property attributes.

• value – The value to validate.

cast(instance, attributes, value)

Overrides PropertyBase.cast().

If the clamped attribute is True and the minval and/or maxval have been set, this function ensures that the given value lies within the minval and maxval limits. Otherwise the value is returned unchanged.

class fsleyes_props.properties_types.Int(**kwargs)

Bases: Number

A Number which encapsulates an integer.

Create an Int property.

cast(instance, attributes, value)

Overrides Number.cast(). Casts the given value to an int, and then passes the value to Number.cast().

class fsleyes_props.properties_types.Real(precision=1e-09, **kwargs)

Bases: Number

A Number which encapsulates a floating point number.

Define a Real property.

Parameters:

precision – Tolerance for equality testing. Set to None to use exact equality.

cast(instance, attributes, value)

Overrides Number.cast(). Casts the given value to a float, and then passes the value to Number.cast().

class fsleyes_props.properties_types.Percentage(**kwargs)

Bases: Real

A Real property which represents a percentage.

A Percentage property is just a Real property with a default minimum value of 0 and default maximum value of 100.

Create a Percentage property.

class fsleyes_props.properties_types.String(minlen=None, maxlen=None, **kwargs)

Bases: PropertyBase

A property which encapsulates a string.

Cteate a String property.

Parameters:

• minlen (int) – Minimum valid string length.

• maxlen (int) – Maximum valid string length.

cast(instance, attributes, value)

Overrides PropertyBase.cast().

Casts the given value to a string. If the given value is the empty string, it is replaced with None.

validate(instance, attributes, value)

Overrides PropertyBase.validate().

Passes the given value to PropertyBase.validate(). Then, if either the minlen or maxlen attributes have been set, and the given value has length less than minlen or greater than maxlen, raises a ValueError.

class fsleyes_props.properties_types.Choice(choices=None, alternates=None, allowStr=False, **kwargs)

Bases: PropertyBase

A property which may only be set to one of a set of predefined values.

Choices can be added/removed via the addChoice(), removeChoice() method, and setChoices() methods. Existing choices can be modified with the updateChoice() method.

Individual choices can be enabled/disabled via the enableChoice() and disableChoice() methods. The choiceEnabled attribute contains a dictionary of {choice : boolean} mappings representing the enabled/disabled state of each choice.

A set of alternate values can be provided for each choice - these alternates will be accepted when assigning to a Choice property.

Note

If you create a Choice property with non-string choice and alternate values, you may run into problems when using serialise and/or cli functionality, unless you set allowStr to True.

Create a Choice property.

Parameters:

• choices – List of values, the possible values that this property can take. Can alternately be a dict - see the note above.

• alternates – A list of lists, specificying alternate acceptable values for each choice. Can also be a dict of {choice : [alternates]} mappings. All alternate values must be unique - different choices cannot have equivalent alternate values.

• allowStr – If True, string versions of any non-string choice values will be accepted - str versions of each choice are added as alternate values for that choice. Defaults to False.

setDefault(default, instance=None)

Sets the default choice value.

enableChoice(choice, instance=None)

Enables the given choice.

disableChoice(choice, instance=None)

Disables the given choice. An attempt to set the property to a disabled value will result in a ValueError.

choiceEnabled(choice, instance=None)

Returns True if the given choice is enabled, False otherwise.

getChoices(instance=None)

Returns a list of the current choices.

getAlternates(instance=None)

Returns a list of the current acceptable alternate values for each choice.

updateChoice(choice, newChoice=None, newAlt=None, instance=None)

Updates the choice value and/or alternates for the specified choice.

setChoices(choices, alternates=None, instance=None, newChoice=None)

Sets the list of possible choices (and their alternate values, if not None).

addChoice(choice, alternate=None, instance=None)

Adds a new choice to the list of possible choices.

removeChoice(choice, instance=None)

Removes the specified choice from the list of possible choices.

validate(instance, attributes, value)

Overrides PropertyBase.validate().

Raises a ValueError if the given value is not one of the possible values for this Choice property.

cast(instance, attributes, value)

Overrides PropertyBase.cast().

Checks to see if the given value is a valid alternate value for a choice. If so, the alternate value is replaced with the choice value.

class fsleyes_props.properties_types.FilePath(exists=False, isFile=True, suffixes=None, **kwargs)

Bases: String

A property which represents a file or directory path.

There is currently no support for validating a path which may be either a file or a directory - only one or the other.

Create a FilePath property.

Parameters:

• exists (bool) – If True, the path must exist.

• isFile (bool) – If True, the path must be a file. If False, the path must be a directory. This check is only performed if exists is True.

• suffixes (list) – List of acceptable file suffixes (only relevant if isFile is True).

validate(instance, attributes, value)

Overrides PropertyBase.validate().

If the exists attribute is not True, does nothing. Otherwise, if isFile is False and the given value is not a path to an existing directory, a ValueError is raised.

If isFile is True, and the given value is not a path to an existing file (which, if suffixes is not None, must end in one of the specified suffixes), a ValueError is raised.

class fsleyes_props.properties_types.List(listType=None, minlen=None, maxlen=None, **kwargs)

Bases: ListPropertyBase

A property which represents a list of items, of another property type.

If you use List properties, you really should read the documentation for the PropertyValueList, as it contains important usage information.

Create a List property.

Parameters:

• listType – A PropertyBase type, specifying the values allowed in the list. If None, anything can be stored in the list, but no casting or validation will occur.

• minlen (int) – Minimum list length.

• maxlen (int) – Maximum list length.

validate(instance, attributes, value)

Overrides PropertyBase.validate().

Checks that the given value (which should be a list) meets the minlen/maxlen attribute. Raises a ValueError if it does not.

class fsleyes_props.properties_types.Colour(**kwargs)

Bases: PropertyBase

A property which represents a RGBA colour, stored as four floating point values in the range 0.0 - 1.0.

Any value which can be interpreted by matplotlib as a RGB(A) colour is accepted. If an RGB colour is provided, the alpha channel is set to 1.0.

Create a Colour property.

If the default kwarg is not provided, the default is set to white.

validate(instance, attributes, value)

Checks the given value, and raises a ValueError if it does not consist of three or four floating point numbers in the range (0.0 - 1.0).

cast(instance, attributes, value)

Ensures that the given value contains three or four floating point numbers, in the range (0.0 - 1.0).

If the alpha channel is not provided, it is set to the current alpha value (which defaults to 1.0).

class fsleyes_props.properties_types.ColourMap(cmaps=None, prefix=None, **kwargs)

Bases: PropertyBase

A property which encapsulates a matplotlib.colors.Colormap.

A ColourMap property can take any Colormap instance as its value. ColourMap values may be specified either as a Colormap instance, or as a string containing the name of a registered colour map instance.

ColourMap properties also maintain an internal list of colour map names; while these names do not restrict the value that a ColourMap property can take, they are used for display purposes - a widget which is created for a ColourMap instance will only display the options returned by the getColourMaps() method. See the widgets._ColourMap() function.

It is possible to specify a colour map name prefix when creating a ColourMap property. When a prefix is set, assignments to the property, e.g. obj.cmap = 'red' will cause a colour map named {prefix}_red to be chosen over a colour map named red, if the former is registered with matplotlib.

This prefix option was added because, for historical reasons, FSLeyes defines some colour maps with the same name as built-in matplotlib colour maps. From matplotlib ~3.5 and newer, it is not possible to override built-in colour maps, so these are registered as fsleyes_{name}. Furthermore, matplotlib 3.8 made it impossible to give a colour map a name which is different to the key under which it is registered.

Define a ColourMap property.

setColourMaps(cmaps, instance=None)

Set the colour maps for this property.

Parameters:

cmaps – a list of registered colour map names.

addColourMap(cmap, instance=None)

Add a colour map to the list.

Parameters:

cmap – The name of a registered colour map.

getColourMaps(instance=None)

Returns a list containing the names of registered colour maps available for this property.

validate(instance, attributes, value)

Overrides PropertyBase.validate().

Raises a ValueError if the given value is not a matplotlib Colormap instance.

cast(instance, attributes, value)

Overrides PropertyBase.cast().

If the provided value is a string, an attempt is made to convert it to a colour map, via the matplotlib.colormaps registry. The value may either be the registered colour map name, or its Colormap.name attribute. The match is case-insensitive.

class fsleyes_props.properties_types.BoundsValueList(*args, **kwargs)

Bases: PropertyValueList

A PropertyValueList with values which represent bounds along a number of dimensions (up to 4).

This class is used by the Bounds property to encapsulate bounding values for an arbitrary number of dimensions. For N+1 dimensions, the bounding values are stored as a list:

[lo0, hi0, lo1, hi1, ..., loN, hiN]

This class just adds some convenience methods and attributes to the PropertyValueList base class. For a single dimension, a bound object has a lo value and a hi value, specifying the bounds along that dimension. To make things confusing, each dimension also has min and max attributes, which define the minimum/maximum values that the lo and high values may take for that dimension.

Some dynamic attributes are available on BoundsValueList objects, allowing access to and assignment of bound values and attributes. Dimensions 0, 1, 2, 3 respectively map to identifiers x, y, z, t. If an attempt is made to access/assign an attribute corresponding to a dimension which does not exist on a particular BoundsValueList instance (e.g. attribute t on a 3-dimensional list), an IndexError will be raised. Here is an example of dynamic bound attribute access:

class MyObj(props.HasProperties):
    myBounds = Bounds(ndims=4)

obj = MyObj()

# set/access lo/hi values together
xlo, xhi = obj.mybounds.x
obj.mybounds.z = (25, 30)

# set/access lo/hi values separately
obj.mybounds.xlo = 2
obj.mybounds.zhi = 50

# get the length of the bounds for a dimension
ylen = obj.mybounds.ylen

# set/access the minimum/maximum
# constraints for a dimension
obj.mybounds.xmin = 0
tmax = obj.mybounds.tmax

Create a BoundsValueList instance - see PropertyValueList.__init__().

getLo(axis=None)

Return the low value for the given (0-indexed) axis. If axis is not specified, the low bounds for all axes are returned.

getHi(axis=None)

Return the high value for the given (0-indexed) axis. If axis is not specified, the high bounds for all axes are returned.

getRange(axis)

Return the (low, high) values for the given (0-indexed) axis.

getLen(axis)

Return the distance between the low and high values for the specified axis.

setLimit(axis, limit, value)

Sets the value for the specified axis and limit (0 == low, 1 == high).

getLimit(axis, limit)

Returns the value for the specified axis and limit (0 == low, 1 == high).

setLo(axis, value)

Set the low value for the specified axis.

setHi(axis, value)

Set the high value for the specified axis.

setRange(axis, loval, hival)

Set the low and high values for the specified axis.

getMin(axis)

Return the minimum value (the low limit) for the specified axis.

getMax(axis)

Return the maximum value (the high limit) for the specified axis.

setMin(axis, value)

Set the minimum value for the specified axis.

setMax(axis, value)

Set the maximum value for the specified axis.

getLimits(axis)

Return (minimum, maximum) limit values for the specified axis.

setLimits(axis, minval, maxval)

Set the minimum and maximum limit values for the specified axis.

inBounds(point)

Returns True if the given point (a sequence of numbers) lies within the bounds represented by this BoundsValueList, False otherwise.

class fsleyes_props.properties_types.Bounds(ndims=1, real=True, minDistance=None, clamped=True, minval=None, maxval=None, **kwargs)

Bases: List

A property which represents numeric bounds in any number of dimensions, as long as that number is no more than 4.

Bounds values are stored in a BoundsValueList, a list of integer or floating point values, with two values (lo, hi) for each dimension.

Bounds values may also have bounds of their own, i.e. minimium/maximum values that the bound values can take. These bound-limits are referred to as ‘min’ and ‘max’, and can be set via the BoundsValueList.setMin() and BoundsValueList.setMax() methods. The advantage to using these methods, instead of using, for example, PropertyValue.setAttribute(), is that if you use the latter you will have to set the attributes on both the low and the high values.

Create a Bounds property.

Parameters:

• ndims – Number of dimensions. This is (currently) not a property attribute, hence it cannot be changed.

• real – If True (the default), the bound values are stored as Real values; otherwise, they are stored as Int values.

• minDistance – Minimum distance to be maintained between the low/high values for each dimension.

• clamped – If True (the default), the bound values are clamped to their limits. See the Number class.

• minval – Initial minimum value to use for all dimensions

• maxval – Initial maximum value to use for all dimensions

validate(instance, attributes, value)

Overrides PropertyBase.validate().

Raises a ValueError if the given value (a list of min/max values) is of the wrong length or data type, or if any of the min values are greater than the corresponding max value.

class fsleyes_props.properties_types.PointValueList(*args, **kwargs)

Bases: PropertyValueList

A list of values which represent a point in some n-dimensional (up to 4) space.

This class is used by the Point property to encapsulate point values for between 1 and 4 dimensions.

This class just adds some convenience methods and attributes to the PropertyValueList base class, in a similar manner to the BoundsValueList class.

The point values for each dimension may be queried/assigned via the dynamic attributes x, y, z, t, which respectively map to dimensions 0, 1, 2, 3. When querying/assigning point values, you may use GLSL-like swizzling. For example:

class MyObj(props.HasProperties):
    mypoint = props.Point(ndims=3)

obj = MyObj()

y,z = obj.mypoint.yz

obj.mypoint.zxy = (3,6,1)

Create a PointValueList - see PropertyValueList.__init__().

getPos(axis)

Return the point value for the specified (0-indexed) axis.

setPos(axis, value)

Set the point value for the specified axis.

getMin(axis)

Get the minimum limit for the specified axis.

getMax(axis)

Get the maximum limit for the specified axis.

getLimits(axis)

Get the (minimum, maximum) limits for the specified axis.

setMin(axis, value)

Set the minimum limit for the specified axis.

setMax(axis, value)

Set the maximum limit for the specified axis.

setLimits(axis, minval, maxval)

Set the minimum and maximum limits for the specified axis.

class fsleyes_props.properties_types.Point(ndims=2, real=True, **kwargs)

Bases: List

A property which represents a point in some n-dimensional (up to 4) space.

Point property values are stored in a PointValueList, a list of integer or floating point values, one for each dimension.

Create a Point property.

Parameters:

• ndims (int) – Number of dimensions.

• real (bool) – If True the point values are stored as Real values, otherwise they are stored as Int values.

class fsleyes_props.properties_types.ArrayProxy(*args, **kwargs)

Bases: PropertyValue

A proxy class indended to encapsulate a numpy array. ArrayProxy instances are used by the Array property type.

An ArrayProxy is a PropertyValue which contains, and tries to act like, a numpy array. Element access andassignment, and attribute access can be performed through the ArrayProxy.

All element assignments which occur via an ArrayProxy instance will result in notification of all registered listeners (see the PropertyValue.addListener() method). A limitation of this implementation is that notification will occur even if the assignment does not change the array values.

The underlying numpy array is accessible via the getArray() method. However, changes made directly to the numpy array will bypass the PropertyValue notification procedure.

Create an ArrayProxy. All arguments are passed through to the PropertyValue.__init__() method.

get()

Overrides PropertyValue.get(). Returns this ArrayProxy.

getArray()

Returns a reference to the numpy array encapsulated by this ArrayProxy.

class fsleyes_props.properties_types.Array(dtype=None, shape=None, resizable=True, nullable=True, **kwargs)

Bases: PropertyBase

A property which represents a numpy array. Each array is encapsulated within an ArrayProxy instance.

Create an Array property.

Parameters:

• dtype – numpy data type.

• shape – Initial shape of the array.

• resizable – Defaults to True. If False, the array size will be fixed to the shape specified here. Different sized arrays will still be allowed, if the allowInvalid parameter to PropertyBase.__init__() is set to True.

• nullable – Defaults to True. Allow the property to be set to None.

cast(instance, attributes, value)

Overrides :meth`.PropertyBase.cast`. Casts the given value to a numpy array (with the data type that was specified in __init__()).

validate(instance, attributes, value)

Overrides :meth`.PropertyBase.validate`. If the given value has the wrong data type, or this Array is not resizable and the value has the wrong shape, a ValueError is raised.