mapreader 1.3.5__tar.gz → 1.3.7__tar.gz

{mapreader-1.3.5 → mapreader-1.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mapreader
-Version: 1.3.5
+Version: 1.3.7
 Summary: A computer vision pipeline for the semantic exploration of maps/images at scale
 Home-page: https://github.com/Living-with-machines/MapReader
 Download-URL: https://github.com/Living-with-machines/MapReader/archive/refs/heads/main.zip
@@ -58,6 +58,7 @@ Requires-Dist: geopandas<1.0.0
 Requires-Dist: pyogrio>=0.7.2
 Requires-Dist: cartopy>=0.22.0
 Requires-Dist: joblib>=1.4.0
+Requires-Dist: opencv-python<5.0.0.0
 Provides-Extra: dev
 Requires-Dist: pytest<9.0.0; extra == "dev"
 Requires-Dist: pytest-cov<6.0.0,>=4.1.0; extra == "dev"

{mapreader-1.3.5 → mapreader-1.3.7}/mapreader/__init__.py

@@ -1,17 +1,25 @@
+# download
+from mapreader.download.sheet_downloader import SheetDownloader
+from mapreader.download.downloader import Downloader
+from mapreader.download.downloader_utils import create_polygon_from_latlons, create_line_from_latlons
+
+
+# load
 from mapreader.load.images import MapImages
 from mapreader.load.loader import loader
 from mapreader.load.loader import load_patches
 
-from mapreader.download.sheet_downloader import SheetDownloader
-from mapreader.download.downloader import Downloader
-from mapreader.download.downloader_utils import create_polygon_from_latlons, create_line_from_latlons
+# annotate
+from mapreader.annotate.annotator import Annotator
 
+# classify
 from mapreader.classify.load_annotations import AnnotationsLoader
 from mapreader.classify.datasets import PatchDataset
 from mapreader.classify.datasets import PatchContextDataset
 from mapreader.classify.classifier import ClassifierContainer
 from mapreader.classify import custom_models
 
+# spot_text
 try:
     from mapreader.spot_text.deepsolo_runner import DeepSoloRunner
 except ImportError:
@@ -22,19 +30,26 @@ try:
 except ImportError:
     pass
 
-from mapreader.process import process
-
-from mapreader.annotate.annotator import Annotator
+try:
+    from mapreader.spot_text.maptext_runner import MapTextRunner
+except ImportError:
+    pass
 
-from . import _version
 
-__version__ = _version.get_versions()["version"]
+# post process
+from mapreader.process.context_post_process import ContextPostProcessor
+from mapreader.process.occlusion_analysis import OcclusionAnalyzer
 
+# utils
 from mapreader.load import geo_utils
 
-import mapreader
 
+# version
+from . import _version
+__version__ = _version.get_versions()["version"]
+
+import mapreader
 
 def print_version():
     """Print the current version of mapreader."""
-    print(mapreader.__version__)
+    print(mapreader.__version__)

{mapreader-1.3.5 → mapreader-1.3.7}/mapreader/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2024-08-02T15:22:56+0100",
+ "date": "2024-08-12T15:00:36+0100",
  "dirty": false,
  "error": null,
- "full-revisionid": "49ac0f1daccf0da74b0570db6ade09578debb164",
- "version": "1.3.5"
+ "full-revisionid": "6eec8310fe00efb31c03d0f4618dd7dd8a8ebd46",
+ "version": "1.3.7"
 }
 '''  # END VERSION_JSON
 

{mapreader-1.3.5 → mapreader-1.3.7}/mapreader/annotate/annotator.py

@@ -55,6 +55,8 @@ class Annotator:
         Name of the column in which labels are stored in patch DataFrame, by default "label"
     show_context : bool, optional
         Whether to show context when loading patches, by default False
+    border : bool, optional
+        Whether to add a border around the central patch when showing context, by default False
     auto_save : bool, optional
         Whether to automatically save annotations, by default True
     delimiter : str, optional
@@ -108,6 +110,7 @@ class Annotator:
         patch_paths_col: str = "image_path",
         label_col: str = "label",
         show_context: bool = False,
+        border: bool = False,
         auto_save: bool = True,
         delimiter: str = ",",
         sortby: str | None = None,
@@ -255,6 +258,7 @@ class Annotator:
         self.patch_paths_col = patch_paths_col
         self.annotations_file = annotations_file
         self.show_context = show_context
+        self.border = border
         self.auto_save = auto_save
         self.username = username
         self.task_name = task_name
@@ -452,7 +456,7 @@ class Annotator:
 
         self.navbox = widgets.VBox([widgets.HBox([prev_btn, next_btn])])
 
-    def get_queue(
+    def _get_queue(
         self, as_type: str | None = "list"
     ) -> list[int] | (pd.Index | pd.Series):
         """
@@ -520,7 +524,7 @@ class Annotator:
             return indices
         return queue_df
 
-    def get_context(self):
+    def _get_context(self):
         """
         Provides the surrounding context for the patch to be annotated.
 
@@ -531,15 +535,21 @@ class Annotator:
             context.
         """
 
-        def get_path(image_path, dim=True):
+        def get_square(image_path, dim=True, border=False):
             # Resize the image
             im = Image.open(image_path)
 
             # Dim the image
-            if dim in [True, "True"]:
+            if dim in ["True", True]:
                 im_array = np.array(im)
                 im_array = 256 - (256 - im_array) * 0.4  # lighten image
                 im = Image.fromarray(im_array.astype(np.uint8))
+
+            if border in ["True", True] and self.border:
+                w, h = im.size
+                im = ImageOps.expand(im, border=2, fill="red")
+                im = im.resize((w, h))
+
             return im
 
         def get_empty_square(patch_size: tuple[int, int]):
@@ -593,7 +603,10 @@ class Annotator:
 
         # derive ids from items
         ids = [x.index[0] if len(x.index) == 1 else None for x in items]
-        ids = [x != ix for x in ids]
+        # list of booleans, True if not the current patch, False if the current patch
+        # used for dimming the surrounding patches and adding a border to the current patch
+        dim_bools = [x != ix for x in ids]
+        border_bools = [x == ix for x in ids]
 
         # derive images from items
         image_paths = [
@@ -601,14 +614,16 @@ class Annotator:
         ]
 
         # zip them
-        image_list = list(zip(image_paths, ids))
+        image_list = list(zip(image_paths, dim_bools, border_bools))
 
         # split them into rows
         per_row = len(deltas)
         images = [
             [
-                get_path(x[0], dim=x[1]) if x[0] else get_empty_square((width, height))
-                for x in lst
+                get_square(image_path, dim=dim, border=border)
+                if image_path
+                else get_empty_square((width, height))
+                for image_path, dim, border in lst
             ]
             for lst in array_split(image_list, per_row)
         ]
@@ -641,6 +656,7 @@ class Annotator:
     def annotate(
         self,
         show_context: bool | None = None,
+        border: bool | None = None,
         sortby: str | None = None,
         ascending: bool | None = None,
         min_values: dict | None = None,
@@ -648,6 +664,7 @@ class Annotator:
         surrounding: int | None = None,
         resize_to: int | None = None,
         max_size: int | None = None,
+        show_vals: list[str] | None = None,
     ) -> None:
         """Annotate at the patch-level of the current patch.
         Renders the annotation interface for the first image.
@@ -657,6 +674,9 @@ class Annotator:
         show_context : bool or None, optional
             Whether or not to display the surrounding context for each image.
             Default is None.
+        border : bool or None, optional
+            Whether or not to display a border around the image (when using `show_context`).
+            Default is None.
         sortby : str or None, optional
             Name of the column to use to sort the patch DataFrame, by default None.
             Default sort order is ``ascending=True``. Pass ``ascending=False`` keyword argument to sort in descending order.
@@ -677,12 +697,18 @@ class Annotator:
         max_size : int or None, optional
             The size in pixels for the longest side to which constrain each
             patch image. Default: 100.
+        resize_to : int or None, optional
+            The size in pixels for the longest side to which resize each patch image. Default: None.
+        show_vals : list[str] or None, optional
+            List of column names to show in the display. By default, None.
 
         Notes
         -----
         This method is a wrapper for the
         :meth:`~.annotate.annotator.Annotate._annotate` method.
         """
+        if border is not None:
+            self.border = border
         if sortby is not None:
             self._sortby = sortby
         if ascending is not None:
@@ -693,8 +719,10 @@ class Annotator:
         if max_values is not None:
             self._max_values = max_values
 
+        self.show_vals = show_vals
+
         # re-set up queue using new min/max values
-        self._queue = self.get_queue()
+        self._queue = self._get_queue()
 
         self._annotate(
             show_context=show_context,
@@ -743,7 +771,7 @@ class Annotator:
             self.max_size = max_size
 
         # re-set up queue
-        self._queue = self.get_queue()
+        self._queue = self._get_queue()
 
         if self._filter_for is not None:
             print(f"[INFO] Filtering for: {self._filter_for}")
@@ -767,7 +795,7 @@ class Annotator:
             Previous index, current index, and path of the current image.
         """
         if self.current_index == len(self._queue):
-            self.render_complete()
+            self._render_complete()
             return
 
         self.previous_index = self.current_index
@@ -777,7 +805,7 @@ class Annotator:
 
         img_path = self.patch_df.at[ix, self.patch_paths_col]
 
-        self.render()
+        self._render()
         return self.previous_index, self.current_index, img_path
 
     def _prev_example(self, *_) -> tuple[int, int, str]:
@@ -790,7 +818,7 @@ class Annotator:
             Previous index, current index, and path of the current image.
         """
         if self.current_index == len(self._queue):
-            self.render_complete()
+            self._render_complete()
             return
 
         if self.current_index > 0:
@@ -801,10 +829,10 @@ class Annotator:
 
         img_path = self.patch_df.at[ix, self.patch_paths_col]
 
-        self.render()
+        self._render()
         return self.previous_index, self.current_index, img_path
 
-    def render(self) -> None:
+    def _render(self) -> None:
         """
         Displays the image at the current index in the annotation interface.
 
@@ -817,7 +845,7 @@ class Annotator:
         """
         # Check whether we have reached the end
         if self.current_index >= len(self) - 1:
-            self.render_complete()
+            self._render_complete()
             return
 
         ix = self._queue[self.current_index]
@@ -841,7 +869,7 @@ class Annotator:
             clear_output(wait=True)
             image = self.get_patch_image(ix)
             if self.show_context:
-                context = self.get_context()
+                context = self._get_context()
                 self._context_image = context
                 display(context.convert("RGB"))
             else:
@@ -852,6 +880,22 @@ class Annotator:
                 text = f'<p><a href="{url}" target="_blank">Click to see entire map.</a></p>'
                 add_ins += [widgets.HTML(text)]
 
+            if self.show_vals:
+                patch_info = []
+                for col in self.show_vals:
+                    if col in self.patch_df.columns:
+                        val = self.patch_df.at[ix, col]
+                        if isinstance(val, float):
+                            val = f"{val:.4g}"
+                        patch_info.append(f"<b>{col}</b>: {val}")
+                add_ins += [
+                    widgets.HTML(
+                        '<p style="text-align: center">'
+                        + "<br>".join(patch_info)
+                        + "</p>"
+                    )
+                ]
+
             value = self.current_index + 1 if self.current_index else 1
             description = f"{value} / {len(self._queue)}"
             add_ins += [
@@ -983,7 +1027,7 @@ class Annotator:
         _filter = ~self.patch_df[self.label_col].isna()
         return self.patch_df[_filter]
 
-    def render_complete(self):
+    def _render_complete(self):
         """
         Renders the completion message once all images have been annotated.
 

{mapreader-1.3.5 → mapreader-1.3.7}/mapreader/annotate/utils.py

@@ -310,7 +310,10 @@ def annotation_interface(
                     # stream=True so we don't download the whole page, only check if
                     # the page exists
                     response = requests.get(url, stream=True)
-                    assert response.status_code < 400
+                    if not response.status_code < 400:
+                        raise RuntimeError(
+                            f"URL could not get a response: {response.status_code}"
+                        )
                     print()
                     print(f"URL: {url}")
                 except:

{mapreader-1.3.5 → mapreader-1.3.7}/mapreader/classify/classifier.py

@@ -86,8 +86,8 @@ class ClassifierContainer:
         The optimizer being used for training the model.
     scheduler : None or torch.optim.lr_scheduler._LRScheduler
         The learning rate scheduler being used for training the model.
-    criterion : None or nn.modules.loss._Loss
-        The criterion to use for training the model.
+    loss_fn : None or nn.modules.loss._Loss
+        The loss function to use for training the model.
     metrics : dict
         A dictionary to store the metrics computed during training.
     last_epoch : int
@@ -159,7 +159,7 @@ class ClassifierContainer:
 
             self.optimizer = None
             self.scheduler = None
-            self.criterion = None
+            self.loss_fn = None
 
             self.metrics = {}
             self.last_epoch = 0
@@ -399,54 +399,54 @@ Use ``initialize_optimizer`` or ``add_optimizer`` to define one."  # noqa
 
         self.scheduler = scheduler
 
-    def add_criterion(
-        self, criterion: str | nn.modules.loss._Loss | None = "cross entropy"
+    def add_loss_fn(
+        self, loss_fn: str | nn.modules.loss._Loss | None = "cross entropy"
     ) -> None:
         """
-        Add a loss criterion to the classifier object.
+        Add a loss function to the classifier object.
 
         Parameters
         ----------
-        criterion : str or torch.nn.modules.loss._Loss
-            The loss criterion to add to the classifier object.
+        loss_fn : str or torch.nn.modules.loss._Loss
+            The loss function to add to the classifier object.
             Accepted string values are "cross entropy" or "ce" (cross-entropy), "bce" (binary cross-entropy) and "mse" (mean squared error).
 
         Returns
         -------
         None
-            The function only modifies the ``criterion`` attribute of the
+            The function only modifies the ``loss_fn`` attribute of the
             classifier and does not return anything.
         """
-        if isinstance(criterion, str):
-            if criterion in ["cross entropy", "ce", "cross_entropy", "cross-entropy"]:
-                criterion = nn.CrossEntropyLoss()
-            elif criterion in [
+        if isinstance(loss_fn, str):
+            if loss_fn in ["cross entropy", "ce", "cross_entropy", "cross-entropy"]:
+                loss_fn = nn.CrossEntropyLoss()
+            elif loss_fn in [
                 "bce",
                 "binary_cross_entropy",
                 "binary cross entropy",
                 "binary cross-entropy",
             ]:
-                criterion = nn.BCELoss()
-            elif criterion in [
+                loss_fn = nn.BCELoss()
+            elif loss_fn in [
                 "mse",
                 "mean_square_error",
                 "mean_squared_error",
                 "mean squared error",
             ]:
-                criterion = nn.MSELoss()
+                loss_fn = nn.MSELoss()
             else:
                 raise NotImplementedError(
-                    '[ERROR] At present, if passing ``criterion`` as a string, criterion can only be "cross entropy" or "ce" (cross-entropy), "bce" (binary cross-entropy) or "mse" (mean squared error).'
+                    '[ERROR] At present, if passing ``loss_fn`` as a string, the loss function can only be "cross entropy" or "ce" (cross-entropy), "bce" (binary cross-entropy) or "mse" (mean squared error).'
                 )
 
-            print(f'[INFO] Using "{criterion}" as criterion.')
+            print(f'[INFO] Using "{loss_fn}" as loss function.')
 
-        elif not isinstance(criterion, nn.modules.loss._Loss):
+        elif not isinstance(loss_fn, nn.modules.loss._Loss):
             raise ValueError(
-                '[ERROR] Please pass ``criterion`` as a string ("cross entropy", "bce" or "mse") or torch.nn loss function (see https://pytorch.org/docs/stable/nn.html).'
+                '[ERROR] Please pass ``loss_fn`` as a string ("cross entropy", "bce" or "mse") or torch.nn loss function (see https://pytorch.org/docs/stable/nn.html).'
             )
 
-        self.criterion = criterion
+        self.loss_fn = loss_fn
 
     def model_summary(
         self,
@@ -643,7 +643,7 @@ Use ``initialize_optimizer`` or ``add_optimizer`` to define one."  # noqa
 
     def train_component_summary(self) -> None:
         """
-        Print a summary of the optimizer, criterion, and trainable model
+        Print a summary of the optimizer, loss function, and trainable model
         components.
 
         Returns:
@@ -655,8 +655,8 @@ Use ``initialize_optimizer`` or ``add_optimizer`` to define one."  # noqa
         print("* Optimizer:")
         print(str(self.optimizer))
         print(divider)
-        print("* Criterion:")
-        print(str(self.criterion))
+        print("* Loss function:")
+        print(str(self.loss_fn))
         print(divider)
         print("* Model:")
         self.model_summary(trainable_col=True)
@@ -783,9 +783,9 @@ Use ``initialize_optimizer`` or ``add_optimizer`` to define one."  # noqa
         Raises
         ------
         ValueError
-            If the criterion is not set. Use the
-            :meth:`~.classify.classifier.ClassifierContainer.add_criterion`
-            method to set the criterion.
+            If the loss function is not set. Use the
+            :meth:`~.classify.classifier.ClassifierContainer.add_loss_fn`
+            method to set the loss function.
 
             If the optimizer is not set and the phase is "train". Use the
             :meth:`~.classify.classifier.ClassifierContainer.initialize_optimizer`
@@ -894,10 +894,10 @@ Use ``initialize_optimizer`` or ``add_optimizer`` to add one."  # noqa
                             #     summing the final output and the auxiliary
                             #     output but in testing we only consider the
                             #     final output.
-                            if self.criterion is None:
+                            if self.loss_fn is None:
                                 raise ValueError(
-                                    "[ERROR] Criterion is not yet defined.\n\n\
-Use ``add_criterion`` to define one."
+                                    "[ERROR] Loss function is not yet defined.\n\n\
+Use ``add_loss_fn`` to define one."
                                 )
 
                             if self.is_inception and (
@@ -910,8 +910,8 @@ Use ``add_criterion`` to define one."
                                 if not isinstance(aux_outputs, torch.Tensor):
                                     aux_outputs = self._get_logits(aux_outputs)
 
-                                loss1 = self.criterion(outputs, label_indices)
-                                loss2 = self.criterion(aux_outputs, label_indices)
+                                loss1 = self.loss_fn(outputs, label_indices)
+                                loss2 = self.loss_fn(aux_outputs, label_indices)
                                 # https://discuss.pytorch.org/t/how-to-optimize-inception-model-with-auxiliary-classifiers/7958
                                 loss = loss1 + 0.4 * loss2
 
@@ -921,7 +921,7 @@ Use ``add_criterion`` to define one."
                                 if not isinstance(outputs, torch.Tensor):
                                     outputs = self._get_logits(outputs)
 
-                                loss = self.criterion(outputs, label_indices)
+                                loss = self.loss_fn(outputs, label_indices)
 
                             _, pred_label_indices = torch.max(outputs, dim=1)
 

{mapreader-1.3.5 → mapreader-1.3.7}/mapreader/classify/load_annotations.py

@@ -25,6 +25,7 @@ class AnnotationsLoader:
 
     def __init__(self):
         self.annotations = pd.DataFrame()
+        self.labels_map = {}
         self.reviewed = pd.DataFrame()
         self.patch_paths_col = None
         self.label_col = None
@@ -33,6 +34,7 @@ class AnnotationsLoader:
     def load(
         self,
         annotations: str | pd.DataFrame,
+        labels_map: dict | None = None,
         delimiter: str | None = ",",
         images_dir: str | None = None,
         remove_broken: bool | None = True,
@@ -52,6 +54,8 @@ class AnnotationsLoader:
         annotations : Union[str, pd.DataFrame]
             The annotations.
             Can either be the path to a csv file or a pandas.DataFrame.
+        labels_map : Optional[dict], optional
+            A dictionary mapping labels to indices. If not provided, labels will be mapped to indices based on the order in which they appear in the annotations dataframe. By default None.
         delimiter : Optional[str], optional
             The delimiter to use when loading the csv file as a dataframe, by default ",".
         images_dir : Optional[str], optional
@@ -132,8 +136,25 @@ class AnnotationsLoader:
 
         self.unique_labels = self.annotations[self.label_col].unique().tolist()
 
-        labels_map = {i: label for i, label in enumerate(self.unique_labels)}
-        self.labels_map = labels_map
+        # if labels_map is explicitly provided
+        if labels_map:
+            self.labels_map = dict(
+                sorted(labels_map.items())
+            )  # sort labels_map by keys
+            if not set(self.unique_labels).issubset(set(labels_map.values())):
+                raise ValueError(
+                    "[ERROR] There are label(s) in the annotations that are not in the labels map. Please check the labels_map."
+                )
+        # if inferring labels_map
+        else:
+            if append:
+                for label in self.unique_labels:
+                    if label not in self.labels_map.values():
+                        self.labels_map[len(self.labels_map)] = label
+            else:
+                # reset labels map
+                labels_map = {i: label for i, label in enumerate(self.unique_labels)}
+                self.labels_map = labels_map
 
         self.annotations["label_index"] = self.annotations[self.label_col].apply(
             self._get_label_index
@@ -451,10 +472,13 @@ Please check your image paths and update them if necessary.'
                     self.reviewed.loc[input_id, "label_index"] = self._get_label_index(
                         input_label
                     )
-                    assert (
+                    if not (
                         self.annotations[self.label_col].value_counts().tolist()
                         == self.annotations["label_index"].value_counts().tolist()
-                    )
+                    ):
+                        raise RuntimeError(
+                            f"[ERROR] Label indices do not match label counts. Please check the label indices for label '{input_label}'."
+                        )
                     print(
                         f'[INFO] Image {input_id} has been relabelled as "{input_label}"'
                     )
@@ -607,12 +631,18 @@ Please check your image paths and update them if necessary.'
                 test_size=float(relative_frac_test),
                 random_state=random_state,
             )
-            assert len(self.annotations) == len(df_train) + len(df_val) + len(df_test)
+            if not len(self.annotations) == len(df_train) + len(df_val) + len(df_test):
+                raise ValueError(
+                    "[ERROR] Number of annotations in the split dataframes does not match the number of annotations in the original dataframe."
+                )
 
         else:
             df_val = df_temp
             df_test = None
-            assert len(self.annotations) == len(df_train) + len(df_val)
+            if not len(self.annotations) == len(df_train) + len(df_val):
+                raise ValueError(
+                    "[ERROR] Number of annotations in the split dataframes does not match the number of annotations in the original dataframe."
+                )
 
         if context_datasets:
             datasets = self.create_patch_context_datasets(

{mapreader-1.3.5 → mapreader-1.3.7}/mapreader/download/data_structures.py

@@ -14,8 +14,11 @@ class Coordinate:
         lon : float
             longitude value (in range [-180°, 180°] )
         """
-        assert -90 <= lat <= 90
-        assert -180 <= lon <= 180
+        if not -90 <= lat <= 90:
+            raise ValueError("Latitude must be in range [-90, 90]")
+        if not -180 <= lon <= 180:
+            raise ValueError("Longitude must be in range [-180, 180]")
+
         self.lat = lat
         self.lon = lon
 
@@ -37,9 +40,12 @@ class GridIndex:
         z : int
             Zoom level
         """
-        assert z >= 0
-        assert 0 <= x < 2**z
-        assert 0 <= y < 2**z
+        if not z >= 0:
+            raise ValueError("Zoom level must be greater than or equal to 0")
+        if not 0 <= x < 2**z:
+            raise ValueError(f"X value must be in range [0, {2**z}]")
+        if not 0 <= y < 2**z:
+            raise ValueError(f"Y value must be in range [0, {2**z}]")
         self.x = x
         self.y = y
         self.z = z
@@ -61,7 +67,9 @@ class GridBoundingBox:
         cell1 : GridIndex
         cell2 : GridIndex
         """
-        assert cell1.z == cell2.z, "Can't calculate a grid on different scales yet"
+        if cell1.z != cell2.z:
+            raise NotImplementedError("Can't calculate a grid on different scales yet")
+
         start_x = min(cell1.x, cell2.x)
         end_x = max(cell1.x, cell2.x)
         start_y = min(cell1.y, cell2.y)