Add ignore_index argument to Mask.as_class_mask() and Mask.as_instance_mask()

[vinnamkim]

Summary

• Ticket no. 137625
• Same as title.

How to test

Added an unit test for this change.

Checklist

• I have added unit tests to cover my changes.​
• I have added integration tests to cover my changes.​
• I have added the description of my changes into CHANGELOG.​
• I have updated the documentation accordingly

License

• I submit my code changes under the same MIT License that covers the project.
  Feel free to contact the maintainers if that's a concern.
• I have updated the license header for each file (see an example below).

# Copyright (C) 2024 Intel Corporation
#
# SPDX-License-Identifier: MIT

[codecov]

Codecov Report

Attention: Patch coverage is 86.20690% with 4 lines in your changes are missing coverage. Please review.

Project coverage is 80.86%. Comparing base (44cc56a) to head (53b3a5a).
Report is 19 commits behind head on develop.

Files	Patch %	Lines
src/datumaro/util/mask_tools.py	88.00%	2 Missing and 1 partial ⚠️
src/datumaro/components/annotation.py	75.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1409   +/-   ##
========================================
  Coverage    80.85%   80.86%           
========================================
  Files          271      271           
  Lines        30689    30713   +24     
  Branches      6197     6203    +6     
========================================
+ Hits         24815    24836   +21     
- Misses        4489     4490    +1     
- Partials      1385     1387    +2     

Flag	Coverage Δ
ubuntu-20.04_Python-3.10	80.84% <86.20%> (+<0.01%)	⬆️
windows-2022_Python-3.10	80.83% <86.20%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[wonjuleee]

Sorry, I was failed to understand this logic correctly. When ignore_index is 255, this returns binary_mask * np.full(tuple(), fill_value=index, dtype=dtype). Is this right?
There is two negative ~ operations. Should we have this?
We have to explanation what ignore_index==255 stands for.

[vinnamkim]

Please see this example

datumaro/src/datumaro/util/mask_tools.py

Lines 152 to 157 in 53b3a5a

	Examples:
	>>> binary_mask = np.eye(2, dtype=np.bool_)
	>>> index_mask = make_index_mask(binary_mask, index=10, ignore_index=255, dtype=np.uint8)
	>>> print(index_mask)
	array([[ 10, 255],
	[255, 10]], dtype=uint8)

We want to convert a binary mask to an index mask by filling 1s with index and 0s with ignore_index. This function would be a simple function like

return np.where(binary_mask, mask, ignore_index)

, but this function has if-else branching in the loop. Thus, it is hard to be accelerated by hardware.

~ is a bit-wise flipping operator. Therefore, this logic is doing (~255 == 0)

[~10, 0]
[0, ~10]

=>

[10, 255]
[255, 10]

Anyway, 53b3a5a improved it further to cover the general cases.

[vinnamkim]

def kernel4(binary_mask, index, ignore_index=0, dtype=None):
    if dtype is None:
        dtype = np.min_scalar_type(index)
        if dtype != np.min_scalar_type(ignore_index):
            raise ValueError()

    mask = binary_mask * np.array([index], dtype=dtype)

    if ignore_index == 0:
        return mask

    return np.where(binary_mask, mask, ignore_index)

from timeit import timeit

binary_mask = np.random.randint(0, 2, size=[1024, 1024], dtype=np.bool_)

print("Kernel4 time: ", timeit(lambda: kernel4(binary_mask, index=10, ignore_index=230), number=200))
print("make_index_mask time: ", timeit(lambda: make_index_mask(binary_mask, index=10, ignore_index=230), number=200))

There was a huge performance gap with/without this optimization in my desktop

Kernel4 time:  0.8781529648695141
make_index_mask time:  0.03690833714790642

[wonjuleee]

Could you update changelog to add this in 2.0 (will 1.6.0)?

[vinnamkim]

Could you update changelog to add this in 2.0 (will 1.6.0)?

Can we do the update after merging #1419 (review) and branching out 1.6.0?