datumaro.plugins.transforms

Classes

AnnsToLabels(extractor)	Collects all labels from annotations (of all types) and transforms them into a set of annotations of type Label
AstypeAnnotations(extractor[, mapping])	Converts the types of annotations within a dataset based on a specified mapping.
BboxValuesDecrement(extractor)	Subtracts one from the coordinates of bounding boxes
BoxesToMasks(extractor)
BoxesToPolygons(extractor)
Clean(extractor[, batch_size, num_workers])	A class used to refine the media items in a dataset.
Correct(extractor, reports)	This class provides functionality to correct and refine a dataset based on a validation report.
CropCoveredSegments(extractor)	Sorts polygons and masks ("segments") according to z_order, crops covered areas of underlying segments.
IdFromImageName(extractor[, ensure_unique, ...])	Renames items in the dataset based on the image file name, excluding the extension.
MapSubsets(extractor[, mapping])	Renames subsets in the dataset.
MasksToPolygons(extractor)
MergeInstanceSegments(extractor[, ...])	Replaces instance masks and, optionally, polygons with a single mask.
PolygonsToMasks(extractor)
ProjectInfos(extractor, dst_infos[, overwrite])	Changes the content of infos.
ProjectLabels(extractor, dst_labels)	Changes the order of labels in the dataset from the existing to the desired one, removes unknown labels and adds new labels.
PseudoLabeling(extractor[, labels, explorer])	A class used to assign pseudo-labels to items in a dataset based on their similarity to predefined labels.
RandomSplit(extractor, splits[, seed])	Joins all subsets into one and splits the result into few parts.
Reindex(extractor[, start])	Replaces dataset item IDs with sequential indices.
ReindexAnnotations(extractor[, start, ...])	Replaces dataset items' annotations with sequential indices.
RemapLabels(extractor, mapping[, default])	Changes labels in the dataset.
RemoveAnnotations(extractor, *, ids)	Allows to remove annotations on specific dataset items.
RemoveAttributes(extractor[, ids, attributes])	Allows to remove item and annotation attributes in a dataset.
RemoveItems(extractor, ids)	Allows to remove specific dataset items from dataset by their ids.
Rename(extractor, regex)	Renames items in the dataset.
ResizeTransform(extractor, width, height)	Resizes images and annotations in the dataset to the specified size.
ShapesToBoxes(extractor)
Sort(extractor[, key])	Sorts dataset items.

class datumaro.plugins.transforms.CropCoveredSegments(extractor: IDataset)

Bases: ItemTransform, CliPlugin

Sorts polygons and masks (“segments”) according to z_order, crops covered areas of underlying segments. If a segment is split into several independent parts by the segments above, produces the corresponding number of separate annotations joined into a group.

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

classmethod crop_segments(segment_anns, img_width, img_height)

class datumaro.plugins.transforms.MergeInstanceSegments(extractor, include_polygons=False)

Bases: ItemTransform, CliPlugin

Replaces instance masks and, optionally, polygons with a single mask. A group of annotations with the same group id is considered an “instance”. The largest annotation in the group is considered the group “head”, so the resulting mask takes properties from that annotation.

classmethod build_cmdline_parser(**kwargs)

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

classmethod merge_segments(instance, img_width, img_height, include_polygons=False)

static find_instances(annotations)

class datumaro.plugins.transforms.PolygonsToMasks(extractor: IDataset)

Bases: ItemTransform, CliPlugin

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

static convert_polygon(polygon: Polygon | Ellipse, img_h, img_w)

class datumaro.plugins.transforms.BoxesToMasks(extractor: IDataset)

Bases: ItemTransform, CliPlugin

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

static convert_bbox(bbox, img_h, img_w)

class datumaro.plugins.transforms.BoxesToPolygons(extractor: IDataset)

Bases: ItemTransform, CliPlugin

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

static convert_bbox(bbox: Bbox)

