QML Widget Models

@QmlElement
class Vec2Model(QObject):
    """Holds a Vec2 and exposes its components as QML properties."""

    valueChanged = Signal()

    def __init__(self, parent: QObject | None = None) -> None:
        """Initialize the model with a zero Vec2.

        Args:
            parent: The parent QObject.
        """
        super().__init__(parent)
        self._value = Vec2(0.0, 0.0)

    def get_x(self) -> float:
        """Return the x component.

        Returns:
            The current x value.
        """
        return float(self._value.x)

    def set_x(self, value: float) -> None:
        """Set the x component and emit valueChanged.

        Args:
            value: The new x value.
        """
        self._value.x = value
        self.valueChanged.emit()

    def get_y(self) -> float:
        """Return the y component.

        Returns:
            The current y value.
        """
        return float(self._value.y)

    def set_y(self, value: float) -> None:
        """Set the y component and emit valueChanged.

        Args:
            value: The new y value.
        """
        self._value.y = value
        self.valueChanged.emit()

    x = Property(float, get_x, set_x, notify=valueChanged)
    y = Property(float, get_y, set_y, notify=valueChanged)

    @Slot(result=Vec2)
    def get_value(self) -> Vec2:
        """Return the current Vec2 value.

        Returns:
            The current value.
        """
        return self._value

    @Slot(Vec2)
    def set_value(self, value: Vec2) -> None:
        """Replace the current value and emit valueChanged.

        Args:
            value: The new Vec2 value.
        """
        self._value = value
        self.valueChanged.emit()

@QmlElement
class Vec3Model(QObject):
    """Holds a Vec3 and exposes its components as QML properties."""

    valueChanged = Signal()

    def __init__(self, parent: QObject | None = None) -> None:
        """Initialize the model with a zero Vec3.

        Args:
            parent: The parent QObject.
        """
        super().__init__(parent)
        self._value = Vec3(0.0, 0.0, 0.0)

    def get_x(self) -> float:
        """Return the x component.

        Returns:
            The current x value.
        """
        return float(self._value.x)

    def set_x(self, value: float) -> None:
        """Set the x component and emit valueChanged.

        Args:
            value: The new x value.
        """
        self._value.x = value
        self.valueChanged.emit()

    def get_y(self) -> float:
        """Return the y component.

        Returns:
            The current y value.
        """
        return float(self._value.y)

    def set_y(self, value: float) -> None:
        """Set the y component and emit valueChanged.

        Args:
            value: The new y value.
        """
        self._value.y = value
        self.valueChanged.emit()

    def get_z(self) -> float:
        """Return the z component.

        Returns:
            The current z value.
        """
        return float(self._value.z)

    def set_z(self, value: float) -> None:
        """Set the z component and emit valueChanged.

        Args:
            value: The new z value.
        """
        self._value.z = value
        self.valueChanged.emit()

    x = Property(float, get_x, set_x, notify=valueChanged)
    y = Property(float, get_y, set_y, notify=valueChanged)
    z = Property(float, get_z, set_z, notify=valueChanged)

    @Slot(result=Vec3)
    def get_value(self) -> Vec3:
        """Return the current Vec3 value.

        Returns:
            The current value.
        """
        return self._value

    @Slot(Vec3)
    def set_value(self, value: Vec3) -> None:
        """Replace the current value and emit valueChanged.

        Args:
            value: The new Vec3 value.
        """
        self._value = value
        self.valueChanged.emit()

