2.7. QeMatrixView - 2D Matrix Display Widget

2.7.1. Overview

QeMatrixView is a dual-view widget for displaying 2D matrix data. It inherits from QMainWindow and contains a vertically split layout with a QeImage widget (the graphical view port) in the top pane and a QTableView (the tabular editor) in the bottom pane. The image view provides color-mapped display with FITS-style rendering; the table view presents the same data as editable cells backed by a QeArrayModel.

The Image and Table panes can be toggled independently through toolbar actions or programmatically via the visibility control methods. A Pointer mode links mouse coordinates over the image with the corresponding table cell selection.

../_images/qematrixview_01.png — QeMatrixView widget

2.7.1.1. Constructor

The constructor signature is

QeMatrixView(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 QeMatrixView
mv = QeMatrixView()
mv.show()

2.7.1.2. Inheritance Hierarchy

QeMatrixView inherits from QMainWindow, giving it native support for toolbars, dock widgets, and menu bars:

2.7.2. Visibility Control

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

Return whether the image view pane is currently visible.

Returns:: True if the image is shown. Default: True.

cut.wdglib.widgets.setImageShown(show: bool) → None

Show or hide the image view pane. Emits ImageShownChanged.

Parameters:: show – True to show the image.

cut.wdglib.widgets.resetImageShown() → None: Reset the image view to shown (True).

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

Return whether the table view pane is currently visible.

Returns:: True if the table is shown. Default: False.

cut.wdglib.widgets.setTableShown(show: bool) → None

Show or hide the table view pane. Emits TableShownChanged.

Parameters:: show – True to show the table.

cut.wdglib.widgets.resetTableShown() → None: Reset the table view to hidden (False).

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

Return whether the image view is disabled. The image is automatically disabled when the data type cannot be displayed (e.g., Unicode string data).

Returns:: True if the image is disabled. Default: False.

cut.wdglib.widgets.setImageDisable(disabled: bool) → None

Enable or disable the image view. When disabled, the image is hidden and the table is shown. Emits ImageDisabledChanged.

Parameters:: disabled – True to disable the image view.

cut.wdglib.widgets.resetImageDisabled() → None: Reset the image to enabled (False).

2.7.3. Data Loading

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

Set the matrix data from a 2-D NumPy array. The array is loaded into both the image view and the table view.

The widget makes an internal copy of the data. Table cell edits are synchronized back to the image view in real time.

Supported dtypes include int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64, bool, and Unicode strings ('U*').

Parameters:: data – A 2-D NumPy array (shape (ny, nx)).
Raises:: TypeError – If the array is not 2-dimensional or the dtype is not supported.

Example:

import numpy as np
from cut.wdglib.widgets import QeMatrixView

mv = QeMatrixView()
data = np.arange(100, dtype=np.float64).reshape(10, 10)
mv.setNumpyNdArray(data)

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

Return the current matrix data as a 2-D NumPy ndarray. If the data has been modified through the table view, the returned array reflects those edits.

Returns:: NumPy ndarray with shape matching the original data passed to setNumpyNdArray(), or None if no data is loaded, if the data is of type String, Boolean, or NotSet.

Example:

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

2.7.4. Data Query Methods

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

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

Returns:: Number of columns (0 if no data loaded).

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

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

Returns:: Number of rows (0 if no data loaded).

2.7.5. Cell Coordinate Methods

cut.wdglib.widgets.showCell(pos: PySide6.QtCore.QPoint) → None

Public slot that converts image coordinates to table cell coordinates, scrolls to and selects the corresponding cell in the table view. Typically connected to the embedded QeImage’s MouseCoordinatesChanged signal when Pointer mode is active (Ctrl+Space).

Parameters:: pos – 1-based coordinates from the image canvas.

2.7.6. Signals

cut.wdglib.widgets.ImageShownChanged(visible: bool)

Emitted when the image view visibility changes via setImageShown().

Parameters:: visible – True if the image is now shown.

cut.wdglib.widgets.TableShownChanged(visible: bool)

Documented as emitted when the table view visibility changes via setTableShown().

Known issue: The current implementation emits ImageShownChanged instead of TableShownChanged when setTableShown() is called. Connecting to this signal will not receive notifications. Use ImageShownChanged as a workaround.

Parameters:: visible – True if the table is now shown.

cut.wdglib.widgets.ImageDisabledChanged(disabled: bool)

Emitted when the image disabled state changes via setImageDisable().

Parameters:: disabled – True if the image is now disabled.

cut.wdglib.widgets.commitData(widget: QWidget)

Emitted when a table cell edit is committed back to the internal data and the image view is updated. The widget argument is the QeMatrixView instance itself.

Parameters:: widget – The QeMatrixView widget that committed the data.

2.7.7. QeTypes Enum

The QeTypes enum is 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.7.8. Example Usage

Basic matrix display:

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

app = QApplication([])
mv = QeMatrixView()

data = np.arange(100, dtype=np.float64).reshape(10, 10)
mv.setNumpyNdArray(data)

# Show both image and table
mv.setTableShown(True)
mv.setImageShown(True)

mv.show()
app.exec()

Data roundtrip with edits:

import numpy as np
from cut.wdglib.widgets import QeMatrixView

mv = QeMatrixView()
original = np.arange(20, dtype=np.float64).reshape(4, 5)
mv.setNumpyNdArray(original)

# After editing cells in the table view:
data = mv.getNumpyNdArray()
print(f"Shape: {data.shape}, dtype: {data.dtype}")

# Query dimensions
print(f"Nx: {mv.getArrayDataNx()}, Ny: {mv.getArrayDataNy()}")

String data (table-only):

import numpy as np
from cut.wdglib.widgets import QeMatrixView

mv = QeMatrixView()
labels = np.array([["alpha", "beta"], ["gamma", "delta"]], dtype='U10')
mv.setNumpyNdArray(labels)

# Image is automatically disabled for string data
print(f"Image disabled: {mv.isImageDisabled()}")  # True
print(f"getNumpyNdArray result: {mv.getNumpyNdArray()}")  # None

Toolbar actions (Pointer mode):

from cut.wdglib.widgets import QeMatrixView
import numpy as np

mv = QeMatrixView()
mv.setNumpyNdArray(np.arange(100, dtype=np.float64).reshape(10, 10))
mv.setTableShown(True)
mv.setImageShown(True)

# In Pointer mode (Ctrl+Space), hovering over the image highlights
# the corresponding cell in the table view. The showCell slot is
# connected to the QeImage MouseCoordinatesChanged signal.

2.7.9. Notes

QeMatrixView inherits from QMainWindow, not QWidget. This means it supports toolbars, dock widgets, and a menu bar natively.
The image view embeds a QeImage widget internally. Its toolbar is docked into the QeMatrixView’s main window.
Default visibility after construction: image shown (True), table hidden (False), image enabled (False for disabled flag).
When data of type Unicode string is loaded, the image view is automatically disabled (setImageDisable(True)) since strings cannot be displayed as color-mapped images. The table view remains functional.
Table cell edits are synchronized back to the image view in real time. The dataChanged signal from the QeArrayModel triggers HandleModelDataChanged which re-attaches the edited vector to the embedded QeImage and emits commitData(this).
The rows in the table view are reversed by default (RowsReversed = True), meaning matrix row 0 appears at the top of the image.
getNumpyNdArray() returns None for String, Boolean, and NotSet data types, even though setNumpyNdArray() accepts Boolean and Unicode string arrays.
The Boolean type is accepted by setNumpyNdArray() but getNumpyNdArray() returns None for Boolean data (the binding helper explicitly handles this).
Known bug: setTableShown() emits ImageShownChanged instead of TableShownChanged. Code relying on the TableShownChanged signal will not receive notifications.