+
Encord Active
+
+
+
+[][join-slack] [][twitter-url]
+[![PRs-Welcome][contribute-image]][contribute-url]
+
+## Documentation
+
+Please refer to our [documentation][encord-active-docs].
+
+## Installation
+
+The simplest way to install the CLI is using `pip` in a suitable virtual environment:
+
+```shell
+pip install encord-active
+```
+
+We recommend using a virtual environment, such as `venv`:
+
+```shell
+$ python3.9 -m venv ea-venv
+$ source ea-venv/bin/activate
+$ pip install encord-active
+```
+
+> `encord-active` requires [python3.9](https://www.python.org/downloads/release/python-3915/).
+> If you have trouble installing `encord-active`, you find more detailed instructions on
+> installing it [here][encord-active-docs].
+
+## Downloading a pre-built project
+
+The quickest way to get started is by downloading an existing dataset.
+The download command will setup a directory where the project will be stored and will ask which pre-built dataset to use.
+
+```shell
+$ encord-active download
+$ encord-active visualise /path/to/project
+```
+
+The app should automatically open in the browser. If not, navigate to `localhost:8501`.
+Our [Docs][encord-active-docs] contain more information about what you can see in the page.
+
+## Importing an Encord Project
+
+This section requires setting up an ssh key with Encord, so slightly more technical.
+
+> If you haven't set up an ssh key with Encord, you can follow the tutorial in this [link](https://docs.encord.com/admins/settings/public-keys/#set-up-public-key-authentication)
+
+To import an Encord project, use this script:
+
+```shell
+$ encord-active import project
+```
+
+## Development
+
+### Write your own metrics
+
+Encord Active isn't limited to the metrics we provided, it is actually quite easy to write your own 🔧
+See the [Writing Your Own Metric](https://docs.encord.com/admins/settings/public-keys/#set-up-public-key-authentication) page on the WIKI for details on this.
+
+### Pre-commit hooks
+
+If you have installed the dependencies with poetry, then you can install pre-commit hooks by running the following command:
+
+```shell
+$ pre-commit install
+```
+
+The effect of this will be that `black`, `isort`, `mypy`, and `pylint` needs to run without finding issues with the code before you are allowed to commit.
+When you commit and either `black` or `isort` fails, committing again is enough, as the side effect of committing the first time is to reformat files.
+
+Running each of the tools individually on your code can be done as follows:
+
+```shell
+$ poetry run black --config=pyproject.toml .
+$ poetry run isort --sp=pyproject.toml .
+$ poetry run mypy . --ignore-missing-imports
+$ poetry run pylint -j 0 --rcfile pyproject.toml [subdir]
+```
+
+## Community and Support
+
+Join our community on [Slack][join-slack] and [Twitter][twitter-url]!
+
+[Suggest improvements and report problems][new-issue]
+
+# Contributions
+
+If you're using Encord Active in your organization, please try to add your company name to the [ADOPTERS.md](./ADOPTERS.md). It really helps the project to gain momentum and credibility. It's a small contribution back to the project with a big impact.
+
+Read the [contributing docs][contribute-url].
+
+# Licence
+
+This project is licensed under the terms of the AGPL-3.0 license.
+
+[encord-active-docs]: https://encord-active-docs.web.app/
+[contribute-url]: https://encord-active-docs.web.app/contributing
+[contribute-image]: https://img.shields.io/badge/PRs-welcome-blue.svg
+[join-slack]: https://join.slack.com/t/encordactive/shared_invite/zt-1hc2vqur9-Fzj1EEAHoqu91sZ0CX0A7Q
+[twitter-url]: https://twitter.com/encord_team
+[new-issue]: https://github.com/encord-team/encord-active/issues/new
diff --git a/docs/.firebaserc b/docs/.firebaserc
new file mode 100644
index 000000000..6ad886351
--- /dev/null
+++ b/docs/.firebaserc
@@ -0,0 +1,14 @@
+{
+ "projects": {
+ "encord-active-frontend": "encord-active-frontend"
+ },
+ "targets": {
+ "encord-active-frontend": {
+ "hosting": {
+ "prod": [
+ "encord-active-docs"
+ ]
+ }
+ }
+ }
+}
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 000000000..b2d6de306
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..767f7cb87
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,25 @@
+# Encord Active Docs
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ npm i
+```
+
+### Local Development
+
+```
+$ npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
diff --git a/docs/babel.config.js b/docs/babel.config.js
new file mode 100644
index 000000000..e00595dae
--- /dev/null
+++ b/docs/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+ presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/docs/builders/build_metrics_pages.py b/docs/builders/build_metrics_pages.py
new file mode 100644
index 000000000..02ba2dc86
--- /dev/null
+++ b/docs/builders/build_metrics_pages.py
@@ -0,0 +1,94 @@
+"""
+Script for building markdown pages with information from the metrics.
+When run this will build pages directly into the `docs/docs/metrics directory.
+"""
+from importlib import import_module
+from pathlib import Path
+from typing import Any, List, Union, cast
+
+from tabulate import tabulate
+
+import encord_active.lib.common.metric as metrics
+import encord_active.lib.metrics.run_all as run_all
+
+github_url = "https://github.com/encord-team/encord-active"
+descriptions = {
+ "heuristic": "Work on images or individual video frames and are heuristic in the sense that they mostly depend on the image content without labels.",
+ "geometric": "Operate on the geometries of objects like bounding boxes, polygons, and polylines.",
+ "semantic": "Operates with the semantic information of images or individual video frames.",
+}
+
+metric_path = Path(run_all.__file__).parent
+docs_root = metric_path.parents[1]
+
+submodules = [p.name for p in metric_path.iterdir() if p.name[0] != "_" and p.is_dir()]
+
+ms = cast( # rename to avoid conflict with metrics module
+ List[List[metrics.Metric]],
+ [
+ sorted(
+ [import_module(m1).__getattribute__(m2)() for m1, m2 in run_all.get_metrics(submodule)],
+ key=lambda m: m.TITLE,
+ )
+ for submodule in submodules
+ ],
+)
+
+
+def fix_strings(row: List[Any]) -> List[str]:
+ for i, val in enumerate(row):
+ val = row[i]
+ if not isinstance(val, list):
+ val = [val]
+ val2: List[Union[str, int, float]] = []
+ for v in val:
+ if hasattr(v, "value"):
+ v = getattr(v, "value")
+ elif hasattr(v, "__name__"):
+ v = "Any"
+ elif v is None:
+ v = "Any"
+
+ if i in {2, 3,} and isinstance(
+ v, str
+ ): # image and annotation type, so replace "_" with space and let every type be a tag
+ v = v.replace("_", " ")
+ v = f"`{v}`"
+ val2.append(v)
+ try:
+ row[i] = ", ".join(map(str, sorted(set(val2))))
+ except TypeError:
+ print(row)
+ print(val2)
+
+ row[0] = f'[{row[0]}]({row[0].lower().replace(" ", "-")}) - {row[1]}'
+ row.pop(1)
+ return row
+
+
+for submodule, metrics_list in zip(submodules, ms):
+ rows = []
+ for m in metrics_list:
+ rows.append(fix_strings([m.TITLE, m.SHORT_DESCRIPTION, m.DATA_TYPE, m.ANNOTATION_TYPE]))
+ markdown_table = tabulate(
+ rows,
+ headers=["Title", "Metric Type", "Data Type", "Annotation Type"],
+ tablefmt="github",
+ )
+
+ md = ""
+ for metric in metrics_list:
+ url = f"{github_url}/blob/main/{type(metric).__module__.replace('.', '/')}.py"
+ md += f"\n## {metric.TITLE} \n" f"{metric.LONG_DESCRIPTION} \n\n" f"Implementation on [GitHub]({url})\n"
+
+ markdown_file = docs_root / "docs" / "metrics" / f"{submodule}.md"
+ with markdown_file.open("w", encoding="utf-8") as f:
+
+ def w(line):
+ f.write(f"{line}")
+ f.write("\n\n")
+
+ w(f"# {submodule.title()}")
+ w(descriptions[submodule])
+ w(markdown_table)
+ w(md)
diff --git a/docs/docs/cli/_category_.json b/docs/docs/cli/_category_.json
new file mode 100644
index 000000000..bc548e372
--- /dev/null
+++ b/docs/docs/cli/_category_.json
@@ -0,0 +1,9 @@
+{
+ "label": "Command Line Interface",
+ "position": 5,
+ "collapsed": true,
+ "link": {
+ "type": "generated-index",
+ "description": "How to use the command line interface (CLI)."
+ }
+}
diff --git a/docs/docs/cli/configuration.md b/docs/docs/cli/configuration.md
new file mode 100644
index 000000000..a201a8525
--- /dev/null
+++ b/docs/docs/cli/configuration.md
@@ -0,0 +1,57 @@
+---
+sidebar_position: 5
+---
+
+# Configuration
+
+Encord Active keeps some configurable properties to prevent repetitive input prompts.
+
+The config file is stored at:
+
+- Linux: `~/.config/encord-active/config.toml`
+- MacOS: `~/Library/Application Support/encord-active/config.toml`
+- Windows: `%APPDATA%/encord-active/config.toml`
+
+And these are the configurable properties.
+
+```toml
+ssh_key_path = "/absolute/path/to/ssh-key" # A key to use when accessing Encord projects
+projects_dir = "/absolute/path/to/projects/dir" # A directory where all projects should be stored
+```
+
+All properties are empty by default and are saved after the first time the user is prompted to provide them.
+
+The CLI also provides the `config` command which allows `list`/`get`/`set`/`unset` configurations.
+
+### Usage examples
+
+```shell
+encord-active config list
+
+# output (only if already set)
+ssh_key_path = "/Users/foo/.ssh/encord"
+projects_dir = "/Users/foo/projects"
+```
+
+```shell
+encord-active config get ssh_key_path
+
+# output
+ssh_key_path = "/Users/foo/.ssh/encord"
+```
+
+```shell
+encord-active config set ssh_key_path ~/.ssh/encord
+
+# output
+Property `ssh_key_path` has been set.
+```
+
+```shell
+encord-active config unset ssh_key_path
+
+# output
+Property `ssh_key_path` was unset.
+
+# note: next the property is needed a prompt will appear
+```
diff --git a/docs/docs/cli/download-sandbox-data.md b/docs/docs/cli/download-sandbox-data.md
new file mode 100644
index 000000000..c303cb300
--- /dev/null
+++ b/docs/docs/cli/download-sandbox-data.md
@@ -0,0 +1,37 @@
+---
+sidebar_position: 1
+---
+
+# Download Sandbox Dataset
+
+To get started quickly with a sandbox dataset, you run the following command.
+
+```shell
+(ea-venv)$ encord-active download
+```
+
+The script will ask you to
+
+1. `Where should we store the data?`: specify a directory in which the data should be stored.
+2. (potentially) `Directory not existing, want to create it? [y/N]` type y then enter.
+3. `[?] Choose a project:` choose a project with ↑ and ↓ and hit enter
+
+:::tip
+
+If you plan on using multiple datasets, it may be worth first creating an empty directory for all the datasets.
+
+```
+$ mkdir /path/to/data/root
+# or windows
+$ md /path/to/data/root
+```
+
+In step 1. above, specify, e.g., `/path/to/data/root/sandbox1`
+
+:::
+
+When the download process is complete, you visualise the results by following the printed instructions.
+For more details, see the [Open Encord Active](/cli/open-encord-active) page.
+
+
+
diff --git a/docs/docs/cli/import-coco-predictions.md b/docs/docs/cli/import-coco-predictions.md
new file mode 100644
index 000000000..80705eafb
--- /dev/null
+++ b/docs/docs/cli/import-coco-predictions.md
@@ -0,0 +1,25 @@
+---
+sidebar_position: 4
+---
+
+# Importing Coco Predictions
+
+:::info
+Make sure you have installed Encord Active with the `coco` [extras](/installation#coco-extras).
+:::
+
+:::note
+This command assume that you have imported you project useing the [COCO importer](/cli/import-coco-project).
+:::
+
+Importing COCO predictions is currently the easiest way to import predictions to Encord Active.
+
+You need to have a results JSON file following the [COCO results format](https://cocodataset.org/#format-results) and run the following command on it:
+
+```shell
+encord-active import predictions --coco results.json
+```
+
+This command will ask you to which project you would want to import the predications.
+
+After the execution is done you should be ready to view your [model assertions metrics](/category/model-assertions).
diff --git a/docs/docs/cli/import-coco-project.md b/docs/docs/cli/import-coco-project.md
new file mode 100644
index 000000000..695a89ed9
--- /dev/null
+++ b/docs/docs/cli/import-coco-project.md
@@ -0,0 +1,55 @@
+---
+sidebar_position: 3
+---
+
+# Importing Coco Project
+
+:::info
+Make sure you have installed Encord Active with the `coco` [extras](/installation#coco-extras).
+:::
+
+If you already have a project on your local machine using the COCO data format, you can import that project with the following command:
+
+```shell
+(ea-venv)$ encord-active import project --coco ./images ./annotations.json
+```
+
+:::info
+The command above assumes the following structure but is not limited to it.
+
+```
+
+coco-project-foo
+├── images
+│ ├── 00000001.jpeg
+│ ├── 00000002.jpeg
+│ ├── ...
+└── annotations.json
+
+```
+
+You can provide any path to each of the arguments as long as the first one is a directory of images and the second is an annotations file following the [COCO data format](https://cocodataset.org/#format-data).
+:::
+
+If this is your first time using Encord Active, you will need the path to your private `ssh-key` associated with Encord and a projects directory where all projects should be stored.
+Don't worry! The script will guide you on the way if you don't know it already.
+
+Running the importer will do the following things.
+
+1. Create a dataset.
+2. Create an ontology.
+3. Create a project.
+4. Create a local Encord Active project.
+5. Compute all the [metrics](category/metrics).
+
+:::info
+
+- Steps 1-3 are on the Encord platform. This is a dependency that we intend to make optional in the future.
+- Step 4 will make a hard copy of the images used in your dataset. In the future, we expect to support symlinks or just pointers to the original images.
+
+:::
+
+The whole flow might take a while depending on the size of your dataset.
+Bare with us, it is worth the wait.
+
+When the process is done, follow the printed instructions to open the app or see more details in the [Open Encord Active](/cli/open-encord-active) page.
diff --git a/docs/docs/cli/import-encord-project.md b/docs/docs/cli/import-encord-project.md
new file mode 100644
index 000000000..d74cf27a1
--- /dev/null
+++ b/docs/docs/cli/import-encord-project.md
@@ -0,0 +1,33 @@
+---
+sidebar_position: 2
+---
+
+# Importing Encord Project
+
+If you already have a project on the Encord platform, you can import that project with the following command:
+
+```
+(ea-venv)$ encord-active import project
+```
+
+:::tip
+
+If you don't have an Encord project ready, you can find your next steps in the SDK section [Migrating Data to Encord](/sdk/migrating-data).
+Otherwise, you can [download one of our sandbox datasets](/cli/download-sandbox-data).
+
+:::
+To be able to do this, you will need the path to your private `ssh-key` associated with Encord and a `project_hash`.
+Don't worry! The script will guide you on the way if you don't know it already.
+The script will ask you:
+
+1. `Where is your private ssh key stored?`: type the path to your private ssh key
+2. `Where should your project directory be located?`: use, e.g., `/path/to/data/root/your_project_title` from above.
+3. `Are you sure you want to use /path/you/chose? [y/N]`: hit