machinevision-toolbox-python 0.9.7__tar.gz → 1.0.0__tar.gz

{machinevision_toolbox_python-0.9.7 → machinevision_toolbox_python-1.0.0}/PKG-INFO

@@ -1,27 +1,27 @@
 Metadata-Version: 2.1
 Name: machinevision-toolbox-python
-Version: 0.9.7
+Version: 1.0.0
 Summary: Python tools for machine vision - education and research
 Author: Dorian Tsai
 Author-email: Peter Corke <rvc@petercorke.com>
 Project-URL: Homepage, https://github.com/petercorke/machinevision-toolbox-python
 Project-URL: Bug Tracker, https://github.com/pypa/sampleproject/issues
 Project-URL: Documentation, https://petercorke.github.io/machinevision-toolbox-python
-Project-URL: Source, https://github.com/petercorke/machinevision-toolbox-python
+Project-URL: GitHub Source, https://github.com/petercorke/machinevision-toolbox-python
+Project-URL: Changelog, https://github.com/petercorke/machinevision-toolbox-python/blob/master/CHANGELOG.md
 Keywords: machine vision,computer vision,multiview geometry,stereo vision,bundle adjustment,visual servoing,image features,color,blobs,morphology,image segmentation,opencv,open3d
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy>=1.17.4
+Requires-Dist: numpy<2.0.0,>=1.17.4
 Requires-Dist: scipy
 Requires-Dist: matplotlib
 Requires-Dist: opencv-python
