lightly-train 0.3.0__tar.gz → 0.3.2__tar.gz

lightly_train-0.3.2/.github/workflows/README.md

@@ -0,0 +1,68 @@
+# Workflows for GitHub Actions
+
+## Caching With UV
+
+Our actions have a special setup because we use self-hosted runners which are persistent
+across jobs. This requires some attention on how caching and environments are set up.
+
+References:
+
+- https://docs.astral.sh/uv/concepts/cache/#caching
+- https://docs.astral.sh/uv/configuration/environment/
+- https://github.com/astral-sh/setup-uv?tab=readme-ov-file#usage
+
+### Environment Variables
+
+- `VIRTUAL_ENV`
+  - This variable sets the path to the virtual environment. This is not a variable by uv
+    but is respected by it.
+  - We set this to `${{ github.workspace }}/.venv` which corresponds to the `.venv`
+    directory in the repository root.
+  - Virtual environments are not persistent across jobs as GitHub Actions creates a new
+    `${{ github.workspace }}` for every job.
+  - We still want to use a virtual environment and not install into the system Python
+    environment with `UV_SYSTEM_PYTHON=1` because the system Python environment is
+    persistent across jobs due to the self-hosted runner setup.
+  - Uv automatically uses `VIRTUAL_ENV` for its commands (you don't have to call
+    `source .venv/bin/activate` before). But not all other tools respect it.
+    For example, pytest still requires the environment to be activated. We activate the
+    environment by adding it to the `GITHUB_PATH` variable instead of calling
+    `source .venv/bin/activate`. This is required because GitHub Actions requires that
+    `source .venv/bin/activate` is called in every step as environment variables are not
+    persisted across steps. By adding the environment to `GITHUB_PATH`, we can skip the
+    activation in every step.
+- `UV_CACHE_DIR`
+  - This variable determines where uv creates its cache.
+  - It is set by the `cache-local-path` setting in the `astral-sh/setup-uv` action.
+  - Must be set to a directory that is persistent across jobs. We set it to
+    `/tmp/setup-uv-cache` which means that the cache is persistent as long as the
+    self-hosted runner is not restarted (`/tmp` is not a mounted volume).
+  - We don't have to worry about the cache too much. Uv handles it automatically.
+    It is also save regarding multi-threading, different uv/python versions, and minimal
+    dependencies etc.
+    See: https://docs.astral.sh/uv/concepts/cache/#cache-safety
+  - The variable is automatically used by uv. We don't have to specify it in commands.
+
+### Environment Information
+
+- The environment is in `${{ github.workspace }}/.venv` which corresponds to the `.venv`
+  directory in the repository root (same as for local development). The environment is
+  not persistent across jobs.
+- The cache is in `/tmp/setup-uv-cache` which is persistent across jobs. Restart the
+  runner to clear the cache.
+- Python is installed to `/gh-actions/_work/_tool/Python/3` which is persistent across
+  jobs.
+
+### astral-sh/setup-uv Action Information
+
+- `cache-local-path` sets the cache directory (`UV_CACHE_DIR`). See `UV_CACHE_DIR` above
+  for more information.
+- `prune-cache: false` disables cache pruning. Cache pruning is efficient for GitHub
+  hosted action runners but not for self-hosted runners.
+  See: https://github.com/astral-sh/setup-uv?tab=readme-ov-file#disable-cache-pruning
+- `enable_cache: true` is NOT set in the action settings. This is because we use a
+  local cache. `enable_cache` only makes sense in combination with GitHub Actions
+  Cache (`actions/cache`) and would upload the cache to GitHub.
+- `cache-dependency-glob` is NOT set in the action settings. My understanding
+  (Guarin, 10/24) is that this is also only used in combination with GitHub Actions
+  Cache (`actions/cache`) and would determine when the cache is invalidated.

lightly_train-0.3.2/.github/workflows/release_documentation.yml

