2.1. QeImage - 2D Image Display Widget

2.1.1. Overview

QeImage is a full-featured 2D image display widget built on the ESO Data Display Toolkit (DDT). It provides FITS file viewing, colour maps, intensity cuts, flip and rotation controls, and numpy array attachment, exposed through Python bindings generated by Shiboken from the C++/Qt implementation.

../_images/qeimage_01.png — QeImage widget

2.1.1.1. Constructor

The constructor signature is

QeImage(parent: QWidget = None, designMode: boolean = False)

Parameters:

parent (QWidget, optional) – Parent widget.
designMode (bool, default False) – Set to True when instantiated from Qt Designer.

Example:

# Any Qt Widget needs an Application running
from PySide6.QtWidgets import QApplication
app = QApplication([])
from cut.wdglib.widgets import QeImage
img = QeImage()
img.show()

2.1.1.2. Inheritance Hierarchy

QeImage inherits from a single chain through the Data Display Toolkit (DDT):

.. uml::

hide empty members hide empty attributes

class QeImage class DdtImageWidget <<DDT>> class DdtWidget <<DDT>> class QDockWidget <<PySide6.QtWidgets>> class QWidget <<PySide6.QtWidgets>> class QObject <<PySide6.QtCore>> class QPaintDevice <<PySide6.QtGui>> class ShibokenObject <<Shiboken>> class object

QeImage –|> DdtImageWidget DdtImageWidget --|> DdtWidget DdtWidget –|> QDockWidget QDockWidget --|> QWidget QWidget –|> QObject QObject --|> QPaintDevice QPaintDevice –|> ShibokenObject ShibokenObject --|> object

2.1.2. Qt Properties

The following Qt properties are defined by QeImage itself (beyond the standard QWidget properties inherited from the DDT stack). Each property is accessible through its getter/setter methods listed in the Methods section.

filename (str) – Path of the currently loaded FITS file. Default: "".
colourmap (str) – Name of the active colour map. Default: "real".
colormapscaling (int) – Intensity scaling function identifier. Values: 0 = linear, 1 = log, 2 = sqrt.
colormapinvert (bool) – Whether the colour map is inverted.
fliphorizontal (bool) – Whether the image is flipped horizontally.
flipvertical (bool) – Whether the image is flipped vertically.
mincutvalue (float) – Minimum intensity cut value. Default: 0.0.
maxcutvalue (float) – Maximum intensity cut value. Default: 65536.0.
rotation (int) – Image rotation angle in degrees. Default: 0.
availablecolourmaps (list[str]) – Read-only list of colour map names available from the DDT colourmap registry (populated from the DDT_COLORMAP_PATH directory).
lastMouseCoordinates (QPoint) – Read-only mouse cursor position over the image canvas, as QPoint(x, y).

2.1.3. Methods

2.1.3.1. File Operations

cut.wdglib.widgets.OpenFile(filename: str) → bool

Open and display a FITS file.

Parameters:: filename – Path to the FITS file.
Returns:: True if the file was successfully opened.

cut.wdglib.widgets.GetFilename() → str

Return the currently loaded file path, or an empty string if no file is loaded.

Returns:: The file path string.

2.1.3.2. Colour Map

cut.wdglib.widgets.GetColourmap() → str

Return the active colour map name. Defaults to "real" if none set.

Returns:: The colour map name.

cut.wdglib.widgets.SetColourmap(newColourmap: str) → None

Set the active colour map by name.

Parameters:: newColourmap – Colour map name string.

cut.wdglib.widgets.GetAvailableColormaps() → list[str]

Return the list of available colour maps from the DDT registry, read from the DDT_COLORMAP_PATH directory. The first call scans the directory; subsequent calls return the cached list.

Returns:: List of colour map name strings (e.g., ["real", "heat", "rainbow", ...]).

Example:

colormaps = img.GetAvailableColormaps()
img.SetColourmap(colormaps[0])

cut.wdglib.widgets.SetColormapScaling(newColormapscaling: int) → None

Set the intensity scaling function.

Parameters:: newColormapscaling – Scaling function identifier (0=linear, 1=log, 2=sqrt).

cut.wdglib.widgets.GetColormapScaling() → int

Return the current intensity scaling function identifier.

Returns:: Scaling function identifier.

cut.wdglib.widgets.SetColormapInverted(newColormapinvert: bool) → None

Invert or restore the colour map.

Parameters:: newColormapinvert – True to invert.

cut.wdglib.widgets.isColormapInverted() → bool

Return whether the colour map is currently inverted.

Returns:: True if inverted.

2.1.3.3. Intensity Cut Values

cut.wdglib.widgets.SetMincutvalue(newMinCutValue: float) → None

