{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Image capture"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this article it is explained how an image is captured from a camera and the parameters that affect this capture."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Video capture"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be obtained a BGR matrix that represents the image using VideoCapture object from OpenCV. Sometimes it is needed to flush the buffer to let the camera be adapted to new settings or to be synchronized with some physical events."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import cv2\n",
    "capture = cv2.VideoCapture(0)\n",
    "\n",
    "flush = 2\n",
    "if capture.isOpened():\n",
    "    for i in range(flush):\n",
    "        ret, image = capture.read()\n",
    "\n",
    "del capture"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Camera settings"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Brightness\n",
    "\n",
    "It is the luminosity of an image. Brightness can be computed as arithmetic mean of RGB values  $\\mu=\\frac{R+G+B}{3}$\n",
    "\n",
    "![](https://raw.githubusercontent.com/Jesus89/3DScanScience/master/notebooks/images/2.%20Image%20capture/brightness.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Contrast\n",
    "It is the relevant difference in the intensity of an image that makes an object distinguishable.\n",
    "\n",
    "![](https://raw.githubusercontent.com/Jesus89/3DScanScience/master/notebooks/images/2.%20Image%20capture/contrast.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Saturation\n",
    "It is the colorfulness of a color relative to its own brightness. This parameter affects the color purity of the image.\n",
    "\n",
    "![](https://raw.githubusercontent.com/Jesus89/3DScanScience/master/notebooks/images/2.%20Image%20capture/saturation.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exposure\n",
    "We defined exposure as the time, in ms, that the camera sensor is exposed to capture the light. There is a relation with this time $t$, the exposure value $EV$ and the relative aperture $N$ of a camera. High values of time increases the capture time linearly.\n",
    "$$EV = log_2 \\: \\frac{N^2}{t}$$\n",
    "\n",
    "![](https://raw.githubusercontent.com/Jesus89/3DScanScience/master/notebooks/images/2.%20Image%20capture/exposure.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Frame rate\n",
    "It is the number of frames that the camera captures per second. For scanning purposes it is recommended to use the highest value permitted by the camera, in this case 30 fps."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Resolution\n",
    "It is the size of an image in pixel units. Also, for scanning purposes it is recommended to use the highest value permitted by the camera, in this case 1280x960."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Distortion correction\n",
    "\n",
    "If the lens of the camera being used causes any distortion, this can be corrected by using the calibration parameters obtained in [Camera calibration](http://nbviewer.ipython.org/github/Jesus89/3DScanScience/blob/master/notebooks/4.2.%20Camera%20calibration.ipynb).\n",
    "\n",
    "![](http://bersoft.com/bimagem/help/undistort.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Code\n",
    "```\n",
    "dist_camera_matrix = cv2.getOptimalNewCameraMatrix(camera_matrix, distortion_vector, (width, height), alpha=1)\n",
    "\n",
    "image = cv2.undistort(image, camera_matrix, distortion_vector, None, dist_camera_matrix)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# References\n",
    "* https://en.wikipedia.org/wiki/Brightness\n",
    "* https://es.wikipedia.org/wiki/Contrast\n",
    "* https://en.wikipedia.org/wiki/Saturation\n",
    "* https://en.wikipedia.org/wiki/Exposure_value\n",
    "* https://en.wikipedia.org/wiki/Distortion_%28optics%29"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}