examples/intro_to_remo-python.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# First steps with Remo python library"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Remo python library provides an intuitive way to visualize, clean and work with images for a variety of computer vision tasks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create a dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Adding data to Remo is as easy as passing the path or URL of your data's location to the ```remo.create_dataset()``` method of the library.\n",
    "\n",
    "In this example, a sample dataset hosted online is added to Remo directly via URL\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import remo\n",
    "import pandas as pd\n",
    "# To seamlessly use Remo within the Jupyter Notebook, use the following setting\n",
    "remo.set_viewer('jupyter')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Acquiring data - completed                                                                           \n",
      "Processing data - completed                                                                          \n",
      "Data upload completed\n"
     ]
    }
   ],
   "source": [
    "urls = ['https://remo-scripts.s3-eu-west-1.amazonaws.com/open_images_sample_dataset.zip']\n",
    "\n",
    "my_dataset = remo.create_dataset(name = 'open images detection',\n",
    "                    urls = urls,\n",
    "                    annotation_task = \"Object detection\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**That's it! Your images are now accessible and stored in a centralised place.**\n",
    "\n",
    "Remo supports a number of annotation formats and tasks out of the box. You can read more in [the documentation](https://remo.ai/docs/annotation-formats/).\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Manage multiple datasets\n",
    "\n",
    "Within Remo, you can host multiple datasets and retrieve one when needed.\n",
    "\n",
    "**This allows you to organize and reuse your data across projects.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's list all the datasets and retrieve one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[Dataset 1 - 'ocr_symbols',\n",
       " Dataset 2 - 'test',\n",
       " Dataset 8 - 'open_images',\n",
       " Dataset 9 - 'test',\n",
       " Dataset 12 - 'open images detection']"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "remo.list_datasets()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "# make sure to use the right ID when running the tutorial\n",
    "new_dataset = remo.get_dataset(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualize"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Providing an easy to use interface is another way in which Remo makes your life working on a computer vision project easier.\n",
    "\n",
    "By calling ```dataset.view()``` method, you can open an interactive interface which allows you to **visually inspect your images and the corresponding annotations**.\n",
    "\n",
    "You can visualise your dataset directly in Jupyter (or in a separate window if you are not a fan of notebooks)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_dataset.view()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![view_dataset.gif](assets/view_dataset.gif)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Annotation Statistics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Once data is in Remo, you can easily explore the statistics and other important properties of your data.**\n",
    "\n",
    "For example, you can quickly see:\n",
    "\n",
    "- what's contained in the annotations\n",
    "- check if there are unbalanced classes\n",
    "- spot if some objects are only contained in a few images"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " You can do this by printing the stats of an annotation set or using the interactive UI.\n",
    " \n",
    " \n",
    "Calling ```my_dataset.get_annotation_statistics()``` will print annotation statistics to the screen"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'AnnotationSet ID': 41,\n",
       "  'AnnotationSet name': 'Object detection',\n",
       "  'n_images': 10,\n",
       "  'n_classes': 18,\n",
       "  'n_objects': 98,\n",
       "  'top_3_classes': [{'name': 'Fruit', 'count': 27},\n",
       "   {'name': 'Sports equipment', 'count': 12},\n",
       "   {'name': 'Human arm', 'count': 10}],\n",
       "  'creation_date': None,\n",
       "  'last_modified_date': '2020-05-29T13:38:52.259776Z'}]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "my_dataset.get_annotation_statistics()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Calling ```my_dataset.view_annotation_stats()``` will show an interactive dashboard.\n",
    "\n",
    "Here you can inspect annotations more in details and manage your classes and tags"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_dataset.view_annotation_stats()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![annotation_statistics.png](assets/annotation_statistics.png) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Export Annotations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**In order to use the dataset for training a model, you can export the annotations to a standardised format such as CSV, JSON, etc**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_dataset.export_annotations_to_file('output.zip', annotation_format='csv')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Further functionalities"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**You can refer to other tutorials and the documentation to further explore the library and see how to use it to better manage your datasets.**\n",
    "    \n",
    "Some of the other things you can do include:\n",
    "\n",
    "- Easily experimenting with choice of annotations from code\n",
    "- Custom uploading of annotations and predictions and joint visualization\n",
    "- Advanced images search by classes, tags and filenames"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.10"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "307.2px"
   },
   "toc_section_display": "block",
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}