mapreader.annotate.annotator

Module Contents

Classes

Annotator

Annotator class for annotating patches with labels.
class mapreader.annotate.annotator.Annotator(patch_df=None, parent_df=None, labels=None, patch_paths=None, parent_paths=None, metadata_path=None, annotations_dir='./annotations', patch_paths_col='image_path', label_col='label', show_context=False, auto_save=True, delimiter=',', sortby=None, ascending=True, username=None, task_name=None, min_values=None, max_values=None, filter_for=None, surrounding=1, max_size=1000, resize_to=None)

Bases: pandas.DataFrame

Annotator class for annotating patches with labels.

Parameters:

  • patch_df (str or pd.DataFrame or None, optional) – Path to a CSV file or a pandas DataFrame containing patch data, by default None

  • parent_df (str or pd.DataFrame or None, optional) – Path to a CSV file or a pandas DataFrame containing parent data, by default None

  • labels (list, optional) – List of labels for annotation, by default None

  • patch_paths (str or None, optional) – Path to patch images, by default None Ignored if patch_df is provided.

  • parent_paths (str or None, optional) – Path to parent images, by default None Ignored if parent_df is provided.

  • metadata_path (str or None, optional) – Path to metadata CSV file, by default None

  • annotations_dir (str, optional) – Directory to store annotations, by default “./annotations”

  • patch_paths_col (str, optional) – Name of the column in which image paths are stored in patch DataFrame, by default “image_path”

  • label_col (str, optional) – 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

  • auto_save (bool, optional) – Whether to automatically save annotations, by default True

  • delimiter (str, optional) – Delimiter used in CSV files, by default “,”

  • 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.

  • ascending (bool, optional) – Whether to sort the DataFrame in ascending order when using the sortby argument, by default True.

  • username (str or None, optional) – Username to use when saving annotations file, by default None. If not provided, a random string is generated.

  • task_name (str or None, optional) – Name of the annotation task, by default None.

  • min_values (dict, optional) – A dictionary consisting of column names (keys) and minimum values as floating point values (values), by default None.

  • max_values (dict, optional) – A dictionary consisting of column names (keys) and maximum values as floating point values (values), by default None.

  • filter_for (dict, optional) – A dictionary consisting of column names (keys) and values to filter for (values), by default None.

  • surrounding (int, optional) – The number of surrounding images to show for context, by default 1.

  • max_size (int, optional) – The size in pixels for the longest side to which constrain each patch image, by default 1000.

  • resize_to (int or None, optional) – The size in pixels for the longest side to which resize each patch image, by default None.

Raises:

  • FileNotFoundError – If the provided patch_df or parent_df file path does not exist

  • ValueError – If patch_df or parent_df is not a valid path to a CSV file or a pandas DataFrame If patch_df or patch_paths is not provided If the DataFrame does not have the required columns If sortby is not a string or None If labels provided are not in the form of a list

  • SyntaxError – If labels provided are not in the form of a list

property filtered: pandas.DataFrame
Return type:

pandas.DataFrame

get_queue(as_type='list')

Gets the indices of rows which are eligible for annotation.

Parameters:

as_type (str, optional) – The format in which to return the indices. Options: “list”, “index”. Default is “list”. If any other value is provided, it returns a pandas.Series.

Returns:

Depending on “as_type”, returns either a list of indices, a pd.Index object, or a pd.Series of legible rows.

Return type:

List[int] or pandas.Index or pandas.Series

get_context()

Provides the surrounding context for the patch to be annotated.

Returns:

An IPython VBox widget containing the surrounding patches for context.

Return type:

ipywidgets.VBox

annotate(show_context=None, sortby=None, ascending=None, min_values=None, max_values=None, surrounding=None, resize_to=None, max_size=None)

Annotate at the patch-level of the current patch. Renders the annotation interface for the first image.

Parameters:

  • show_context (bool or None, optional) – Whether or not to display the surrounding context for each image. 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.

  • ascending (bool, optional) – Whether to sort the DataFrame in ascending order when using the sortby argument, by default True.

  • min_values (dict or None, optional) – Minimum values for each property to filter images for annotation. It should be provided as a dictionary consisting of column names (keys) and minimum values as floating point values (values). Default is None.

  • max_values (dict or None, optional) – Maximum values for each property to filter images for annotation. It should be provided as a dictionary consisting of column names (keys) and minimum values as floating point values (values). Default is None

  • surrounding (int or None, optional) – The number of surrounding images to show for context. Default: 1.

  • 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 | None)

Return type:

None

Notes

This method is a wrapper for the _annotate method.

render()

Displays the image at the current index in the annotation interface.

If the current index is greater than or equal to the length of the dataframe, the method disables the “next” button and saves the data.

Return type:

None

get_patch_image(ix)

Returns the image at the given index.

Parameters:

ix (int | str) – The index of the image in the dataframe.

Returns:

A PIL.Image object of the image at the given index.

Return type:

PIL.Image

get_labelled_data(sort=True, index_labels=False, include_paths=True)

Returns the annotations made so far.

Parameters:

  • sort (bool, optional) – Whether to sort the dataframe by the order of the images in the input data, by default True

  • index_labels (bool, optional) – Whether to return the label’s index number (in the labels list provided in setting up the instance) or the human-readable label for each row, by default False

  • include_paths (bool, optional) – Whether to return a column containing the full path to the annotated image or not, by default True

Returns:

A dataframe containing the labelled images and their associated label index.

Return type:

pandas.DataFrame

render_complete()

Renders the completion message once all images have been annotated.

Return type:

None