@QmlElement
class Vec4Model(QObject):
    """Holds a Vec4 and exposes its components as QML properties."""

    valueChanged = Signal()

    def __init__(self, parent: QObject | None = None) -> None:
        """Initialize the model with a zero Vec4.

        Args:
            parent: The parent QObject.
        """
        super().__init__(parent)
        self._value = Vec4(0.0, 0.0, 0.0, 0.0)

    def get_x(self) -> float:
        """Return the x component.

        Returns:
            The current x value.
        """
        return float(self._value.x)

    def set_x(self, value: float) -> None:
        """Set the x component and emit valueChanged.

        Args:
            value: The new x value.
        """
        self._value.x = value
        self.valueChanged.emit()

    def get_y(self) -> float:
        """Return the y component.

        Returns:
            The current y value.
        """
        return float(self._value.y)

    def set_y(self, value: float) -> None:
        """Set the y component and emit valueChanged.

        Args:
            value: The new y value.
        """
        self._value.y = value
        self.valueChanged.emit()

    def get_z(self) -> float:
        """Return the z component.

        Returns:
            The current z value.
        """
        return float(self._value.z)

    def set_z(self, value: float) -> None:
        """Set the z component and emit valueChanged.

        Args:
            value: The new z value.
        """
        self._value.z = value
        self.valueChanged.emit()

    def get_w(self) -> float:
        """Return the w component.

        Returns:
            The current w value.
        """
        return float(self._value.w)

    def set_w(self, value: float) -> None:
        """Set the w component and emit valueChanged.

        Args:
            value: The new w value.
        """
        self._value.w = value
        self.valueChanged.emit()

    x = Property(float, get_x, set_x, notify=valueChanged)
    y = Property(float, get_y, set_y, notify=valueChanged)
    z = Property(float, get_z, set_z, notify=valueChanged)
    w = Property(float, get_w, set_w, notify=valueChanged)

    @Slot(result=Vec4)
    def get_value(self) -> Vec4:
        """Return the current Vec4 value.

        Returns:
            The current value.
        """
        return self._value

    @Slot(Vec4)
    def set_value(self, value: Vec4) -> None:
        """Replace the current value and emit valueChanged.

        Args:
            value: The new Vec4 value.
        """
        self._value = value
        self.valueChanged.emit()

@QmlElement
class TransformModel(QObject):
    """Combines position/rotation/scale Vec3Models into a Mat4 transform."""

    valueChanged = Signal()

    def __init__(self, parent: QObject | None = None) -> None:
        """Initialize child position/rotation/scale models and compute the matrix.

        Args:
            parent: The parent QObject.
        """
        super().__init__(parent)
        self._position = Vec3Model(self)
        self._rotation = Vec3Model(self)
        self._scale = Vec3Model(self)
        self._scale.x = 1.0
        self._scale.y = 1.0
        self._scale.z = 1.0
        self._rotation_order_index = 0
        self._matrix = Mat4()
        self._position.valueChanged.connect(self._update_matrix)
        self._rotation.valueChanged.connect(self._update_matrix)
        self._scale.valueChanged.connect(self._update_matrix)
        self._update_matrix()

    def get_position(self) -> Vec3Model:
        """Return the position child model.

        Returns:
            The position Vec3Model.
        """
        return self._position

    def get_rotation(self) -> Vec3Model:
        """Return the rotation child model.

        Returns:
            The rotation Vec3Model.
        """
        return self._rotation

    def get_scale(self) -> Vec3Model:
        """Return the scale child model.

        Returns:
            The scale Vec3Model.
        """
        return self._scale

    position = Property(QObject, get_position, constant=True)
    rotation = Property(QObject, get_rotation, constant=True)
    scale = Property(QObject, get_scale, constant=True)

    def get_rotation_order_index(self) -> int:
        """Return the index into ROTATION_ORDERS currently in use.

        Returns:
            The current rotation order index.
        """
        return self._rotation_order_index

    def set_rotation_order_index(self, index: int) -> None:
        """Set the rotation order by index and recompute the matrix.

        Args:
            index: An index into ROTATION_ORDERS.
        """
        self._rotation_order_index = index
        self._update_matrix()

    rotationOrderIndex = Property(
        int, get_rotation_order_index, set_rotation_order_index, notify=valueChanged
    )

    @Slot(result=list)
    def rotation_orders(self) -> list:
        """Return the ordered list of valid rotation order strings.

        Returns:
            The rotation order names, in combo-box order.
        """
        return list(ROTATION_ORDERS)

    def _update_matrix(self) -> None:
        """Recompute the transform matrix from the current child values."""
        position = self._position.get_value()
        rotation = self._rotation.get_value()
        scale = self._scale.get_value()

        tx = Transform()
        tx.set_order(ROTATION_ORDERS[self._rotation_order_index])
        tx.set_position(position.x, position.y, position.z)
        tx.set_rotation(rotation.x, rotation.y, rotation.z)
        tx.set_scale(scale.x, scale.y, scale.z)
        self._matrix = tx.matrix()
        self.valueChanged.emit()

    @Slot(result=Mat4)
    def get_matrix(self) -> Mat4:
        """Return the current transform matrix.

        Returns:
            The current Mat4.
        """
        return self._matrix

    matrix = Property(Mat4, get_matrix, notify=valueChanged)

    @Slot(result=str)
    def matrix_text(self) -> str:
        """Return the current matrix formatted as a readable multi-line string.

        Returns:
            The matrix formatted with 2 decimal places per cell.
        """
        rows = [
            " ".join(f"{self._matrix[r][c]:6.2f}" for c in range(4)) for r in range(4)
        ]
        return "\n".join(rows)