Set the minimum intensity cut value. If the new value exceeds maxcutvalue, it is clamped to maxcutvalue.

Parameters:: newMinCutValue – New minimum cut value.

cut.wdglib.widgets.GetMincutvalue() → float

Return the current minimum intensity cut value.

Returns:: Current min cut value.

cut.wdglib.widgets.SetMaxcutvalue(newMaxCutValue: float) → None

Set the maximum intensity cut value. If the new value is below mincutvalue, it is clamped to mincutvalue.

Parameters:: newMaxCutValue – New maximum cut value.

cut.wdglib.widgets.GetMaxcutvalue() → float

Return the current maximum intensity cut value.

Returns:: Current max cut value.

2.1.3.4. Flip

cut.wdglib.widgets.SetFlipHorizontal(newFliphorizontal: bool) → None

Flip the image horizontally.

Parameters:: newFliphorizontal – True to flip.

cut.wdglib.widgets.isHorizontallyFlipped() → bool

Return whether the image is currently flipped horizontally.

Returns:: True if flipped horizontally.

cut.wdglib.widgets.SetFlipVertical(newFlipvertical: bool) → None

Flip the image vertically.

Parameters:: newFlipvertical – True to flip.

cut.wdglib.widgets.isVerticallyFlipped() → bool

Return whether the image is currently flipped vertically.

Returns:: True if flipped vertically.

2.1.3.5. Rotation

cut.wdglib.widgets.SetRotation(newRotation: int) → None

Set the image rotation angle.

Parameters:: newRotation – Rotation angle in degrees.

cut.wdglib.widgets.GetRotation() → int

Return the current image rotation angle in degrees.

Returns:: Rotation angle in degrees.

2.1.3.6. Mouse Coordinates

cut.wdglib.widgets.GetLastMouseCoordinates() → PySide6.QtCore.QPoint

Return the last reported mouse coordinates over the image canvas.

Returns:: QPoint with (x, y) pixel coordinates.

2.1.3.7. NumPy Array Data

cut.wdglib.widgets.setNumpyNdArray(data: object) → None

Attach image data from a NumPy ndarray. The array is attached directly; the widget maintains a reference to keep the data alive.

Supported dtypes include int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, and float64.

Parameters:: data – A 2-D NumPy array (shape (ny, nx)).

Example:

import numpy as np
data = np.random.rand(512, 512).astype(np.float64)
img.setNumpyNdArray(data)

cut.wdglib.widgets.getNumpyNdArray() → object

Return the currently attached image data as a NumPy ndarray with the same shape and dtype as the original data passed to setNumpyNdArray().

Returns:: NumPy ndarray, or empty array if no data attached.

Example:

arr = img.getNumpyNdArray()
print(f"Shape: {arr.shape}, dtype: {arr.dtype}")

2.1.3.8. Raw Pointer Attachment

cut.wdglib.widgets.AttachImageFromPointer(data, nx: int, ny: int)

Attach raw image data for display. This method is overloaded for the following pointer types:

int8_t*, int16_t*, int32_t*, int64_t*
uint8_t*, uint16_t*, uint32_t*, uint64_t*
float*, double*

The widget internally stores shared ownership of the data.

Parameters:

data – Raw pointer to the image pixel data, or an array-like object providing contiguous memory. The type is inferred automatically.
nx – Number of columns (X dimension).
ny – Number of rows (Y dimension).

Note: When passing nullptr or invalid dimensions, the widget resets to a 1x1 placeholder image to free previously allocated containers.

2.1.3.9. Data Information

cut.wdglib.widgets.GetArrayDataNx() → int

Return the number of columns (X dimension) of the currently attached data.

Returns:: X dimension (0 if no data attached).

cut.wdglib.widgets.GetArrayDataNy() → int

Return the number of rows (Y dimension) of the currently attached data.

Returns:: Y dimension (0 if no data attached).

2.1.3.10. MainWindow Integration

cut.wdglib.widgets.SetMainWindowForToolbar(window: PySide6.QtWidgets.QMainWindow) → None

Assign the owning QMainWindow so the image toolbar can be docked into it.

Parameters:: window – The QMainWindow that will host the image toolbar.

2.1.3.11. Inherited Data File Methods (from DdtImageWidget)

These methods are inherited from the DDT stack and are available on the QeImage instance:

AttachDataFile(filename) – Attach a FITS data file to the widget.
AttachDataStream(stream) – Attach a data stream to the widget.
DetachStream() – Detach the currently attached stream.

2.1.4. Signals

Each Qt property has a corresponding signal emitted when its value changes. Connect to these signals using the PyQt/PySide .connect() mechanism.

cut.wdglib.widgets.FilenameChanged(filename: str): Emitted when the loaded filename changes.

