Skip to content
Back to top
View this page

# `ImageMorph` module

The `ImageMorph` module allows morphology operators (“MorphOp”) to be applied to 1 or L mode images:

    from PIL import Image, ImageMorph
    img = Image.open("Tests/images/hopper.bw")
    mop = ImageMorph.MorphOp(op_name="erosion4")
    count, imgOut = mop.apply(img)
    imgOut.show()

In addition to applying operators, you can also analyse images.

You can inspect an image in isolation to determine which pixels are non-empty:

    print(mop.get_on_pixels(img))  # [(0, 0), (1, 0), (2, 0), ...]

Or you can retrieve a list of pixels that match the operator. This is the number of pixels that will be non-empty after the operator is applied:

    coords = mop.match(img)
    print(coords)  # [(17, 1), (18, 1), (34, 1), ...]
    print(len(coords))  # 550

    imgOut = mop.apply(img)[1]
    print(len(mop.get_on_pixels(imgOut)))  # 550

If you would like more customized operators, you can pass patterns to the MorphOp class:

    mop = ImageMorph.MorphOp(patterns=["1:(... ... ...)->0", "4:(00. 01. ...)->1"])

Or you can pass lookup table (“LUT”) data directly. This LUT data can be constructed with the `LutBuilder`:

    builder = ImageMorph.LutBuilder()
    mop = ImageMorph.MorphOp(lut=builder.build_lut())

class PIL.ImageMorph.LutBuilder(patterns: list[str] | None = None, op_name: str | None = None)

  Bases: `object`

  A class for building a MorphLut from a descriptive language

  The input patterns is a list of a strings sequences like these:

      4:(...
         .1.
         111)->1

  (whitespaces including linebreaks are ignored). The option 4 describes a series of symmetry operations (in this case a 4-rotation), the pattern is described by:

  - . or X - Ignore

  - 1 - Pixel is on

  - 0 - Pixel is off

  The result of the operation is described after “->” string.

  The default is to return the current pixel value, which is returned if no other match is found.

  Operations:

  - 4 - 4 way rotation

  - N - Negate

  - 1 - Dummy op for no other operation (an op must always be given)

  - M - Mirroring

  Example:

      lb = LutBuilder(patterns = ["4:(... .1. 111)->1"])
      lut = lb.build_lut()

  add_patterns(patterns: list[str]) → None

    Append to list of patterns.

    Parameters:

      patterns – Additional patterns.

  build_default_lut() → bytearray

    Set the current LUT, and return it.

    This is the default LUT that patterns will be applied against when building.

  build_lut() → bytearray

    Compile all patterns into a morphology LUT, and return it.

    This is the data to be passed into MorphOp.

  get_lut() → bytearray | None

    Returns the current LUT

class PIL.ImageMorph.MorphOp(lut: bytearray | None = None, op_name: str | None = None, patterns: list[str] | None = None)

  Bases: `object`

  A class for binary morphological operators

  apply(image: Image) → tuple[int, Image]

    Run a single morphological operation on an image.

    Returns a tuple of the number of changed pixels and the morphed image.

    Parameters:

      image – A 1-mode or L-mode image.

    Raises:

      - Exception – If the current operator is None.

      - ValueError – If the image is not 1 or L mode.

  get_on_pixels(image: Image) → list[tuple[int, int]]

    Get a list of all turned on pixels in a 1 or L mode image.

    Returns a list of tuples of (x,y) coordinates of all non-empty pixels. See Coordinate system.

    Parameters:

      image – A 1-mode or L-mode image.

    Raises:

      ValueError – If the image is not 1 or L mode.

  load_lut(filename: str) → None

    Load an operator from an mrl file

    Parameters:

      filename – The file to read from.

    Raises:

      Exception – If the length of the file data is not 512.

  match(image: Image) → list[tuple[int, int]]

    Get a list of coordinates matching the morphological operation on an image.

    Returns a list of tuples of (x,y) coordinates of all matching pixels. See Coordinate system.

    Parameters:

      image – A 1-mode or L-mode image.

    Raises:

      - Exception – If the current operator is None.

      - ValueError – If the image is not 1 or L mode.

  save_lut(filename: str) → None

    Save an operator to an mrl file.

    Parameters:

      filename – The destination file.

    Raises:

      Exception – If the current operator is None.

  set_lut(lut: bytearray | None) → None

    Set the LUT from an external source

    Parameters:

      lut – A new LUT.