class datumaro.plugins.transforms.MasksToPolygons(extractor: IDataset)

Bases: ItemTransform, CliPlugin

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

static convert_mask(mask)

class datumaro.plugins.transforms.ShapesToBoxes(extractor: IDataset)

Bases: ItemTransform, CliPlugin

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

static convert_shape(shape)

class datumaro.plugins.transforms.Reindex(extractor, start: int = 1)

Bases: Transform, CliPlugin

Replaces dataset item IDs with sequential indices.

classmethod build_cmdline_parser(**kwargs)

class datumaro.plugins.transforms.ReindexAnnotations(extractor, start: int = 1, reindex_each_item: bool = False)

Bases: ItemTransform, CliPlugin

Replaces dataset items’ annotations with sequential indices.

classmethod build_cmdline_parser(**kwargs)

transform_item(item: DatasetItem) → DatasetItem

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.Sort(extractor, key=None)

Bases: Transform, CliPlugin

Sorts dataset items.

classmethod build_cmdline_parser(**kwargs)

class datumaro.plugins.transforms.MapSubsets(extractor, mapping=None)

Bases: ItemTransform, CliPlugin

Renames subsets in the dataset.

classmethod build_cmdline_parser(**kwargs)

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.RandomSplit(extractor, splits, seed=None)

Bases: Transform, CliPlugin

Joins all subsets into one and splits the result into few parts. It is expected that item ids are unique and subset ratios sum up to 1.

Example:

random_split --subset train:.67 --subset test:.33

classmethod build_cmdline_parser(**kwargs)

class datumaro.plugins.transforms.IdFromImageName(extractor, ensure_unique: bool = False, suffix_length: int = 3)

Bases: ItemTransform, CliPlugin

Renames items in the dataset based on the image file name, excluding the extension. When ‘ensure_unique’ is enabled, a random suffix is appened to ensure each identifier is unique in cases where the image name is not distinct. By default, the random suffix is three characters long, but this can be adjusted with the ‘suffix_length’ parameter.

Examples:

• Renames items without duplication check:

id_from_image_name

• Renames items with duplication check:

  id_from_image_name --ensure_unique


- Renames items with duplication check and alters the suffix length(default: 3):

id_from_image_name --ensure_unique --suffix_length 2

DEFAULT_RETRY = 1000

SUFFIX_LETTERS = 'abcdefghijklmnopqrstuvwxyz0123456789'

classmethod build_cmdline_parser(**kwargs)

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.Rename(extractor, regex)

Bases: ItemTransform, CliPlugin

Renames items in the dataset. Supports regular expressions. The first character in the expression is a delimiter for the pattern and replacement parts. Replacement part can also contain str.format replacement fields with the item (of type DatasetItem) object available. Please use doulbe quotes to represent regex.

Examples:

• Replace ‘pattern’ with ‘replacement’:

rename -e "|pattern|replacement|"

• Remove ‘frame_’ from item ids:

rename -e "|^frame_||"

• Rename by regex:

rename -e "|frame_(\d+)_extra|{item.subset}_id_\1|"

classmethod build_cmdline_parser(**kwargs)

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.RemapLabels(extractor: IDataset, mapping: Dict[str, str] | List[Tuple[str, str]], default: None | str | DefaultAction = None)

Bases: ItemTransform, CliPlugin

Changes labels in the dataset.

A label can be:

• renamed (and joined with existing) - when ‘–label <old_name>:<new_name>’ is specified

• deleted - when ‘–label <name>:’ is specified, or default action is ‘delete’ and the label is not mentioned in the list. When a label is deleted, all the associated annotations are removed

• kept unchanged - when specified ‘–label <name>:<name>’ or default action is ‘keep’ and the label is not mentioned in the list.

Annotations with no label are managed by the default action policy.

Examples:

• Remove the ‘person’ label (and corresponding annotations):

remap_labels -l person: --default keep