@QmlElement
class LookAtModel(QObject):
    """Combines eye/look Vec3Models and a world-up choice into a view Mat4."""

    valueChanged = Signal()

    def __init__(self, parent: QObject | None = None) -> None:
        """Initialize eye/look child models and compute the initial view matrix.

        Args:
            parent: The parent QObject.
        """
        super().__init__(parent)
        self._eye = Vec3Model(self)
        self._eye.x = 2.0
        self._eye.y = 2.0
        self._eye.z = 2.0
        self._look = Vec3Model(self)
        self._up_index = 0
        self._matrix = Mat4()
        self._eye.valueChanged.connect(self._update_matrix)
        self._look.valueChanged.connect(self._update_matrix)
        self._update_matrix()

    def get_eye(self) -> Vec3Model:
        """Return the eye child model.

        Returns:
            The eye Vec3Model.
        """
        return self._eye

    def get_look(self) -> Vec3Model:
        """Return the look-at child model.

        Returns:
            The look Vec3Model.
        """
        return self._look

    eye = Property(QObject, get_eye, constant=True)
    look = Property(QObject, get_look, constant=True)

    def get_up_index(self) -> int:
        """Return the index into WORLD_UP currently in use.

        Returns:
            The current world-up index.
        """
        return self._up_index

    def set_up_index(self, index: int) -> None:
        """Set the world-up vector by index and recompute the matrix.

        Args:
            index: An index into WORLD_UP.
        """
        self._up_index = index
        self._update_matrix()

    upIndex = Property(int, get_up_index, set_up_index, notify=valueChanged)

    @Slot(result=list)
    def up_names(self) -> list:
        """Return the ordered list of world-up display names.

        Returns:
            The world-up names, in combo-box order.
        """
        return list(WORLD_UP_NAMES)

    def _update_matrix(self) -> None:
        """Recompute the view matrix from the current eye/look/up values."""
        eye = self._eye.get_value()
        look = self._look.get_value()
        up = WORLD_UP[self._up_index]
        self._matrix = look_at(eye, look, up)
        self.valueChanged.emit()

    @Slot(result=Mat4)
    def get_matrix(self) -> Mat4:
        """Return the current view matrix.

        Returns:
            The current Mat4.
        """
        return self._matrix

    matrix = Property(Mat4, get_matrix, notify=valueChanged)

    @Slot(result=str)
    def matrix_text(self) -> str:
        """Return the current matrix formatted as a readable multi-line string.

        Returns:
            The matrix formatted with 2 decimal places per cell.
        """
        rows = [
            " ".join(f"{self._matrix[r][c]:6.2f}" for c in range(4)) for r in range(4)
        ]
        return "\n".join(rows)

