doc: updating readme (#733)

* update Readme.md and Contributing.md
* remove markdown-toc
* new screenshots ( jpg )
* add mouse and keyboard shortcuts from vott-ct

#AB17930

CONTRIBUTING.md

@@ -1,50 +1,55 @@
 # Contributing to VoTT
+
 We welcome [issues](https://github.com/Microsoft/VoTT/issues) and [pull requests](https://github.com/Microsoft/VoTT/pulls) into the project. We ask that you follow these simple guidelines:
 
+<!-- generated using: https://www.npmjs.com/package/markdown-toc-->
+<!-- command: `markdown-toc -i CONTRIBUTING.md --bullets "*"`-->
+
 <!-- toc -->
 
-- [Issues](#issues)
-- [Pull Requests](#pull-requests)
-- [Commit Message Guidelines](#commit-message-guidelines)
-  - [Commit Message Format](#commit-message-format)
-  - [Header](#header)
-    - [Type](#type)
-    - [Short Description](#short-description)
-  - [Body](#body)
-  - [Footer](#footer)
-  - [Commit Message Example](#commit-message-example)
-- [Style](#style)
+* [Issues](#issues)
+* [Pull Requests](#pull-requests)
+* [Commit Message Guidelines](#commit-message-guidelines)
+  * [Commit Message Format](#commit-message-format)
+  * [Header](#header)
+    * [Type](#type)
+    * [Short Description](#short-description)
+  * [Body](#body)
+  * [Footer](#footer)
+  * [Commit Message Example](#commit-message-example)
+* [Style](#style)
 
 <!-- tocstop -->
 
 ## Issues
 
-- Look for duplicate issues & comment on thread if experiencing something similar
-- Fill in template information (platform, OS, version, screenshots, etc.)
+* Look for duplicate issues & comment on thread if experiencing something similar
+* Fill in template information (platform, OS, version, screenshots, etc.)
 
 ## Pull Requests
 
-1. Find an issue to work on, or create a new one
-2. Fork repo, make sure you have latest changes from `v2`
-3. Create branch following naming convention: `git checkout -b issue-<###>-<short-description>`.
-4. Write code
-5. Add unit tests
-6. Verify linting and unit tests by running `npm test`
-7. Update docs if needed
-8. Rebase on `v2` and resolve conflicts
-9. Commit your changes using a descriptive commit message that follows [our commit message conventions](#commit-message-guidelines). Adherence to these conventions is necessary because the [change log](CHANGELOG.md) is automatically generated from these messages.
-10. Submit PR to `v2` branch
+1. Find an issue to work on, or create a new one.
+1. Fork the repo and/or pull down the latest changes from `master`.
+1. Create branch following naming convention: `git checkout -b issue-<###>-<short-description>`.
+1. Write code.
+1. Add unit tests.
+1. Verify linting and unit tests by running `npm test`.
+1. Update docs if needed.
+1. Rebase on `master` and resolve conflicts.
+1. Commit your changes using a descriptive commit message that follows [our commit message conventions](#commit-message-guidelines). Adherence to these conventions is necessary for the [change log](CHANGELOG.md) to be automatically generated from these messages.
+1. Submit PR to `master` branch.
 
-Try to keep PRs small to decrease the time required to review and merge.
+Please try to keep PRs small to decrease the time required to review and merge.
 
 ## Commit Message Guidelines
-We have adopted standards similar to [Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit) for how our git commit messages should be formatted. We believe that this leads to more readable messages that are easier to follow when looking through the project history and in addition, are used to generate the [VoTT change log](CHANGELOG.md).
 
+We have adopted standards similar to [Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit) for how our git commit messages should be formatted. This leads to more readable messages, which are easier to follow when looking through the project history. Those messages are used to generate the [VoTT change log](CHANGELOG.md).
 
 ### Commit Message Format
+
 Each commit message consists of a **header**, a **body** and a **footer**.
 
-```
+```text
 <type>: <short description>
 <BLANK LINE>
 <body>
@@ -53,7 +58,9 @@ Each commit message consists of a **header**, a **body** and a **footer**.
 ```
 
 ### Header
+
 #### Type
+
 Must be one of the following:
 
 * **build**: Changes that affect the build system or external dependencies
@@ -67,6 +74,7 @@ Must be one of the following:
 * **test**: Adding missing tests or correcting existing tests
 
 #### Short Description
+
 Contains a succinct description of the change:
 
 * use the imperative, present tense: "change" not "changed" nor "changes"
@@ -74,19 +82,22 @@ Contains a succinct description of the change:
 * no dot (.) at the end
 
 ### Body
+
 Just as in the **short description**, use the imperative, present tense: "change" not "changed" nor "changes".
 The body should include the motivation for the change and contrast this with previous behavior.
 
 ### Footer
-The footer should contain any information about **Breaking Changes** and is also the place to
-reference Azure DevOps user stories/tasks or GitHub issues that this commit **Closes**.
+
+The footer should contain any information about **breaking changes** and is also the place to
+reference Azure DevOps user stories/tasks or GitHub issues that this commit **closes**.
 
 ### Commit Message Example
-```
+
+```text
 fix: add debouncing to asset scroller to correct browser scroll position
 
 There is no debouncing when we store the asset container's scroll position.
-This results in erratic, jumpy scrolling and a poor user experience. improve
+This results in erratic, jumpy scrolling and a poor user experience. Improve
 stability and usability with debouncing.
 
 AB#17056
@@ -94,5 +105,7 @@ AB#17056
 
 ## Style
 
-1. This repo uses [EditorConfig](https://editorconfig.org/) to maintain consistent styles across multiple platforms and IDEs., please refer to
+* This repo uses [EditorConfig](https://editorconfig.org/) to maintain consistent styles across multiple platforms and IDEs. Please refer to
    this [guide](docs/STYLE.md) for more information.
+
+Thank you!

README.md

@@ -5,9 +5,8 @@
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Microsoft_VoTT&metric=alert_status)](https://sonarcloud.io/dashboard?id=Microsoft_VoTT)
 [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=Microsoft_VoTT&metric=ncloc)](https://sonarcloud.io/dashboard?id=Microsoft_VoTT)
 
-[Current Complexity Analysis Report](https://vottv2.z5.web.core.windows.net/)
+[Complexity Analysis Report](https://vottv2.z5.web.core.windows.net/)
 
-## **NOTE:** this is a Preview release of VoTT. Features may be incomplete or behave incorrectly (bugs! 🐞). [Feedback is appreciated!](https://github.com/Microsoft/VoTT/issues)
 ----------
 
 An open source annotation and labeling tool for image and video assets.
@@ -26,35 +25,36 @@ VoTT helps facilitate an end-to-end machine learning pipeline:
 
 ## Table of Contents
 <!-- generated using: https://www.npmjs.com/package/markdown-toc-->
-<!-- command: `markdown-toc -i README.md`-->
+<!-- command: `markdown-toc -i README.md --bullets "*"`-->
 
 <!-- toc -->
-- [VoTT (Visual Object Tagging Tool)](#vott-visual-object-tagging-tool)
-  - [## **NOTE:** this is a Preview release of VoTT. Features may be incomplete or behave incorrectly (bugs! 🐞). Feedback is appreciated!](#note-this-is-a-preview-release-of-vott-features-may-be-incomplete-or-behave-incorrectly-bugs-%F0%9F%90%9E-feedback-is-appreciated)
-  - [Table of Contents](#table-of-contents)
-- [Getting Started](#getting-started)
-  - [Running VoTT](#running-vott)
-    - [Download and install a release package for your platform (recommended)](#download-and-install-a-release-package-for-your-platform-recommended)
-    - [Build and run from source](#build-and-run-from-source)
-- [V1 & V2](#v1--v2)
-  - [Where is V1?](#where-is-v1)
-  - [Can I use my V1 projects in V2?](#converting-to-v2)
-- [Using VoTT](#using-vott)
-  - [Creating Connections](#creating-connections)
-  - [Creating a New Project](#creating-a-new-project)
-    - [Project Settings](#project-settings)
-      - [Security Tokens](#security-tokens)
-  - [Labeling an Image](#labeling-an-image)
-  - [Labeling a Video](#labeling-a-video)
-  - [Exporting Labels](#exporting-labels)
-- [Collaborators](#collaborators)
-- [Contributing to VoTT](#contributing-to-vott)
+
+* [Getting Started](#getting-started)
+  * [Download and install a release package for your platform (recommended)](#download-and-install-a-release-package-for-your-platform-recommended)
+  * [Build and run from source](#build-and-run-from-source)
+* [V1 & V2](#v1--v2)
+  * [Where is V1](#where-is-v1)
+    * [V1 releases](#v1-releases)
+  * [Can I use my V1 project in V2](#can-i-use-my-v1-project-in-v2)
+* [Using VoTT](#using-vott)
+  * [Creating Connections](#creating-connections)
+  * [Creating a New Project](#creating-a-new-project)
+    * [Project Settings](#project-settings)
+    * [Security Tokens](#security-tokens)
+  * [Labeling an Image](#labeling-an-image)
+  * [Labeling a Video](#labeling-a-video)
+  * [Exporting Labels](#exporting-labels)
+  * [Keyboard Shortcuts](#keyboard-shortcuts)
+    * [Tag Shortcuts](#tag-shortcuts)
+    * [Tag Ordering](#tag-ordering)
+    * [Tag Locking](#tag-locking)
+    * [Editor Shortcuts](#editor-shortcuts)
+* [Collaborators](#collaborators)
+* [Contributing to VoTT](#contributing-to-vott)
 
 <!-- tocstop -->
 
-# Getting Started
-
-## Running VoTT
+## Getting Started
 
 VoTT can be installed as a native application or run from source.
 
@@ -69,15 +69,17 @@ VoTT requires [NodeJS (>= 10.x, Dubnium) and NPM](https://github.com/nodejs/Rele
    ```bash
     git clone https://github.com/Microsoft/VoTT.git
     cd VoTT
-    git checkout v2
-    npm install
+    npm ci
     npm start
    ```
-   **Important:** When running locally with `npm`, both the electron and the browser versions of the application will start. One major difference is that electron can access the local file system.
 
-# V1 & V2
+   > **IMPORTANT**
+   >
+   > When running locally with `npm`, both the electron and the browser versions of the application will start. One major difference is that the electron version can access the local file system.
 
-VoTT V2 is a refactor and refresh of the original Electron-based application. As the usage and demand for VoTT grew, V2 was started as an initiative to improve and make VoTT more extensible and maintainable. In addition, V2 uses more modern development frameworks and patterns (React, Redux) and is authored in TypeScript.
+## V1 & V2
+
+VoTT V2 is a refactor and refresh of the original Electron-based application. As the usage and demand for VoTT grew, `V2` was started as an initiative to improve and make VoTT more extensible and maintainable. In addition, `V2` uses more modern development frameworks and patterns (React, Redux) and is authored in TypeScript.
 
 A number of code quality practices have been adopted, including:
 
@@ -86,78 +88,90 @@ A number of code quality practices have been adopted, including:
 * [Code coverage](https://codecov.io/gh/Microsoft/VoTT) ([CodeCov.io](https://codecov.io/))
 * [Complexity analysis](https://vottv2.z5.web.core.windows.net/) ([Plato](docs/PLATO.md))
 
-All V2 efforts are on the [v2](https://github.com/Microsoft/VoTT/tree/v2) branch. The git history for V1 and V2 have significantly diverged; when V2 is complete, master will be updated to reflect V2.
+All `V2` efforts are on the [master](https://github.com/Microsoft/VoTT/tree/master) branch
 
-## Where is V1?
+### Where is V1
 
-Master still reflects The V1 codebase - any fixes or updates can still be made there.  Likewise, all 1.x releases can still be found under [GitHub Releases](https://github.com/Microsoft/VoTT/releases).
+`V1` will be on the [v1](https://github.com/Microsoft/VoTT/tree/v1)  branch. There will not be any fixes or updates.
 
-## Can I use my V1 project in V2?
+#### V1 releases
 
-Yes you can! There is support for converting a V1 project into V2 format, but only for V1 projects that have only picture assets. Video assets from V1 are not yet supported. For a smooth experience, it is recommended that you keep your current V1 project (JSON) file in a directory with all your images for that project. When you open the JSON file, you will asked to confirm that you would like to convert your project and then you will be directed to the editor screen. In this process, a `.vott` file will be generated in the same project directory and you can use this as your project file from now on. It is recommended that you back up your V1 project file before converting the project.
+1.x releases can still be found under [GitHub Releases](https://github.com/Microsoft/VoTT/releases).
 
-# Using VoTT
+### V1 projects in V2
 
-## Creating Connections
+There is support for converting a V1 project into V2 format, but only for V1 projects that have only picture assets. Video assets from V1 are not yet supported. For a smooth experience, we recommend keeping the current V1 project (JSON) file in a directory with all the images for that project. Upon opening the JSON file, a window will pop up to confirm that the app should convert the project before redirecting to the editor screen. In this process, a `.vott` file will be generated in the same project directory, which may be used as the main project file going forward. We recommend backing up the V1 project file before converting the project.
 
-VoTT is a 'Bring Your Own Data' (BYOD) application. In VoTT, connections are used to configure and manage source (assets to labeled) and target (where labels should be exported to) data sources.
+## Using VoTT
 
-Connections can be setup and shared across projects. Connections have been designed using an extensible provider model -- new source/target provides can easily be added.  Currently, VOTT supports:
+### Creating Connections
 
-* Azure Blob Storage
+VoTT is a 'Bring Your Own Data' (BYOD) application. In VoTT, connections are used to configure and manage source (the assets to label) and target (the location to which labels should be exported).
+
+Connections can be set up and shared across projects. They use an extensible provider model, so new source/target providers can easily be added.
+
+Currently, VoTT supports:
+
+* [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction)
 * [Bing Image Search](https://azure.microsoft.com/en-us/services/cognitive-services/bing-image-search-api/)
 * Local File System
 
-To create a new connection, click the 'New Connection' icon, in the left hand navigation bar:
+To create a new connection, click the `New Connections` (plug) icon, in the left hand navigation bar:
 
-![alt text](docs/images/new-connection.png "New Connection")
+![alt text](docs/images/new-connection.jpg "New Connection")
 
-## Creating a New Project
+### Creating a New Project
 
-Labeling workflows in VoTT revolve around projects - a collection of configuration and settings that are persisted. Projects define a source and target connection, as well as project metadata - including tags to be used when labeling source assests.
+Labeling workflows in VoTT revolve around projects - a collection of configurations and settings that persist.
+
+Projects define source and target connections, and project metadata - including tags to be used when labeling source assets.
 
 As mentioned above, all projects require a source and target connection:
 
-* **Source Connection** - Where to pull assests from
-* **Target Connection** - Where project files and exported data are stored
+* **Source Connection** - Where to pull assets from
+* **Target Connection** - Where project files and exported data should be stored
 
-![alt text](docs/images/new-project.png "New Project")
+![alt text](docs/images/new-project.jpg "New Project")
 
-### Project Settings
+#### Project Settings
 
-Project settings can be modified after a project has been created, by clicking on the 'Project Setting' icon in the left hand navigation bar.
+Project settings can be modified after a project has been created, by clicking on the `Project Setting` (slider) icon in the left hand navigation bar. Project metrics, such as Visited Assets, Tagged Assets, and Average Tags Per Asset can also be viewed on this screen.
+
+![alt text](docs/images/project-settings.jpg "Project Settings")
 
 #### Security Tokens
 
 Some project settings can include sensitive values, such as API keys or other shared secrets. Each project will generate a security token that can be used to encrypt/decrypt sensitive project settings.
 
-Security tokens can be found under 'Application Settings' by clicking the gear icon in the lower corner of the left hand navigation bar.
+Security tokens can be found in `Application Settings` by clicking the gear icon in the lower corner of the left hand navigation bar.
 
 **NOTE:** Project files can be shared among multiple people. In order to share sensitive project settings, *all parties must have/use the same security token.*
 
-The token name and key *must* match in order for sensitive values to be successfully decrypted.
+The token name and key **must** match in order for sensitive values to be successfully decrypted.
 
-![alt text](docs/images/security-tokens.png "Security Tokens")
+![alt text](docs/images/security-tokens.jpg "Security Tokens")
 
-## Labeling an Image
+### Labeling an Image
 
-When a project is created or opened, the main tag editor window opens. The tag editor consists of two main parts:
+When a project is created or opened, the main tag editor window opens. The tag editor consists of three main parts:
 
-* A preview pane that contains a scrollable list of images and videos, from the source target
-* The main editor tool that allows tags to be applied to drawn regions
+* A resizeable preview pane that contains a scrollable list of images and videos, from the source connection
+* The main editor pane that allows tags to be applied to drawn regions
+* The tags editor pane that allows users to modify, lock, reorder, and delete tags
 
 Selecting an image or video on the left will load that image in the main tag editor. Regions can then be drawn on the loaded asset and a tag can be applied.
 
 As desired, repeat this process for any additional assets.
 
-![alt text](docs/images/label-image.png "Image Tagging")
+![alt text](docs/images/label-image.jpg "Image Tagging")
 
-## Labeling a Video
+### Labeling a Video
 
 Labeling a video is much like labeling a series of images. When a video is selected from the left, it will begin automatically playing, and there are several controls on the player, as seen here:
-![alt text](docs/images/video-player.png "Video Player")
 
-In addition to the normal video playback controls, there are two extra pairs of buttons. 
+![alt text](docs/images/video-player.jpg "Video Player")
+
+In addition to the normal video playback controls, there are two extra pairs of buttons.
 
 On the left, there are the previous and next frame buttons. Clicking these will pause the video, and move to the next appropriate frame as determined by the project settings. For example, if the project settings have a frame extraction rate of 1, these buttons will cause the video to be moved back or forward 1 second, while if the frame extraction rate is 10, the video will be moved back or forward a tenth of a second.
 
@@ -169,7 +183,7 @@ The timeline can also be used to manually scrub through the video to an arbitrar
 
 Tagging and drawing regions is not possible while the video is playing.
 
-## Exporting Labels
+### Exporting Labels
 
 Once assets have been labeled, they can be exported into a variety of formats:
 
@@ -177,30 +191,58 @@ Once assets have been labeled, they can be exported into a variety of formats:
 * TensorFlow (Pascal VOC and TFRecords)
 * VoTT (generic JSON schema)
 
-In addition, users may choose to export all assets, only visited assets, or only tagged assets.  Click on the 'Export' icon in the left hand navigation. Select the appropriate export provider and which assets to export.
+In addition, users may choose to export
 
-![alt text](docs/images/export-labels.png "Export Labels")
+* all assets
+* only visited assets
+* only tagged assets
 
-## Keyboard Shortcuts
+Click on the `Export` (arrow) icon in the left hand navigation. Select the appropriate export provider and which assets to export. The percentage separated into testing and training sets can be adjusted here too.
+
+![alt text](docs/images/export-labels.jpg "Export Labels")
+
+### Keyboard Shortcuts
 
 VoTT allows a number of keyboard shortcuts to make it easier to keep one hand on the mouse while tagging. It allows most common shortcuts:
 
-* Ctrl+C - copy
-* Ctrl+X - cut 
-* Ctrl+V - paste
-* Ctrl+A - select all
-* Ctrl+Z - undo
-* Ctrl+Shift+Z - redo
+* Ctrl or Cmd + C - copy
+* Ctrl or Cmd + X - cut
+* Ctrl or Cmd + V - paste
+* Ctrl or Cmd + A - select all
+* Ctrl or Cmd + Z - undo
+* Ctrl or Cmd + Shift + Z - redo
 
-The editor page assigns hotkeys of 1 through 0 to the first ten tags. These can be reordered by dragging tags in the footer. In addition, the editor page has some special shortcuts to select tagging tools:
+#### Tag Ordering
+
+Hotkeys of 1 through 0 are assigned to the first ten tags. These can be reordered by using the up/down arrow icons in in the tag editor pane.
+
+
+#### Tag Locking
+
+A tag can be locked for repeated tagging using the lock icon at the top of the tag editor pane. Tags can also be locked by combining Ctrl or Cmd and the tag hotkey, i.e. `Ctrl+2` would lock the second tag in the list.
+
+![alt text](docs/images/reorder-tag.jpg "Tag Editor")
+
+#### Editor Shortcuts
+
+In addition, the editor page has some special shortcuts to select tagging tools:
 
 * V - Pointer/Select
 * R - Draw Rectangle
 * P - Draw Polygon
+* Ctrl or Cmd + S - Save Project
+* Ctrl or Cmd + E - Export Project
+
+VOTT allows you to fine tune the bounding boxes using the arrow keys in a few different ways. While a region is selected:
+
+* Ctrl + Arrowkey - Move Region
+* Ctrl + Alt + Arrowkey - Shrink Region
+* Ctrl + Shift + Arrowkey - Expand Region
+
+The slide viewer can be navigated from the keyboard as follows: 
+
 * W or ArrowUp - Previous Asset
 * S or ArrowDown - Next Asset
-* Ctrl+S - Save Project
-* Ctrl+E - Export Project
 
 When the video playback bar is present, it allows the following shortcuts to select frames:
 
@@ -209,11 +251,21 @@ When the video playback bar is present, it allows the following shortcuts to sel
 * Q - Previous Tagged Frame
 * E - Next Tagged Frame
 
-# Collaborators
+#### Mouse Controls
+
+* Two-point mode - Hold down Ctrl while creating a region
+* Square mode - Hold down Shift while creating a region
+* Multi-select - Hold down Shift while selecting regions
+* Exclusive Tracking mode - Ctrl + N to block frame UI allowing a user to create a region on top of existing regions
+
+
+## Collaborators
 
 VoTT was originally developed by the [Commercial Software Engineering (CSE) group at Microsoft](https://www.microsoft.com/developerblog/) in Israel.
 
-# Contributing to VoTT
+V2 is developed by the CSE group at Microsoft in Redmond, Washington.
+
+## Contributing to VoTT
 
 There are many ways to contribute to VoTT -- please review our [contribution guidelines](CONTRIBUTING.md).