@@ -0,0 +1,80 @@
+name: Release Documentation
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release-documentation:
+    name: Build and release documentation
+    runs-on: cpu
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Checkout latest release tag
+      id: checkout_latest_release_tag
+      run: |
+        LATEST_TAG=$(git describe --tags `git rev-list --tags --max-count=1`)
+        git checkout $LATEST_TAG
+        echo "tag_name=$LATEST_TAG" >> $GITHUB_OUTPUT;
+    - name: Assert version in code matches latest release tag
+      id: assert_version
+      run: |
+        LATEST_TAG=${{steps.checkout_latest_release_tag.outputs.tag_name}}
+        VERSION_FROM_INIT=$(grep -oP '(?<=__version__ = ")[^"]*' src/lightly_train/__init__.py)
+        VERSION_FROM_INIT="v$VERSION_FROM_INIT"
+        if [ "$VERSION_FROM_INIT" != "$LATEST_TAG" ]; then
+        echo "Version mismatch: Tag is $LATEST_TAG, but __version__ in __init__.py is $VERSION_FROM_INIT"
+        exit 1
+        fi
+        echo "__version__ from __init__.py $VERSION_FROM_INIT matches latest tag $LATEST_TAG"
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+    - name: Set Up Environment
+      run: |
+        make install-uv reset-venv
+        source .venv/bin/activate
+        make install-dev
+    - name: Authenticate with GCP
+      id: auth-gcp
+      uses: 'google-github-actions/auth@v2'
+      with:
+        project_id: ${{ secrets.GCP_PROJECT_ID }}
+        credentials_json: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}
+    - name: Build
+      run: |
+        source .venv/bin/activate
+        cd docs && make docs docs-stable
+    - name: Release
+      id: build_and_release
+      run: |
+        gsutil -m rsync -r ./docs/build gs://docs-pip/lightly-train/build
+        gcloud compute scp \
+          --zone ${{ secrets.DOCS_INSTANCE_ZONE }} \
+          --recurse ./docs/build/* ${{ secrets.DOCS_INSTANCE_ID }}:${{ secrets.DOCS_INSTANCE_DIR }}/lightly-train/docs/build
+    - name: Convert success/failure strings to emojis
+      if: always()
+      id: emoji_status
+      run: |
+        function set-emoji-output {
+          if [ "$2" == "success" ];
+          then echo "$1=:github-check-mark:" >> $GITHUB_OUTPUT;
+          else echo "$1=:github-changes-requested:" >> $GITHUB_OUTPUT;
+          fi
+        }
+        set-emoji-output status ${{ steps.build_and_release.outcome }}
+    - name: Slack notification
+      if: always()
+      uses: rtCamp/action-slack-notify@v2
+      env:
+        SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_RELEASES }}
+        SLACK_ICON_EMOJI: ":books:"
+        SLACK_USERNAME: Release of LightlyTrain Docs ${{steps.checkout_latest_release_tag.outputs.tag_name}}
+        SLACK_COLOR: ${{ steps.build_and_release.outcome }}
+        SLACK_FOOTER: ""
+        SLACK_MESSAGE: |
+          Build status: ${{steps.emoji_status.outputs.status}}
+          https://docs.lightly.ai/train/stable/

lightly_train-0.3.2/.github/workflows/test_unit.yml

@@ -0,0 +1,76 @@
+name: Test Unit
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+env:
+  # Virtual environment path used by uv and other tools.
+  # We create a new environment for each job to avoid conflicts.
+  # For more information, see: https://github.com/lightly-ai/lightly-train/.github/workflows/README.md
+  VIRTUAL_ENV: ${{ github.workspace }}/.venv
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  detect-code-changes:
+    name: Detect Code Changes
+    runs-on: docker-cpu
+    outputs:
+      run-tests: ${{ steps.filter.outputs.run-tests }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          list-files: shell
+          filters: |
+            run-tests:
+              - '!docs/**'
+              - '!docker/**'
+              - '!.github/**'
+              - '.github/workflows/test_unit.yml'
+  test-unit:
+    name: Test Unit
+    needs: detect-code-changes
+    if: needs.detect-code-changes.outputs.run-tests == 'true'
+    runs-on: docker-gpu
+    strategy:
+      matrix:
+        python: ["3.8", "3.11"]
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+      - name: Set Up uv
+        uses: astral-sh/setup-uv@v3
+        id: setup-uv
+        with:
+          # For more information about the settings, see: 
+          # https://github.com/lightly-ai/lightly-train/.github/workflows/README.md
+          version: 0.2.25
+          cache-local-path: /tmp/setup-uv-cache
+          prune-cache: false
+      - name: Set Up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Set Up FFmpeg
+        uses: FedericoCarboni/setup-ffmpeg@v3
+        with:
+          ffmpeg-version: 4.3.1
+      - name: Set Up Environment
+        # For more information about the environment setup, see:
+        # https://github.com/lightly-ai/lightly-train/.github/workflows/README.md
+        run: |
+          rm -rf ${VIRTUAL_ENV}                                 # Make sure the venv is clean
+          uv venv ${VIRTUAL_ENV} --python ${{ matrix.python }}  # Create the venv
+          echo "${VIRTUAL_ENV}/bin" >> $GITHUB_PATH             # Add the venv to the PATH
+          make install-pinned-${{ matrix.python }}              # Install the dependencies
+      - name: Run Pytest
+        run: |
+          make test-ci

{lightly_train-0.3.0 → lightly_train-0.3.2}/MAINTAINING.md

@@ -1,11 +1,11 @@
 # Maintaining LightlyTrain
 
-This document is intended for maintainers of LightlyTrain. If you would like to
+This document is intended for maintainers of Lightly**Train**. If you would like to
 contribute, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) document.
 
 ## Release
 
-Follow these steps to release a new version of LightlyTrain:
+Follow these steps to release a new version of Lightly**Train**:
 
 1. Bump the version in `lightly_train/__init__.py`. We use [Semantic Versioning](https://semver.org/). Note that we are still on major version 0 and therefore minor version
    bumps are considered breaking changes.
@@ -15,5 +15,5 @@ Follow these steps to release a new version of LightlyTrain:
 1. To release on DockerHub, run the [DockerHub Release action](https://github.com/lightly-ai/lightly-train/actions/workflows/release_dockerhub.yml) from the branch with the new
    version tag.
 1. If the README was updated, make sure to copy the information to the DockerHub
-   description for LightlyTrain: https://hub.docker.com/r/lightly/ (you might have to ask
+   description for Lightly**Train**: https://hub.docker.com/r/lightly/ (you might have to ask
    someone who is a member of the Lightly DockerHub organization to do this for you).

{lightly_train-0.3.0 → lightly_train-0.3.2}/Makefile

@@ -39,11 +39,11 @@ static-checks: format-check type-check
 # Files to format with mdformat.
 # This is needed to avoid formatting files in .venv. The mdformat command has an
 # --exclude option but only on Python 3.13+.
-MDFORMAT_FILES=.github docker docs src tests *.md
+MDFORMAT_FILES := .github docker docs src tests *.md
 
 # run formatter
 .PHONY: format
-format:
+format: add-header
 	# Format code
 	ruff format .
 	# Fix linting issues and sort imports
@@ -107,26 +107,26 @@ reset-venv:
 # Set EDITABLE to -e to install the package in editable mode outside of CI. This is
 # useful for local development.
 ifdef CI
-EDITABLE=
+EDITABLE :=
 else
-EDITABLE=-e
+EDITABLE := -e
 endif
 
 # SuperGradients is not compatible with Python>=3.10. It is also not easy to install
 # on MacOS. Therefore we exclude it from the default extras.
-EXTRAS = [dev,tensorboard,timm,ultralytics,wandb]
+EXTRAS := [dev,tensorboard,timm,ultralytics,wandb]
 # Exclude ultralytics from docker extras as it has an AGPL license and we should not
 # distribute it with the docker image.
-DOCKER_EXTRAS = --extra tensorboard --extra timm --extra wandb
+DOCKER_EXTRAS := --extra tensorboard --extra timm --extra wandb
 
 # Date until which dependencies installed with --exclude-newer must have been released.
 # Dependencies released after this date are ignored.
-EXCLUDE_NEWER_DATE="2024-08-28"
+EXCLUDE_NEWER_DATE := "2024-08-28"
 # Pinned versions for Torch and TorchVision to avoid issues with the CUDA version on the CI machine.
 # These versions are compatible with CUDA 11.4 and Python 3.8. They are the latest versions
 # available before 2024-08-28.
-PINNED_TORCH_VERSION="2.4.0+cu118"
-PINNED_TORCHVISION_VERSION="0.19.0+cu118"
+PINNED_TORCH_VERSION := "2.4.0+cu118"
+PINNED_TORCHVISION_VERSION := "0.19.0+cu118"
 
 # Install ffmpeg on Ubuntu.
 . PHONY: install-ffmpeg-ubuntu

{lightly_train-0.3.0/src/lightly_train.egg-info → lightly_train-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lightly_train
-Version: 0.3.0
+Version: 0.3.2
 Summary: Train models with self-supervised learning in a single command
 Author: Lightly Team
 License: AGPL-3.0
@@ -49,17 +49,17 @@ Requires-Dist: wandb>=0.12.10; extra == "wandb"
 
 ## Why LightlyTrain
 
-LightlyTrain uses self-supervised learning (SSL) to train models on large datasets
+Lightly**Train** uses self-supervised learning (SSL) to train models on large datasets
 without the need for labels. It provides simple Python, Command Line, and Docker
 interfaces to train models with popular SSL methods such as SimCLR or DINO. The trained
 models are ideal starting points for fine-tuning on downstream tasks such as image
 classification, object detection, and segmentation or for generating image embeddings.
-Models trained with LightlyTrain result in improved performance, faster convergence, and
+Models trained with Lightly**Train** result in improved performance, faster convergence, and
 better generalization compared to models trained without SSL. Image embeddings created
-with LightlyTrain capture more relevant information than their supervised counterparts
+with Lightly**Train** capture more relevant information than their supervised counterparts
 and seamlessly extend to new classes due to the unsupervised nature of SSL.
 
-Lightly is the expert in SSL for computer vision and developed LightlyTrain to simplify
+Lightly is the expert in SSL for computer vision and developed Lightly**Train** to simplify
 model training for any task and dataset.
 
 ## Features
@@ -77,7 +77,7 @@ model training for any task and dataset.
 
 ## License
 
-LightlyTrain is available under an AGPL-3.0 and a commercial license. Please contact us
+Lightly**Train** is available under an AGPL-3.0 and a commercial license. Please contact us
 at info@lightly.ai for more information.
 
 ## Contact

{lightly_train-0.3.0 → lightly_train-0.3.2}/README.md

@@ -4,17 +4,17 @@
 
 ## Why LightlyTrain
 
-LightlyTrain uses self-supervised learning (SSL) to train models on large datasets
+Lightly**Train** uses self-supervised learning (SSL) to train models on large datasets
 without the need for labels. It provides simple Python, Command Line, and Docker
 interfaces to train models with popular SSL methods such as SimCLR or DINO. The trained
 models are ideal starting points for fine-tuning on downstream tasks such as image
 classification, object detection, and segmentation or for generating image embeddings.
-Models trained with LightlyTrain result in improved performance, faster convergence, and
+Models trained with Lightly**Train** result in improved performance, faster convergence, and
 better generalization compared to models trained without SSL. Image embeddings created
-with LightlyTrain capture more relevant information than their supervised counterparts
+with Lightly**Train** capture more relevant information than their supervised counterparts
 and seamlessly extend to new classes due to the unsupervised nature of SSL.
 
-Lightly is the expert in SSL for computer vision and developed LightlyTrain to simplify
+Lightly is the expert in SSL for computer vision and developed Lightly**Train** to simplify
 model training for any task and dataset.
 
 ## Features
@@ -32,7 +32,7 @@ model training for any task and dataset.
 
 ## License
 
-LightlyTrain is available under an AGPL-3.0 and a commercial license. Please contact us
+Lightly**Train** is available under an AGPL-3.0 and a commercial license. Please contact us
 at info@lightly.ai for more information.
 
 ## Contact

{lightly_train-0.3.0 → lightly_train-0.3.2}/docker/Makefile

@@ -1,11 +1,11 @@
 TAG ?= $(shell git rev-parse HEAD)
 IMAGE ?= train
-DOCKER_BUILDKIT=1
-CONTAINER_REGISTRY=eu.gcr.io/boris-250909
+DOCKER_BUILDKIT := 1
+CONTAINER_REGISTRY := eu.gcr.io/boris-250909
 
-VERSION = $(shell grep '__version__' ../src/lightly_train/__init__.py | sed -E 's/[^0-9.]//g')
-VERSION_X=$(shell echo $(VERSION) | cut -d. -f1)
-VERSION_XY=$(shell echo $(VERSION) | cut -d. -f1-2)
+VERSION := $(shell grep '__version__' ../src/lightly_train/__init__.py | sed -E 's/[^0-9.]//g')
+VERSION_X := $(shell echo $(VERSION) | cut -d. -f1)
+VERSION_XY := $(shell echo $(VERSION) | cut -d. -f1-2)
 
 # print all versions
 .PHONY: print-versions
@@ -52,8 +52,8 @@ main-deploy-amd64-cuda:
 		--output=$(OUTPUT) \
 		..
 
-
-DATE=$(shell date +'%Y-%m-%d-%H-%M-%S')
+# DATE variable must be assigned with `:=` to avoid re-evaluation.
+DATE := $(shell date +'%Y-%m-%d-%H-%M-%S')
 LIGHTLY_TRAIN_OUT ?= $(PWD)/../out/docker/$(DATE)
 LIGHTLY_TRAIN_DATA ?= $(PWD)/../lightly_train_docker_test_data
 

{lightly_train-0.3.0 → lightly_train-0.3.2}/docs/Makefile

@@ -1,27 +1,31 @@
 ### Documentation
 
 VERSION ?= $(shell grep '__version__' ../src/lightly_train/__init__.py | sed -E 's/[^0-9.]//g')
-BUILD_DIR = build
+BUILD_DIR := build
 # The build directory for the current version. We create a new directory for each
 # version to simplify hosting the documentation for multiple versions. This follows
 # the pattern used by PyTorch: https://pytorch.org/docs/versions.html
-BUILD_VERSION_DIR = ${BUILD_DIR}/${VERSION}
-BUILD_STABLE_DIR = ${BUILD_DIR}/stable
-SOURCE_DIR = source
+BUILD_VERSION_DIR := ${BUILD_DIR}/${VERSION}
+BUILD_STABLE_DIR := ${BUILD_DIR}/stable
+SOURCE_DIR := source
 
 
 # Build docs for the current version.
 .PHONY: docs
 docs:
+	@echo "📚 Building v${VERSION} documentation..."
 	sphinx-build --builder html ${SOURCE_DIR} ${BUILD_VERSION_DIR}
 	python build.py --build-dir ${BUILD_DIR}
+	@echo "✅ Documentation built successfully!"
 
 # Build docs for the stable version. Assumes that the current version is the stable
 # version.
 .PHONY: docs-stable
 docs-stable:
+	@echo "🗿 Building stable documentation..."
 	sphinx-build --builder html ${SOURCE_DIR} ${BUILD_STABLE_DIR}
 	python build.py --build-dir ${BUILD_DIR}
+	@echo "✅ Documentation built successfully!"
 
 # Serve the documentation on localhost.
 .PHONY: serve

{lightly_train-0.3.0 → lightly_train-0.3.2}/docs/source/_static/custom.css

@@ -3,9 +3,9 @@
     color: var(--color-brand-primary);
     font-size: 1rem;
     text-align: left;
-    margin: var(--sidebar-item-spacing-vertical) 0;
+    padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);
 }
 
 .sidebar-version:visited {
     color: var(--color-brand-primary);
-}
+}

{lightly_train-0.3.0 → lightly_train-0.3.2}/docs/source/_static/lightly_train.svg

@@ -1,4 +1,4 @@
-<svg width="189" height="48" viewBox="0 0 189 48" fill="none" xmlns="http://www.w3.org/2000/svg">
+<svg width="100%" height="auto" viewBox="0 0 189 48" fill="none" xmlns="http://www.w3.org/2000/svg">
 <path fill-rule="evenodd" clip-rule="evenodd" d="M0 5.64209H5.01493V42.157H41.6866V47.1719H0V5.64209Z" fill="#A72264"/>
 <path fill-rule="evenodd" clip-rule="evenodd" d="M10.9701 0H15.985V31.0299H30.7164V36.0448H10.9701V0Z" fill="#A72264"/>
 <path fill-rule="evenodd" clip-rule="evenodd" d="M42 36.0449H36.9851V10.3434H22.2537V5.3285H42V36.0449Z" fill="#A72264"/>

lightly_train-0.3.2/docs/source/_templates/sidebar/version.html

@@ -0,0 +1 @@
+<a class="sidebar-version" href="../versions.html">{{ version }} ▼</a>

lightly_train-0.3.2/docs/source/docker.md

@@ -0,0 +1,62 @@
+(docker)=
+
+# Docker
+
+Lightly**Train** is available as a Docker image on [Docker Hub](https://hub.docker.com/r/lightly/train)
+for containerized deployment.
+
+(docker-installation)=
+
+## Installation
+
+Install Docker with NVIDIA GPU support ([docs](https://docs.lightly.ai/docs/lightly-worker-installation-guide#install-docker-optionally-with-gpu-support)).
+Then, pull the latest version of the Lightly**Train** Docker image from Docker Hub:
+
+```bash
+docker pull lightly/train:latest
+```
+
+You can verify that the image is working correctly by running the following command:
+
+```bash
+docker run --rm --gpus=all lightly/train:latest lightly-train --help
+```
+
+This should print the Lightly**Train** help message.
+
+(docker-usage)=
+
+## Usage
+
+Start a Lightly**Train** Docker container in interactive mode:
+
+```bash
+docker run -it --rm --gpus=all --shm-size=4gb --user $(id -u):$(id -g) -v /my_output_dir:/out -v /my_data_dir:/data lightly/train:latest
+```
+
+Flags:
+
+- `-it`: Starts the container in interactive mode.
+- `--rm`: Removes the container after it has been stopped.
+- `--gpus=all`: Enables GPU support.
+- `--shm-size=4gb`: Sets the shared memory size to 4 GB. Increase this for large datasets.
+- `--user $(id -u):$(id -g)`: Run the container with the same user as the host. This
+  makes sure that all files created by the container (checkpoints, logs, etc.) have
+  the same permissions as the user running the container.
+- `-v /my_output_dir:/out`: Mounts the host directory `/my_output_dir` to the container
+  directory `/out`. All files created by the container (checkpoints, logs, etc.) will
+  be saved in this directory.
+- `-v /my_data_dir:/data`: Mounts the host directory `/my_data_dir` to the container
+  directory `/data`. This directory must contain your training data. See the
+  [Data](#train-data) docs for more information on how to structure your data.
+
+Once the container is running, you can run Lightly**Train** commands inside the container
+as if you had installed it locally. The only difference is that paths must be specified
+relative to the mounted directories `/out` and `/data`. For example, to train a model,
+run the following command inside the container:
+
+````{tab} Command Line
+```bash
+lightly-train train out="/out/my_experiment" data="/data" model="torchvision/resnet50" method="dino"
+```
+````

lightly_train-0.3.2/docs/source/embed.md

@@ -0,0 +1,100 @@
+(embed)=
+
+# Embed
+
+The `embed` command is used to embed images with a [training checkpoint](#train-output).
+An example command looks like this:
+
+````{tab} Python
+```python
+import lightly_train
+
+lightly_train.train(
+    out="out/my_experiment",
+    data="my_data_dir",
+    model="torchvision/resnet50",
+    method="dino",
+)
+
+lightly_train.embed(
+    out="my_embeddings.pth",                            
+    data="my_data_dir",                                 
+    checkpoint="out/my_experiment/checkpoints/last.ckpt",
+    format="torch",
+)
+````
+
+````{tab} Command Line
+```bash
+lightly-train train out="out/my_experiment" data="my_data_dir" model="torchvision/resnet50" method="dino"
+lightly-train embed out=my_embeddings.pth data=my_data_dir checkpoint=out/my_experiment/checkpoints/last.ckpt format=torch
+````
+
+The above code example trains a model and uses the last training checkpoint to generate
+image embeddings from the images in `"my_data_dir"`.
+
+```{tip}
+See {meth}`lightly_train.embed` for a complete list of arguments.
+```
+
+## Out
+
+The `out` argument specifies the output file where the embeddings and corresponding
+image filenames are saved. Image filenames are always relative to the `data` directory.
+See [format](#embedding-format) for details on how the embeddings are saved.
+
+The embedding dimension is determined by the model used for training. If the `embed_dim`
+argument was set during training, the embeddings will have this dimension, otherwise
+the default embedding dimension of the model is used.
+
+## Data
+
+The `data` argument specifies the directory with images to embed. The same image formats
+as in the [training command](#train-data) are supported.
+
+## Checkpoint
+
+The `checkpoint` argument specifies the Lightly**Train** checkpoint to use for embedding.
+This is the checkpoint saved to `out/my_experiment/checkpoints/last.ckpt` after
+training.
+
+(embedding-format)=
+
+## Format
+
+The `format` argument specifies the format in which the embeddings are saved. The
+following formats are supported:
+
+- `csv`: Embeddings are saved as a CSV file with one row per image. The first column
+  contains the filename and the remaining columns contain the embedding values.
+  An example CSV file looks like this:
+  ```text
+    filename,embedding_0,embedding_1,embedding_2
+    image1.jpg,0.1,0.2,0.3
+    image2.jpg,0.4,0.5,0.6
+  ```
+- `lightly_csv`: Embeddings are saved as a CSV file with one row per image. The CSV file
+  is compatible with the [Lightly Worker](https://docs.lightly.ai/docs/custom-embeddings).
+  The labels column is always set to 0. An example CSV file looks like this:
+  ```text
+    filenames,embedding_0,embedding_1,embedding_2,labels
+    image1.jpg,0.1,0.2,0.3,0
+    image2.jpg,0.4,0.5,0.6,0
+  ```
+- `torch`: The embeddings are saved as dictionary in a torch file with the following
+  structure:
+  ```python
+  {
+      "embeddings": torch.Tensor,    # Embeddings with shape (N, D) where N is the number
+                                     # of images and D is the embedding dimension.
+      "filenames": list[str],        # List of N filenames corresponding to the embeddings.
+  }
+  ```
+  The embeddings can be loaded with:
+  ```python
+    import torch
+
+    embeddings = torch.load("my_embeddings.pth", weights_only=True)
+    embeddings["embeddings"]    # Embeddings
+    embeddings["filenames"]     # Image filenames
+  ```