• Rename ‘person’ to ‘pedestrian’ and ‘human’ to ‘pedestrian’, join:

remap_labels -l person:pedestrian -l human:pedestrian --default keep

• Rename ‘person’ to ‘car’ and ‘cat’ to ‘dog’, keep ‘bus’, remove others:

remap_labels -l person:car -l bus:bus -l cat:dog --default delete

class DefaultAction(value)

Bases: Enum

An enumeration.

keep = 1

delete = 2

classmethod build_cmdline_parser(**kwargs)

categories()

Returns metainfo about dataset labels.

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.ProjectInfos(extractor: IDataset, dst_infos: Dict[str, Any], overwrite: bool = False)

Bases: Transform, CliPlugin

Changes the content of infos. A user can add meta-data of dataset such as author, comments, or related papers. Infos values are not affect on the dataset structure. We thus can add any meta-data freely.

classmethod build_cmdline_parser(**kwargs)

infos()

Returns meta-info of dataset.

class datumaro.plugins.transforms.ProjectLabels(extractor: IDataset, dst_labels: Iterable[str] | LabelCategories)

Bases: ItemTransform

Changes the order of labels in the dataset from the existing to the desired one, removes unknown labels and adds new labels. Updates or removes the corresponding annotations.

Labels are matched by names (case dependent). Parent labels are only kept if they are present in the resulting set of labels. If new labels are added, and the dataset has mask colors defined, new labels will obtain generated colors.

Useful for merging similar datasets, whose labels need to be aligned.

Examples:

• Align the source dataset labels to [person, cat, dog]:

project_labels -l person -l cat -l dog

classmethod build_cmdline_parser(**kwargs)

categories()

Returns metainfo about dataset labels.

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.AnnsToLabels(extractor: IDataset)

Bases: ItemTransform, CliPlugin

Collects all labels from annotations (of all types) and transforms them into a set of annotations of type Label

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.BboxValuesDecrement(extractor: IDataset)

Bases: ItemTransform, CliPlugin

Subtracts one from the coordinates of bounding boxes

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.ResizeTransform(extractor: IDataset, width: int, height: int)

Bases: ItemTransform

Resizes images and annotations in the dataset to the specified size. Supports upscaling, downscaling and mixed variants.

Examples:

• Resize all images to 256x256 size

resize -dw 256 -dh 256

classmethod build_cmdline_parser(**kwargs)

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.RemoveItems(extractor: IDataset, ids: Iterable[Tuple[str, str]])

Bases: ItemTransform

Allows to remove specific dataset items from dataset by their ids.

Can be useful to clean the dataset from broken or unnecessary samples.

Examples:

• Remove specific items from the dataset

remove_items --id 'image1:train' --id 'image2:test'

classmethod build_cmdline_parser(**kwargs)

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.RemoveAnnotations(extractor: IDataset, *, ids: Iterable[Tuple[str, str, int | None]])

Bases: ItemTransform

Allows to remove annotations on specific dataset items.

Can be useful to clean the dataset from broken or unnecessary annotations.

Examples:

• Remove annotations from specific items in the dataset

remove_annotations --id 'image1:train' --id 'image2:test'

classmethod build_cmdline_parser(**kwargs)

transform_item(item: DatasetItem)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.RemoveAttributes(extractor: IDataset, ids: Iterable[Tuple[str, str]] | None = None, attributes: Iterable[str] | None = None)

Bases: ItemTransform

Allows to remove item and annotation attributes in a dataset.

Can be useful to clean the dataset from broken or unnecessary attributes.

Examples:

• Remove the is_crowd attribute from dataset

remove_attributes --attr 'is_crowd'

• Remove the occluded attribute from annotations of the 2010_001705 item in the train subset

remove_attributes --id '2010_001705:train' --attr 'occluded'

classmethod build_cmdline_parser(**kwargs)

transform_item(item: DatasetItem)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.Correct(extractor: IDataset, reports: str | Dict)

