🚀 Getting Started#
⚙️ Installation#
pip install landmarker
Overview#
Landmarker provides a simple API for training and evaluating landmark detection models. The API is designed to be easy to use and to be flexible such that it can be used intertwined with other libraries or custom code. Landmarker can also act as utility library for certain components of landmark detection algorithms. For example, it provides a set of loss functions and heatmap decoding operations that can be used in combination with other PyTorch-based libraries.
In the following sections, we provide a brief overview of the library and the API. For more specific details, we refer to the API reference.
📦 Modules#
Data Loading, Preprocessing, and Augmentation#
The landmarker.data module contains classes for loading and preprocessing
data. All classes inherit from the
Dataset
class such that they
can be used with PyTorch’s
DataLoader
class. There
are three types of datasets:
LandmarkDataset
: A dataset of images and corresponding landmarks (landmark coordinates). Is constructed from images and landmarks pairs.HeatmapDataset
: A dataset of images and corresponding heatmaps representing the associated landmark. Is constructed from images and landmarks pairs.MaskDataset
: A dataset of images and corresponding masks (i.e., binary segmentation masks indiciating the location of the landmarks). Can be constructed from specified image and landmarks pairs, or from images and masks pairs, because often that is how the data is distributed.
Both the HeatmapDataset
and MaskDataset
inherit from the LandmarkDataset
class, and thus also
contain information about the landmarks. The MaskDataset
can be constructed from specified image
and landmarks pairs, or from images and masks pairs, because often that is how the data is
distributed. The HeatmapDataset
can be constructed from images and landmarks pairs.
For all three types of datasets images can be provided as a list of paths to stored images, or as a a numpy arary, torch tensor, list of numpy arrays or list of torch tensors. Landmarks can be as numpy arrays or torch tensors. The landmarks are assumed to be in the range of the dimensions of the image. For example, if the image is 256x256, the values of the landmarks are assumed to be in the range [0, 256]. These landmarks can be provided in three different shapes:
(N, D) where N is the number of samples and D is the number of dimensions
(N, C, D) where C is the number of landmark classes
(N, C, I, D) where I is the number of instances per landmark class, if less than I instances are provided, the remaining instances are filled with NaNs.
Preprocessing#
If the images are provided as a list of paths, the images loaded from these paths and their values
are normalized to the range [0, 1]. If the images are provided as numpy arrays or torch tensors,
they are assumed to be normalized to the range [0, 1]. When a dim argument is provided, the images
and landmarks are rescaled to the specified dimensions. The original dimensions and original
landmarksare stored in the original_dims
and original_landmarks
attributes of the dataset. By
default the rescalling is done such that the aspect ratio is preserved, i.e., padding is added to
the image such that the aspect ratio is preserved. If resize_pad
is set to False
, the image is
rescaled without preserving the aspect ratio.
Augmentation#
All datasets can be augmented using the transforms
argument. Currently the transforms needs to
follow the monai, and more specifically they need
to be in a compose function.
Datasets#
Comming soon…
Heatmap Generation and Decoding#
Comming soon…
Loss Functions#
Comming soon…
Model Architectures#
Comming soon…
Training and Evaluation#
Comming soon…
Utilities#
Comming soon…