Skip to main content

The Kitware Image Module

Project description

GitlabCIPipeline GitlabCICoverage Appveyor Pypi Downloads ReadTheDocs

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/master/

The top-level API is:

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,
                      find_robust_normalizers, make_channels_comparable,
                      normalize, normalize_intensity, num_channels,
                      padded_slice,)
from .im_cv2 import (convert_colorspace, gaussian_blur, gaussian_patch, imcrop,
                     imresize, imscale, morphology, warp_affine,)
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,)
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 (Boxes, Coords, Detections, Heatmap, Mask, MaskList,
                      MultiPolygon, Points, PointsList, Polygon, PolygonList,
                      Segmentation, SegmentationList, smooth_prob,)
from .transform import (Affine, Linear, Matrix, Projective, Transform,
                        profile,)
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_image,
                        warp_points, warp_tensor,)

NOTE: THE KWIMAGE STRUCTS WILL 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 compositie strucutres 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:

# We recommend using the headless version
pip install kwimage[headless]

# OR

# If other parts of your system depend on the opencv qt libs
# (this can conflict with pyqt5)
pip install kwimage[graphics]

On linux, pip install commands will download precompiled manylinux wheels. On other operating systems, or if you are installing from source, you may need to compile C-extension modules. However, there are equivalent python-only implementations of almost every c-extension. You can disable compilation or loading of c-extensions at compile or runtime by setting the environment variable: KWIMAGE_DISABLE_C_EXTENSIONS=1.

Also note, that when building from source, the build may fail if you not in a fresh state (related to skbuild-386. You can mitigate this by running python setup.py clean to remove build artifacts. Building from a clean environment should work.

A Note on GDAL

The kwimage library can use 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:

pip install --find-links https://girder.github.io/large_image_wheels GDAL

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kwimage-0.9.0.tar.gz (266.9 kB view details)

Uploaded Source

Built Distribution

kwimage-0.9.0-py3-none-any.whl (272.2 kB view details)

Uploaded Python 3

File details

Details for the file kwimage-0.9.0.tar.gz.

File metadata

  • Download URL: kwimage-0.9.0.tar.gz
  • Upload date:
  • Size: 266.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.8.13

File hashes

Hashes for kwimage-0.9.0.tar.gz
Algorithm Hash digest
SHA256 ff819dddb3089c3bf0a07cab5f268da743f31f5fa0782d1caeafc61137f38585
MD5 43e2c6b1c20ce4a156326c4863f14226
BLAKE2b-256 9e81fcbd49110b19b04c93156af8b7ce169efb0511b47d45f4044980066b09f4

See more details on using hashes here.

File details

Details for the file kwimage-0.9.0-py3-none-any.whl.

File metadata

  • Download URL: kwimage-0.9.0-py3-none-any.whl
  • Upload date:
  • Size: 272.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.8.13

File hashes

Hashes for kwimage-0.9.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9f5753f8da427f71519964c59a03609264990431032b946d560dfd629ffa843c
MD5 73cec8ff51bcc60498d12dc20418a016
BLAKE2b-256 08197679db0ac2b7f4dc58900fc6b5aafc8edeaf79caea77bd1f811e7b4a2d71

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page