.core

Contains the core functionality of the lightly Python package.

lightly.core.embed_images(checkpoint: str, config_path: Optional[str] = None, **kwargs)

Embed images with a self-supervised model.

Calls the same function as lightly-embed. All arguments passed to lightly-embed can also be passed to this function (see below for an example).

Parameters

• checkpoint – Path to the checkpoint file for the embedding model.

• config_path – Path to config.yaml. If None, the default configs will be used.

• **kwargs – Overwrite default configs py passing keyword arguments.

Returns

Embeddings, labels, and filenames of the images.

Examples

>>> import lightly
>>> my_checkpoint_path = 'path/to/checkpoint.ckpt'
>>>
>>> # embed images with default configs
>>> embeddings, _, _ = lightly.embed_images(
>>>     my_checkpoint_path, input_dir='path/to/data')
>>>
>>> # embed images with separate config file
>>> my_config_path = 'my/config/file.yaml'
>>> embeddings, _, _ = lightly.embed_images(
>>>     my_checkpoint_path, input_dir='path/to/data', config_path=my_config_path)
>>>
>>> # embed images with default settings and overwrites: at inference,
>>> # we can use larger input_sizes because it requires less memory.
>>> my_collate = {input_size: 256}
>>> embeddings, _, _ = lightly.embed_images(
>>>     my_checkpoint_path, input_dir='path/to/data', collate=my_collate)
>>> # the command above is equivalent to:
>>> # lightly-embed input_dir='path/to/data' collate.input_size=256

lightly.core.train_embedding_model(config_path: Optional[str] = None, **kwargs)

Train a self-supervised model.

Calls the same function as lightly-train. All arguments passed to lightly-train can also be passed to this function (see below for an example).

Parameters

• config_path – Path to config.yaml. If None, the default configs will be used.

• **kwargs – Overwrite default configs py passing keyword arguments.

Returns

Path to checkpoint of the trained embedding model.

Examples

>>> import lightly
>>>
>>> # train a model with default configs
>>> checkpoint_path = lightly.train_embedding_model(
>>>     input_dir='path/to/data')
>>>
>>> # train a model with separate config file
>>> my_config_path = 'my/config/file.yaml'
>>> checkpoint_path = lightly.train_embedding_model(
>>>     input_dir='path/to/data', config_path=my_config_path)
>>>
>>> # train a model with default settings and overwrites: large batch
>>> # sizes are benefitial for self-supervised training and more
>>> # workers speed up the dataloading process.
>>> my_loader = {
>>>     batch_size: 100,
>>>     num_workers: 8,
>>> }
>>> checkpoint_path = lightly.train_embedding_model(
>>>     input_dir='path/to/data', loader=my_loader)
>>> # the command above is equivalent to:
>>> # lightly-train input_dir='path/to/data' loader.batch_size=100 loader.num_workers=8

lightly.core.train_model_and_embed_images(config_path: Optional[str] = None, **kwargs) → Tuple[ndarray, List[int], List[str]]

Train a self-supervised model and use it to embed images.

First trains a modle using the _train_cli(), then embeds with the _embed_cli(). All arguments passed to the CLI functions can also be passed to this function (see below for an example).

Parameters

• config_path – Path to config.yaml. If None, the default configs will be used.

• **kwargs – Overwrite default configs py passing keyword arguments.

Returns

Embeddings, labels, and filenames of the images. Embeddings are of shape (n_samples, embedding_size) len(labels) = len(filenames) = n_samples

Examples

>>> import lightly
>>>
>>> # train a model and embed images with default configs
>>> embeddings, _, _ = lightly.train_model_and_embed_images(
>>>     input_dir='path/to/data')
>>>
>>> # train a model and embed images with separate config file
>>> my_config_path = 'my/config/file.yaml'
>>> embeddings, _, _ = lightly.train_model_and_embed_images(
>>>     input_dir='path/to/data', config_path=my_config_path)
>>>
>>> # train a model and embed images with default settings + overwrites
>>> my_trainer = {max_epochs: 10}
>>> embeddings, _, _ = lightly.train_model_and_embed_images(
>>>     input_dir='path/to/data', trainer=my_trainer)