machinevision-toolbox-python 2.3.0__tar.gz → 2.4.0__tar.gz

machinevision_toolbox_python-2.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+    ".": "2.4.0"
+}

machinevision_toolbox_python-2.4.0/AGENTS.md

@@ -0,0 +1,30 @@
+# machinevision-toolbox-python — Agent Instructions
+
+Part of the RVC ecosystem. **Read [rvc-ecosystem/AGENTS.md](https://github.com/petercorke/rvc-ecosystem/blob/main/AGENTS.md) first** — it defines shared conventions: repo ownership, math invariants, dependency boundaries, git/PR workflow, code standards, tech-debt tracking. This file only adds what's specific to this repo.
+
+| | |
+|---|---|
+| PyPI package | `machinevision-toolbox-python` |
+| Nickname | MVTB |
+| Owner | Peter Corke (`petercorke`) |
+| Default branch | `main` |
+| Contribution model | Branch → PR; direct push to `main` at Peter's discretion |
+
+## Notes specific to this repo
+
+- Pure Python — no compiled extensions, builds with Hatch (`hatchling`) directly.
+- Depends on `spatialmath`, `pgraph-python`, `ansitable`, plus the third-party `opencv-python`/
+  `opencv-contrib-python` and `open3d`.
+- `open3d` is consistently a Python version or two behind — never assume it supports the
+  latest Python release; check compatibility before bumping this repo's Python floor/ceiling.
+- OpenCV 5.x support was just added alongside the existing 4.x support (a major version jump,
+  not a minor bump). This is fresh work — aim to keep both working, but treat 4.x/5.x
+  compatibility friction as expected teething problems to fix, not a regression.
+- Tech-debt tracked as GitHub Issues labelled `tech-debt` (migrated 2026-08-02) — this repo
+  was first to migrate off `tech-debt.md`.
+- This repo's `.github/pull_request_template.md` and `.github/ISSUE_TEMPLATE/*.yml` are the
+  canonical source other repos' templates were copied from — check here first if updating
+  template content ecosystem-wide.
+- Codacy is wired in (badge + automated PR comments); grade A is the aspiration. Real backlog
+  exists, tracked via `tech-debt`-labelled issues (including a "mypy not in CI" entry) — see
+  ecosystem `AGENTS.md` §5 for how that target is framed.

{machinevision_toolbox_python-2.3.0 → machinevision_toolbox_python-2.4.0}/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [2.4.0](https://github.com/petercorke/machinevision-toolbox-python/compare/v2.3.0...v2.4.0) (2026-08-25)
+
+
+### Features
+
+* add __array__ protocol to Image and Kernel, ndim to Kernel ([e762f57](https://github.com/petercorke/machinevision-toolbox-python/commit/e762f578faa269655cbd06b02d48c4c30d48c516))
+* relax opencv pin to support both 4.x and 5.x, add CI matrix axis ([2ec69fe](https://github.com/petercorke/machinevision-toolbox-python/commit/2ec69fe4d116bb51f717e0a4a3c8baed95a7101f)), closes [#44](https://github.com/petercorke/machinevision-toolbox-python/issues/44)
+
+
+### Bug Fixes
+
+* assert hygiene -- unreachable assert, two caller-facing checks ([7afe33e](https://github.com/petercorke/machinevision-toolbox-python/commit/7afe33eb02af65d4e64d52481f668a610f63b807))
+* CameraBase.plot() unbound call (self=None) crashed instead of working ([e2d4600](https://github.com/petercorke/machinevision-toolbox-python/commit/e2d460029d6ef1d5bb807168f37b37b3eb10ff1c))
+* catch cv2.error in points2F(), not just F/mask=None ([c4197cb](https://github.com/petercorke/machinevision-toolbox-python/commit/c4197cbd22784b8c002df8a02bb95764dc589b50))
+* correct stale open3d-python PyPI name, add py3.13 exclusion marker ([87c1e8f](https://github.com/petercorke/machinevision-toolbox-python/commit/87c1e8f5a2eb3a2b17f2a1f1c182b22fbb025483))
+* esttheta() -- broken pickregion() helper and missing theta-sweep body ([50b00cc](https://github.com/petercorke/machinevision-toolbox-python/commit/50b00cc95c15b56b3598505f4cd532a0612f6ff9))
+* exclude tests/ from Bandit's assert_used (B101) check ([e62b116](https://github.com/petercorke/machinevision-toolbox-python/commit/e62b116e0b57aef73882ee4689153eda326c399f))
+* Histogram.plot(type='ncdf') never actually worked, docstring lied ([6d4152d](https://github.com/petercorke/machinevision-toolbox-python/commit/6d4152d58bb63970863ff0ca49593c21ec815b5b))
+* idisp() crashes when reuse=True with no title given ([a05b13b](https://github.com/petercorke/machinevision-toolbox-python/commit/a05b13b93ab4ed03397548348e8de48230b284f3))
+* Image.metadata() missing camera-specific Exif sub-IFD tags ([d554ef2](https://github.com/petercorke/machinevision-toolbox-python/commit/d554ef257d2d494c66daaf928114c8097fb8fb91))
+* Image() drops maxintval when dtype= is also given, silently truncating ([15f1d32](https://github.com/petercorke/machinevision-toolbox-python/commit/15f1d32576183c862592dca009828ea7e2765d79))
+* Image(dtype='float') resolved to float64, not float32 ([18c5d85](https://github.com/petercorke/machinevision-toolbox-python/commit/18c5d85d82ebd2c09a43adb278e4435658f0c2b7))
+* ImageConstantsMixin factories silently downcast explicit dtype requests ([977dbf6](https://github.com/petercorke/machinevision-toolbox-python/commit/977dbf6402307f38f695c697d68009ddd914d237))
+* mvtbtool's %precision line spuriously echoes with --showassign ([ed43ca6](https://github.com/petercorke/machinevision-toolbox-python/commit/ed43ca64652a7d64a4536ae5665e672ffcc7db4a))
+* name2color() colororder reordering returns list, not ndarray ([c90e6fb](https://github.com/petercorke/machinevision-toolbox-python/commit/c90e6fb4db7814707fd1548a7d87b1057b665499))
+* PointCloud.Read() double-joins a caller-supplied "data/" prefix ([fff671c](https://github.com/petercorke/machinevision-toolbox-python/commit/fff671cdd28c85a555ee9fc0b7dd6f4bad4eccc9))
+* printstats() crashes if .stats hasn't been accessed yet ([3484224](https://github.com/petercorke/machinevision-toolbox-python/commit/34842247c529159364591528ec109deac182899f))
+* suppress divide-by-zero RuntimeWarning in BagOfWords idf computation ([05c85e0](https://github.com/petercorke/machinevision-toolbox-python/commit/05c85e0189061019dc55888b33ddb30cc3e9d9ae))
+* visual-odometry robustness -- match() metric, points2F(), BundleAdjust ([8691847](https://github.com/petercorke/machinevision-toolbox-python/commit/8691847df58cc3cf003838436f7d94c59d5ae609))
+
+
+### Documentation
+
+* add AGENTS.md stub linking to rvc-ecosystem conventions ([0827291](https://github.com/petercorke/machinevision-toolbox-python/commit/082729184414b821a9e610f8a409f5cbeabc308c))
+* points2F() kwargs -- correct which params apply to which method ([6b10d64](https://github.com/petercorke/machinevision-toolbox-python/commit/6b10d6401925564163568a09e1e504c99eec99fa))
+
 ## [2.3.0](https://github.com/petercorke/machinevision-toolbox-python/compare/v2.2.0...v2.3.0) (2026-08-13)
 
 **Highlight: Notebooks working in all environments** Fixed a number of problems with getting notebooks to execute in desktop Jupyter, Colab, and

{machinevision_toolbox_python-2.3.0 → machinevision_toolbox_python-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: machinevision-toolbox-python
-Version: 2.3.0
+Version: 2.4.0
 Summary: Object-oriented machine vision for Python.
 Project-URL: Homepage, https://github.com/petercorke/machinevision-toolbox-python
 Project-URL: Bug Tracker, https://github.com/pypa/sampleproject/issues
@@ -23,8 +23,8 @@ Requires-Dist: ansitable
 Requires-Dist: matplotlib
 Requires-Dist: mvtb-data
 Requires-Dist: numpy
-Requires-Dist: opencv-contrib-python<5.0.0
-Requires-Dist: opencv-python<5.0.0
+Requires-Dist: opencv-contrib-python<6.0.0,>=4.5
+Requires-Dist: opencv-python<6.0.0,>=4.5
 Requires-Dist: pgraph-python
 Requires-Dist: pillow
 Requires-Dist: requests
@@ -35,7 +35,7 @@ Provides-Extra: all
 Requires-Dist: ipympl; extra == 'all'
 Requires-Dist: ipython; extra == 'all'
 Requires-Dist: ipywidgets; extra == 'all'
-Requires-Dist: open3d-python; extra == 'all'
+Requires-Dist: open3d; (python_version < '3.13') and extra == 'all'
 Requires-Dist: pygments; extra == 'all'
 Requires-Dist: pytesseract; extra == 'all'
 Requires-Dist: rosbags; extra == 'all'
@@ -64,7 +64,7 @@ Requires-Dist: ipywidgets; extra == 'jupyter'
 Provides-Extra: ocr
 Requires-Dist: pytesseract; extra == 'ocr'
 Provides-Extra: open3d
-Requires-Dist: open3d-python; extra == 'open3d'
+Requires-Dist: open3d; (python_version < '3.13') and extra == 'open3d'
 Provides-Extra: ros
 Requires-Dist: rosbags; extra == 'ros'
 Requires-Dist: roslibpy; extra == 'ros'

{machinevision_toolbox_python-2.3.0 → machinevision_toolbox_python-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "machinevision-toolbox-python"
-version = "2.3.0"
+version = "2.4.0"
 authors = [{ name = "Peter Corke", email = "rvc@petercorke.com" }]
 description = "Object-oriented machine vision for Python."
 readme = "README.md"
@@ -39,8 +39,8 @@ dependencies = [
     "scipy",
     "matplotlib",
     "pillow",
-    "opencv-python<5.0.0",
-    "opencv-contrib-python<5.0.0",
+    "opencv-python>=4.5,<6.0.0",
+    "opencv-contrib-python>=4.5,<6.0.0",
     "spatialmath-python",
     "pgraph-python",
     "ansitable",
@@ -86,7 +86,7 @@ docs = [
 
 jupyter = ["ipywidgets", "ipympl"]
 
-open3d = ["open3d-python"]
+open3d = ["open3d; python_version < '3.13'"]
 
 torch = ["torch"]
 
@@ -95,7 +95,7 @@ ocr = ["pytesseract"]
 all = [
     "ipywidgets",
     "ipympl",
-    "open3d-python",
+    "open3d; python_version < '3.13'",
     "torch",
     "pytesseract",
     "rosbags",
@@ -119,6 +119,14 @@ select = ["E", "F", "I"]
 [tool.ruff.lint.isort]
 known-first-party = ["machinevisiontoolbox"]
 
+[tool.bandit]
+# bare `assert` is idiomatic pytest style, not a security concern -- Bandit's
+# B101 ("assert used") is meant for src/, where assert can silently vanish
+# under `python -O`. Excluding tests/ keeps that check meaningful without
+# flagging every test assertion (Codacy runs Bandit via Prospector and
+# honours this file).
+exclude_dirs = ["tests"]
+
 [tool.pyright]
 include = ["src"]
 ignore = ["docs", "tests", "examples"]

{machinevision_toolbox_python-2.3.0 → machinevision_toolbox_python-2.4.0}/src/machinevisiontoolbox/BagOfWords.py

@@ -58,6 +58,13 @@ class BagOfWords:
         of image features is assigned labels from the ``.centroids`` any with a
         label greater that ``.nstopwords`` is a stop word and can be discarded.
 
+        .. note:: Removing stop words can leave a remaining word that never
+            occurs in any image, giving it an inverse document frequency (idf)
+            of ``inf`` (``log(N / 0)``). This is harmless -- every place idf is
+            used to compute a word-frequency vector, the corresponding word
+            count is also always zero there, so the ``0 * inf`` result is
+            ``nan`` and gets replaced with 0 before the vector is returned.
+
         :reference:
             - Video Google: a text retrieval approach to object matching in videos
               J.Sivic and A.Zisserman,
@@ -139,7 +146,12 @@ class BagOfWords:
         # total number of occurrences of word i
         # multiple occurrences in the one image count only as one
         ni = (W > 0).sum(axis=1)
-        idf = np.log(N / ni)
+        # a word that never occurs in any image (ni=0, possible after
+        # stopword removal) gives idf=inf here; harmless since nid is
+        # always 0 at that same position below, so 0*inf->nan, already
+        # suppressed by the invalid="ignore" there.
+        with np.errstate(divide="ignore"):
+            idf = np.log(N / ni)
 
         M = []
 

{machinevision_toolbox_python-2.3.0 → machinevision_toolbox_python-2.4.0}/src/machinevisiontoolbox/BundleAdjust.py

@@ -405,7 +405,8 @@ if pgraph_installed:
 
             :seealso: :meth:`add_view` :meth:`add_landmark`
             """
-            assert len(uv) == 2, "uv must be a 2-vector"
+            if len(uv) != 2:
+                raise ValueError("uv must be a 2-vector")
 
             edge = Observation(viewpoint, landmark, uv.flatten())  # create edge object
             e = viewpoint.connect(landmark, edge=edge)  # connect nodes with it
@@ -562,6 +563,8 @@ if pgraph_installed:
             :type iterations: int, optional
             :param verbose: show Levenberg-Marquadt status, defaults to False
             :type verbose: bool, optional
+            :raises ValueError: no landmark projections have been added to
+                the graph
             :return: optimized state vector
             :rtype: ndarray(N)
 
@@ -578,6 +581,13 @@ if pgraph_installed:
 
             self.update_index()
 
+            if self.g.ne == 0:
+                raise ValueError(
+                    "no landmark projections in the graph -- nothing to "
+                    "optimize (add_projection() was never called, or every "
+                    "candidate landmark was discarded)"
+                )
+
             if x is None:
                 x = self.getstate()
             x0 = x

{machinevision_toolbox_python-2.3.0 → machinevision_toolbox_python-2.4.0}/src/machinevisiontoolbox/Camera.py

@@ -350,7 +350,8 @@ class CameraBase(ABC):
 
         :seealso: :meth:`nv` :meth:`width` :meth:`imagesize`
         """
-        assert self._imagesize is not None, "imagesize not set"
+        if self._imagesize is None:
+            raise ValueError("imagesize not set")
         return self._imagesize[0]
 
     @property
@@ -370,7 +371,8 @@ class CameraBase(ABC):
 
         :seealso: :meth:`nu` :meth:`height`  :meth:`imagesize`
         """
-        assert self._imagesize is not None, "imagesize not set"
+        if self._imagesize is None:
+            raise ValueError("imagesize not set")
         return self._imagesize[1]
 
     @property
@@ -390,7 +392,8 @@ class CameraBase(ABC):
 
         :seealso: :meth:`nu` :meth:`height`
         """
-        assert self._imagesize is not None, "imagesize not set"
+        if self._imagesize is None:
+            raise ValueError("imagesize not set")
         return self._imagesize[0]
 
     @property
@@ -410,7 +413,8 @@ class CameraBase(ABC):
 
         :seealso: :meth:`nv` :meth:`width`
         """
-        assert self._imagesize is not None, "imagesize not set"
+        if self._imagesize is None:
+            raise ValueError("imagesize not set")
         return self._imagesize[1]
 
     @property
@@ -1152,7 +1156,7 @@ class CameraBase(ABC):
         """
         Plot 3D camera icon in world view (base method)
 
-        :param pose: camera pose
+        :param pose: camera pose, required when called unbound (see below)
         :type pose: :class:`~spatialmath.pose3d.SE3`
         :param scale: scale factor, defaults to 1
         :type scale: float
@@ -1170,6 +1174,8 @@ class CameraBase(ABC):
         :type projection: str, optional
         :param ax: axes to draw in, defaults to current 3D axes
         :type ax: :class:`~matplotlib.Axes3D`, optional
+        :raises ValueError: called unbound (eg. ``CentralCamera.plot(...)``)
+            without a ``pose``
         :return: axes drawn into
         :rtype: :class:`~matplotlib.Axes3D`
 
@@ -1177,8 +1183,19 @@ class CameraBase(ABC):
         plot.  Two icons are supported: the traditional frustum, and a
         simplistic camera comprising a box and cylinder.
 
-        .. note:: If ``pose`` is not given it defaults to the pose of the
-            instance.
+        This method can be called two ways:
+
+        - **Bound**, ``camera.plot(...)`` -- draws an icon for ``camera``.
+          ``pose`` defaults to the instance's own pose if not given.
+        - **Unbound**, ``CentralCamera.plot(pose=..., ...)`` -- called on
+          the class itself, with no camera instance involved (``self`` is
+          ``None``). Useful for drawing icons at a set of poses that don't
+          correspond to any single camera instance -- e.g. plotting the
+          calibration frames returned by :meth:`images2C`. ``pose`` is
+          required in this form.
+
+        .. note:: If ``pose`` is not given, it defaults to the pose of
+            ``self`` -- this only applies to the bound form.
         """
 
         # if (fig is None) and (ax is None):
@@ -1195,6 +1212,11 @@ class CameraBase(ABC):
         ax = smb.axes_logic(ax, 3, projection=projection)
 
         if pose is None:
+            if self is None:
+                raise ValueError(
+                    "pose is required when plot() is called unbound, eg. "
+                    "CentralCamera.plot(pose=...)"
+                )
             pose = self.pose
 
         # Matplotlib >=3.10 can raise while autoscaling ragged 3D line
@@ -1216,26 +1238,27 @@ class CameraBase(ABC):
         try:
             # draw camera-like object:
             if shape == "frustum":
-                self._plot_frustum(ax, pose, scale, alpha)
+                CameraBase._plot_frustum(ax, pose, scale, alpha)
 
             elif shape == "camera":
-                self._plot_camera_icon(ax, pose, scale, solid, color, alpha, label)
+                CameraBase._plot_camera_icon(ax, pose, scale, solid, color, alpha, label)
 
             if frame is True:
-                self.pose.plot(
+                pose.plot(
                     length=scale * 1.5,
                     style="line",
                     color=color,
                     flo=(0.07, 0, -0.01),
                 )
             elif frame is not False:
-                self.pose.plot(**frame)
+                pose.plot(**frame)
         finally:
             ax.add_collection3d = _orig_add_collection3d
 
         return ax
 
-    def _plot_frustum(self, ax: Axes, pose: SE3, scale: float, alpha: float) -> None:
+    @staticmethod
+    def _plot_frustum(ax: Axes, pose: SE3, scale: float, alpha: float) -> None:
         """Draw the ``shape="frustum"`` camera icon into ``ax``."""
         # TODO make this kwargs or optional inputs
         # side colors:
@@ -1279,8 +1302,8 @@ class CameraBase(ABC):
         poly = Poly3DCollection(points, facecolors=["r", "g", "r", "y"], alpha=alpha)
         ax.add_collection3d(poly)
 
+    @staticmethod
     def _plot_camera_icon(
-        self,
         ax: Axes,
         pose: SE3,
         scale: float,
@@ -2684,8 +2707,41 @@ class CentralCamera(CameraBase):
         :type p2: ndarray(2,N)
         :param method: algorithm '7p', '8p' [default], 'ransac', 'lmeds'
         :type method: str, optional
-        :param kwargs: optional arguments as required for ransac', 'lmeds'
-            methods
+        :param residual: also return the reprojection residual, defaults to True
+        :type residual: bool, optional
+        :param seed: seed the RNG used by 'ransac'/'lmeds' for repeatable
+            results, defaults to None (not seeded)
+        :type seed: int, optional
+        :param kwargs: passed through to ``cv2.findFundamentalMat``.
+            ``ransacReprojThreshold`` (float, defaults to 3.0) applies only
+            when ``method='ransac'`` -- max distance in pixels from a point
+            to its epipolar line for the point to still count as an inlier;
+            ``method='lmeds'`` ignores it entirely (verified empirically --
+            identical result regardless of value). ``confidence`` (float in
+            (0,1), defaults to 0.99) and ``maxIters`` (int, defaults to
+            1000) apply to either ``method='ransac'`` or ``method='lmeds'``
+            -- ``method`` only ever selects one algorithm at a time (a
+            combined "ransac+lmeds" method isn't a real OpenCV feature;
+            verified empirically that OR-ing the two method flags together
+            doesn't error, but silently reduces to plain LMedS -- an
+            implementation accident, not a documented hybrid mode).
+            Defaults verified empirically 2026-08-16 (identical inlier
+            masks with/without them explicit, same RNG seed) -- not
+            otherwise documented by the ``cv2`` Python bindings. Same
+            parameter set and defaults on OpenCV 4.10 and 5.0.
+
+            .. warning:: ``maxIters`` only works when ``ransacReprojThreshold``
+                and ``confidence`` are *also* given explicitly -- passing
+                only ``maxIters=`` hits a ``cv2.findFundamentalMat``
+                overload-resolution failure (a confusing low-level OpenCV
+                error, not a clear Python one), since the 3-argument
+                overload this method otherwise uses has no ``maxIters``
+                parameter at all.
+        :type kwargs: dict, optional
+        :raises ValueError: fewer than the minimum number of point
+            correspondences for ``method`` (7 for '7p', 8 otherwise), or
+            the points are too degenerate (eg. coplanar, collinear) for
+            ``cv2.findFundamentalMat`` to estimate F from
         :return: fundamental matrix and residual
         :rtype: ndarray(3,3), float
 
@@ -2719,13 +2775,40 @@ class CentralCamera(CameraBase):
             "ransac": cv2.FM_RANSAC,
             "lmeds": cv2.FM_LMEDS,
         }
+        min_points = 7 if method == "7p" else 8
+        if p1.shape[1] < min_points:
+            raise ValueError(
+                f"points2F() needs at least {min_points} point correspondences "
+                f"for method={method!r}, got {p1.shape[1]}"
+            )
 
         if seed is not None:
             cv2.setRNGSeed(seed)
 
-        F, mask = cv2.findFundamentalMat(
-            points1=p1.T, points2=p2.T, method=points2F_dict[method], **kwargs
-        )
+        try:
+            F, mask = cv2.findFundamentalMat(
+                points1=p1.T, points2=p2.T, method=points2F_dict[method], **kwargs
+            )
+        except cv2.error as e:
+            # on some degenerate point configurations cv2.findFundamentalMat
+            # raises a raw C++ assertion (eg. a Mat rowRange error) instead
+            # of returning None -- same underlying cause as the F is None
+            # case below, just surfaced differently by OpenCV
+            raise ValueError(
+                f"cv2.findFundamentalMat could not estimate F from "
+                f"{p1.shape[1]} point correspondences using method={method!r} "
+                f"-- points are likely too degenerate (eg. coplanar, collinear): {e}"
+            ) from e
+
+        if F is None or mask is None:
+            # already know p1.shape[1] >= min_points (checked above), so a
+            # failure here means the points themselves are degenerate (eg.
+            # coplanar, collinear), not a raw-count problem
+            raise ValueError(
+                f"cv2.findFundamentalMat could not estimate F from "
+                f"{p1.shape[1]} point correspondences using method={method!r} "
+                "-- points are likely too degenerate (eg. coplanar, collinear)"
+            )
 
         mask = mask.ravel().astype(bool)
 

{machinevision_toolbox_python-2.3.0 → machinevision_toolbox_python-2.4.0}/src/machinevisiontoolbox/ImageConstants.py

@@ -23,7 +23,7 @@ from spatialmath import base as smb
 from spatialmath.base import islistof, isscalar
 
 # from numpy.lib.arraysetops import isin
-from machinevisiontoolbox.base import float_image, int_image, name2color
+from machinevisiontoolbox.base import DTYPE_ALIASES, float_image, int_image, name2color
 from machinevisiontoolbox.base.imageio import convert, idisp, iread, iwrite
 from machinevisiontoolbox.Kernel import Kernel
 from machinevisiontoolbox.mvtb_types import Dtype
@@ -110,6 +110,9 @@ def _resolve_pattern_options(
         else:
             dtype = default_dtype
 
+    if isinstance(dtype, str):
+        dtype = DTYPE_ALIASES.get(dtype, dtype)
+
     if colororder is None and like is not None and like.iscolor:
         colororder = like.colororder_str.replace(":", "")
 
@@ -121,7 +124,7 @@ def _pattern_image(cls, image: np.ndarray, colororder: str | None):
         image = np.repeat(
             image[..., np.newaxis], len(cls.colordict(colororder)), axis=2
         )
-    return cls(image, colororder=colororder)
+    return cls(image, colororder=colororder, dtype=True)
 
 
 class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
@@ -145,6 +148,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type colororder: str
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param like: template image supplying default ``size`` and ``colororder``
             when those are not given explicitly
         :type like: :class:`Image` or None, optional
@@ -179,7 +184,7 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         )
 
         shape = _getshape(cls, None, None, colororder, size)
-        return cls(np.zeros(shape, dtype=dtype), colororder=colororder)
+        return cls(np.zeros(shape, dtype=dtype), colororder=colororder, dtype=True)
 
     @classmethod
     def Constant(
@@ -202,6 +207,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type colororder: str
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param like: template image supplying default ``size``, ``dtype`` and
             ``colororder`` when those are not given explicitly
         :type like: :class:`Image` or None, optional
@@ -258,11 +265,11 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
             planes = []
             for bg in value:
                 planes.append(np.full(shape[:2], bg, dtype=dtype))
-            return cls(np.stack(planes, axis=2), colororder=colororder)
+            return cls(np.stack(planes, axis=2), colororder=colororder, dtype=True)
 
         else:
             # scalar
-            return cls(np.full(shape, value, dtype=dtype))
+            return cls(np.full(shape, value, dtype=dtype), dtype=True)
 
     @classmethod
     def String(
@@ -406,6 +413,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type colororder: str
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param maxval: maximum value for random values, defaults to None
         :type maxval: same as ``dtype``, optional
         :param pdf: probability density function for pixel values, defaults to None
@@ -535,7 +544,7 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
             else:
                 raise ValueError("pdf must be a 1D or 2D array")
 
-        return cls(im, colororder=colororder)
+        return cls(im, colororder=colororder, dtype=True)
 
     @classmethod
     def Squares(
@@ -562,6 +571,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type bg: int, optional
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -654,6 +665,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type bg: int, optional
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -746,6 +759,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type cycles: int, optional
         :param dtype: NumPy datatype, defaults to 'float32'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -842,6 +857,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type cycles: int, optional
         :param dtype: NumPy datatype, defaults to 'float32'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -922,6 +939,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type square: int, optional
         :param dtype: image data type, defaults to "uint8"
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -1012,6 +1031,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type shift: int, optional
         :param dtype: image data type, defaults to "uint8"
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and