The Kitware Image Module
========================
.. # TODO Get CI services running on gitlab
.. #
|GitlabCIPipeline| |GitlabCICoverage| |Appveyor| |Pypi| |PypiDownloads| |ReadTheDocs|
+------------------+-------------------------------------------------------+
| Read the docs | https://kwimage.readthedocs.io |
+------------------+-------------------------------------------------------+
| Gitlab (main) | https://gitlab.kitware.com/computer-vision/kwimage |
+------------------+-------------------------------------------------------+
| Github (mirror) | https://github.com/Kitware/kwimage |
+------------------+-------------------------------------------------------+
| Pypi | https://pypi.org/project/kwimage |
+------------------+-------------------------------------------------------+
The main webpage for this project is: https://gitlab.kitware.com/computer-vision/kwimage
The ``kwimage`` module handles low-level image operations at a high level.
The core ``kwimage`` is a functional library with image-related helper
functions that are either unimplemented in or more have a more general
interface then their opencv counterparts.
The ``kwimage`` module builds on ``kwarray`` and provides tools commonly needed
when addressing computer vision problems. This includes functions for reading
images, resizing, image warp transformations, run-length-encoding, and
non-maximum-suppression.
The ``kwimage`` module is also the current home of my annotation data
structures, which provide efficient ways to interoperate between different
common annotation formats (e.g. different bounding box / polygon / point
formats). These data structures have both a ``.draw`` and ``.draw_on`` method
for overlaying visualizations on matplotlib axes or numpy image matrices
respectively.
Read the docs at: http://kwimage.readthedocs.io/en/main/
The top-level API is:
.. code:: python
from .algo import (available_nms_impls, daq_spatial_nms, non_max_supression,)
from .im_alphablend import (ensure_alpha_channel, overlay_alpha_images,
overlay_alpha_layers,)
from .im_color import (Color,)
from .im_core import (atleast_3channels, ensure_float01, ensure_uint255,
exactly_1channel, find_robust_normalizers,
make_channels_comparable, normalize, normalize_intensity,
num_channels, padded_slice,)
from .im_cv2 import (connected_components, convert_colorspace, gaussian_blur,
gaussian_patch, imcrop, imresize, imscale, morphology,
warp_affine, warp_image, warp_projective,)
from .im_demodata import (checkerboard, grab_test_image,
grab_test_image_fpath,)
from .im_draw import (draw_boxes_on_image, draw_clf_on_image, draw_header_text,
draw_line_segments_on_image, draw_text_on_image,
draw_vector_field, fill_nans_with_checkers,
make_heatmask, make_orimask, make_vector_field,
nodata_checkerboard,)
from .im_filter import (fourier_mask, radial_fourier_mask,)
from .im_io import (imread, imwrite, load_image_shape,)
from .im_runlen import (decode_run_length, encode_run_length, rle_translate,)
from .im_stack import (stack_images, stack_images_grid,)
from .structs import (Box, Boxes, Coords, Detections, Heatmap, Mask, MaskList,
MultiPolygon, Points, PointsList, Polygon, PolygonList,
Segmentation, SegmentationList, smooth_prob,)
from .transform import (Affine, Linear, Matrix, Projective, Transform,)
from .util_warp import (add_homog, remove_homog, subpixel_accum,
subpixel_align, subpixel_getvalue, subpixel_maximum,
subpixel_minimum, subpixel_set, subpixel_setvalue,
subpixel_slice, subpixel_translate, warp_points,
warp_tensor,)
NOTE: THE KWIMAGE STRUCTS MAY? EVENTUALLY MOVE TO THE KWANNOT REPO
(But this transition might take awhile)
The most notable feature of the ``kwimage`` module are the ``kwimage.structs``
objects. This includes the primitive ``Boxes``, ``Mask``, and ``Coords`` objects, The
semi-primitive ``Points``, ``Polygon`` structures, and the composite ``Heatmap`` and
``Detections`` structures (note: ``Heatmap`` is just a composite of array-like
structures).
The primitive and semi-primitive objects store and manipulate annotation
geometry, and the composite structures combine primitives into a single
object that jointly manipulates the primitives using ``warp`` operations.
The ``Detections`` structure is a meta-structure that associates the other more
primitive components, and allows a developer to compose them into something
that represents objects of interest. The details of this composition are left
up to the end-application.
The ``Detections`` object can also be "rasterized" and converted into a ``Heatmap``
object, which represents the same information, but is in a form that is more
suitable for use when training convolutional neural networks. Likewise, the
output of neural networks can be directly encoded in a ``kwimage.Heatmap``
object. The ``Heatmap.detect`` method can then be used to convert the dense
heatmap representation into a spare ``Detections`` representation that is more
suitable for use in an object-detection system. We note that the ``detect``
function is not a special detection algorithm. The detection algorithm (which
is outside the scope of kwimage) produces the heatmap, and the ``detect`` method
effectively "inverts" the ``rasterize`` procedure of ``Detections`` by finding
peaks in the heatmap, and running non-maximum suppression.
This module contains data structures for three image annotation primitives:
* Boxes # technically this could be made out of Coords, probably not for efficiency and decoupling
* Mask # likewise this could be renamed to Raster
* Coords #
These primative structures are used to define these metadata-containing composites:
* Detections
* Polygon
* Heatmap
* MultiPolygon
* PolygonList
* MaskList
All of these structures have a ``self.data`` attribute that holds a pointer to
the underlying data representation.
Some of these structures have a ``self.format`` attribute describing the
underlying data representation.
Most of the composite structures also have a ``self.meta`` attribute, which
holds user-level metadata (e.g. info about the classes).
Installation
------------
There are a few small quirks with installing kwimage. There is an issue with
the opencv python bindings such that we could rely on either the
`opencv-python` or `opencv-python-headless` package. If you have either of
these module already installed you can simply `pip install kwimage` without
encountering any issues related to this. But if you do not already have a
module that provides `import cv2` installed, then you should install kwimage
with one of the following "extra install" tags:
.. code-block:: bash
# We recommend using the headless version
pip install kwimage[headless]
# OR
# If other parts of your system depend on the opencv qt libs
# (NOT RECOMMENDED: this can conflict with pyqt5)
pip install kwimage[graphics]
Some features also require the ``kwimage_ext`` package to be installed, which
contains binary extensions that used to be distributed with this package in
older versions. These extension can be obtained by explicitly
``pip install kwimage_ext`` or via ``pip install kwimage[optional]`` (which also
brings in other optional libraries). You can disable loading of c-extensions at
runtime by setting the environment variable: `KWIMAGE_DISABLE_C_EXTENSIONS=1`.
A Note on GDAL
--------------
The kwimage library can use `GDAL <https://github.com/OSGeo/gdal/>`_ library
for certain tasks (e.g. IO of geotiffs). GDAL can be a pain to install without
relying on conda. Kitware also has a pypi index that hosts GDAL wheels for
linux systems:
.. code-block:: bash
pip install --find-links https://girder.github.io/large_image_wheels GDAL
.. |Pypi| image:: https://img.shields.io/pypi/v/kwimage.svg
:target: https://pypi.python.org/pypi/kwimage
.. |PypiDownloads| image:: https://img.shields.io/pypi/dm/kwimage.svg
:target: https://pypistats.org/packages/kwimage
.. |ReadTheDocs| image:: https://readthedocs.org/projects/kwimage/badge/?version=release
:target: http://kwimage.readthedocs.io/en/release/
.. # See: https://ci.appveyor.com/project/jon.crall/kwimage/settings/badges
.. |Appveyor| image:: https://ci.appveyor.com/api/projects/status/py3s2d6tyfjc8lm3/branch/main?svg=true
:target: https://ci.appveyor.com/project/jon.crall/kwimage/branch/main
.. |GitlabCIPipeline| image:: https://gitlab.kitware.com/computer-vision/kwimage/badges/main/pipeline.svg
:target: https://gitlab.kitware.com/computer-vision/kwimage/-/jobs
.. |GitlabCICoverage| image:: https://gitlab.kitware.com/computer-vision/kwimage/badges/main/coverage.svg
:target: https://gitlab.kitware.com/computer-vision/kwimage/commits/main
Raw data
{
"_id": null,
"home_page": "https://gitlab.kitware.com/computer-vision/kwimage",
"name": "kwimage",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Jon Crall",
"author_email": "jon.crall@kitware.com",
"download_url": "",
"platform": null,
"description": "The Kitware Image Module\n========================\n\n\n.. # TODO Get CI services running on gitlab\n.. #\n\n|GitlabCIPipeline| |GitlabCICoverage| |Appveyor| |Pypi| |PypiDownloads| |ReadTheDocs|\n\n+------------------+-------------------------------------------------------+\n| Read the docs | https://kwimage.readthedocs.io |\n+------------------+-------------------------------------------------------+\n| Gitlab (main) | https://gitlab.kitware.com/computer-vision/kwimage |\n+------------------+-------------------------------------------------------+\n| Github (mirror) | https://github.com/Kitware/kwimage |\n+------------------+-------------------------------------------------------+\n| Pypi | https://pypi.org/project/kwimage |\n+------------------+-------------------------------------------------------+\n\nThe main webpage for this project is: https://gitlab.kitware.com/computer-vision/kwimage\n\nThe ``kwimage`` module handles low-level image operations at a high level.\n\nThe core ``kwimage`` is a functional library with image-related helper\nfunctions that are either unimplemented in or more have a more general\ninterface then their opencv counterparts.\n\nThe ``kwimage`` module builds on ``kwarray`` and provides tools commonly needed\nwhen addressing computer vision problems. This includes functions for reading\nimages, resizing, image warp transformations, run-length-encoding, and\nnon-maximum-suppression.\n\n\nThe ``kwimage`` module is also the current home of my annotation data\nstructures, which provide efficient ways to interoperate between different\ncommon annotation formats (e.g. different bounding box / polygon / point\nformats). These data structures have both a ``.draw`` and ``.draw_on`` method\nfor overlaying visualizations on matplotlib axes or numpy image matrices\nrespectively.\n\n\nRead the docs at: http://kwimage.readthedocs.io/en/main/\n\n\nThe top-level API is:\n\n\n.. code:: python\n\n from .algo import (available_nms_impls, daq_spatial_nms, non_max_supression,)\n from .im_alphablend import (ensure_alpha_channel, overlay_alpha_images,\n overlay_alpha_layers,)\n from .im_color import (Color,)\n from .im_core import (atleast_3channels, ensure_float01, ensure_uint255,\n exactly_1channel, find_robust_normalizers,\n make_channels_comparable, normalize, normalize_intensity,\n num_channels, padded_slice,)\n from .im_cv2 import (connected_components, convert_colorspace, gaussian_blur,\n gaussian_patch, imcrop, imresize, imscale, morphology,\n warp_affine, warp_image, warp_projective,)\n from .im_demodata import (checkerboard, grab_test_image,\n grab_test_image_fpath,)\n from .im_draw import (draw_boxes_on_image, draw_clf_on_image, draw_header_text,\n draw_line_segments_on_image, draw_text_on_image,\n draw_vector_field, fill_nans_with_checkers,\n make_heatmask, make_orimask, make_vector_field,\n nodata_checkerboard,)\n from .im_filter import (fourier_mask, radial_fourier_mask,)\n from .im_io import (imread, imwrite, load_image_shape,)\n from .im_runlen import (decode_run_length, encode_run_length, rle_translate,)\n from .im_stack import (stack_images, stack_images_grid,)\n from .structs import (Box, Boxes, Coords, Detections, Heatmap, Mask, MaskList,\n MultiPolygon, Points, PointsList, Polygon, PolygonList,\n Segmentation, SegmentationList, smooth_prob,)\n from .transform import (Affine, Linear, Matrix, Projective, Transform,)\n from .util_warp import (add_homog, remove_homog, subpixel_accum,\n subpixel_align, subpixel_getvalue, subpixel_maximum,\n subpixel_minimum, subpixel_set, subpixel_setvalue,\n subpixel_slice, subpixel_translate, warp_points,\n warp_tensor,)\n\n\nNOTE: THE KWIMAGE STRUCTS MAY? EVENTUALLY MOVE TO THE KWANNOT REPO\n(But this transition might take awhile)\n\n\nThe most notable feature of the ``kwimage`` module are the ``kwimage.structs``\nobjects. This includes the primitive ``Boxes``, ``Mask``, and ``Coords`` objects, The\nsemi-primitive ``Points``, ``Polygon`` structures, and the composite ``Heatmap`` and\n``Detections`` structures (note: ``Heatmap`` is just a composite of array-like\nstructures).\n\nThe primitive and semi-primitive objects store and manipulate annotation\ngeometry, and the composite structures combine primitives into a single\nobject that jointly manipulates the primitives using ``warp`` operations.\n\nThe ``Detections`` structure is a meta-structure that associates the other more\nprimitive components, and allows a developer to compose them into something\nthat represents objects of interest. The details of this composition are left\nup to the end-application.\n\nThe ``Detections`` object can also be \"rasterized\" and converted into a ``Heatmap``\nobject, which represents the same information, but is in a form that is more\nsuitable for use when training convolutional neural networks. Likewise, the\noutput of neural networks can be directly encoded in a ``kwimage.Heatmap``\nobject. The ``Heatmap.detect`` method can then be used to convert the dense\nheatmap representation into a spare ``Detections`` representation that is more\nsuitable for use in an object-detection system. We note that the ``detect``\nfunction is not a special detection algorithm. The detection algorithm (which\nis outside the scope of kwimage) produces the heatmap, and the ``detect`` method\neffectively \"inverts\" the ``rasterize`` procedure of ``Detections`` by finding\npeaks in the heatmap, and running non-maximum suppression.\n\n\nThis module contains data structures for three image annotation primitives:\n\n * Boxes # technically this could be made out of Coords, probably not for efficiency and decoupling\n * Mask # likewise this could be renamed to Raster\n * Coords #\n\nThese primative structures are used to define these metadata-containing composites:\n\n * Detections\n * Polygon\n * Heatmap\n * MultiPolygon\n * PolygonList\n * MaskList\n\nAll of these structures have a ``self.data`` attribute that holds a pointer to\nthe underlying data representation.\n\nSome of these structures have a ``self.format`` attribute describing the\nunderlying data representation.\n\nMost of the composite structures also have a ``self.meta`` attribute, which\nholds user-level metadata (e.g. info about the classes).\n\n\nInstallation\n------------\n\nThere are a few small quirks with installing kwimage. There is an issue with\nthe opencv python bindings such that we could rely on either the\n`opencv-python` or `opencv-python-headless` package. If you have either of\nthese module already installed you can simply `pip install kwimage` without\nencountering any issues related to this. But if you do not already have a\nmodule that provides `import cv2` installed, then you should install kwimage\nwith one of the following \"extra install\" tags:\n\n.. code-block:: bash\n\n # We recommend using the headless version\n pip install kwimage[headless]\n\n # OR\n\n # If other parts of your system depend on the opencv qt libs\n # (NOT RECOMMENDED: this can conflict with pyqt5)\n pip install kwimage[graphics]\n\n\nSome features also require the ``kwimage_ext`` package to be installed, which\ncontains binary extensions that used to be distributed with this package in\nolder versions. These extension can be obtained by explicitly\n``pip install kwimage_ext`` or via ``pip install kwimage[optional]`` (which also\nbrings in other optional libraries). You can disable loading of c-extensions at\nruntime by setting the environment variable: `KWIMAGE_DISABLE_C_EXTENSIONS=1`.\n\n\nA Note on GDAL\n--------------\n\nThe kwimage library can use `GDAL <https://github.com/OSGeo/gdal/>`_ library\nfor certain tasks (e.g. IO of geotiffs). GDAL can be a pain to install without\nrelying on conda. Kitware also has a pypi index that hosts GDAL wheels for\nlinux systems:\n\n.. code-block:: bash\n\n pip install --find-links https://girder.github.io/large_image_wheels GDAL\n\n\n\n.. |Pypi| image:: https://img.shields.io/pypi/v/kwimage.svg\n :target: https://pypi.python.org/pypi/kwimage\n\n.. |PypiDownloads| image:: https://img.shields.io/pypi/dm/kwimage.svg\n :target: https://pypistats.org/packages/kwimage\n\n.. |ReadTheDocs| image:: https://readthedocs.org/projects/kwimage/badge/?version=release\n :target: http://kwimage.readthedocs.io/en/release/\n\n.. # See: https://ci.appveyor.com/project/jon.crall/kwimage/settings/badges\n.. |Appveyor| image:: https://ci.appveyor.com/api/projects/status/py3s2d6tyfjc8lm3/branch/main?svg=true\n :target: https://ci.appveyor.com/project/jon.crall/kwimage/branch/main\n\n.. |GitlabCIPipeline| image:: https://gitlab.kitware.com/computer-vision/kwimage/badges/main/pipeline.svg\n :target: https://gitlab.kitware.com/computer-vision/kwimage/-/jobs\n\n.. |GitlabCICoverage| image:: https://gitlab.kitware.com/computer-vision/kwimage/badges/main/coverage.svg\n :target: https://gitlab.kitware.com/computer-vision/kwimage/commits/main\n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "The kwimage module",
"version": "0.9.24",
"project_urls": {
"Homepage": "https://gitlab.kitware.com/computer-vision/kwimage"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "438c1b7813eccd8d6ce27f4d01040ade8d799b63e16049afcc5a351a9f83483b",
"md5": "12998adbd332f2e7bd4291d4f3096839",
"sha256": "dff1014342e923cd463e99dee4da847d8311bb41a1edba573c84c748c95db760"
},
"downloads": -1,
"filename": "kwimage-0.9.24-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12998adbd332f2e7bd4291d4f3096839",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 332862,
"upload_time": "2024-02-23T20:10:09",
"upload_time_iso_8601": "2024-02-23T20:10:09.560924Z",
"url": "https://files.pythonhosted.org/packages/43/8c/1b7813eccd8d6ce27f4d01040ade8d799b63e16049afcc5a351a9f83483b/kwimage-0.9.24-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-23 20:10:09",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "kwimage"
}
JSON