example-apps/PDD/pcb-defect-detection/data/lib_coco/PythonAPI/pycocotools/mask.py

   1 __author__ = 'tsungyi'
   2
   3 import pycocotools._mask as _mask
   4
   5 # Interface for manipulating masks stored in RLE format.
   6 #
   7 # RLE is a simple yet efficient format for storing binary masks. RLE
   8 # first divides a vector (or vectorized image) into a series of piecewise
   9 # constant regions and then for each piece simply stores the length of
  10 # that piece. For example, given M=[0 0 1 1 1 0 1] the RLE counts would
  11 # be [2 3 1 1], or for M=[1 1 1 1 1 1 0] the counts would be [0 6 1]
  12 # (note that the odd counts are always the numbers of zeros). Instead of
  13 # storing the counts directly, additional compression is achieved with a
  14 # variable bitrate representation based on a common scheme called LEB128.
  15 #
  16 # Compression is greatest given large piecewise constant regions.
  17 # Specifically, the size of the RLE is proportional to the number of
  18 # *boundaries* in M (or for an image the number of boundaries in the y
  19 # direction). Assuming fairly simple shapes, the RLE representation is
  20 # O(sqrt(n)) where n is number of pixels in the object. Hence space usage
  21 # is substantially lower, especially for large simple objects (large n).
  22 #
  23 # Many common operations on masks can be computed directly using the RLE
  24 # (without need for decoding). This includes computations such as area,
  25 # union, intersection, etc. All of these operations are linear in the
  26 # size of the RLE, in other words they are O(sqrt(n)) where n is the area
  27 # of the object. Computing these operations on the original mask is O(n).
  28 # Thus, using the RLE can result in substantial computational savings.
  29 #
  30 # The following API functions are defined:
  31 #  encode         - Encode binary masks using RLE.
  32 #  decode         - Decode binary masks encoded via RLE.
  33 #  merge          - Compute union or intersection of encoded masks.
  34 #  iou            - Compute intersection over union between masks.
  35 #  area           - Compute area of encoded masks.
  36 #  toBbox         - Get bounding boxes surrounding encoded masks.
  37 #  frPyObjects    - Convert polygon, bbox, and uncompressed RLE to encoded RLE mask.
  38 #
  39 # Usage:
  40 #  Rs     = encode( masks )
  41 #  masks  = decode( Rs )
  42 #  R      = merge( Rs, intersect=false )
  43 #  o      = iou( dt, gt, iscrowd )
  44 #  a      = area( Rs )
  45 #  bbs    = toBbox( Rs )
  46 #  Rs     = frPyObjects( [pyObjects], h, w )
  47 #
  48 # In the API the following formats are used:
  49 #  Rs      - [dict] Run-length encoding of binary masks
  50 #  R       - dict Run-length encoding of binary mask
  51 #  masks   - [hxwxn] Binary mask(s) (must have type np.ndarray(dtype=uint8) in column-major order)
  52 #  iscrowd - [nx1] list of np.ndarray. 1 indicates corresponding gt image has crowd region to ignore
  53 #  bbs     - [nx4] Bounding box(es) stored as [x y w h]
  54 #  poly    - Polygon stored as [[x1 y1 x2 y2...],[x1 y1 ...],...] (2D list)
  55 #  dt,gt   - May be either bounding boxes or encoded masks
  56 # Both poly and bbs are 0-indexed (bbox=[0 0 1 1] encloses first pixel).
  57 #
  58 # Finally, a note about the intersection over union (iou) computation.
  59 # The standard iou of a ground truth (gt) and detected (dt) object is
  60 #  iou(gt,dt) = area(intersect(gt,dt)) / area(union(gt,dt))
  61 # For "crowd" regions, we use a modified criteria. If a gt object is
  62 # marked as "iscrowd", we allow a dt to match any subregion of the gt.
  63 # Choosing gt' in the crowd gt that best matches the dt can be done using
  64 # gt'=intersect(dt,gt). Since by definition union(gt',dt)=dt, computing
  65 #  iou(gt,dt,iscrowd) = iou(gt',dt) = area(intersect(gt,dt)) / area(dt)
  66 # For crowd gt regions we use this modified criteria above for the iou.
  67 #
  68 # To compile run "python setup.py build_ext --inplace"
  69 # Please do not contact us for help with compiling.
  70 #
  71 # Microsoft COCO Toolbox.      version 2.0
  72 # Data, paper, and tutorials available at:  http://mscoco.org/
  73 # Code written by Piotr Dollar and Tsung-Yi Lin, 2015.
  74 # Licensed under the Simplified BSD License [see coco/license.txt]
  75
  76 iou         = _mask.iou
  77 merge       = _mask.merge
  78 frPyObjects = _mask.frPyObjects
  79
  80 def encode(bimask):
  81     if len(bimask.shape) == 3:
  82         return _mask.encode(bimask)
  83     elif len(bimask.shape) == 2:
  84         h, w = bimask.shape
  85         return _mask.encode(bimask.reshape((h, w, 1), order='F'))[0]
  86
  87 def decode(rleObjs):
  88     if type(rleObjs) == list:
  89         return _mask.decode(rleObjs)
  90     else:
  91         return _mask.decode([rleObjs])[:,:,0]
  92
  93 def area(rleObjs):
  94     if type(rleObjs) == list:
  95         return _mask.area(rleObjs)
  96     else:
  97         return _mask.area([rleObjs])[0]
  98
  99 def toBbox(rleObjs):
 100     if type(rleObjs) == list:
 101         return _mask.toBbox(rleObjs)
 102     else:
 103         return _mask.toBbox([rleObjs])[0]