Remove RasterMask and PointCloudMask classes in favor of boolean dtype in parent class (#737)

Author: rhugonnet

doc/source/api.md

@@ -72,6 +72,7 @@ documentation.
 .. autosummary::
     :toctree: gen_modules/
 
+    Raster.is_mask
     Raster.count_on_disk
     Raster.bands_on_disk
     Raster.is_loaded
@@ -198,7 +199,7 @@ documentation.
 
 And reverse operations.
 
-### Logical operator casting to Mask
+### Logical operators casting to mask (boolean raster)
 
 ```{eval-rst}
 .. autosummary::
@@ -222,34 +223,6 @@ And reverse operations.
     Raster.__array_function__
 ```
 
-## Raster mask
-
-```{eval-rst}
-.. minigallery:: geoutils.RasterMask
-      :add-heading:
-```
-
-### Opening a file
-
-```{eval-rst}
-.. autosummary::
-    :toctree: gen_modules/
-
-    RasterMask
-```
-
-### Overloaded Raster methods
-
-```{eval-rst}
-.. autosummary::
-    :toctree: gen_modules/
-
-    RasterMask.crop
-    RasterMask.reproject
-    RasterMask.polygonize
-    RasterMask.proximity
-```
-
 ## Multiple rasters
 
 ```{eval-rst}
@@ -655,20 +628,3 @@ documentation](https://shapely.readthedocs.io/en/stable/properties.html).
     PointCloud.pointcloud_equal
     PointCloud.georeferenced_coords_equal
 ```
-
-
-## Point cloud mask
-
-```{eval-rst}
-.. minigallery:: geoutils.PointCloudMask
-      :add-heading:
-```
-
-### Opening a file
-
-```{eval-rst}
-.. autosummary::
-    :toctree: gen_modules/
-
-    PointCloudMask
-```

doc/source/conf.py

@@ -124,9 +124,7 @@
 # To avoid long path names in inheritance diagrams
 inheritance_alias = {
     "geoutils.raster.raster.Raster": "geoutils.Raster",
-    "geoutils.raster.raster.RasterMask": "geoutils.RasterMask",
     "geoutils.pointcloud.pointcloud.PointCloud": "geoutils.PointCloud",
-    "geoutils.pointcloud.pointcloud.PointCloudMask": "geoutils.PointCloudMask",
     "geoutils.vector.Vector": "geoutils.Vector",
     "xdem.dem.DEM": "xdem.DEM",
 }

doc/source/core_array_funcs.md

@@ -75,7 +75,7 @@ np.modf(rast)
 ```
 
 Similar to with Python operators, NumPy's [logical comparison functions](https://numpy.org/doc/stable/reference/ufuncs.html#comparison-functions) cast
-{class}`Rasters<geoutils.Raster>` to a {class}`~geoutils.RasterMask`.
+{class}`Rasters<geoutils.Raster>` to a boolean {class}`~geoutils.Raster`, a raster mask.
 
 ```{code-cell} ipython3
 # Universal function with a single input and two outputs

doc/source/core_inheritance.md

@@ -22,8 +22,6 @@ implemented in GeoUtils.
 
 Current {class}`~geoutils.Raster` inheritance extends into other packages, such as [xDEM](https://xdem.readthedocs.io/)
 for analyzing digital elevation models.
-Within GeoUtils, inheritance extends only to {class}`~geoutils.RasterMask` that implements overloaded methods specific to binary raster masks,
-as shown in the diagram below.
 
 ```{eval-rst}
 .. inheritance-diagram:: geoutils.raster.raster

doc/source/core_match_ref.md

@@ -62,7 +62,7 @@ at modifying the georeferencing of {class}`Rasters<geoutils.Raster>` or {class}`
 
 The {func}`~geoutils.Vector.rasterize` operation to convert from {class}`~geoutils.Vector` to {class}`~geoutils.Raster` accepts a {class}`~geoutils.Raster` to define the
 grid and georeferencing. The behaviour is similar for {func}`~geoutils.Vector.create_mask`, that directly relies on {func}`~geoutils.Vector.rasterize` to
-rasterize directly into a boolean {class}`~geoutils.RasterMask`.
+rasterize directly into a boolean {class}`~geoutils.Raster`.
 
 In addition, the {func}`~geoutils.Vector.proximity` operation to compute proximity distances from the vector also relies on a
 {func}`~geoutils.Vector.rasterize`, and therefore also accepts a {class}`~geoutils.Raster` as reference.

doc/source/core_py_ops.md

@@ -69,14 +69,13 @@ If an unmasked {class}`~numpy.ndarray` is passed, it will internally be cast int
 {class}`~geoutils.Raster.nodata` values. Additionally, the {attr}`~geoutils.Raster.dtype` are also reconciled as they would for {class}`~numpy.ndarray`,
 following [standard NumPy coercion rules](https://numpy.org/doc/stable/reference/generated/numpy.find_common_type.html).
 
-## Logical comparisons cast to {class}`~geoutils.RasterMask`
+## Logical comparisons cast to a raster mask
 
 Logical comparison operators ({func}`==<operator.eq>`, {func}` != <operator.ne>`, {func}`>=<operator.ge>`, {func}`><operator.gt>`, {func}`<=<operator.le>`,
 {func}`<<operator.lt>`) can be used on a {class}`~geoutils.Raster`, also in combination with any other {class}`~geoutils.Raster`, {class}`~numpy.ndarray` or
 number.
 
-Those operation always return a {class}`~geoutils.RasterMask`, a subclass of {class}`~geoutils.Raster` with a boolean {class}`~numpy.ma.MaskedArray`
-as {class}`~geoutils.Raster.data`.
+Those operation always return a raster mask i.e. a {class}`~geoutils.Raster` with a boolean {class}`~numpy.ma.MaskedArray` as {class}`~geoutils.Raster.data`.
 
 ```{code-cell} ipython3
 # Logical comparison with a number
@@ -85,14 +84,14 @@ mask
 ```
 
 ```{note}
-A {class}`~geoutils.RasterMask`'s {attr}`~geoutils.Raster.data` remains a {class}`~numpy.ma.MaskedArray`. Therefore, it still maps invalid values through its
-{attr}`~numpy.ma.MaskedArray.mask`, but has no associated {attr}`~geoutils.Raster.nodata`.
+A boolean {class}`~geoutils.Raster`'s {attr}`~geoutils.Raster.data` remains a {class}`~numpy.ma.MaskedArray`. Therefore, it still maps invalid values
+through its {attr}`~numpy.ma.MaskedArray.mask`, but has no associated {attr}`~geoutils.Raster.nodata`.
 ```
 
-## Logical bitwise operations on {class}`~geoutils.RasterMask`
+## Logical bitwise operations on raster masks
 
 Logical bitwise operators ({func}`~ <operator.invert>`, {func}`& <operator.and_>`, {func}`| <operator.or_>`, {func}`^ <operator.xor>`) can be used to
-combine a {class}`~geoutils.RasterMask` with another {class}`~geoutils.RasterMask`, and always output a {class}`~geoutils.RasterMask`.
+combine a boolean {class}`~geoutils.Raster` with another boolean {class}`~geoutils.Raster`, and always output a boolean {class}`~geoutils.Raster`.
 
 ```{code-cell} ipython3
 # Logical bitwise operation between masks
@@ -102,17 +101,18 @@ mask
 
 (py-ops-indexing)=
 
-## Indexing a {class}`~geoutils.Raster` with a {class}`~geoutils.RasterMask`
+## Indexing a {class}`~geoutils.Raster` with a raster mask
 
 Finally, indexing and index assignment operations ({func}`[] <operator.getitem>`, {func}`[]= <operator.setitem>`) are both supported by
 {class}`Rasters<geoutils.Raster>`.
 
-For indexing, they can be passed either a {class}`~geoutils.RasterMask` with the same georeferencing, or a boolean {class}`~numpy.ndarray` of the same shape.
+For indexing, they can be passed either a boolean {class}`~geoutils.Raster` with the same georeferencing, or a boolean {class}`~numpy.ndarray` of the same
+shape.
 For assignment, either a {class}`~geoutils.Raster` with the same georeferencing, or any {class}`~numpy.ndarray` of the same shape is expected.
 
-When indexing, a flattened {class}`~numpy.ma.MaskedArray` is returned with the indexed values of the {class}`~geoutils.RasterMask` **excluding those masked in its
-{class}`~geoutils.Raster.data`'s {class}`~numpy.ma.MaskedArray` (for instance, nodata values present during a previous logical comparison)**. To bypass this
-behaviour, simply index without the mask using {attr}`Mask.data.data`.
+When indexing, a flattened {class}`~numpy.ma.MaskedArray` is returned with the indexed values of the boolean {class}`~geoutils.Raster` **excluding those masked
+in its {class}`~geoutils.Raster.data`'s {class}`~numpy.ma.MaskedArray` (for instance, nodata values present during a previous logical comparison)**. To bypass this
+behaviour, simply index without the mask using {attr}`Raster.data.data`.
 
 ```{code-cell} ipython3
 # Indexing the raster with the previous mask

doc/source/feature_overview.md

@@ -195,25 +195,26 @@ import numpy as np
 rast = (rast - np.min(rast)) / (np.max(rast) - np.min(rast))
 ```
 
-## Casting to {class}`~geoutils.RasterMask`, indexing and overload
+## Casting to raster mask, indexing and overload
 
 All {class}`~geoutils.Raster` objects also support Python logical comparison operators ({func}`==<operator.eq>`, {func}` != <operator.ne>`, {func}`>=<operator.ge>`, {func}`><operator.gt>`, {func}`<=<operator.le>`,
-{func}`<<operator.lt>`), or more complex NumPy logical functions. Those operations automatically casts them into a {class}`~geoutils.RasterMask`, a boolean raster that inherits all methods from {class}`~geoutils.Raster`.
+{func}`<<operator.lt>`), or more complex NumPy logical functions. Those operations automatically casts them into a raster mask, i.e. a boolean
+{class}`~geoutils.Raster`.
 
 ```{code-cell} ipython3
 # Get mask of an AOI: infrared index above 0.6, at least 200 m from glaciers
 mask_aoi = np.logical_and(rast > 0.6, rast_proximity_to_vec > 200)
 ```
 
-Masks can then be used for indexing a {class}`~geoutils.Raster`, which returns a {class}`~numpy.ma.MaskedArray` of indexed values.
+Raster masks can then be used for indexing a {class}`~geoutils.Raster`, which returns a {class}`~numpy.ma.MaskedArray` of indexed values.
 
 ```{code-cell} ipython3
 # Index raster with mask to extract a 1-D array
 values_aoi = rast[mask_aoi]
 ```
 
-Masks also have simplified, overloaded {class}`~geoutils.Raster` methods due to their boolean {class}`dtype<numpy.dtype>`. Using {func}`~geoutils.Raster.polygonize` with a
-{class}`~geoutils.RasterMask` is straightforward, for instance, to retrieve a {class}`~geoutils.Vector` of the area-of-interest:
+Raster masks also have simplified {class}`~geoutils.Raster` methods due to their boolean {class}`dtype<numpy.dtype>` rendering many arguments implicit.
+For instance, using {func}`~geoutils.Raster.polygonize` with a raster mask is straightforward, to retrieve a {class}`~geoutils.Vector` of the area-of-interest:
 
 ```{code-cell} ipython3
 # Polygonize areas where mask is True