First commit

Author: philippmwirth

CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# How to contribute to lightly?
+
+Everyone is welcome to contribute, and we value everybody's contribution. Code is thus not the only way to help the community. Answering questions, helping others, reaching out and improving the documentations are immensely valuable to the community.
+
+It also helps us if you spread the word: reference the library from blog posts on the awesome projects it made possible, shout out on Twitter every time it has helped you, or simply star the repo to say "thank you".
+
+## You can contribute in so many ways!
+
+There are 4 ways you can contribute to lightly:
+* Fixing outstanding issues with the existing code;
+* Implementing new models;
+* Contributing to the examples or to the documentation;
+* Submitting issues related to bugs or desired new features.
+
+*All are equally valuable to the community.*
+
+## Submitting a new issue or feature request
+
+Do your best to follow these guidelines when submitting an issue or a feature
+request. It will make it easier for us to come back to you quickly and with good
+feedback.
+
+### Did you find a bug?
+
+First, **please make sure the bug was not already reported** (use the search bar on Github under Issues).
+
+* Include your **OS type and version**, the versions of **Python**, **PyTorch**, and **PyTorch Lightning**.
+* A code snippet that allows us to reproduce the bug in less than 30s.
+* Provide the *full* traceback if an exception is raised.
+
+### Do you want to implement a new self-supervised model?
+
+Awesome! Please provide the following information:
+
+* Short description of the model and link to the paper;
+* Link to the implementation if it's open source;
+
+If you are willing to contribute the model yourself, let us know so we can best
+guide you.
+
+### Do you want a new feature (that is not a model)?
+
+A world-class feature request addresses the following points:
+
+1. Motivation first:
+  * Is it related to a problem/frustration with the library? If so, please explain
+    why. Providing a code snippet that demonstrates the problem is best.
+  * Is it related to something you would need for a project? We'd love to hear
+    about it!
+  * Is it something you worked on and think could benefit the community?
+    Awesome! Tell us what problem it solved for you.
+2. Provide a **code snippet** that demonstrates its future use;
+3. Attach any additional information (drawings, screenshots, etc.) you think may help.
+
+
+## Pull Requests
+
+Before writing code, we strongly advise you to search through the exising PRs or
+issues to make sure that nobody is already working on the same thing. If you are
+unsure, it is always a good idea to open an issue to get some feedback.
+
+Follow these steps to start contributing:
+
+1. Fork the [repository](https://github.com/lightly-ai/lightly/) by
+   clicking on the 'Fork' button on the repository's page. This creates a copy of the code
+   under your GitHub user account.
+
+2. Clone your fork to your local disk, and add the base repository as a remote:
+
+   ```bash
+   $ git clone [email protected]:lightly-ai/lightly.git
+   $ cd lightly
+   $ git remote add upstream https://github.com/lightly-ai/lightly.git
+   ```
+
+3. Create a new branch to hold your development changes:
+
+   ```bash
+   $ git checkout -b a_descriptive_name_for_my_changes
+   ```
+
+   **do not** work on the `master` branch.
+
+4. Set up a development environment by running the following command in a virtual environment:
+
+   ```bash
+   $ pip install -e ".[dev]"
+   ```
+
+5. Develop the features on your branch.
+
+   As you work on the features, you should make sure that the test suite
+   passes:
+
+   ```bash
+   $ make test
+   ```
+
+   If you're modifying documents under `docs/source`, make sure to validate that
+   they can still be built. This check also runs in CI. 
+
+   ```bash
+   $ cd docs
+   $ make html
+   ```
+   Once you're happy with your changes, add changed files using `git add` and
+   make a commit with `git commit` to record your changes locally:
+
+   ```bash
+   $ git add modified_file.py
+   $ git commit
+   ```
+
+   Please write [good commit messages](https://chris.beams.io/posts/git-commit/).
+
+   It is a good idea to sync your copy of the code with the original
+   repository regularly. This way you can quickly account for changes:
+
+   ```bash
+   $ git fetch upstream
+   $ git rebase upstream/master
+   ```
+
+   Push the changes to your account using:
+
+   ```bash
+   $ git push -u origin a_descriptive_name_for_my_changes
+   ```
+
+6. Once you are satisfied, go to the webpage of your fork on GitHub.
+   Click on 'Pull request' to send your changes to the project maintainers for review.
+
+7. It's ok if maintainers ask you for changes. It happens to core contributors
+   too! So everyone can see the changes in the Pull request, work in your local
+   branch and push the changes to your fork. They will automatically appear in
+   the pull request.
+
+### Style guide
+
+`lightly` follows the [Google styleguide](https://google.github.io/styleguide/pyguide.html) and the [PyTorch styleguide](https://github.com/IgorSusmelj/pytorch-styleguide) by Igor Susmelj.
+Check our [documentation writing guide](https://github.com/lightly-ai/lightly/docs/README.md) for more information.
+
+#### This guide was inspired by Transformers [transformers guide to contributing](https://github.com/huggingface/transformers/blob/master/CONTRIBUTING.md) which was influenced by Scikit-learn [scikit-learn guide to contributing](https://github.com/scikit-learn/scikit-learn/blob/master/CONTRIBUTING.md).

DOCS.md

@@ -0,0 +1,31 @@
+# Lightly
+
+Lightly is a PIP package for self-supervised active learning.
+
+> We, at [Lightly](https://www.lightly.ai), are passionate engineers who want to make deep learning more efficient. We want to help popularize the use of self-supervised methods to understand and filter raw image data. Our solution can be applied before any data annotation step and the learned representations can be used to analyze and visualize datasets as well as for selecting a core set of samples.
+
+> Coming soon: Our active-learning library is powered by state-of-the-art algorithms to help you with interactive learning loops.
+
+If you are curious to learn more about our work - check out [Lightly](https://www.lightly.ai)!
+
+## Installation
+
+```
+pip install lightly
+```
+
+## Dependencies
+- hydra-core >= 1.0.0
+- numpy >= 1.18.1
+- pytorch_lightning
+- requests >= 2.23.0
+- torchvision
+- tqdm
+
+
+## Links
+- [Homepage](https://www.lightly.ai)
+- [Web-App](https://app.lightly.ai)
+- [Documentation](https://www.notion.so/whattolabel/WhatToLabel-Documentation-28e645f5564a453e807d0a384a4e6ea7)
+- [Github](https://github.com/lightly-ai/lightly)
+- [Discord](https://discord.gg/xvNJW94)

LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,4 @@
+# include config files for command-line interface
+recursive-include lightly/cli *.yaml
+# exclude tests
+recursive-exclude tests *

Makefile

@@ -0,0 +1,70 @@
+# Copyright (c) 2020. Lightly AG and its affiliates.
+# All Rights Reserved
+
+.PHONY: clean clean-build clean-pyc clean-out docs help
+.DEFAULT_GOAL := help
+
+# TODO
+help:
+
+## make clean
+clean: clean-tox clean-build clean-pyc clean-out
+
+## remove build artifacts
+clean-build:
+	rm -fr build/
+	rm -fr dist/
+	rm -fr .eggs/
+	find . -name '*.egg-info' -exec rm -fr {} +
+	find . -name '*.egg' -exec rm -f {} +
+
+## remove python file artifacts
+clean-pyc:
+	find . -name '__pycache__' -exec rm -fr {} +
+
+## remove hydra outputs
+clean-out:
+	rm -fr outputs/
+	rm -fr lightning_logs/
+	rm -fr lightly_epoch_*.ckpt
+
+## remove tox cache
+clean-tox:
+	rm -fr .tox
+
+# check style with flake8
+lint: lint-lightly lint-tests
+
+## check lightly style with flake8
+lint-lightly:
+	flake8 lightly
+
+## check tests style with flake8
+lint-tests:
+	flake8 tests
+
+## run tests
+test:
+	pytest tests -n 20
+
+## build source and wheel package
+dist: clean 
+	python setup.py sdist bdist_wheel
+	ls -l dist
+
+## install the package to active site
+install: clean 
+	pip install .
+
+# uninstall package from active site
+uninstall: clean
+	pip uninstall lightly
+
+## run tests in tox envs
+tox: uninstall
+	tox
+
+## helper for renaming
+find: 
+	@read -p "Enter Term: " term; \
+	grep -rnw ./ -e "$$term"

PRECOMMITHOOKS.md

@@ -0,0 +1,52 @@
+# Pre-Commit Hooks
+We use pre-commit hooks to identify simple issues before submission to code review. In particular, our hooks currently check for:
+* Private keys in the commit
+* Large files in the commit (>500kB)
+* Units which don't pass their unit tests (on push only)
+
+## Install Pre-Commit
+
+`pre-commit` comes as a pip package and is specified in `requirements/dev.txt`.
+
+To install it either run:
+```
+$ pip install .[dev]
+```
+Or, to install it separately:
+```
+$ pip install pre-commit
+```
+
+Test your installation:
+```
+$ pre-commit --version
+```
+If the installation failed, try
+```
+$ curl https://pre-commit.com/install-local.py | python -
+```
+or see the [documentation of pre-commit](https://pre-commit.com/) for more information.
+
+## Install Pre-Commit Hooks
+To install the pre-commit hooks specified in `.pre-commit-hooks.yaml`, simply run
+```
+$ pre-commit install
+```
+Install the pre-push hooks like this
+```
+$ pre-commit install --hook-type pre-push
+```
+
+You can verify that the hooks were installed correctly with
+```
+$ pre-commit run --all-files
+```
+The output should look like this:
+```
+$ pre-commit run --all-files
+Detect Private Key................................Passed
+Check for added large files.......................Passed 
+```
+
+## Usage
+With the new setup, checks for private keys and large files are made before every commit and all tests must pass for a push.

README.md

@@ -0,0 +1,60 @@
+
+![Lightly Logo](docs/logos/lightly_logo_crop.png)
+
+Lightly is a computer vision framework for self-supervised learning.
+
+> We, at [Lightly](https://www.lightly.ai), are passionate engineers who want to make deep learning more efficient. We want to help popularize the use of self-supervised methods to understand and filter raw image data. Our solution can be applied before any data annotation step and the learned representations can be used to analyze and visualize datasets as well as for selecting a core set of samples.
+
+- [Homepage](https://www.lightly.ai)
+- [Web-App](https://app.lightly.ai)
+- [Documentation](https://www.notion.so/whattolabel/WhatToLabel-Documentation-28e645f5564a453e807d0a384a4e6ea7)
+- [Github](https://github.com/lightly-ai/lightly)
+- [Discord](https://discord.gg/xvNJW94)
+
+## Terminology
+- **Dataset:** A collection of raw images.
+- **Embedding:** Representation of an image in a vector space.
+- **Embedding Model:** Function (typically a convolutional neural network) to create embeddings from images.
+- **Self-supervised Learning:** A form of unsupervised learning where the data provides the supervision.
+
+## Quick Start
+
+Lightly requires Python 3.5+. We recommend installing Lightly in a Linux or OSX environment.
+
+### Installation
+You can install Lightly and its dependencies from PyPI with:
+```
+pip install lightly
+```
+
+We strongly recommend that you install Lightly in a dedicated virtualenv, to avoid conflicting with your system packages.
+
+### Next Steps
+Head to the [documentation](https://www.notion.so/whattolabel/WhatToLabel-Documentation-28e645f5564a453e807d0a384a4e6ea7) and see the things you can achieve with Lightly!
+
+
+## Further Reading
+
+**Self-supervised Learning:**
+- [A Simple Framework for Contrastive Learning of Visual Representations (2020)](https://arxiv.org/abs/2002.05709)
+- [Momentum Contrast for Unsupervised Visual Representation Learning (2020)](https://arxiv.org/abs/1911.05722)
+- [Unsupervised Learning of Visual Features by Contrasting Cluster Assignments (2020)](https://arxiv.org/abs/2006.09882)
+- [What Should Not Be Contrastive in Contrastive Learning (2020)](https://arxiv.org/abs/2008.05659)
+
+## FAQ
+
+- Why should I care about self-supervised learning? Aren't pre-trained models from ImageNet much better for transfer learning?
+  - Self-supervised learning has become increasingly popular among scientists over the last year because the learned representations perform extraordinarily well on downstream tasks. This means that they capture the important information in an image better than other types of pre-trained models. By training a self-supervised model on *your* dataset, you can make sure that the representations have all the necessary information about your images.
+
+- How can I contribute?
+  - Create an issue if you encounter bugs or have ideas for features we should implement. You can also add your own code by forking this repository and creating a PR. More details about how to contribute with code is in our contribution guide.
+
+- Is this framework for free?
+  - Yes, this framework completely free to use and we provide the code. We believe that
+  we need to make training deep learning models more data efficient to achieve widespread adoption. One step to achieve this goal is by leveraging self-supervised learning. The company behind lightly commited to keep this framework open-source.
+
+- If this framework is free, how is the company behind lightly making money?
+  - Training self-supervised models is only part of the solution. The company behind lightly focuses on processing and analyzing embeddings created by self-supervised models. 
+  By building, what we call a self-supervised active learning loop we help companies understand and work with their data more efficiently. This framework acts as an interface
+  for our platform to easily upload and download datasets, embeddings and models. Whereas 
+  the platform will cost for additional features this frameworks will always remain free of charge (even for commercial use).