@QmlElement
class PerspectiveModel(QObject):
    """Combines fov/aspect/near/far and a clip-space mode into a perspective Mat4."""

    valueChanged = Signal()

    def __init__(self, parent: QObject | None = None) -> None:
        """Initialize the model with default projection parameters.

        Args:
            parent: The parent QObject.
        """
        super().__init__(parent)
        self._fov = 45.0
        self._aspect = 1.333
        self._near = 0.1
        self._far = 100.0
        self._mode_index = 0
        self._matrix = Mat4()
        self._update_matrix()

    def get_fov(self) -> float:
        """Return the field of view in degrees.

        Returns:
            The current fov value.
        """
        return self._fov

    def set_fov(self, value: float) -> None:
        """Set the field of view and recompute the matrix.

        Args:
            value: The new fov value in degrees.
        """
        self._fov = value
        self._update_matrix()

    fov = Property(float, get_fov, set_fov, notify=valueChanged)

    def get_aspect(self) -> float:
        """Return the aspect ratio.

        Returns:
            The current aspect ratio.
        """
        return self._aspect

    def set_aspect(self, value: float) -> None:
        """Set the aspect ratio and recompute the matrix.

        Args:
            value: The new aspect ratio.
        """
        self._aspect = value
        self._update_matrix()

    aspect = Property(float, get_aspect, set_aspect, notify=valueChanged)

    def get_near(self) -> float:
        """Return the near clipping plane distance.

        Returns:
            The current near value.
        """
        return self._near

    def set_near(self, value: float) -> None:
        """Set the near clipping plane distance and recompute the matrix.

        Args:
            value: The new near value.
        """
        self._near = value
        self._update_matrix()

    near = Property(float, get_near, set_near, notify=valueChanged)

    def get_far(self) -> float:
        """Return the far clipping plane distance.

        Returns:
            The current far value.
        """
        return self._far

    def set_far(self, value: float) -> None:
        """Set the far clipping plane distance and recompute the matrix.

        Args:
            value: The new far value.
        """
        self._far = value
        self._update_matrix()

    far = Property(float, get_far, set_far, notify=valueChanged)

    def get_mode_index(self) -> int:
        """Return the index into MODE_NAMES currently in use.

        Returns:
            The current mode index.
        """
        return self._mode_index

    def set_mode_index(self, index: int) -> None:
        """Set the clip-space mode by index and recompute the matrix.

        Args:
            index: An index into MODE_NAMES/MODES.
        """
        self._mode_index = index
        self._update_matrix()

    modeIndex = Property(int, get_mode_index, set_mode_index, notify=valueChanged)

    @Slot(result=list)
    def mode_names(self) -> list:
        """Return the ordered list of clip-space mode display names.

        Returns:
            The mode names, in combo-box order.
        """
        return list(MODE_NAMES)

    def _update_matrix(self) -> None:
        """Recompute the perspective matrix from the current property values."""
        self._matrix = perspective(
            self._fov, self._aspect, self._near, self._far, MODES[self._mode_index]
        )
        self.valueChanged.emit()

    @Slot(result=Mat4)
    def get_matrix(self) -> Mat4:
        """Return the current perspective matrix.

        Returns:
            The current Mat4.
        """
        return self._matrix

    matrix = Property(Mat4, get_matrix, notify=valueChanged)

    @Slot(result=str)
    def matrix_text(self) -> str:
        """Return the current matrix formatted as a readable multi-line string.

        Returns:
            The matrix formatted with 2 decimal places per cell.
        """
        rows = [
            " ".join(f"{self._matrix[r][c]:6.2f}" for c in range(4)) for r in range(4)
        ]
        return "\n".join(rows)

@QmlElement
class RGBColourModel(QObject):
    """Holds an RGB Vec3 colour and exposes r/g/b plus a hex swatch colour."""

    colourChanged = Signal()

    def __init__(self, parent: QObject | None = None) -> None:
        """Initialize the model with white (1, 1, 1).

        Args:
            parent: The parent QObject.
        """
        super().__init__(parent)
        self._colour = Vec3(1.0, 1.0, 1.0)

    def get_r(self) -> float:
        """Return the red channel.

        Returns:
            The current red value.
        """
        return float(self._colour.x)

    def set_r(self, value: float) -> None:
        """Set the red channel and emit colourChanged.

        Args:
            value: The new red value.
        """
        self._colour.x = value
        self.colourChanged.emit()

    def get_g(self) -> float:
        """Return the green channel.

        Returns:
            The current green value.
        """
        return float(self._colour.y)

    def set_g(self, value: float) -> None:
        """Set the green channel and emit colourChanged.

        Args:
            value: The new green value.
        """
        self._colour.y = value
        self.colourChanged.emit()

    def get_b(self) -> float:
        """Return the blue channel.

        Returns:
            The current blue value.
        """
        return float(self._colour.z)

    def set_b(self, value: float) -> None:
        """Set the blue channel and emit colourChanged.

        Args:
            value: The new blue value.
        """
        self._colour.z = value
        self.colourChanged.emit()

    r = Property(float, get_r, set_r, notify=colourChanged)
    g = Property(float, get_g, set_g, notify=colourChanged)
    b = Property(float, get_b, set_b, notify=colourChanged)

    def get_hex(self) -> str:
        """Return the colour as a `#RRGGBB` hex string.

        Returns:
            The hex colour string.
        """
        return QColor.fromRgbF(self._colour.x, self._colour.y, self._colour.z).name()

    hex = Property(str, get_hex, notify=colourChanged)

    @Slot(result=Vec3)
    def get_value(self) -> Vec3:
        """Return the current colour as a Vec3.

        Returns:
            The current colour.
        """
        return self._colour

    @Slot(Vec3)
    def set_value(self, value: Vec3) -> None:
        """Replace the current colour and emit colourChanged.

        Args:
            value: The new colour value.
        """
        self._colour = value
        self.colourChanged.emit()