Bases: Transform, CliPlugin

This class provides functionality to correct and refine a dataset based on a validation report. It processes a validation report (typically in JSON format) to identify and rectify various dataset issues, such as undefined labels, missing annotations, outliers, empty labels/captions, and unnecessary characters in captions. The correction process includes:

• Adding missing labels and attributes.

• Removing or adjusting annotations with invalid or anomalous values.

• Filling in missing labels and captions with appropriate values.

• Removing unnecessary characters from text-based annotations like captions.

• Handling outliers by capping values within specified bounds.

• Updating dataset categories and annotations according to the corrections.

The class is designed to be used as part of a command-line interface (CLI) and can be configured with different validation reports. It integrates with the dataset extraction process, ensuring that corrections are applied consistently across the dataset.

classmethod build_cmdline_parser(**kwargs)

categories()

Returns metainfo about dataset labels.

remove_unnecessary_char(annotations, item_id)

update_caption_value()

update_label_value()

fill_missing_value(annotations, labels, captions)

cap_far_from_mean(annotations, far_from_mean_captions)

cap_outliers(annotations, outliers)

find_outliers(annotations, outliers)

class datumaro.plugins.transforms.AstypeAnnotations(extractor: IDataset, mapping: Dict[str, str] | List[Tuple[str, str]] | None = None)

Bases: ItemTransform

Converts the types of annotations within a dataset based on a specified mapping.

This transform changes annotations to ‘Label’ if they are categorical, and to ‘Caption’ if they are of type string, float, or integer. This is particularly useful when working with tabular data that needs to be converted into a format suitable for specific machine learning tasks.

Examples:

• Converts the type of a title annotation:

astype_annotations --mapping 'title:text'

classmethod build_cmdline_parser(**kwargs)

categories()

Returns metainfo about dataset labels.

transform_item(item: DatasetItem)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.Clean(extractor: IDataset, batch_size: int = 1, num_workers: int = 0)

Bases: TabularTransform

A class used to refine the media items in a dataset.

This class provides methods to clean and preprocess media data within a dataset. The media data can be of various types such as strings, numeric values, or categorical values. The cleaning process for each type of data is handled differently:

• String Media: For string data, the class employs natural language processing (NLP)

techniques to remove unnecessary characters. This involves cleaning tasks such as removing special characters, punctuation, and other irrelevant elements to refine the textual data. - Numeric Media: For numeric data, the class identifies and handles outliers and missing values. Outliers are either removed or replaced based on a defined strategy, and missing values are filled using appropriate methods such as mean, median, or a predefined value.

static remove_unnecessary_char(text)

check_outlier(table, numeric_cols)

check_missing_value(table, float_cols, countable_cols)

static find_closest_value(series, target_value)

cap_outliers(table)

fill_missing_value(series)

refine_tabular_media(item)

transform_item(item)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.

class datumaro.plugins.transforms.PseudoLabeling(extractor: IDataset, labels: List[str] | None = None, explorer: Explorer | None = None)

Bases: ItemTransform

A class used to assign pseudo-labels to items in a dataset based on their similarity to predefined labels.

This class leverages hashing techniques to compute the similarity between dataset items and a set of predefined labels. It assigns the most similar label as a pseudo-label to each item. This is particularly useful in semi-supervised learning scenarios where some labels are missing or uncertain.

Attributes:

• extractor : IDataset

The dataset extractor that provides access to dataset items and their annotations. - labels : Optional[List[str]] A list of label names to be used for pseudo-labeling. If not provided, all available labels in the dataset will be used. - explorer : Optional[Explorer] An optional Explorer object used to compute hash keys for items and labels. If not provided, a new Explorer will be created.

categories()

Returns metainfo about dataset labels.

transform_item(item: DatasetItem)

Returns a modified copy of the input item.

Avoid changing and returning the input item, because it can lead to unexpected problems. Use wrap_item() or item.wrap() to simplify copying.