@@ -56,7 +56,7 @@ Requires-Dist: sphinx-favicon; extra == "docs"
 [![Powered by Open3D](https://raw.githubusercontent.com/petercorke/machinevision-toolbox-python/master/.github/svg/open3d_powered.svg)](https://open3d.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-[![Build Status](https://github.com/petercorke/machinevision-toolbox-python/workflows/Test-master/badge.svg?branch=master)](https://github.com/petercorke/machinevision-toolbox-python/actions?query=workflow%3Abuild)
+[![Build Status](https://github.com/petercorke/machinevision-toolbox-python/actions/workflows/main.yml/badge.svg)](https://github.com/petercorke/machinevision-toolbox-python/actions?query=workflow%3Abuild)
 [![Coverage](https://codecov.io/gh/petercorke/machinevision-toolbox-python/branch/master/graph/badge.svg)](https://codecov.io/gh/petercorke/machinevision-toolbox-python)
 [![PyPI - Downloads](https://img.shields.io/pypi/dw/machinevision-toolbox-python)](https://pypistats.org/packages/machinevision-toolbox-python)
 
@@ -68,16 +68,17 @@ Requires-Dist: sphinx-favicon; extra == "docs"
 <img src="https://github.com/petercorke/machinevision-toolbox-python/raw/master/figs/VisionToolboxLogo_NoBackgnd@2x.png" width="200"></td>
 <td style="border:0px">
 
-A Python implementation of the <a href="https://github.com/petercorke/machinevision-toolbox-matlab">Machine Vision Toolbox for MATLAB<sup>&reg;</sup></a><ul>
-
 <li><a href="https://github.com/petercorke/machinevision-toolbox-python">GitHub repository </a></li>
 <li><a href="https://petercorke.github.io/machinevision-toolbox-python/">Documentation</a></li>
 <li><a href="https://github.com/petercorke/machinevision-toolbox-python/wiki">Examples and details</a></li>
 <li><a href="installation#">Installation</a></li>
+<li><a href="https://github.com/petercorke/machinevision-toolbox-python/wiki">Examples and details</a></li>
+<li><a href="https://github.com/petercorke/machinevision-toolbox-python/blob/master/CHANGELOG.md">Changelog</a></li>
 </ul>
 </td>
 </tr>
 </table>
+<p style="font-size:80%">A Python implementation of the <a href="https://github.com/petercorke/machinevision-toolbox-matlab">Machine Vision Toolbox for MATLAB<sup>&reg;</sup></a></p>
 
 ## Synopsis
 

{machinevision_toolbox_python-0.9.7 → machinevision_toolbox_python-1.0.0}/README.md

@@ -10,7 +10,7 @@
 [![Powered by Open3D](https://raw.githubusercontent.com/petercorke/machinevision-toolbox-python/master/.github/svg/open3d_powered.svg)](https://open3d.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-[![Build Status](https://github.com/petercorke/machinevision-toolbox-python/workflows/Test-master/badge.svg?branch=master)](https://github.com/petercorke/machinevision-toolbox-python/actions?query=workflow%3Abuild)
+[![Build Status](https://github.com/petercorke/machinevision-toolbox-python/actions/workflows/main.yml/badge.svg)](https://github.com/petercorke/machinevision-toolbox-python/actions?query=workflow%3Abuild)
 [![Coverage](https://codecov.io/gh/petercorke/machinevision-toolbox-python/branch/master/graph/badge.svg)](https://codecov.io/gh/petercorke/machinevision-toolbox-python)
 [![PyPI - Downloads](https://img.shields.io/pypi/dw/machinevision-toolbox-python)](https://pypistats.org/packages/machinevision-toolbox-python)
 
@@ -22,16 +22,17 @@
 <img src="https://github.com/petercorke/machinevision-toolbox-python/raw/master/figs/VisionToolboxLogo_NoBackgnd@2x.png" width="200"></td>
 <td style="border:0px">
 
-A Python implementation of the <a href="https://github.com/petercorke/machinevision-toolbox-matlab">Machine Vision Toolbox for MATLAB<sup>&reg;</sup></a><ul>
-
 <li><a href="https://github.com/petercorke/machinevision-toolbox-python">GitHub repository </a></li>
 <li><a href="https://petercorke.github.io/machinevision-toolbox-python/">Documentation</a></li>
 <li><a href="https://github.com/petercorke/machinevision-toolbox-python/wiki">Examples and details</a></li>
 <li><a href="installation#">Installation</a></li>
+<li><a href="https://github.com/petercorke/machinevision-toolbox-python/wiki">Examples and details</a></li>
+<li><a href="https://github.com/petercorke/machinevision-toolbox-python/blob/master/CHANGELOG.md">Changelog</a></li>
 </ul>
 </td>
 </tr>
 </table>
+<p style="font-size:80%">A Python implementation of the <a href="https://github.com/petercorke/machinevision-toolbox-matlab">Machine Vision Toolbox for MATLAB<sup>&reg;</sup></a></p>
 
 ## Synopsis
 

{machinevision_toolbox_python-0.9.7 → machinevision_toolbox_python-1.0.0}/machinevision_toolbox_python.egg-info/PKG-INFO

@@ -1,27 +1,27 @@
 Metadata-Version: 2.1
 Name: machinevision-toolbox-python
-Version: 0.9.7
+Version: 1.0.0
 Summary: Python tools for machine vision - education and research
 Author: Dorian Tsai
 Author-email: Peter Corke <rvc@petercorke.com>
 Project-URL: Homepage, https://github.com/petercorke/machinevision-toolbox-python
 Project-URL: Bug Tracker, https://github.com/pypa/sampleproject/issues
 Project-URL: Documentation, https://petercorke.github.io/machinevision-toolbox-python
-Project-URL: Source, https://github.com/petercorke/machinevision-toolbox-python
+Project-URL: GitHub Source, https://github.com/petercorke/machinevision-toolbox-python
+Project-URL: Changelog, https://github.com/petercorke/machinevision-toolbox-python/blob/master/CHANGELOG.md
 Keywords: machine vision,computer vision,multiview geometry,stereo vision,bundle adjustment,visual servoing,image features,color,blobs,morphology,image segmentation,opencv,open3d
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy>=1.17.4
+Requires-Dist: numpy<2.0.0,>=1.17.4
 Requires-Dist: scipy
 Requires-Dist: matplotlib
 Requires-Dist: opencv-python
@@ -56,7 +56,7 @@ Requires-Dist: sphinx-favicon; extra == "docs"
 [![Powered by Open3D](https://raw.githubusercontent.com/petercorke/machinevision-toolbox-python/master/.github/svg/open3d_powered.svg)](https://open3d.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-[![Build Status](https://github.com/petercorke/machinevision-toolbox-python/workflows/Test-master/badge.svg?branch=master)](https://github.com/petercorke/machinevision-toolbox-python/actions?query=workflow%3Abuild)
+[![Build Status](https://github.com/petercorke/machinevision-toolbox-python/actions/workflows/main.yml/badge.svg)](https://github.com/petercorke/machinevision-toolbox-python/actions?query=workflow%3Abuild)
 [![Coverage](https://codecov.io/gh/petercorke/machinevision-toolbox-python/branch/master/graph/badge.svg)](https://codecov.io/gh/petercorke/machinevision-toolbox-python)
 [![PyPI - Downloads](https://img.shields.io/pypi/dw/machinevision-toolbox-python)](https://pypistats.org/packages/machinevision-toolbox-python)
 
@@ -68,16 +68,17 @@ Requires-Dist: sphinx-favicon; extra == "docs"
 <img src="https://github.com/petercorke/machinevision-toolbox-python/raw/master/figs/VisionToolboxLogo_NoBackgnd@2x.png" width="200"></td>
 <td style="border:0px">
 
-A Python implementation of the <a href="https://github.com/petercorke/machinevision-toolbox-matlab">Machine Vision Toolbox for MATLAB<sup>&reg;</sup></a><ul>
-
 <li><a href="https://github.com/petercorke/machinevision-toolbox-python">GitHub repository </a></li>
 <li><a href="https://petercorke.github.io/machinevision-toolbox-python/">Documentation</a></li>
 <li><a href="https://github.com/petercorke/machinevision-toolbox-python/wiki">Examples and details</a></li>
 <li><a href="installation#">Installation</a></li>
+<li><a href="https://github.com/petercorke/machinevision-toolbox-python/wiki">Examples and details</a></li>
+<li><a href="https://github.com/petercorke/machinevision-toolbox-python/blob/master/CHANGELOG.md">Changelog</a></li>
 </ul>
 </td>
 </tr>
 </table>
+<p style="font-size:80%">A Python implementation of the <a href="https://github.com/petercorke/machinevision-toolbox-matlab">Machine Vision Toolbox for MATLAB<sup>&reg;</sup></a></p>
 
 ## Synopsis
 

{machinevision_toolbox_python-0.9.7 → machinevision_toolbox_python-1.0.0}/machinevision_toolbox_python.egg-info/SOURCES.txt

@@ -1,9 +1,11 @@
 LICENSE
 README.md
 pyproject.toml
+setup.cfg
 machinevision_toolbox_python.egg-info/PKG-INFO
 machinevision_toolbox_python.egg-info/SOURCES.txt
 machinevision_toolbox_python.egg-info/dependency_links.txt
+machinevision_toolbox_python.egg-info/entry_points.txt
 machinevision_toolbox_python.egg-info/requires.txt
 machinevision_toolbox_python.egg-info/top_level.txt
 machinevisiontoolbox/BagOfWords.py
@@ -29,6 +31,7 @@ machinevisiontoolbox/VisualServo.py
 machinevisiontoolbox/__init__.py
 machinevisiontoolbox/camera_derivatives.py
 machinevisiontoolbox/fiducial.py
+machinevisiontoolbox/mvtb_types.py
 machinevisiontoolbox/newcameras.py
 machinevisiontoolbox/base/__init__.py
 machinevisiontoolbox/base/color.py
@@ -44,8 +47,10 @@ machinevisiontoolbox/blocks/__init__.py
 machinevisiontoolbox/blocks/camera.py
 machinevisiontoolbox/blocks/test_blocks.py
 tests/test_base_color.py
+tests/test_blobs.py
 tests/test_camera.py
 tests/test_color.py
+tests/test_constants.py
 tests/test_core.py
 tests/test_image_io.py
 tests/test_imageprocessing_kernel.py

machinevision_toolbox_python-1.0.0/machinevision_toolbox_python.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mvtbtool = machinevisiontoolbox.bin.mvtbtool:main

{machinevision_toolbox_python-0.9.7 → machinevision_toolbox_python-1.0.0}/machinevision_toolbox_python.egg-info/requires.txt

@@ -1,4 +1,4 @@
-numpy>=1.17.4
+numpy<2.0.0,>=1.17.4
 scipy
 matplotlib
 opencv-python

{machinevision_toolbox_python-0.9.7 → machinevision_toolbox_python-1.0.0}/machinevisiontoolbox/Camera.py

@@ -71,16 +71,16 @@ class CameraBase(ABC):
         :type camtype: str, optional
         :param rho: pixel size, defaults to 1
         :type rho: scalar or array_like(2), optional
-        :param imagesize: image dimension in pixels, defaults to None
+        :param imagesize: image dimension (width, height) in pixels, defaults to None
         :type imagesize: int or array_like(2), optional
-        :param sensorsize: image sensor size, defaults to None
+        :param sensorsize: image sensor size (width, height), defaults to None
         :type sensorsize: array_like(2), optional
         :param pp: principal point position, defaults to None
         :type pp: array_like(2), optional
         :param noise: standard deviation of image plane projection noise, defaults to None
         :type noise: float, optional
         :param pose: camera pose, defaults to None
-        :type pose: :class:`~spatialmath..pose3d.SE3`, optional
+        :type pose: :class:`~spatialmath.pose3d.SE3`, optional
         :param limits: bounds of virtual image plane [umin, umax, vmin, vmax], defaults to None
         :type limits: array_like(4), optional
         :param labels: axis labels for virtual image plane, defaults to ``('u', 'v')``
@@ -118,8 +118,8 @@ class CameraBase(ABC):
                 self.pp = pp
 
         if sensorsize is not None:
-            self._rhou = sensorsize[0] / self.imagesize[1]
-            self._rhov = sensorsize[1] / self.imagesize[0]
+            self._rhou = sensorsize[0] / self.imagesize[0]
+            self._rhov = sensorsize[1] / self.imagesize[1]
         else:
             rho = base.getvector(rho)
             if len(rho) == 1:
@@ -277,9 +277,8 @@ class CameraBase(ABC):
         """
         Set/get size of virtual image plane (base method)
 
-        The dimensions of the virtual image plane is a 2-tuple, width and
-        height, that can be read or written.  For writing the size must be an
-        iterable of length 2.
+        The dimensions of the virtual image plane is a 2-tuple (width, height) that can
+        be read or written.  For writing the size must be an iterable of length 2.
 
         Example:
 
@@ -629,7 +628,7 @@ class CameraBase(ABC):
             >>> camera.project_point([0, 0, 2])
             >>> camera.project_point([0, 0, 2])
 
-        :seealso: :meth:`project`
+        :seealso: :meth:`project_point`
         """
         return self._noise
 
@@ -637,6 +636,39 @@ class CameraBase(ABC):
     def noise(self, noise):
         self._noise = noise
 
+    @property
+    def distortion(self):
+        r"""
+        Set/Get distortion model (base method)
+
+        :return: distortion model
+        :rtype: array_like()
+
+        The distortion model is a vector of various lengths that can be read or written.
+        It is passed directly to OpenCV functions which define how it is used:
+
+        - 4-element vector, :math:`[k_1, k_2, p_1, p_2]`
+        - 5-element vector, :math:`[k_1, k_2, p_1, p_2, k_3]`
+        - 8-element vector, :math:`[k_1, k_2, p_1, p_2, k_3, k_4, k_5, k_6]`
+        - 12-element vector, :math:`[k_1, k_2, p_1, p_2, k_3, k_4, k_5, k_6, s_1, s_2, s_3, s_4]`,
+        - 14-element vector, :math:`[k_1, k_2, p_1, p_2, k_3, k_4, k_5, k_6, s_1, s_2, s_3, s_4, \tau_x, \tau_y]`
+
+        The elements :math:`k_i` are radial distortion coefficients, :math:`p_i` are
+        tangential distortion coefficients, :math:`s_i` are thin prism
+        distortion coefficients, and :math:`\tau_i` apply when the camera's image plane
+        is tilted with respect to the lens.
+
+        If the vector is ``None``, then zero distortion (all coefficients are zero) is
+        assumed.
+
+        :seealso: :meth:`~CentralCamera.project_point` `OpenCV distortion model <https://docs.opencv.org/4.x/d9/d0c/group__calib3d.html>`_
+        """
+        return self._distortion
+
+    @distortion.setter
+    def distortion(self, distortion):
+        self._distortion = distortion
+
     def move(self, T, name=None, relative=False):
         """
         Move camera (base method)
@@ -1690,7 +1722,7 @@ class CentralCamera(CameraBase):
             >>> line = camera.ray((100, 200))
             >>> line
 
-        :reference:
+        :references:
             - "Multiview Geometry", Hartley & Zisserman, p.162
             - Robotics, Vision & Control for Python, Section 14.3, P. Corke, Springer 2023.
 
@@ -2196,7 +2228,7 @@ class CentralCamera(CameraBase):
         :note: Since only :math:`f s_x` and :math:`f s_y` can be estimated we
             set :math:`s_x = 1`.
 
-        :reference:
+        :references:
             - Multiple View Geometry, Hartley&Zisserman, p 163-164
             - Robotics, Vision & Control for Python, Section 13.2.3, P. Corke,
               Springer 2023.
@@ -2355,7 +2387,7 @@ class CentralCamera(CameraBase):
             of inliers is also returned, True means the corresponding input
             point pair is an inlier.
 
-        :reference:
+        :references:
             - Robotics, Vision & Control for Python, Section 14.2.4, P. Corke,
               Springer 2023.
 
@@ -2418,7 +2450,7 @@ class CentralCamera(CameraBase):
             >>> T.printline(orient="camera")
             >>> normals
 
-        :reference:
+        :references:
             - Robotics, Vision & Control for Python, Section 14.2.4, P. Corke,
               Springer 2023.
 
@@ -2504,7 +2536,7 @@ class CentralCamera(CameraBase):
             >>> F = camera1.F(SE3.Tx(0.2))
             >>> F
 
-        :reference:
+        :references:
             - Y.Ma, J.Kosecka, S.Soatto, S.Sastry, "An invitation to 3D",
               Springer, 2003. p.177
             - Robotics, Vision & Control for Python, Section 14.2.1, P. Corke,
@@ -2656,7 +2688,7 @@ class CentralCamera(CameraBase):
         * a relative motion represented by a :class:`~spatialmath..pose3d.SE3`
         * a fundamental matrix
 
-        :reference:
+        :references:
             - Y.Ma, J.Kosecka, S.Soatto, S.Sastry, "An invitation to 3D",
               Springer, 2003. p.177
 
@@ -2758,7 +2790,7 @@ class CentralCamera(CameraBase):
         - a single 3D world point in front of the camera
         - a :class:`~machinevisiontoolbox.ImagePointFeatures.FeatureMatch` object
 
-        :reference:
+        :references:
             - Robotics, Vision & Control for Python, Section 14.2.2 P. Corke,
               Springer 2023.
 
@@ -3494,9 +3526,9 @@ class CatadioptricCamera(CameraBase):
 
     :note:
         - If ``K`` is not specified it is computed such that the circular
-            imaging region maximally fills the image plane.
+          imaging region maximally fills the image plane.
         - This camera model assumes central projection, that is, the focal point
-            is at :math:`z=0` and the image plane is at :math:`z=f`.  The image is not inverted.
+          is at :math:`z=0` and the image plane is at :math:`z=f`.  The image is not inverted.
 
     :references:
         - Robotics, Vision & Control for Python, Section 13.3.2, P. Corke, Springer 2023.

{machinevision_toolbox_python-0.9.7 → machinevision_toolbox_python-1.0.0}/machinevisiontoolbox/ImageBlobs.py

@@ -25,6 +25,7 @@ import random as rng
 rng.seed(13543)  # would this be called every time at Blobs init?
 import matplotlib.pyplot as plt
 
+
 # decorators
 def scalar_result(func):
     def innerfunc(*args):
@@ -99,32 +100,58 @@ class Blob:
     level = None
 
     def __init__(self):
+        """Constructor for Blob class
+
+        A :class:`Blob` instance is a simple container for the parameters
+        of a single blob.
+
+        A set of blobs is represented by a :class:`Blobs` instance which acts
+        like a list of :class:`Blob` instance.
+        """
         return
 
     def __str__(self):
-        l = [f"{key}: {value}" for key, value in self.__dict__.items()]
-        return "\n".join(l)
+        """Create a compact string representation of the Blob object
+
+        :return: compact string representation
+        :rtype: str
+        """
+        return f"Blob[{self.id}](area={self.moments.m00:.2g}, color={self.color}, parent={self.parent.id if self.parent else None})]"
 
     def __repr__(self):
         return str(self)
 
+    def print(self):
+        """Create a detailed string representation of the Blob object
+
+        :return: detailed string representation
+        :rtype: str
+
+        The string representation includes all the attributes of the Blob object.
+        """
+        l = [f"{key}: {value}" for key, value in self.__dict__.items()]
+        return "\n".join(l)
+
 
 class Blobs(UserList):  # lgtm[py/missing-equals]
 
     _image = []  # keep image saved for each Blobs object
 
-    def __init__(self, image=None, **kwargs):
+    def __init__(self, image=None, kulpa=True, **kwargs):
         """
         Find blobs and compute their attributes
 
         :param image: image to use, defaults to None
         :type image: :class:`Image`, optional
+        :param kulpa: apply Kulpa's correction factor to circularity, defaults to True
+        :type kulpa: bool, optional
 
         Uses OpenCV functions ``findContours`` to find a hierarchy of regions
         represented by their contours, and ``boundingRect``, ``moments`` to
         compute moments, perimeters, centroids etc.
 
-        This class behaves like a list and each blob is an element of the list
+        This class behaves like a list and each element of the list is a blob
+        represented by a :class:`Blob` instance
 
         .. runblock:: pycon
 
@@ -154,8 +181,56 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
 
             >>> blobs.area
 
+        A blob has many attributes:
+
+        .. list-table::
+           :header-rows: 1
+
+           * - Attribute
+             - Description
+           * - :meth:`area`
+             - The area of the blob.
+           * - :meth:`u`, :meth:`v`
+             - The centroid (center of mass) of the blob.
+           * - :meth:`bbox`
+             - The bounding box of the blob.
+           * - :meth:`color`
+             - The vaue of pixels within the blob.
+           * - :meth:`touch`
+             - True if the blob touches the border.
+           * - :meth:`contour_point`
+             - A point on the contour of the blob.
+           * - :meth:`perimeter`
+             - A 2xN array of points on the perimeter of the blob.
+           * - :meth:`perimeter_length`
+             - The perimeter length of the blob.
+           * - :meth:`circularity`
+             - The circularity of the blob.
+           * - :meth:`moments`
+             - The moments of the blob including central, normalized upto 3rd order.
+           * - :meth:`orientation`
+             - Orientation of the equivalent ellipse.
+           * - :meth:`a, b`
+             - The equivalent ellipse radii.
+           * - :meth:`children`
+             - A list of references to child :class:`Blob` instances.
+           * - :meth:`parent`
+             - A reference to the parent :class:`Blob` instance, or None if no parent.
+           * - :meth:`level`
+             - The depth of the blob in the region tree.
+
         :note: A color image is internally converted to greyscale.
 
+        :note: ``findContours`` can give surprising results for small images:
+
+            - The perimeter length is computed between the mid points of the pixels, and
+              the OpenCV function ``arcLength`` seems to underestimate the perimeter
+              even more.  The perimeter length is not the same as the number of pixels
+              in the contour.
+            - The area will be less than the number of pixels in the blob, because the
+              area is computed from the moments of the blob, which are computed from the
+              contour, see above.
+
         :references:
             - Robotics, Vision & Control for Python, Section 12.1.2.1, P. Corke, Springer 2023.
 
@@ -197,6 +272,7 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
 
         ## first pass: moments, children, bbox
 
+        runts = 0
         for i, (contour, hier) in enumerate(zip(contours, hierarchy)):
 
             blob = Blob()
@@ -204,8 +280,8 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
 
             ## bounding box: umin, vmin, width, height
             u1, v1, w, h = cv.boundingRect(contour)
-            u2 = u1 + w
-            v2 = v1 + h
+            u2 = u1 + w - 1
+            v2 = v1 + h - 1
             blob.bbox = np.r_[u1, u2, v1, v2]
 
             blob.touch = u1 == 0 or v1 == 0 or u2 == image.umax or v2 == image.vmax
@@ -225,6 +301,9 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
                 child = hierarchy[child, 0]
             blob.children = children
 
+            pp = contour[0, :]
+            blob.color = image.A[pp[1], pp[0]]
+
             ## moments
 
             # get moments as a dictionary for each contour
@@ -239,7 +318,9 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
 
             ## For a single set pixel OpenCV returns all moments as zero, skip such blobs
             ## TODO handle this situation by setting m00=1, m10=x, m01=y etc.
-            if blob.moments["m00"] != 0:
+            if blob.moments["m00"] == 0:
+                runts += 1
+            else:
                 self.data.append(blob)
 
         ## second pass: equivalent ellipse
@@ -289,9 +370,14 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
             #   Comparison. Proc. IAPR Workshop on Machine Vision Applications.,
             #   December 13-15, 1994, Kawasaki, Japan
             #   L. Yang, F. Albregtsen, T. Loennestad, P. Groettum
-            kulpa = np.pi / 8.0 * (1.0 + np.sqrt(2.0))
+            if kulpa is True:
+                kfactor = np.pi / 8.0 * (1.0 + np.sqrt(2.0))
+            elif isinstance(kulpa, (int, float)):
+                kfactor = kulpa
+            else:
+                kfactor = 1.0
             blob.circularity = (4.0 * np.pi * M.m00) / (
-                blob.perimeter_length * kulpa
+                blob.perimeter_length * kfactor
             ) ** 2
 
         ## third pass, region tree coloring to determine vertex depth
@@ -306,6 +392,17 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
 
         self.filter(**kwargs)
 
+        for blob in self.data:
+            if blob.parent != -1:
+                blob.parent = self.data[blob.parent]
+            else:
+                blob.parent = None
+            if len(blob.children) > 0:
+                blob.children = [self.data[i] for i in blob.children]
+
+        if runts > 0:
+            print(f"blobs: found {runts} runt blob{'s' if runts > 1 else ''}")
+
         return
 
     def filter(self, area=None, circularity=None, color=None, touch=None, aspect=None):
@@ -347,10 +444,15 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
 
             >>> from machinevisiontoolbox import Image
             >>> img = Image.Read('sharks.png')
+            >>> blobs = img.blobs()
             >>> blobs
             >>> blobs.filter(area=10_000)
             >>> blobs.filter(area=10_000, circularity=0.3)
 
+        .. warning:: Filtering can destroy the hierarchy of the blobs, deleting
+            parents and children in the blob tree.  A blob may have references
+            to parents and children that are not in the filtered set.
+
         :references:
             - Robotics, Vision & Control for Python, Section 12.1.2.1, P. Corke, Springer 2023.
 
@@ -493,7 +595,7 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
         for b in self.data:
             table.row(
                 b.id,
-                b.parent,
+                b.parent.id if b.parent else -1,
                 f"{b.uc:.1f}, {b.vc:.1f}",
                 b.moments.m00,
                 b.touch,
@@ -1490,7 +1592,10 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
         # add the nodes including name and position
         for id, blob in enumerate(self):
             print('  "{:d}"'.format(id), file=f)
-            print('  "{:d}" -> "{:d}"'.format(blob.parent, id), file=f)
+            print(
+                '  "{:d}" -> "{:d}"'.format(blob.parent.id if blob.parent else -1, id),
+                file=f,
+            )
 
         print("}", file=f)