cut.wdglib.widgets.ColourmapChanged(colourmap: str): Emitted when the colour map changes.

cut.wdglib.widgets.MincutvalueChanged(value: float): Emitted when the min cut value changes.

cut.wdglib.widgets.MaxcutvalueChanged(value: float): Emitted when the max cut value changes.

cut.wdglib.widgets.ColormapScalingChanged(scaling: int): Emitted when the colormap scaling function changes.

cut.wdglib.widgets.ColormapInvertedChanged(inverted: bool): Emitted when the colormap inversion toggles.

cut.wdglib.widgets.FlipHorizontalChanged(flipped: bool): Emitted when horizontal flip toggles.

cut.wdglib.widgets.FlipVerticalChanged(flipped: bool): Emitted when vertical flip toggles.

cut.wdglib.widgets.RotationChanged(rotation: int): Emitted when the image rotation changes.

cut.wdglib.widgets.AvailableColormapsChanged(colormaps: list[str]): Emitted when the available colour maps list is refreshed.

cut.wdglib.widgets.MouseCoordinatesChanged(coordinates: PySide6.QtCore.QPoint)

Emitted when the mouse position over the image canvas changes.

The coordinates argument is a QPoint providing (x, y) pixel values. Access x/y via coordinates.x() and coordinates.y().

Example:

def on_mouse_move(pt):
    print(f"Cursor at ({pt.x()}, {pt.y()})")

img.MouseCoordinatesChanged.connect(on_mouse_move)

2.1.5. Protected Event Handlers

These methods are called by Qt during widget lifecycle events. Override them for custom behaviour, but call the base implementation.

cut.wdglib.widgets.showEvent(event: PySide6.QtGui.QShowEvent) → None: Called when the widget becomes visible. Shows the toolbar and docks it into the owning QMainWindow.

cut.wdglib.widgets.hideEvent(event: PySide6.QtGui.QHideEvent) → None: Called when the widget is hidden. Hides the toolbar and removes it from the owning QMainWindow.

2.1.6. QeTypes Enum

The data type of the attached image is represented by the QeTypes enum, importable from cut.common.pyb.

QeTypes.Int8

QeTypes.Int16

QeTypes.Int32

QeTypes.Int64

QeTypes.UInt8

QeTypes.UInt16

QeTypes.UInt32

QeTypes.UInt64

QeTypes.Float

QeTypes.Double

QeTypes.String

QeTypes.Boolean

QeTypes.NotSet

2.1.7. Example Usage

Opening a FITS file and configuring display:

from cut.wdglib.widgets import QeImage
from PySide6.QtWidgets import QApplication

app = QApplication([])
img = QeImage()

# Open a FITS file
ok = img.OpenFile("/path/to/spectrum.fits")

# Configure display
img.SetColourmap("heat")
img.SetColormapScaling(0)   # linear
img.SetMincutvalue(10.0)
img.SetMaxcutvalue(1000.0)
img.SetColormapInverted(False)
img.SetRotation(0)

# Connect to signals
img.MouseCoordinatesChanged.connect(lambda pt: print(f"x={pt.x()} y={pt.y()}"))

img.show()
app.exec()

Attaching NumPy data:

import numpy as np
from cut.wdglib.widgets import QeImage
from PySide6.QtWidgets import QApplication

app = QApplication([])
img = QeImage()

# Generate test data
data = np.random.randn(256, 256).astype(np.float64)
img.setNumpyNdArray(data)

# Verify
arr = img.getNumpyNdArray()
print(f"Shape: {arr.shape}, dtype: {arr.dtype}")
print(f"Nx: {img.GetArrayDataNx()}, Ny: {img.GetArrayDataNy()}")

img.show()
app.exec()

Use it through the taurus designer:

../_images/taurus_designer_qeimage_01.gif — Adding a QeImage using the Taurus Designer

2.1.8. Notes

The widget requires the DDT_COLORMAP_PATH environment variable to be set for colour map look-up. GetAvailableColormaps() will call qFatal() if the variable is unset, the directory doesn’t exist, or contains no .lut files.
Colormap scaling values: 0 = linear, 1 = logarithmic, 2 = square root.
Setting mincutvalue to a value >= maxcutvalue (or vice versa) will auto-clamp to maintain a valid range.
The setNumpyNdArray() method supports 2D arrays of dtypes int8/16/32/64, uint8/16/32/64, float32, and float64.
When attaching data from a raw pointer via AttachImageFromPointer(), the caller is responsible for managing the lifetime of the pointed-to memory.
Toolbar integration requires the widget to be parented to (or a child of) a QMainWindow. Use SetMainWindowForToolbar() to explicitly set the hosting window.