+++ /dev/null
-function insertIframe (elementId, iframeSrc)
-{
- var iframe;
- if (document.createElement && (iframe = document.createElement('iframe')))
- {
- iframe.src = unescape(iframeSrc);
- iframe.width = "100%";
- iframe.height = "511px";
- var element = document.getElementById(elementId);
- element.parentNode.replaceChild(iframe, element);
- }
-}
+++ /dev/null
-{#
- basic/layout.html
- ~~~~~~~~~~~~~~~~~
-
- Master layout template for Sphinx themes.
-
- :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
- :license: BSD, see LICENSE for details.
-#}
-{%- block doctype -%}
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-{%- endblock %}
-{% set script_files = script_files + [pathto("_static/insertIframe.js", 1)] %}
-{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %}
-{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %}
-{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and
- (sidebars != []) %}
-{%- set url_root = pathto('', 1) %}
-{%- if url_root == '#' %}{% set url_root = '' %}{% endif %}
-<script type="text/javascript">
-
- var _gaq = _gaq || [];
- _gaq.push(['_setAccount', 'UA-33108845-1']);
- _gaq.push(['_setDomainName', 'opencv.org']);
- _gaq.push(['_trackPageview']);
-
- (function() {
- var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
- ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
- var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
- })();
-
-</script>
-{%- macro relbar() %}
- <div class="related">
- <h3>{{ _('Navigation') }}</h3>
- <ul>
- {%- for rellink in rellinks %}
- <li class="right" {% if loop.first %}style="margin-right: 10px"{% endif %}>
- <a href="{{ pathto(rellink[0]) }}" title="{{ rellink[1]|striptags|e }}"
- {{ accesskey(rellink[2]) }}>{{ rellink[3] }}</a>
- {%- if not loop.first %}{{ reldelim2 }}{% endif %}</li>
- {%- endfor %}
- {%- block rootrellink %}
- <li><a href="{{ pathto(master_doc) }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
- {%- endblock %}
- {%- for parent in parents %}
- <li><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li>
- {%- endfor %}
- {%- block relbaritems %} {% endblock %}
- </ul>
- </div>
-{%- endmacro %}
-
-{%- macro sidebar() %}
- {%- if render_sidebar %}
- <div class="sphinxsidebar">
- <div class="sphinxsidebarwrapper">
- {%- block sidebarlogo %}
- {%- if logo %}
- <p class="logo"><a href="{{ pathto(master_doc) }}">
- <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
- </a></p>
- {%- endif %}
- {%- endblock %}
- {%- if sidebars == None %}
- {%- block sidebarsearch %}
- {%- include "searchbox.html" %}
- {%- endblock %}
- {%- endif %}
- {%- if sidebars != None %}
- {#- new style sidebar: explicitly include/exclude templates #}
- {%- for sidebartemplate in sidebars %}
- {%- include sidebartemplate %}
- {%- endfor %}
- {%- else %}
- {#- old style sidebars: using blocks -- should be deprecated #}
- {%- block sidebartoc %}
- {%- include "localtoc.html" %}
- {%- endblock %}
- {%- block sidebarrel %}
- {%- include "relations.html" %}
- {%- endblock %}
- {%- block sidebarsourcelink %}
- {%- include "sourcelink.html" %}
- {%- endblock %}
- {%- if customsidebar %}
- {%- include customsidebar %}
- {%- endif %}
- {%- endif %}
- </div>
- </div>
- {%- endif %}
-{%- endmacro %}
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset={{ encoding }}" />
- {{ metatags }}
- {%- if not embedded and docstitle %}
- {%- set titlesuffix = " — "|safe + docstitle|e %}
- {%- else %}
- {%- set titlesuffix = "" %}
- {%- endif %}
- {%- block htmltitle %}
- <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
- {%- endblock %}
- <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
- <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
- {%- for cssfile in css_files %}
- <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
- {%- endfor %}
- {%- if not embedded %}
- <script type="text/javascript">
- var DOCUMENTATION_OPTIONS = {
- URL_ROOT: '{{ url_root }}',
- VERSION: '{{ release|e }}',
- COLLAPSE_INDEX: false,
- FILE_SUFFIX: '{{ '' if no_search_suffix else file_suffix }}',
- HAS_SOURCE: {{ has_source|lower }}
- };
- </script>
- {%- for scriptfile in script_files %}
- <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
- {%- endfor %}
- {%- if use_opensearch %}
- <link rel="search" type="application/opensearchdescription+xml"
- title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}"
- href="{{ pathto('_static/opensearch.xml', 1) }}"/>
- {%- endif %}
- {%- if favicon %}
- <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
- {%- endif %}
- {%- endif %}
-{%- block linktags %}
- {%- if hasdoc('about') %}
- <link rel="author" title="{{ _('About these documents') }}" href="{{ pathto('about') }}" />
- {%- endif %}
- {%- if hasdoc('genindex') %}
- <link rel="index" title="{{ _('Index') }}" href="{{ pathto('genindex') }}" />
- {%- endif %}
- {%- if hasdoc('search') %}
- <link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}" />
- {%- endif %}
- {%- if hasdoc('copyright') %}
- <link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}" />
- {%- endif %}
- <link rel="top" title="{{ docstitle|e }}" href="{{ pathto('index') }}" />
- {%- if parents %}
- <link rel="up" title="{{ parents[-1].title|striptags|e }}" href="{{ parents[-1].link|e }}" />
- {%- endif %}
- {%- if next %}
- <link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}" />
- {%- endif %}
- {%- if prev %}
- <link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}" />
- {%- endif %}
-{%- endblock %}
-{%- block extrahead %} {% endblock %}
- </head>
- <body>
-{%- block header %}{% endblock %}
-
-{%- block relbar1 %}{{ relbar() }}{% endblock %}
-
-{%- block content %}
- {%- block sidebar1 %} {# possible location for sidebar #} {% endblock %}
-
- <div class="document">
- {% block document %}
- <div class="documentwrapper">
- {%- if not embedded %}{% if not theme_nosidebar|tobool %}
- <div class="bodywrapper">
- {%- endif %}{% endif %}
- <div class="body">
- {% block body %} {% endblock %}
- </div>
- <div class="feedback">
- <h2>Help and Feedback</h2>
- You did not find what you were looking for?
- <ul>
- {% if theme_lang == 'c' %}
- {% endif %}
- {% if theme_lang == 'cpp' %}
- <li>Try the <a href="http://docs.opencv.org/opencv_cheatsheet.pdf">Cheatsheet</a>.</li>
- {% endif %}
- {% if theme_lang == 'py' %}
- <li>Try the <a href="cookbook.html">Cookbook</a>.</li>
- {% endif %}
- <li>Ask a question on the <a href="http://answers.opencv.org">Q&A forum</a>.</li>
- <li>If you think something is missing or wrong in the documentation,
- please file a <a href="http://code.opencv.org">bug report</a>.</li>
- </ul>
- </div>
- {%- if not embedded %}{% if not theme_nosidebar|tobool %}
- </div>
- {%- endif %}{% endif %}
- </div>
-{% endblock %}
-
- {%- block sidebar2 %}{{ sidebar() }}{% endblock %}
- <div class="clearer"></div>
- </div>
-{%- endblock %}
-
-{%- block relbar2 %}{{ relbar() }}{% endblock %}
-
-{%- block footer %}
- <div class="footer">
- {%- if show_copyright %}
- {%- if hasdoc('copyright') %}
- {% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
- {%- else %}
- {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %}
- {%- endif %}
- {%- endif %}
- {%- if last_updated %}
- {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
- {%- endif %}
- {%- if show_sphinx %}
- {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
- {%- endif %}
- </div>
-{%- endblock %}
- </body>
-</html>
+++ /dev/null
-{#
- basic/searchbox.html
- ~~~~~~~~~~~~~~~~~~~~
-
- Sphinx sidebar template: quick search box.
-
- :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
- :license: BSD, see LICENSE for details.
-#}
-{%- if pagename != "search" %}
-<div id="searchbox" style="display: none">
- <form class="search" action="{{ pathto('search') }}" method="get">
- <input type="text" name="q" size="18" />
- <input type="submit" value="{{ _('Search') }}" />
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
- </p>
- </form>
-</div>
-<script type="text/javascript">$('#searchbox').show(0);</script>
-{%- endif %}
+++ /dev/null
-/**
- * Sphinx stylesheet -- default theme
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- */
-
-@import url("basic.css");
-
-/* -- page layout ----------------------------------------------------------- */
-
-body {
- font-family: {{ theme_bodyfont }};
- font-size: 100%;
- background-color: {{ theme_footerbgcolor }};
- color: #000;
- margin: 0;
- padding: 0;
-}
-
-img.logo {
- width: 150px;
-}
-
-div.document {
- background-color: {{ theme_sidebarbgcolor }};
-}
-
-div.documentwrapper {
- float: left;
- width: 100%;
-}
-
-div.bodywrapper {
- margin: 0 0 0 270px;
-}
-
-div.body {
- background-color: {{ theme_bgcolor }};
- color: {{ theme_textcolor }};
- padding: 0 20px 30px 20px;
-}
-
-div.feedback {
- background-color: {{ theme_feedbackbgcolor }};
- color: {{ theme_feedbacktextcolor }};
- padding: 20px 20px 30px 20px;
-}
-
-div.feedback h2 {
- margin: 10px 0 10px 0;
-}
-
-div.feedback a {
- color: {{ theme_feedbacklinkcolor }};
- font-weight: bold;
-}
-
-{%- if theme_rightsidebar|tobool %}
-div.bodywrapper {
- margin: 0 230px 0 0;
-}
-{%- endif %}
-
-div.footer {
- color: {{ theme_footertextcolor }};
- width: 100%;
- padding: 9px 0 9px 0;
- text-align: center;
- font-size: 75%;
-}
-
-div.footer a {
- color: {{ theme_footertextcolor }};
- text-decoration: underline;
-}
-
-div.related {
- background-color: {{ theme_relbarbgcolor }};
- line-height: 30px;
- color: {{ theme_relbartextcolor }};
-}
-
-div.related a {
- color: {{ theme_relbarlinkcolor }};
-}
-
-div.sphinxsidebar {
- word-wrap: break-word;
- width: 270px;
- {%- if theme_stickysidebar|tobool %}
- top: 30px;
- margin: 0;
- position: fixed;
- overflow: auto;
- height: 100%;
- {%- endif %}
- {%- if theme_rightsidebar|tobool %}
- float: right;
- {%- if theme_stickysidebar|tobool %}
- right: 0;
- {%- endif %}
- {%- endif %}
-}
-
-{%- if theme_stickysidebar|tobool %}
-/* this is nice, but it it leads to hidden headings when jumping
- to an anchor */
-/*
-div.related {
- position: fixed;
-}
-
-div.documentwrapper {
- margin-top: 30px;
-}
-*/
-{%- endif %}
-
-div.sphinxsidebar h3 {
- font-family: {{ theme_headfont }};
- color: {{ theme_sidebartextcolor }};
- font-size: 1.4em;
- font-weight: normal;
- margin: 0;
- padding: 0;
-}
-
-div.sphinxsidebar h3 a {
- color: {{ theme_sidebartextcolor }};
-}
-
-div.sphinxsidebar h4 {
- font-family: {{ theme_headfont }};
- color: {{ theme_sidebartextcolor }};
- font-size: 1.3em;
- font-weight: normal;
- margin: 5px 0 0 0;
- padding: 0;
-}
-
-div.sphinxsidebar p {
- color: {{ theme_sidebartextcolor }};
-}
-
-div.sphinxsidebar p.topless {
- margin: 5px 10px 10px 10px;
-}
-
-div.sphinxsidebar ul {
- margin: 10px 0 10px 10px;
- padding: 0;
- color: {{ theme_sidebartextcolor }};
-}
-
-div.sphinxsidebar a {
- color: {{ theme_sidebarlinkcolor }};
-}
-
-div.sphinxsidebar input {
- border: 1px solid {{ theme_sidebarlinkcolor }};
- font-family: sans-serif;
- font-size: 1em;
-}
-
-/* -- body styles ----------------------------------------------------------- */
-
-a {
- color: {{ theme_linkcolor }};
- text-decoration: none;
-}
-
-a:hover {
- text-decoration: underline;
-}
-
-div.body p, div.body dd, div.body li {
- text-align: justify;
- line-height: 130%;
- margin-top: 1em;
- margin-bottom: 1em;
-}
-
-div.toctree-wrapper li, ul.simple li {
- margin:0;
-}
-
-div.body h1,
-div.body h2,
-div.body h3,
-div.body h4,
-div.body h5,
-div.body h6 {
- font-family: {{ theme_headfont }};
- background-color: {{ theme_headbgcolor }};
- font-weight: normal;
- color: {{ theme_headtextcolor }};
- border-bottom: 1px solid #ccc;
- margin: 20px -20px 10px -20px;
- padding: 3px 0 3px 10px;
-}
-
-a.toc-backref, a.toc-backref:hover {
- font-family: {{ theme_headfont }};
- background-color: {{ theme_headbgcolor }};
- font-weight: normal;
- color: {{ theme_headtextcolor }};
- text-decoration: none;
-}
-
-div.body h1 { margin-top: 0; font-size: 200%; }
-div.body h2 { font-size: 160%; }
-div.body h3 { font-size: 140%; }
-div.body h4 { font-size: 120%; }
-div.body h5 { font-size: 110%; }
-div.body h6 { font-size: 100%; }
-
-a.headerlink {
- color: {{ theme_headlinkcolor }};
- font-size: 0.8em;
- padding: 0 4px 0 4px;
- text-decoration: none;
-}
-
-a.headerlink:hover {
- background-color: {{ theme_headlinkcolor }};
- color: white;
-}
-
-
-div.body p, div.body dd, div.body li {
- text-align: justify;
- line-height: 130%;
-}
-
-div.admonition p.admonition-title + p {
- display: inline;
-}
-
-div.note {
- background-color: #eee;
- border: 1px solid #ccc;
-}
-
-div.seealso {
- background-color: #ffc;
- border: 1px solid #ff6;
-}
-
-div.topic {
- background-color: #eee;
-}
-
-div.warning {
- background-color: #ffe4e4;
- border: 1px solid #f66;
-}
-
-p.admonition-title {
- display: inline;
-}
-
-p.admonition-title:after {
- content: ":";
-}
-
-pre {
- padding: 5px;
- background-color: {{ theme_codebgcolor }};
- color: {{ theme_codetextcolor }};
- line-height: 120%;
- border: 1px solid #ace;
- border-left: none;
- border-right: none;
-}
-
-tt {
- color: {{ theme_headtextcolor }};
- /*background-color: #ecf0f3;*/
- padding: 0 1px 0 1px;
- font-size: 1.2em;
-}
-
-tt.descname {
- color: {{ theme_headtextcolor }};
- /*background-color: #ecf0f3;*/
- padding: 0 1px 0 1px;
- font-size: 1.4em;
-}
-
-div.math p {
- margin-top: 10px;
- margin-bottom: 10px;
-}
-
-dl.function > dt:first-child {
- margin-bottom: 7px;
-}
-
-dl.cfunction > dt:first-child {
- margin-bottom: 7px;
- color: #8080B0;
-}
-
-dl.cfunction > dt:first-child tt.descname
-{
- color: #8080B0;
-}
-
-
-dl.pyfunction > dt:first-child {
- margin-bottom: 7px;
-}
-
-dl.jfunction > dt:first-child {
- margin-bottom: 7px;
-}
-
-table.field-list {
- margin-top: 20px;
-}
-
-/*ul.simple {
- list-style: none;
-}*/
-
-em.menuselection, em.guilabel {
- font-family: {{ theme_guifont }};
-}
-
-.enumeratevisibleitemswithsquare ul {
-list-style: square;
-margin-bottom: 0px;
-margin-left: 0px;
-margin-right: 0px;
-margin-top: 0px;
-}
-
-.enumeratevisibleitemswithsquare li {
-margin-bottom: 0.2em;
-margin-left: 0px;
-margin-right: 0px;
-margin-top: 0.2em;
- }
-
- .enumeratevisibleitemswithsquare p {
- margin-bottom: 0pt;
- margin-top: 1pt;
- }
-
- .enumeratevisibleitemswithsquare dl{
-margin-bottom: 0px;
-margin-left: 0px;
-margin-right: 0px;
-margin-top: 0px;
- }
-
- .toctableopencv
- {
- width: 100% ;
- table-layout: fixed;
- }
-
-
- .toctableopencv colgroup col:first-child
- {
- width: 100pt !important;
- max-width: 100pt !important;
- min-width: 100pt !important;
- }
-
- .toctableopencv colgroup col:nth-child(2)
- {
- width: 100% !important;
- }
-
-div.body ul.search li {
- text-align: left;
-}
-
-div.linenodiv {
- min-width: 1em;
- text-align: right;
-}
-
-div.sphinxsidebar #searchbox input[type="text"] {
- width:auto;
-}
-
-div.sphinxsidebar #searchbox input[type="submit"] {
- width:auto;
-}
+++ /dev/null
-[theme]
-inherit = basic
-stylesheet = default.css
-pygments_style = sphinx
-
-[options]
-rightsidebar = false
-stickysidebar = false
-footerbgcolor = #004068
-footertextcolor = #ffffff
-sidebarbgcolor = #006090
-sidebartextcolor = #ffffff
-sidebarlinkcolor = #cceeff
-relbarbgcolor = #003048
-relbartextcolor = #ffffff
-relbarlinkcolor = #ffffff
-bgcolor = #ffffff
-textcolor = #000000
-headbgcolor = #f2f2f2
-headtextcolor = #003048
-headlinkcolor = #65a136
-linkcolor = #0090d9
-codebgcolor = #e0f5ff
-codetextcolor = #333333
-feedbackbgcolor = #004068
-feedbacktextcolor = #ffffff
-feedbacklinkcolor = #ffffff
-bodyfont = sans-serif
-headfont = 'Trebuchet MS', sans-serif
-guifont = "Lucida Sans","Lucida Sans Unicode","Lucida Grande",Verdana,Arial,Helvetica,sans-serif
-lang = none
+++ /dev/null
-{#
- basic/layout.html
- ~~~~~~~~~~~~~~~~~
-
- Master layout template for Sphinx themes.
-
- :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
- :license: BSD, see LICENSE for details.
-#}
-{%- block doctype -%}
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-{%- endblock %}
-{% set script_files = script_files + [pathto("_static/insertIframe.js", 1)] %}
-{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %}
-{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %}
-{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and
- (sidebars != []) %}
-{%- set url_root = pathto('', 1) %}
-{# XXX necessary? #}
-{%- if url_root == '#' %}{% set url_root = '' %}{% endif %}
-{%- if not embedded and docstitle %}
- {%- set titlesuffix = " — "|safe + docstitle|e %}
-{%- else %}
- {%- set titlesuffix = "" %}
-{%- endif %}
-<script type="text/javascript">
-
- var _gaq = _gaq || [];
- _gaq.push(['_setAccount', 'UA-33108845-1']);
- _gaq.push(['_setDomainName', 'opencv.org']);
- _gaq.push(['_trackPageview']);
-
- (function() {
- var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
- ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
- var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
- })();
-
-</script>
-{%- macro relbar() %}
- <div class="related">
- <h3>{{ _('Navigation') }}</h3>
- <ul>
- {%- for rellink in rellinks %}
- <li class="right" {% if loop.first %}style="margin-right: 10px"{% endif %}>
- <a href="{{ pathto(rellink[0]) }}" title="{{ rellink[1]|striptags|e }}"
- {{ accesskey(rellink[2]) }}>{{ rellink[3] }}</a>
- {%- if not loop.first %}{{ reldelim2 }}{% endif %}</li>
- {%- endfor %}
- {%- block rootrellink %}
- <li><a href="{{ pathto(master_doc) }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
- {%- endblock %}
- {%- for parent in parents %}
- <li><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li>
- {%- endfor %}
- {%- block relbaritems %} {% endblock %}
- </ul>
- </div>
-{%- endmacro %}
-
-{%- macro sidebar() %}
- {%- if render_sidebar %}
- <div class="sphinxsidebar">
- <div class="sphinxsidebarwrapper">
- {%- block sidebarlogo %}
- {%- if logo %}
- <p class="logo"><a href="{{ pathto(master_doc) }}">
- <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
- </a></p>
- {%- endif %}
- {%- endblock %}
- {%- if sidebars == None %}
- {%- block sidebarsearch %}
- {%- include "searchbox.html" %}
- {%- endblock %}
- {%- endif %}
- {%- if sidebars != None %}
- {#- new style sidebar: explicitly include/exclude templates #}
- {%- for sidebartemplate in sidebars %}
- {%- include sidebartemplate %}
- {%- endfor %}
- {%- else %}
- {#- old style sidebars: using blocks -- should be deprecated #}
- {%- block sidebartoc %}
- {%- include "localtoc.html" %}
- {%- endblock %}
- {%- block sidebarrel %}
- {%- include "relations.html" %}
- {%- endblock %}
- {%- if customsidebar %}
- {%- include customsidebar %}
- {%- endif %}
- {%- endif %}
- </div>
- </div>
- {%- endif %}
-{%- endmacro %}
-
-{%- macro script() %}
- <script type="text/javascript">
- var DOCUMENTATION_OPTIONS = {
- URL_ROOT: '{{ url_root }}',
- VERSION: '{{ release|e }}',
- COLLAPSE_INDEX: false,
- FILE_SUFFIX: '{{ '' if no_search_suffix else file_suffix }}',
- HAS_SOURCE: {{ has_source|lower }}
- };
- </script>
- {%- for scriptfile in script_files %}
- <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
- {%- endfor %}
-{%- endmacro %}
-
-{%- macro css() %}
- <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
- <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
- {%- for cssfile in css_files %}
- <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
- {%- endfor %}
-{%- endmacro %}
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset={{ encoding }}" />
- {{ metatags }}
- {%- block htmltitle %}
- <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
- {%- endblock %}
- {{ css() }}
- {%- if not embedded %}
- {{ script() }}
- {%- if use_opensearch %}
- <link rel="search" type="application/opensearchdescription+xml"
- title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}"
- href="{{ pathto('_static/opensearch.xml', 1) }}"/>
- {%- endif %}
- {%- if favicon %}
- <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
- {%- endif %}
- {%- endif %}
-{%- block linktags %}
- {%- if hasdoc('about') %}
- <link rel="author" title="{{ _('About these documents') }}" href="{{ pathto('about') }}" />
- {%- endif %}
- {%- if hasdoc('genindex') %}
- <link rel="index" title="{{ _('Index') }}" href="{{ pathto('genindex') }}" />
- {%- endif %}
- {%- if hasdoc('search') %}
- <link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}" />
- {%- endif %}
- {%- if hasdoc('copyright') %}
- <link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}" />
- {%- endif %}
- <link rel="top" title="{{ docstitle|e }}" href="{{ pathto('index') }}" />
- {%- if parents %}
- <link rel="up" title="{{ parents[-1].title|striptags|e }}" href="{{ parents[-1].link|e }}" />
- {%- endif %}
- {%- if next %}
- <link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}" />
- {%- endif %}
- {%- if prev %}
- <link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}" />
- {%- endif %}
-{%- endblock %}
-{%- block extrahead %}
- <link href='http://fonts.googleapis.com/css?family=Open+Sans:300,400,700'
- rel='stylesheet' type='text/css' />
-{%- if not embedded %}
- <style type="text/css">
- table.right { float: right; margin-left: 20px; }
- table.right td { border: 1px solid #ccc; }
- </style>
- <script type="text/javascript">
- // intelligent scrolling of the sidebar content
- $(window).scroll(function() {
- var sb = $('.sphinxsidebarwrapper');
- var win = $(window);
- var sbh = sb.height();
- var offset = $('.sphinxsidebar').position()['top'];
- var wintop = win.scrollTop();
- var winbot = wintop + win.innerHeight();
- var curtop = sb.position()['top'];
- var curbot = curtop + sbh;
- // does sidebar fit in window?
- if (sbh < win.innerHeight()) {
- // yes: easy case -- always keep at the top
- sb.css('top', $u.min([$u.max([0, wintop - offset - 10]),
- $(document).height() - sbh - 200]));
- } else {
- // no: only scroll if top/bottom edge of sidebar is at
- // top/bottom edge of window
- if (curtop > wintop && curbot > winbot) {
- sb.css('top', $u.max([wintop - offset - 10, 0]));
- } else if (curtop < wintop && curbot < winbot) {
- sb.css('top', $u.min([winbot - sbh - offset - 20,
- $(document).height() - sbh - 200]));
- }
- }
- });
- </script>
-{%- endif %}
-{% endblock %}
- </head>
-{%- block header %}{% endblock %}
-
-{%- block relbar1 %}{{ relbar() }}{% endblock %}
-
- {%- block sidebar1 %} {# possible location for sidebar #} {% endblock %}
- {%- block sidebar2 %}{{ sidebar() }}{% endblock %}
- <body>
-
-{%- block content %}
-
- <div class="document">
- {%- block document %}
- <div class="documentwrapper">
- {%- if render_sidebar %}
- <div class="bodywrapper">
- {%- endif %}
- <div class="body">
- {% block body %} {% endblock %}
- </div>
- <div class="feedback">
- <h2>Help and Feedback</h2>
- You did not find what you were looking for?
- <ul>
- {% if theme_lang == 'c' %}
- {% endif %}
- {% if theme_lang == 'cpp' %}
- <li>Try the <a href="http://docs.opencv.org/opencv_cheatsheet.pdf">Cheatsheet</a>.</li>
- {% endif %}
- {% if theme_lang == 'py' %}
- <li>Try the <a href="cookbook.html">Cookbook</a>.</li>
- {% endif %}
- <li>Ask a question on the <a href="http://answers.opencv.org">Q&A forum</a>.</li>
- <li>If you think something is missing or wrong in the documentation,
- please file a <a href="http://code.opencv.org">bug report</a>.</li>
- </ul>
- </div>
- {%- if render_sidebar %}
- </div>
- {%- endif %}
- </div>
- {%- endblock %}
-
- <div class="clearer"></div>
- </div>
-{%- endblock %}
-
-{%- block relbar2 %}{{ relbar() }}{% endblock %}
-
-{%- block footer %}
- <div class="footer">
- {%- if show_copyright %}
- {%- if hasdoc('copyright') %}
- {% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
- {%- else %}
- {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %}
- {%- endif %}
- {%- endif %}
- {%- if last_updated %}
- {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
- {%- endif %}
- {%- if show_sphinx %}
- {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
- {%- endif %}
- {%- if show_source and has_source and sourcename %}
- <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow">{{ _('Show this page source.') }}</a>
- {%- endif %}
- </div>
-{%- endblock %}
- </body>
-</html>
+++ /dev/null
-{#
- basic/searchbox.html
- ~~~~~~~~~~~~~~~~~~~~
-
- Sphinx sidebar template: quick search box.
-
- :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
- :license: BSD, see LICENSE for details.
-#}
-{%- if pagename != "search" and builder != "singlehtml" %}
-<div id="searchbox" style="display: none">
- <h3>{{ _('Quick search') }}</h3>
- <form class="search" action="{{ pathto('search') }}" method="get">
- <input type="text" name="q" />
- <input type="submit" value="{{ _('Go') }}" />
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
- </form>
-</div>
-<script type="text/javascript">$('#searchbox').show(0);</script>
-{%- endif %}
+++ /dev/null
-/*
- * sphinxdoc.css_t
- * ~~~~~~~~~~~~~~~
- *
- * Sphinx stylesheet -- sphinxdoc theme.
- *
- * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
- */
-
-@import url("basic.css");
-
-/* -- page layout ----------------------------------------------------------- */
-
-body {
- font-family: 'Open Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
- 'Verdana', sans-serif;
- font-size: 14px;
- text-align: center;
- background-image: url(bodybg.png);
- color: black;
- padding: 0;
- border-right: 1px solid #0a507a;
- border-left: 1px solid #0a507a;
-
- margin: 0 auto;
- min-width: 780px;
- max-width: 1080px;
-}
-
-div.document {
- background-color: white;
- text-align: left;
-}
-
-div.bodywrapper {
- margin: 0 240px 0 0;
- border-right: 1px solid #0a507a;
-}
-
-div.body {
- margin: 0;
- padding: 0.5em 20px 20px 20px;
-}
-
-div.related {
- font-size: 1em;
- color: white;
-}
-
-div.related ul {
- background-image: url(relbg.png);
- text-align: left;
- border-top: 1px solid #002e50;
- border-bottom: 1px solid #002e50;
-}
-
-div.related li + li {
- display: inline;
-}
-
-div.related ul li.right {
- float: right;
- margin-right: 5px;
-}
-
-div.related ul li a {
- margin: 0;
- padding: 0 5px 0 5px;
- line-height: 1.75em;
- color: #f9f9f0;
- text-shadow: 0px 0px 1px rgba(0, 0, 0, 0.5);
-}
-
-div.related ul li a:hover {
- color: white;
- text-shadow: 0px 0px 1px rgba(255, 255, 255, 0.5);
-}
-
-div.footer {
- background-image: url(footerbg.png);
- color: #ccc;
- text-shadow: 0 0 .2px rgba(255, 255, 255, 0.8);
- padding: 3px 8px 3px 0;
- clear: both;
- font-size: 0.8em;
- text-align: center;
-}
-
-div.sphinxsidebarwrapper {
- position: relative;
- top: 0px;
- padding: 0;
-}
-
-div.sphinxsidebar {
- word-wrap: break-word;
- margin: 0;
- padding: 0 15px 15px 0;
- width: 210px;
- float: right;
- font-size: 1em;
- text-align: left;
-}
-
-div.sphinxsidebar .logo {
- text-align: center;
-}
-
-div.sphinxsidebar .logo img {
- width: 150px;
- vertical-align: middle;
-}
-
-div.sphinxsidebar input {
- border: 1px solid #aaa;
- font-family: 'Open Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
- 'Verdana', sans-serif;
- font-size: 1em;
-}
-
-div.sphinxsidebar #searchbox input[type="text"] {
- width: 160px;
-}
-
-div.sphinxsidebar #searchbox input[type="submit"] {
- width: 40px;
-}
-
-div.sphinxsidebar h3 {
- font-size: 1.5em;
- border-top: 1px solid #0a507a;
- margin-top: 1em;
- margin-bottom: 0.5em;
- padding-top: 0.5em;
-}
-
-div.sphinxsidebar h4 {
- font-size: 1.2em;
- margin-bottom: 0;
-}
-
-div.sphinxsidebar h3, div.sphinxsidebar h4 {
- margin-right: -15px;
- margin-left: -15px;
- padding-right: 14px;
- padding-left: 14px;
- color: #333;
- font-weight: 300;
- /*text-shadow: 0px 0px 0.5px rgba(0, 0, 0, 0.4);*/
-}
-
-div.sphinxsidebarwrapper > h3:first-child {
- margin-top: 0.5em;
- border: none;
-}
-
-div.sphinxsidebar h3 a {
- color: #333;
-}
-
-div.sphinxsidebar ul {
- color: #444;
- margin-top: 7px;
- padding: 0;
- line-height: 130%;
-}
-
-div.sphinxsidebar ul ul {
- margin-left: 20px;
- list-style-image: url(listitem.png);
-}
-
-/* -- body styles ----------------------------------------------------------- */
-
-p {
- margin: 0.8em 0 0.5em 0;
-}
-
-a, a tt {
- color: #2878a2;
-}
-
-a:hover, a tt:hover {
- color: #68b8c2;
-}
-
-a tt {
- border: 0;
-}
-
-h1, h2, h3, h4, h5, h6 {
- color: #0a507a;
- background-color: #e5f5ff;
- font-weight: 300;
-}
-
-h1 {
- margin: 10px 0 0 0;
-}
-
-h2 {
- margin: 1.em 0 0.2em 0;
- padding: 0;
-}
-
-h3 {
- margin: 1em 0 -0.3em 0;
-}
-
-h1 { font-size: 200%; }
-h2 { font-size: 160%; }
-h3 { font-size: 140%; }
-h4 { font-size: 120%; }
-h5 { font-size: 110%; }
-h6 { font-size: 100%; }
-
-div a, h1 a, h2 a, h3 a, h4 a, h5 a, h6 a {
- text-decoration: none;
-}
-
-div.body h1 a tt, div.body h2 a tt, div.body h3 a tt,
-div.body h4 a tt, div.body h5 a tt, div.body h6 a tt {
- color: #0a507a !important;
- font-size: inherit !important;
-}
-
-a.headerlink {
- color: #0a507a !important;
- font-size: 12px;
- margin-left: 6px;
- padding: 0 4px 0 4px;
- text-decoration: none !important;
- float: right;
-}
-
-a.headerlink:hover {
- background-color: #ccc;
- color: white!important;
-}
-
-cite, code, tt {
- font-family: 'Consolas', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono',
- monospace;
- font-size: 14px;
- min-width: 780px;
- max-width: 1080px;
-}
-
-tt {
- color: #003048;
- padding: 1px;
-}
-
-tt.descname, tt.descclassname, tt.xref {
- font-size: 12px;
-}
-
-hr {
- border: 1px solid #abc;
- margin: 2em;
-}
-
-pre {
- font-family: 'Consolas', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono',
- monospace;
- font-size: 13px;
- letter-spacing: 0.015em;
- line-height: 120%;
- padding: 0.5em;
- border: 1px solid #ccc;
- border-radius: 2px;
- background-color: #f8f8f8;
-}
-
-pre a {
- color: inherit;
- text-decoration: none;
-}
-
-td.linenos pre {
- padding: 0.5em 0;
-}
-
-td.code pre {
- max-width: 740px;
- overflow: auto;
- overflow-y: hidden; /* fixes display issues on Chrome browsers */
-}
-
-div.quotebar {
- background-color: #f8f8f8;
- max-width: 250px;
- float: right;
- padding: 0px 7px;
- border: 1px solid #ccc;
- margin-left: 1em;
-}
-
-div.topic {
- background-color: #f8f8f8;
-}
-
-table {
- border-collapse: collapse;
- margin: 0 -0.5em 0 -0.5em;
-}
-
-table td, table th {
- padding: 0.2em 0.5em 0.2em 0.5em;
-}
-
-div.note {
- background-color: #eee;
- border: 1px solid #ccc;
-}
-
-div.seealso {
- background-color: #ffc;
- border: 1px solid #ff6;
-}
-
-div.topic {
- background-color: #eee;
-}
-
-div.warning {
- background-color: #ffe4e4;
- border: 1px solid #f66;
-}
-
-div.admonition ul li, div.warning ul li,
-div.admonition ol li, div.warning ol li {
- text-align: left;
-}
-
-div.admonition p.admonition-title + p {
- display: inline;
-}
-
-p.admonition-title {
- display: inline;
-}
-
-p.admonition-title:after {
- content: ":";
-}
-
-/* ------------------ our styles ----------------*/
-
-div.body p, div.body dd, div.body li {
- text-align: justify;
- line-height: 130%;
- margin-top: 1em;
- margin-bottom: 1em;
-}
-
-div.toctree-wrapper li, ul.simple li {
- margin:0;
-}
-
-/*a.toc-backref {
-}*/
-
-div.feedback {
- /*background-color: #;*/
- /*color: #;*/
- padding: 20px 20px 30px 20px;
- border-top: 1px solid #002e50;
-}
-
-div.feedback h2 {
- margin: 10px 0 10px 0;
-}
-
-div.feedback a {
- /*color: #;*/
- font-weight: bold;
-}
-
-div.math p {
- margin-top: 10px;
- margin-bottom: 10px;
-}
-
-dl.function > dt:first-child {
- margin-bottom: 7px;
-}
-
-dl.cfunction > dt:first-child {
- margin-bottom: 7px;
- color: #8080B0;
-}
-
-dl.cfunction > dt:first-child tt.descname {
- color: #8080B0;
-}
-
-dl.pyfunction > dt:first-child {
- margin-bottom: 7px;
-}
-
-dl.jfunction > dt:first-child {
- margin-bottom: 7px;
-}
-
-table.field-list {
- margin-top: 20px;
-}
-
-em.menuselection, em.guilabel {
- font-family: 'Lucida Sans', 'Lucida Sans Unicode', 'Lucida Grande', Verdana,
- Arial, Helvetica, sans-serif;
-}
-
-.enumeratevisibleitemswithsquare ul {
- list-style: square;
- margin-bottom: 0px;
- margin-left: 0px;
- margin-right: 0px;
- margin-top: 0px;
-}
-
-.enumeratevisibleitemswithsquare li {
- margin-bottom: 0.2em;
- margin-left: 0px;
- margin-right: 0px;
- margin-top: 0.2em;
- }
-
-.enumeratevisibleitemswithsquare p {
- margin-bottom: 0pt;
- margin-top: 1pt;
-}
-
-.enumeratevisibleitemswithsquare dl {
- margin-bottom: 0px;
- margin-left: 0px;
- margin-right: 0px;
- margin-top: 0px;
-}
-
-.toctableopencv {
- width: 100% ;
- table-layout: fixed;
-}
-
-.toctableopencv colgroup col:first-child {
- width: 100pt !important;
- max-width: 100pt !important;
- min-width: 100pt !important;
-}
-
-.toctableopencv colgroup col:nth-child(2) {
- width: 100% !important;
-}
-
-div.body ul.search li {
- text-align: left;
-}
-
-div.linenodiv {
- min-width: 1em;
- text-align: right;
-}
+++ /dev/null
-[theme]
-inherit = basic
-stylesheet = default.css
-pygments_style = sphinx
+++ /dev/null
-#!/usr/bin/env python
-
-import sys, glob
-
-sys.path.append("../modules/python/src2/")
-import hdr_parser as hp
-
-opencv_hdr_list = [
-"../modules/core/include/opencv2/core.hpp",
-"../modules/ml/include/opencv2/ml.hpp",
-"../modules/imgproc/include/opencv2/imgproc.hpp",
-"../modules/calib3d/include/opencv2/calib3d.hpp",
-"../modules/features2d/include/opencv2/features2d.hpp",
-"../modules/video/include/opencv2/video/tracking.hpp",
-"../modules/video/include/opencv2/video/background_segm.hpp",
-"../modules/objdetect/include/opencv2/objdetect.hpp",
-"../modules/imgcodecs/include/opencv2/imgcodecs.hpp",
-"../modules/videoio/include/opencv2/videoio.hpp",
-"../modules/highgui/include/opencv2/highgui.hpp",
-]
-
-opencv_module_list = [
-"core",
-"imgproc",
-"calib3d",
-"features2d",
-"video",
-"objdetect",
-"imgcodecs",
-"videoio",
-"highgui",
-"ml"
-]
-
-class RSTParser(object):
-
- def __init__(self):
- self.read_whitelist()
-
- # reads the file containing functions and classes that do not need to be documented
- def read_whitelist(self):
- self.whitelist = {}
- try:
- wf = open("check_docs_whitelist.txt", "rt")
- except IOError:
- return
- self.parser = hp.CppHeaderParser()
-
- for l in wf.readlines():
- cpos = l.find("#")
- if cpos >= 0:
- l = l[:cpos]
- l = l.strip()
- if not l:
- continue
- rst_decl = None
- if "(" in l:
- l = l.replace("cv::", "")
- rst_decl = self.parser.parse_func_decl_no_wrap(l)
- fname = rst_decl[0]
- else:
- fname = l.replace("::", ".")
- complist = fname.split(".")
- prefix = ""
- alreadyListed = False
- wl = []
- for c in complist:
- prefix = (prefix + "." + c).lstrip(".")
- wl = self.whitelist.get(prefix, [])
- if wl == "*":
- break
- if wl == "*":
- continue
- if not rst_decl:
- self.whitelist[fname] = "*"
- else:
- wl.append(rst_decl)
- self.whitelist[fname] = wl
- wf.close()
-
- def process_rst(self, docname):
- df = open(docname, "rt")
- fdecl = ""
- balance = 0
- lineno = 0
-
- for l in df.readlines():
- lineno += 1
- ll = l.strip()
- if balance == 0:
- if not ll.startswith(".. c:function::") and \
- not ll.startswith(".. cpp:function::") and \
- not ll.startswith(".. ocv:function::") and \
- not ll.startswith(".. ocv:cfunction::"):
- continue
- fdecl = ll[ll.find("::") + 3:]
- elif balance > 0:
- fdecl += ll
- balance = fdecl.count("(") - fdecl.count(")")
- assert balance >= 0
- if balance > 0:
- continue
- rst_decl = self.parser.parse_func_decl_no_wrap(fdecl)
- fname = rst_decl[0]
- hdr_decls = self.fmap.get(fname, [])
- if not hdr_decls:
- fname = fname.replace("cv.", "")
- hdr_decls = self.fmap.get(fname, [])
- if not hdr_decls:
- print "Documented function %s (%s) in %s:%d is not in the headers" % (fdecl, rst_decl[0].replace(".", "::"), docname, lineno)
- continue
- decl_idx = 0
- for hd in hdr_decls:
- if len(hd[3]) != len(rst_decl[3]):
- decl_idx += 1
- continue
- idx = 0
- for a in hd[3]:
- if a[0] != rst_decl[3][idx][0] and a[0].replace("cv::", "") != rst_decl[3][idx][0]:
- break
- idx += 1
- if idx == len(hd[3]):
- break
- decl_idx += 1
- if decl_idx < len(hdr_decls):
- self.fmap[fname] = hdr_decls[:decl_idx] + hdr_decls[decl_idx+1:]
- continue
- print "Documented function %s in %s:%d does not have a match" % (fdecl, docname, lineno)
- df.close()
-
- def decl2str(self, decl):
- return "%s %s(%s)" % (decl[1], decl[0], ", ".join([a[0] + " " + a[1] for a in decl[3]]))
-
- def check_module_docs(self, name):
- self.parser = hp.CppHeaderParser()
- decls = []
- self.fmap = {}
-
- for hname in opencv_hdr_list:
- if hname.startswith("../modules/" + name):
- decls += self.parser.parse(hname, wmode=False)
-
- for d in decls:
- fname = d[0]
- if not fname.startswith("struct") and not fname.startswith("class") and not fname.startswith("const"):
- dlist = self.fmap.get(fname, [])
- dlist.append(d)
- self.fmap[fname] = dlist
-
- self.missing_docfunc_list = []
-
- doclist = glob.glob("../modules/" + name + "/doc/*.rst")
- for d in doclist:
- self.process_rst(d)
-
- print "\n\n########## The list of undocumented functions: ###########\n\n"
- misscount = 0
- fkeys = sorted(self.fmap.keys())
- for f in fkeys:
- # skip undocumented destructors
- if "~" in f:
- continue
- decls = self.fmap[f]
- fcomps = f.split(".")
- prefix = ""
- wlist_decls = []
- for c in fcomps:
- prefix = (prefix + "." + c).lstrip(".")
- wlist_decls = self.whitelist.get(prefix, [])
- if wlist_decls == "*":
- break
- if wlist_decls == "*":
- continue
- wlist_decls = [self.decl2str(d) for d in wlist_decls]
-
- for d in decls:
- dstr = self.decl2str(d)
- # special hack for ML: skip old variants of the methods
- if name == "ml" and ("CvMat" in dstr):
- continue
- if dstr not in wlist_decls:
- misscount += 1
- print "%s %s(%s)" % (d[1], d[0].replace(".", "::"), ", ".join([a[0] + " " + a[1] for a in d[3]]))
- print "\n\n\nundocumented functions in %s: %d" % (name, misscount)
-
-
-p = RSTParser()
-for m in opencv_module_list:
- print "\n\n*************************** " + m + " *************************\n"
- p.check_module_docs(m)
+++ /dev/null
-#!/usr/bin/env python
-
-import os, sys, fnmatch, re
-
-sys.path.append("../modules/python/src2/")
-sys.path.append("../modules/java/generator")
-
-import hdr_parser as hp
-import rst_parser as rp
-
-rp.show_warnings = False
-rp.show_errors = False
-
-allmodules = rp.allmodules
-DOCUMENTED_MARKER = "verified"
-
-ERROR_001_NOTACLASS = 1
-ERROR_002_NOTASTRUCT = 2
-ERROR_003_INCORRECTBASE = 3
-ERROR_004_MISSEDNAMESPACE = 4
-ERROR_005_MISSINGPYFUNC = 5
-ERROR_006_INVALIDPYOLDDOC = 6
-ERROR_007_INVALIDPYDOC = 7
-ERROR_008_CFUNCISNOTGLOBAL = 8
-ERROR_009_OVERLOADNOTFOUND = 9
-ERROR_010_UNKNOWNCLASS = 10
-ERROR_011_UNKNOWNFUNC = 11
-
-do_python_crosscheck = True
-errors_disabled = [ERROR_004_MISSEDNAMESPACE]
-
-doc_signatures_whitelist = [
-# templates
-"Matx", "Vec", "SparseMat_", "Scalar_", "Mat_", "Ptr", "Size_", "Point_", "Rect_", "Point3_",
-"DataType", "detail::RotationWarperBase", "flann::Index_", "CalonderDescriptorExtractor",
-"cuda::PtrStepSz", "cuda::PtrStep", "cuda::PtrElemStep_",
-# black boxes
-"CvArr", "CvFileStorage",
-# other
-"InputArray", "OutputArray",
-]
-
-defines = ["cvGraphEdgeIdx", "cvFree", "CV_Assert", "cvSqrt", "cvGetGraphVtx", "cvGraphVtxIdx",
-"cvCaptureFromFile", "cvCaptureFromCAM", "cvCalcBackProjectPatch", "cvCalcBackProject",
-"cvGetHistValue_1D", "cvGetHistValue_2D", "cvGetHistValue_3D", "cvGetHistValue_nD",
-"cvQueryHistValue_1D", "cvQueryHistValue_2D", "cvQueryHistValue_3D", "cvQueryHistValue_nD",
-# not a real function but behaves as function
-"Mat::size",
-# ugly "virtual" functions from ml module
-"CvStatModel::train", "CvStatModel::predict",
-# TODO:
-"cvExtractSURF"
-]
-
-synonims = {
- "StarDetector" : ["StarFeatureDetector"],
- "MSER" : ["MserFeatureDetector"],
- "GFTTDetector" : ["GoodFeaturesToTrackDetector"],
- "cvCaptureFromFile" : ["cvCreateFileCapture"],
- "cvCaptureFromCAM" : ["cvCreateCameraCapture"],
- "cvCalcArrBackProjectPatch" : ["cvCalcBackProjectPatch"],
- "cvCalcArrBackProject" : ["cvCalcBackProject"],
- "InputArray" : ["_InputArray"],
- "OutputArray" : ["_OutputArray"],
-}
-
-if do_python_crosscheck:
- try:
- import cv2
- except ImportError:
- print "Could not load cv2"
- do_python_crosscheck = False
-
-def get_cv2_object(name):
- if name.startswith("cv2."):
- name = name[4:]
- if name.startswith("cv."):
- name = name[3:]
- if name == "Algorithm":
- return cv2.Algorithm__create("Feature2D.ORB"), name
- elif name == "FeatureDetector":
- return cv2.FeatureDetector_create("ORB"), name
- elif name == "DescriptorExtractor":
- return cv2.DescriptorExtractor_create("ORB"), name
- elif name == "BackgroundSubtractor":
- return cv2.createBackgroundSubtractorMOG(), name
- elif name == "StatModel":
- return cv2.KNearest(), name
- else:
- try:
- obj = getattr(cv2, name)()
- except AttributeError:
- obj = getattr(cv2, "create" + name)()
- return obj, name
-
-def compareSignatures(f, s):
- # function names
- if f[0] != s[0]:
- return False, "name mismatch"
- # return type
- stype = (s[1] or "void")
- ftype = f[1]
- stype = re.sub(r"\b(cv|std)::", "", stype)
- if ftype:
- ftype = re.sub(r"\b(cv|std)::", "", ftype)
- if ftype and ftype != stype:
- return False, "return type mismatch"
- if ("\C" in f[2]) ^ ("\C" in s[2]):
- return False, "const qualifier mismatch"
- if ("\S" in f[2]) ^ ("\S" in s[2]):
- return False, "static qualifier mismatch"
- if ("\V" in f[2]) ^ ("\V" in s[2]):
- return False, "virtual qualifier mismatch"
- if ("\A" in f[2]) ^ ("\A" in s[2]):
- return False, "abstract qualifier mismatch"
- if len(f[3]) != len(s[3]):
- return False, "different number of arguments"
- for idx, arg in enumerate(zip(f[3], s[3])):
- farg = arg[0]
- sarg = arg[1]
- ftype = re.sub(r"\b(cv|std)::", "", (farg[0] or ""))
- stype = re.sub(r"\b(cv|std)::", "", (sarg[0] or ""))
- ftype = re.sub(r"\s+(\*|&)$", "\\1", ftype)
- stype = re.sub(r"\s+(\*|&)$", "\\1", stype)
- if ftype != stype:
- return False, "type of argument #" + str(idx+1) + " mismatch"
- fname = farg[1] or "arg" + str(idx)
- sname = sarg[1] or "arg" + str(idx)
- if fname != sname:
- return False, "name of argument #" + str(idx+1) + " mismatch"
- fdef = re.sub(r"\b(cv|std)::", "", (farg[2] or ""))
- sdef = re.sub(r"\b(cv|std)::", "", (sarg[2] or ""))
- if fdef != sdef:
- return False, "default value of argument #" + str(idx+1) + " mismatch"
- return True, "match"
-
-def formatSignature(s):
- _str = ""
- if "/V" in s[2]:
- _str += "virtual "
- if "/S" in s[2]:
- _str += "static "
- if s[1]:
- _str += s[1] + " "
- else:
- if not bool(re.match(r"(\w+\.)*(?P<cls>\w+)\.(?P=cls)", s[0])):
- _str += "void "
- if s[0].startswith("cv."):
- _str += s[0][3:].replace(".", "::")
- else:
- _str += s[0].replace(".", "::")
- if len(s[3]) == 0:
- _str += "()"
- else:
- _str += "( "
- for idx, arg in enumerate(s[3]):
- if idx > 0:
- _str += ", "
- argtype = re.sub(r"\bcv::", "", arg[0])
- argtype = re.sub(r"\s+(\*|&)$", "\\1", arg[0])
- bidx = argtype.find('[')
- if bidx < 0:
- _str += argtype
- else:
- _str += argtype[:bidx]
- _str += " "
- if arg[1]:
- _str += arg[1]
- else:
- _str += "arg" + str(idx)
- if bidx >= 0:
- _str += argtype[bidx:]
- if arg[2]:
- _str += "=" + re.sub(r"\bcv::", "", arg[2])
- _str += " )"
- if "/C" in s[2]:
- _str += " const"
- if "/A" in s[2]:
- _str += " = 0"
- return _str
-
-
-def logerror(code, message, doc = None):
- if code in errors_disabled:
- return
- if doc:
- print doc["file"] + ":" + str(doc["line"]),
- print "error %03d: %s" % (code, message)
- #print
-
-def process_module(module, path):
- hppparser = hp.CppHeaderParser()
- rstparser = rp.RstParser(hppparser)
-
- rstparser.parse(module, path)
- rst = rstparser.definitions
-
- hdrlist = []
- for root, dirs, files in os.walk(os.path.join(path, "include")):
- for filename in fnmatch.filter(files, "*.h*"):
- hdrlist.append(os.path.join(root, filename))
-
- if module == "cuda":
- hdrlist.append(os.path.join(path, "..", "core", "include", "opencv2", "core", "cuda_types.hpp"))
- hdrlist.append(os.path.join(path, "..", "core", "include", "opencv2", "core", "cuda.hpp"))
- hdrlist.append(os.path.join(path, "..", "core", "include", "opencv2", "core", "cuda_stream_accessor.hpp"))
-
- decls = []
- for hname in hdrlist:
- if not "ts_gtest.h" in hname:
- decls += hppparser.parse(hname, wmode=False)
-
- funcs = []
- # not really needed to hardcode all the namespaces. Normally all they are collected automatically
- namespaces = ['cv', 'cv.cuda', 'cvflann', 'cvflann.anyimpl', 'cvflann.lsh', 'cv.flann', 'cv.linemod', 'cv.detail', 'cvtest', 'perf', 'cv.videostab']
- classes = []
- structs = []
-
- # collect namespaces and classes/structs
- for decl in decls:
- if decl[0].startswith("const"):
- pass
- elif decl[0].startswith("class") or decl[0].startswith("struct"):
- if decl[0][0] == 'c':
- classes.append(decl)
- else:
- structs.append(decl)
- dotIdx = decl[0].rfind('.')
- if dotIdx > 0:
- namespace = decl[0][decl[0].find(' ')+1:dotIdx]
- if not [c for c in classes if c[0].endswith(namespace)] and not [s for s in structs if s[0].endswith(namespace)]:
- if namespace not in namespaces:
- namespaces.append(namespace)
- else:
- funcs.append(decl)
-
- clsnamespaces = []
- # process classes
- for cl in classes:
- name = cl[0][cl[0].find(' ')+1:]
- if name.find('.') < 0 and not name.startswith("Cv"):
- logerror(ERROR_004_MISSEDNAMESPACE, "class " + name + " from opencv_" + module + " is placed in global namespace but violates C-style naming convention")
- clsnamespaces.append(name)
- if do_python_crosscheck and not name.startswith("cv.") and name.startswith("Cv"):
- clsnamespaces.append("cv." + name[2:])
- if name.startswith("cv."):
- name = name[3:]
- name = name.replace(".", "::")
- sns = synonims.get(name, [])
- sns.append(name)
- for name in sns:
- doc = rst.get(name)
- if not doc:
- #TODO: class is not documented
- continue
- doc[DOCUMENTED_MARKER] = True
- # verify class marker
- if not doc.get("isclass"):
- logerror(ERROR_001_NOTACLASS, "class " + name + " is not marked as \"class\" in documentation", doc)
- else:
- # verify base
- signature = doc.get("class", "")
- signature = signature.replace(" public ", " ")
- namespaceIdx = signature.rfind("::")
-
- signature = ("class " + signature).strip()
- hdrsignature = ("class " + name + " " + cl[1]).replace(".", "::").replace("cv::","").strip()
- if signature != hdrsignature:
- logerror(ERROR_003_INCORRECTBASE, "invalid base class documentation\ndocumented: " + signature + "\nactual: " + hdrsignature, doc)
-
- # process structs
- for st in structs:
- name = st[0][st[0].find(' ')+1:]
- if name.find('.') < 0 and not name.startswith("Cv"):
- logerror(ERROR_004_MISSEDNAMESPACE, "struct " + name + " from opencv_" + module + " is placed in global namespace but violates C-style naming convention")
- clsnamespaces.append(name)
- if name.startswith("cv."):
- name = name[3:]
- name = name.replace(".", "::")
- doc = rst.get(name)
- if not doc:
- #TODO: struct is not documented
- continue
- doc[DOCUMENTED_MARKER] = True
- # verify struct marker
- if not doc.get("isstruct"):
- logerror(ERROR_002_NOTASTRUCT, "struct " + name + " is not marked as \"struct\" in documentation", doc)
- else:
- # verify base
- signature = doc.get("class", "")
- signature = signature.replace(", public ", " ").replace(" public ", " ")
- signature = signature.replace(", protected ", " ").replace(" protected ", " ")
- signature = signature.replace(", private ", " ").replace(" private ", " ")
- signature = ("struct " + signature).strip()
- hdrsignature = (st[0] + " " + st[1]).replace("struct cv.", "struct ").replace(".", "::").strip()
- if signature != hdrsignature:
- logerror(ERROR_003_INCORRECTBASE, "invalid base struct documentation\ndocumented: " + signature + "\nactual: " + hdrsignature, doc)
- print st, doc
-
- # process functions and methods
- flookup = {}
- for fn in funcs:
- name = fn[0]
- parent = None
- namespace = None
- for cl in clsnamespaces:
- if name.startswith(cl + "."):
- if cl.startswith(parent or ""):
- parent = cl
- if parent:
- name = name[len(parent) + 1:]
- for nm in namespaces:
- if parent.startswith(nm + "."):
- if nm.startswith(namespace or ""):
- namespace = nm
- if namespace:
- parent = parent[len(namespace) + 1:]
- else:
- for nm in namespaces:
- if name.startswith(nm + "."):
- if nm.startswith(namespace or ""):
- namespace = nm
- if namespace:
- name = name[len(namespace) + 1:]
- #print namespace, parent, name, fn[0]
- if not namespace and not parent and not name.startswith("cv") and not name.startswith("icv") and not name.startswith("CV_"):
- logerror(ERROR_004_MISSEDNAMESPACE, "function " + name + " from opencv_" + module + " is placed in global namespace but violates C-style naming convention")
- else:
- fdescr = (namespace, parent, name, fn)
- flookup_entry = flookup.get(fn[0], [])
- flookup_entry.append(fdescr)
- flookup[fn[0]] = flookup_entry
-
- if do_python_crosscheck:
- pyclsnamespaces = ["cv." + x[3:].replace(".", "_") for x in clsnamespaces]
- for name, doc in rst.iteritems():
- decls = doc.get("decls")
- if not decls:
- continue
- for signature in decls:
- if signature[0] == "Python1":
- pname = signature[1][:signature[1].find('(')]
- try:
- fn = getattr(cv2.cv, pname[3:])
- docstr = "cv." + fn.__doc__
- except AttributeError:
- logerror(ERROR_005_MISSINGPYFUNC, "could not load documented function: cv2." + pname, doc)
- continue
- docstring = docstr
- sign = signature[1]
- signature.append(DOCUMENTED_MARKER)
- # convert old signature to pydoc style
- if docstring.endswith("*"):
- docstring = docstring[:-1]
- s = None
- while s != sign:
- s = sign
- sign = re.sub(r"^(.*\(.*)\(.*?\)(.*\) *->)", "\\1_\\2", sign)
- s = None
- while s != sign:
- s = sign
- sign = re.sub(r"\s*,\s*([^,]+)\s*=\s*[^,]+\s*(( \[.*\])?)\)", " [, \\1\\2])", sign)
- sign = re.sub(r"\(\s*([^,]+)\s*=\s*[^,]+\s*(( \[.*\])?)\)", "([\\1\\2])", sign)
-
- sign = re.sub(r"\)\s*->\s*", ") -> ", sign)
- sign = sign.replace("-> convexHull", "-> CvSeq")
- sign = sign.replace("-> lines", "-> CvSeq")
- sign = sign.replace("-> boundingRects", "-> CvSeq")
- sign = sign.replace("-> contours", "-> CvSeq")
- sign = sign.replace("-> retval", "-> int")
- sign = sign.replace("-> detectedObjects", "-> CvSeqOfCvAvgComp")
-
- def retvalRplace(match):
- m = match.group(1)
- m = m.replace("CvScalar", "scalar")
- m = m.replace("CvMemStorage", "memstorage")
- m = m.replace("ROIplImage", "image")
- m = m.replace("IplImage", "image")
- m = m.replace("ROCvMat", "mat")
- m = m.replace("CvMat", "mat")
- m = m.replace("double", "float")
- m = m.replace("CvSubdiv2DPoint", "point")
- m = m.replace("CvBox2D", "Box2D")
- m = m.replace("IplConvKernel", "kernel")
- m = m.replace("CvHistogram", "hist")
- m = m.replace("CvSize", "width,height")
- m = m.replace("cvmatnd", "matND")
- m = m.replace("CvSeqOfCvConvexityDefect", "convexityDefects")
- mm = m.split(',')
- if len(mm) > 1:
- return "(" + ", ".join(mm) + ")"
- else:
- return m
-
- docstring = re.sub(r"(?<=-> )(.*)$", retvalRplace, docstring)
- docstring = docstring.replace("( [, ", "([")
-
- if sign != docstring:
- logerror(ERROR_006_INVALIDPYOLDDOC, "old-style documentation differs from pydoc\npydoc: " + docstring + "\nfixup: " + sign + "\ncvdoc: " + signature[1], doc)
- elif signature[0] == "Python2":
- pname = signature[1][4:signature[1].find('(')]
- cvname = "cv." + pname
- parent = None
- for cl in pyclsnamespaces:
- if cvname.startswith(cl + "."):
- if cl.startswith(parent or ""):
- parent = cl
- try:
- if parent:
- instance, clsname = get_cv2_object(parent)
- fn = getattr(instance, cvname[len(parent)+1:])
- docstr = fn.__doc__
- docprefix = "cv2." + clsname + "."
- else:
- fn = getattr(cv2, pname)
- docstr = fn.__doc__
- docprefix = "cv2."
- except AttributeError:
- if parent:
- logerror(ERROR_005_MISSINGPYFUNC, "could not load documented member of " + parent + " class: cv2." + pname, doc)
- else:
- logerror(ERROR_005_MISSINGPYFUNC, "could not load documented function cv2." + pname, doc)
- signature.append(DOCUMENTED_MARKER) # stop subsequent errors
- continue
- docstrings = [docprefix + s.replace("([, ", "([") for s in docstr.split(" or ")]
- if not signature[1] in docstrings:
- pydocs = "\npydoc: ".join(docstrings)
- logerror(ERROR_007_INVALIDPYDOC, "documentation differs from pydoc\npydoc: " + pydocs + "\ncvdoc: " + signature[1], doc)
- signature.append(DOCUMENTED_MARKER)
-
- # verify C/C++ signatures
- for name, doc in rst.iteritems():
- decls = doc.get("decls")
- if not decls:
- continue
- for signature in decls:
- if signature[0] == "C" or signature[0] == "C++":
- if "template" in (signature[2][1] or ""):
- # TODO find a way to validate templates
- signature.append(DOCUMENTED_MARKER)
- continue
- fd = flookup.get(signature[2][0])
- if not fd:
- if signature[2][0].startswith("cv."):
- fd = flookup.get(signature[2][0][3:])
- if not fd:
- continue
- else:
- signature[2][0] = signature[2][0][3:]
- if signature[0] == "C":
- ffd = [f for f in fd if not f[0] and not f[1]] # filter out C++ stuff
- if not ffd:
- if fd[0][1]:
- logerror(ERROR_008_CFUNCISNOTGLOBAL, "function " + fd[0][2] + " is documented as C function but is actually member of " + fd[0][1] + " class", doc)
- elif fd[0][0]:
- logerror(ERROR_008_CFUNCISNOTGLOBAL, "function " + fd[0][2] + " is documented as C function but is actually placed in " + fd[0][0] + " namespace", doc)
- fd = ffd
- error = None
- for f in fd:
- match, error = compareSignatures(signature[2], f[3])
- if match:
- signature.append(DOCUMENTED_MARKER)
- break
- if signature[-1] != DOCUMENTED_MARKER:
- candidates = "\n\t".join([formatSignature(f[3]) for f in fd])
- logerror(ERROR_009_OVERLOADNOTFOUND, signature[0] + " function " + signature[2][0].replace(".","::") + " is documented but misses in headers (" + error + ").\nDocumented as:\n\t" + signature[1] + "\nCandidates are:\n\t" + candidates, doc)
- signature.append(DOCUMENTED_MARKER) # to stop subsequent error on this function
-
- # verify that all signatures was found in the library headers
- for name, doc in rst.iteritems():
- # if doc.get(DOCUMENTED_MARKER, False):
- # continue # this class/struct was found
- if not doc.get(DOCUMENTED_MARKER, False) and (doc.get("isclass", False) or doc.get("isstruct", False)):
- if name in doc_signatures_whitelist:
- continue
- logerror(ERROR_010_UNKNOWNCLASS, "class/struct " + name + " is mentioned in documentation but is not found in OpenCV headers", doc)
- for d in doc.get("decls", []):
- if d[-1] != DOCUMENTED_MARKER:
- if d[0] == "C" or d[0] =="C++" or (do_python_crosscheck and d[0].startswith("Python")):
- if d[0][0] == 'C':
- sname = d[2][0][3:].replace(".", "::")
- if sname in defines:
- #TODO: need to find a way to verify #define's
- continue
- else:
- sname = d[1][:d[1].find("(")]
- prefixes = [x for x in doc_signatures_whitelist if sname.startswith(x)]
- if prefixes:
- # TODO: member of template class
- continue
- logerror(ERROR_011_UNKNOWNFUNC, d[0] + " function " + sname + " is documented but is not found in OpenCV headers. It is documented as:\n\t" + d[1], doc)
- # end of process_module
-
-if __name__ == "__main__":
- if len(sys.argv) < 2:
- print "Usage:\n", os.path.basename(sys.argv[0]), " <module path>"
- exit(0)
-
- modules = sys.argv[1:]
- if modules[0] == "all":
- modules = allmodules
-
- for module in modules:
- selfpath = os.path.dirname(os.path.abspath(sys.argv[0]))
- module_path = os.path.join(selfpath, "..", "modules", module)
-
- if not os.path.isdir(module_path):
- print "Module \"" + module + "\" could not be found."
- exit(1)
-
- process_module(module, module_path)
+++ /dev/null
-# this is a list of functions, classes and methods
-# that are not supposed to be documented in the near future,
-# to make the output of check_docs.py script more sensible.
-#
-# Syntax:
-# every line starting with # is a comment
-# there can be empty lines
-# each line includes either a class name (including all the necessary namespaces),
-# or a function/method name
-# or a full declaration of a function/method
-# if a class name is in the whitelist, all the methods are considered "white-listed" too
-# if a method/function name is listed, then all the overload variants are "white-listed".
-# that is, to white list a particular overloaded variant of a function/method you need to put
-# full declaration into the file
-#
-
-######################################### core #####################################
-cv::Mat::MSize
-cv::Mat::MStep
-cv::MatConstIterator
-cv::NAryMatIterator
-cv::Algorithm
-cv::_InputArray
-cv::_OutputArray
-
-######################################## imgproc ###################################
-CvLSHOperations
-cv::FilterEngine
-cv::BaseFilter
-cv::BaseRowFilter
-cv::BaseColumnFilter
-cv::Moments
-
-###################################### features2d###################################
-cv::BOWKMeansTrainer::cluster
-cv::BOWTrainer::BOWTrainer
-cv::BOWTrainer::clear
-cv::AdjusterAdapter::clone
-
-cv::MSER::MSER
-cv::StarDetector::StarDetector
-cv::SIFT::CommonParams::CommonParams
-cv::SIFT::SIFT
-cv::SURF::SURF
-cv::SimpleBlobDetector::Params::Params
-
-cv::FastFeatureDetector::read
-cv::MserFeatureDetector::read
-cv::StarFeatureDetector::read
-cv::SurfFeatureDetector::read
-cv::SiftFeatureDetector::read
-cv::GoodFeaturesToTrackDetector::read
-cv::OrbFeatureDetector::read
-
-cv::FastFeatureDetector::write
-cv::MserFeatureDetector::write
-cv::StarFeatureDetector::write
-cv::SurfFeatureDetector::write
-cv::SiftFeatureDetector::write
-cv::GoodFeaturesToTrackDetector::write
-cv::OrbFeatureDetector::write
-
-cv::DynamicAdaptedFeatureDetector::empty
-cv::GridAdaptedFeatureDetector::empty
-cv::PyramidAdaptedFeatureDetector::empty
-
-cv::BriefDescriptorExtractor::descriptorSize
-cv::SurfDescriptorExtractor::descriptorSize
-cv::SiftDescriptorExtractor::descriptorSize
-cv::OpponentColorDescriptorExtractor::descriptorSize
-cv::OrbDescriptorExtractor::descriptorSize
-
-cv::BriefDescriptorExtractor::descriptorType
-cv::SurfDescriptorExtractor::descriptorType
-cv::SiftDescriptorExtractor::descriptorType
-cv::OpponentColorDescriptorExtractor::descriptorType
-cv::OrbDescriptorExtractor::descriptorType
-
-cv::SurfDescriptorExtractor::read
-cv::SiftDescriptorExtractor::read
-cv::OpponentColorDescriptorExtractor::read
-cv::OrbDescriptorExtractor::read
-
-cv::SurfDescriptorExtractor::write
-cv::SiftDescriptorExtractor::write
-cv::OpponentColorDescriptorExtractor::write
-cv::OrbDescriptorExtractor::write
-
-cv::OpponentColorDescriptorExtractor::empty
-
-cv::FlannBasedMatcher::train
-
-cv::FlannBasedMatcher::clear
-
-cv::FlannBasedMatcher::clone
-
-cv::FlannBasedMatcher::isMaskSupported
-
-
-cv::GenericDescriptorMatcher::GenericDescriptorMatcher
-
-cv::VectorDescriptorMatcher::clear
-cv::FernDescriptorMatcher::clear
-cv::OneWayDescriptorMatcher::clear
-
-cv::VectorDescriptorMatcher::empty
-cv::FernDescriptorMatcher::empty
-cv::OneWayDescriptorMatcher::empty
-
-cv::OneWayDescriptorMatcher::read
-
-cv::VectorDescriptorMatcher::isMaskSupported
-cv::FernDescriptorMatcher::isMaskSupported
-cv::OneWayDescriptorMatcher::isMaskSupported
-
-cv::VectorDescriptorMatcher::train
-cv::FernDescriptorMatcher::train
-cv::OneWayDescriptorMatcher::train
-
-cv::VectorDescriptorMatcher::read
-cv::FernDescriptorMatcher::read
-
-cv::VectorDescriptorMatcher::write
-cv::FernDescriptorMatcher::write
-cv::OneWayDescriptorMatcher::write
-
-
-
-cv::FastAdjuster::good
-cv::StarAdjuster::good
-cv::SurfAdjuster::good
-cv::FastAdjuster::tooFew
-cv::StarAdjuster::tooFew
-cv::SurfAdjuster::tooFew
-cv::FastAdjuster::tooMany
-cv::StarAdjuster::tooMany
-cv::SurfAdjuster::tooMany
-cv::FastAdjuster::clone
-cv::StarAdjuster::clone
-cv::SurfAdjuster::clone
-
-######################################## calib3d ###################################
-CvLevMarq
-Mat cv::findFundamentalMat( InputArray points1, InputArray points2, OutputArray mask, int method=FM_RANSAC, double param1=3., double param2=0.99)
-Mat findHomography( InputArray srcPoints, InputArray dstPoints, OutputArray mask, int method=0, double ransacReprojThreshold=3);
-
-########################################## ml ######################################
-CvBoostTree
-CvForestTree
-CvSVMKernel
-CvSVMSolver
-CvDTreeTrainData
-CvERTreeTrainData
-CvKNearest::CvKNearest
-CvKNearest::clear
-CvDTreeNode::get_num_valid
-CvDTreeNode::set_num_valid
-CvDTree::CvDTree
-CvDTree::clear
-CvDTree::read
-CvDTree::write
-CvEM::CvEM
-CvEM::clear
-CvEM::read
-CvEM::write
-CvSVM::CvSVM
-CvSVM::clear
-CvSVM::read
-CvSVM::write
-CvMLData::CvMLData
-CvRTrees::CvRTrees
-CvRTrees::clear
-CvRTrees::read
-CvRTrees::write
-CvBoost::CvBoost
-CvBoost::clear
-CvBoost::read
-CvBoost::write
-CvGBTrees::CvGBTrees
-CvGBTrees::clear
-CvGBTrees::read
-CvGBTrees::write
-CvNormalBayesClassifier::CvNormalBayerClassifier
-CvNormalBayesClassifier::clear
-CvNormalBayesClassifier::read
-CvNormalBayesClassifier::write
-CvANN_MLP::CvANN_MLP
-CvANN_MLP::clear
-CvANN_MLP::read
-CvANN_MLP::write
-CvTrainTestSplit
-cvParamLattice
-cvDefaultParamLattice
+++ /dev/null
-#!/usr/bin/env python
-
-# -*- coding: utf-8 -*-
-#
-# opencvstd documentation build configuration file, created by
-# sphinx-quickstart on Mon Feb 14 00:30:43 2011.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-import sys, os, re
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('.'))
-
-# -- General configuration -----------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.pngmath', 'sphinx.ext.ifconfig', 'sphinx.ext.todo', 'sphinx.ext.extlinks', 'ocv', 'sphinx.ext.doctest']
-
-have_plantuml_ext = False
-if tags.has('plantuml'):
- try:
- import sphinxcontrib.plantuml
- extensions.append("sphinxcontrib.plantuml")
- have_plantuml_ext = True
- except ImportError:
- print "No module sphinxcontrib.plantuml found, sphinx will not render UML diagrams"
-
-doctest_test_doctest_blocks = 'block'
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'OpenCV'
-copyright = u'2011-2014, opencv dev team'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-
-version_file = open("../modules/core/include/opencv2/core/version.hpp", "rt").read()
-version_major = re.search("^W*#\W*define\W+CV_VERSION_MAJOR\W+(\d+)\W*$", version_file, re.MULTILINE).group(1)
-version_minor = re.search("^W*#\W*define\W+CV_VERSION_MINOR\W+(\d+)\W*$", version_file, re.MULTILINE).group(1)
-version_patch = re.search("^W*#\W*define\W+CV_VERSION_REVISION\W+(\d+)\W*$", version_file, re.MULTILINE).group(1)
-version_status = re.search("^W*#\W*define\W+CV_VERSION_STATUS\W+\"(.*?)\"\W*$", version_file, re.MULTILINE).group(1)
-
-# The short X.Y version.
-version = version_major + '.' + version_minor
-# The full version, including alpha/beta/rc tags.
-release = version_major + '.' + version_minor + '.' + version_patch + version_status
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['doc/tutorials/definitions']
-
-if not have_plantuml_ext:
- exclude_patterns.append('**/uml/*')
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-todo_include_todos=True
-
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages. See the documentation for
-# a list of builtin themes.
-html_theme = 'sphinxdoc'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['_themes']
-
-# The name for this set of Sphinx documents. If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-html_logo = 'opencv-logo2.png'
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it. The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'opencv'
-
-# OpenCV docs use some custom LaTeX macros in the formula. Make sure we include the definitions
-pngmath_latex_preamble = r"""
-\usepackage{euler}\usepackage[usenames,dvipsnames]{color}\usepackage{amssymb}\usepackage{amsmath}\usepackage{bbm}\usepackage{colortbl}
-\newcommand{\matTT}[9]{
-\[
-\left|\begin{array}{ccc}
- #1 & #2 & #3\\
- #4 & #5 & #6\\
- #7 & #8 & #9
-\end{array}\right|
-\]
-}
-
-\newcommand{\fork}[4]{
- \left\{
- \begin{array}{l l}
- #1 & \mbox{#2}\\
- #3 & \mbox{#4}\\
- \end{array} \right.}
-\newcommand{\forkthree}[6]{
- \left\{
- \begin{array}{l l}
- #1 & \mbox{#2}\\
- #3 & \mbox{#4}\\
- #5 & \mbox{#6}\\
- \end{array} \right.}
-
-\newcommand{\vecthree}[3]{
-\begin{bmatrix}
- #1\\
- #2\\
- #3
-\end{bmatrix}
-}
-
-\newcommand{\vecthreethree}[9]{
-\begin{bmatrix}
- #1 & #2 & #3\\
- #4 & #5 & #6\\
- #7 & #8 & #9
-\end{bmatrix}
-}
-"""
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
- ('modules/refman', 'opencv2refman.tex', u'The OpenCV Reference Manual',
- u'', 'manual'),
- ('doc/user_guide/user_guide', 'opencv_user.tex', u'The OpenCV User Guide',
- u'', 'manual'),
- ('doc/tutorials/tutorials', 'opencv_tutorials.tex', u'The OpenCV Tutorials',
- u'', 'manual'),
- ('platforms/android/refman', 'opencv2manager.tex', u'The OpenCV Manager Manual',
- u'', 'manual'),
-]
-
-preamble ="""
-\usepackage{euler}
-\usepackage[scaled=0.85]{beramono}
-\usepackage{mymath}\usepackage{amssymb}\usepackage{amsmath}\usepackage{bbm}\setcounter{secnumdepth}{1}
-\usepackage{colortbl}
-\usepackage{enumitem}
-\setlist{labelsep=1ex}
-"""
-
-latex_elements = {'preamble': preamble}
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-latex_domain_indices = True
-
-
-# -- Options for manual page output --------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
- ('index', 'opencv', u'The OpenCV Reference Manual',
- [u'admin@opencv.org'], 1)
-]
-
-# ---- External links for tutorials -----------------
-extlinks = {
- 'basicstructures' : ('http://docs.opencv.org/modules/core/doc/basic_structures.html#%s', None),
- 'oldbasicstructures' : ('http://docs.opencv.org/modules/core/doc/old_basic_structures.html#%s', None),
- 'readwriteimage' : ('http://docs.opencv.org/modules/imgcodecs/doc/reading_and_writing_images.html#%s', None),
- 'readwritevideo' : ('http://docs.opencv.org/modules/videoio/doc/reading_and_writing_video.html#%s', None),
- 'operationsonarrays' : ('http://docs.opencv.org/modules/core/doc/operations_on_arrays.html#%s', None),
- 'utilitysystemfunctions' : ('http://docs.opencv.org/modules/core/doc/utility_and_system_functions_and_macros.html#%s', None),
- 'imgprocfilter' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html#%s', None),
- 'svms' : ('http://docs.opencv.org/modules/ml/doc/support_vector_machines.html#%s', None),
- 'drawingfunc' : ('http://docs.opencv.org/modules/core/doc/drawing_functions.html#%s', None),
- 'xmlymlpers' : ('http://docs.opencv.org/modules/core/doc/xml_yaml_persistence.html#%s', None),
- 'rwimg' : ('http://docs.opencv.org/modules/imgcodecs/doc/reading_and_writing_images.html#%s', None),
- 'hgvideo' : ('http://docs.opencv.org/modules/videoio/doc/reading_and_writing_video.html#%s', None),
- 'gpuinit' : ('http://docs.opencv.org/modules/gpu/doc/initalization_and_information.html#%s', None),
- 'gpudatastructure' : ('http://docs.opencv.org/modules/gpu/doc/data_structures.html#%s', None),
- 'gpuopmatrices' : ('http://docs.opencv.org/modules/gpu/doc/operations_on_matrices.html#%s', None),
- 'gpuperelement' : ('http://docs.opencv.org/modules/gpu/doc/per_element_operations.html#%s', None),
- 'gpuimgproc' : ('http://docs.opencv.org/modules/gpu/doc/image_processing.html#%s', None),
- 'gpumatrixreduct' : ('http://docs.opencv.org/modules/gpu/doc/matrix_reductions.html#%s', None),
- 'filtering' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html#%s', None),
- 'flann' : ('http://docs.opencv.org/modules/flann/doc/flann_fast_approximate_nearest_neighbor_search.html#%s', None ),
- 'calib3d' : ('http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html#%s', None ),
- 'feature2d' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html#%s', None ),
- 'imgproc_geometric' : ('http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html#%s', None ),
- 'miscellaneous_transformations' : ('http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html#%s', None),
- 'user_interface' : ('http://docs.opencv.org/modules/highgui/doc/user_interface.html#%s', None),
- 'video' : ('http://docs.opencv.org/modules/video/doc/motion_analysis_and_object_tracking.html#%s', None),
-
- # 'opencv_group' : ('http://answers.opencv.org/%s', None),
- 'opencv_qa' : ('http://answers.opencv.org/%s', None),
- 'how_to_contribute' : ('http://code.opencv.org/projects/opencv/wiki/How_to_contribute/%s', None),
-
- 'cvt_color' : ('http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html?highlight=cvtcolor#cvtcolor%s', None),
- 'imread' : ('http://docs.opencv.org/modules/imgcodecs/doc/reading_and_writing_images.html?highlight=imread#imread%s', None),
- 'imwrite' : ('http://docs.opencv.org/modules/imgcodecs/doc/reading_and_writing_images.html?highlight=imwrite#imwrite%s', None),
- 'imshow' : ('http://docs.opencv.org/modules/highgui/doc/user_interface.html?highlight=imshow#imshow%s', None),
- 'named_window' : ('http://docs.opencv.org/modules/highgui/doc/user_interface.html?highlight=namedwindow#namedwindow%s', None),
- 'wait_key' : ('http://docs.opencv.org/modules/highgui/doc/user_interface.html?highlight=waitkey#waitkey%s', None),
- 'add_weighted' : ('http://docs.opencv.org/modules/core/doc/operations_on_arrays.html?highlight=addweighted#addweighted%s', None),
- 'saturate_cast' : ('http://docs.opencv.org/modules/core/doc/utility_and_system_functions_and_macros.html?highlight=saturate_cast#saturate-cast%s', None),
- 'mat_zeros' : ('http://docs.opencv.org/modules/core/doc/basic_structures.html?highlight=zeros#mat-zeros%s', None),
- 'convert_to' : ('http://docs.opencv.org/modules/core/doc/basic_structures.html#mat-convertto%s', None),
- 'create_trackbar' : ('http://docs.opencv.org/modules/highgui/doc/user_interface.html?highlight=createtrackbar#createtrackbar%s', None),
- 'point' : ('http://docs.opencv.org/modules/core/doc/basic_structures.html#point%s', None),
- 'scalar' : ('http://docs.opencv.org/modules/core/doc/basic_structures.html#scalar%s', None),
- 'line' : ('http://docs.opencv.org/modules/core/doc/drawing_functions.html#line%s', None),
- 'ellipse' : ('http://docs.opencv.org/modules/core/doc/drawing_functions.html#ellipse%s', None),
- 'rectangle' : ('http://docs.opencv.org/modules/core/doc/drawing_functions.html#rectangle%s', None),
- 'circle' : ('http://docs.opencv.org/modules/core/doc/drawing_functions.html#circle%s', None),
- 'fill_poly' : ('http://docs.opencv.org/modules/core/doc/drawing_functions.html#fillpoly%s', None),
- 'rng' : ('http://docs.opencv.org/modules/core/doc/operations_on_arrays.html?highlight=rng#rng%s', None),
- 'put_text' : ('http://docs.opencv.org/modules/core/doc/drawing_functions.html#puttext%s', None),
- 'gaussian_blur' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=gaussianblur#gaussianblur%s', None),
- 'blur' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=blur#blur%s', None),
- 'median_blur' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=medianblur#medianblur%s', None),
- 'bilateral_filter' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=bilateralfilter#bilateralfilter%s', None),
- 'erode' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=erode#erode%s', None),
- 'dilate' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=dilate#dilate%s', None),
- 'get_structuring_element' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=getstructuringelement#getstructuringelement%s', None),
- 'flood_fill' : ( 'http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html?highlight=floodfill#floodfill%s', None),
- 'morphology_ex' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=morphologyex#morphologyex%s', None),
- 'pyr_down' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=pyrdown#pyrdown%s', None),
- 'pyr_up' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=pyrup#pyrup%s', None),
- 'resize' : ('http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html?highlight=resize#resize%s', None),
- 'threshold' : ('http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html?highlight=threshold#threshold%s', None),
- 'filter2d' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=filter2d#filter2d%s', None),
- 'copy_make_border' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=copymakeborder#copymakeborder%s', None),
- 'sobel' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=sobel#sobel%s', None),
- 'scharr' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=scharr#scharr%s', None),
- 'laplacian' : ('http://docs.opencv.org/modules/imgproc/doc/filtering.html?highlight=laplacian#laplacian%s', None),
- 'canny' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html?highlight=canny#canny%s', None),
- 'copy_to' : ('http://docs.opencv.org/modules/core/doc/basic_structures.html?highlight=copyto#mat-copyto%s', None),
- 'hough_lines' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html?highlight=houghlines#houghlines%s', None),
- 'hough_lines_p' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html?highlight=houghlinesp#houghlinesp%s', None),
- 'hough_circles' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html?highlight=houghcircles#houghcircles%s', None),
- 'remap' : ('http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html?highlight=remap#remap%s', None),
- 'warp_affine' : ('http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html?highlight=warpaffine#warpaffine%s' , None),
- 'get_rotation_matrix_2d' : ('http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html?highlight=getrotationmatrix2d#getrotationmatrix2d%s', None),
- 'get_affine_transform' : ('http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html?highlight=getaffinetransform#getaffinetransform%s', None),
- 'equalize_hist' : ('http://docs.opencv.org/modules/imgproc/doc/histograms.html?highlight=equalizehist#equalizehist%s', None),
- 'split' : ('http://docs.opencv.org/modules/core/doc/operations_on_arrays.html?highlight=split#split%s', None),
- 'calc_hist' : ('http://docs.opencv.org/modules/imgproc/doc/histograms.html?highlight=calchist#calchist%s', None),
- 'normalize' : ('http://docs.opencv.org/modules/core/doc/operations_on_arrays.html?highlight=normalize#normalize%s', None),
- 'match_template' : ('http://docs.opencv.org/modules/imgproc/doc/object_detection.html?highlight=matchtemplate#matchtemplate%s', None),
- 'min_max_loc' : ('http://docs.opencv.org/modules/core/doc/operations_on_arrays.html?highlight=minmaxloc#minmaxloc%s', None),
- 'mix_channels' : ( 'http://docs.opencv.org/modules/core/doc/operations_on_arrays.html?highlight=mixchannels#mixchannels%s', None),
- 'calc_back_project' : ('http://docs.opencv.org/modules/imgproc/doc/histograms.html?highlight=calcbackproject#calcbackproject%s', None),
- 'compare_hist' : ('http://docs.opencv.org/modules/imgproc/doc/histograms.html?highlight=comparehist#comparehist%s', None),
- 'corner_harris' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html?highlight=cornerharris#cornerharris%s', None),
- 'good_features_to_track' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html?highlight=goodfeaturestotrack#goodfeaturestotrack%s', None),
- 'corner_min_eigenval' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html?highlight=cornermineigenval#cornermineigenval%s', None),
- 'corner_eigenvals_and_vecs' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html?highlight=cornereigenvalsandvecs#cornereigenvalsandvecs%s', None),
- 'corner_sub_pix' : ('http://docs.opencv.org/modules/imgproc/doc/feature_detection.html?highlight=cornersubpix#cornersubpix%s', None),
- 'find_contours' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=findcontours#findcontours%s', None),
- 'convex_hull' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=convexhull#convexhull%s', None),
- 'draw_contours' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=drawcontours#drawcontours%s', None),
- 'bounding_rect' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=boundingrect#boundingrect%s', None),
- 'min_enclosing_circle' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=minenclosingcircle#minenclosingcircle%s', None),
- 'min_area_rect' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=minarearect#minarearect%s', None),
- 'fit_ellipse' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=fitellipse#fitellipse%s', None),
- 'moments' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=moments#moments%s', None),
- 'contour_area' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=contourarea#contourarea%s', None),
- 'arc_length' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=arclength#arclength%s', None),
- 'point_polygon_test' : ('http://docs.opencv.org/modules/imgproc/doc/structural_analysis_and_shape_descriptors.html?highlight=pointpolygontest#pointpolygontest%s', None),
- 'feature_detection_and_description' : ('http://docs.opencv.org/modules/features2d/doc/feature_detection_and_description.html#%s', None),
- 'feature_detector' : ( 'http://docs.opencv.org/modules/features2d/doc/common_interfaces_of_feature_detectors.html?highlight=featuredetector#FeatureDetector%s', None),
- 'feature_detector_detect' : ('http://docs.opencv.org/modules/features2d/doc/common_interfaces_of_feature_detectors.html?highlight=detect#featuredetector-detect%s', None ),
- 'surf_feature_detector' : ('http://docs.opencv.org/modules/features2d/doc/common_interfaces_of_feature_detectors.html?highlight=surffeaturedetector#surffeaturedetector%s', None ),
- 'draw_keypoints' : ('http://docs.opencv.org/modules/features2d/doc/drawing_function_of_keypoints_and_matches.html?highlight=drawkeypoints#drawkeypoints%s', None ),
- 'descriptor_extractor': ( 'http://docs.opencv.org/modules/features2d/doc/common_interfaces_of_descriptor_extractors.html?highlight=descriptorextractor#descriptorextractor%s', None ),
- 'descriptor_extractor_compute' : ( 'http://docs.opencv.org/modules/features2d/doc/common_interfaces_of_descriptor_extractors.html?highlight=compute#descriptorextractor-compute%s', None ),
- 'surf_descriptor_extractor' : ( 'http://docs.opencv.org/modules/features2d/doc/common_interfaces_of_descriptor_extractors.html?highlight=surfdescriptorextractor#surfdescriptorextractor%s', None ),
- 'draw_matches' : ( 'http://docs.opencv.org/modules/features2d/doc/drawing_function_of_keypoints_and_matches.html?highlight=drawmatches#drawmatches%s', None ),
- 'find_homography' : ('http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html?highlight=findhomography#findhomography%s', None),
- 'perspective_transform' : ('http://docs.opencv.org/modules/core/doc/operations_on_arrays.html?highlight=perspectivetransform#perspectivetransform%s', None ),
- 'flann_based_matcher' : ('http://docs.opencv.org/modules/features2d/doc/common_interfaces_of_descriptor_matchers.html?highlight=flannbasedmatcher#flannbasedmatcher%s', None),
- 'brute_force_matcher' : ('http://docs.opencv.org/modules/features2d/doc/common_interfaces_of_descriptor_matchers.html?highlight=bruteforcematcher#bruteforcematcher%s', None ),
- 'cascade_classifier' : ('http://docs.opencv.org/modules/objdetect/doc/cascade_classification.html?highlight=cascadeclassifier#cascadeclassifier%s', None ),
- 'cascade_classifier_load' : ('http://docs.opencv.org/modules/objdetect/doc/cascade_classification.html?highlight=load#cascadeclassifier-load%s', None ),
- 'cascade_classifier_detect_multiscale' : ('http://docs.opencv.org/modules/objdetect/doc/cascade_classification.html?highlight=detectmultiscale#cascadeclassifier-detectmultiscale%s', None ),
- 'background_subtractor' : ('http://docs.opencv.org/modules/video/doc/motion_analysis_and_object_tracking.html?highlight=backgroundsubtractor#backgroundsubtractor%s', None),
- 'background_subtractor_mog' : ('http://docs.opencv.org/modules/video/doc/motion_analysis_and_object_tracking.html?highlight=backgroundsubtractorMOG#backgroundsubtractormog%s', None),
- 'background_subtractor_mog_two' : ('http://docs.opencv.org/modules/video/doc/motion_analysis_and_object_tracking.html?highlight=backgroundsubtractorMOG2#backgroundsubtractormog2%s', None),
- 'video_capture' : ('http://docs.opencv.org/modules/videoio/doc/reading_and_writing_video.html?highlight=videocapture#videocapture%s', None),
- 'ippa_convert': ('http://docs.opencv.org/modules/core/doc/ipp_async_converters.html#%s', None),
- 'ptr':('http://docs.opencv.org/modules/core/doc/basic_structures.html?highlight=Ptr#Ptr%s', None)
- }
+++ /dev/null
-<html>
-
-<head>
-<meta http-equiv=Content-Type content="text/html; charset=windows-1251">
-<meta name=Generator content="Microsoft Word 11 (filtered)">
-<title>Object Detection Using Haar-like Features with Cascade of Boosted
-Classifiers</title>
-<style>
-<!--
- /* Style Definitions */
- p.MsoNormal, li.MsoNormal, div.MsoNormal
- {margin:0in;
- margin-bottom:.0001pt;
- text-align:justify;
- font-size:12.0pt;
- font-family:"Times New Roman";}
-h1
- {margin-top:12.0pt;
- margin-right:0in;
- margin-bottom:3.0pt;
- margin-left:0in;
- text-align:justify;
- page-break-after:avoid;
- font-size:16.0pt;
- font-family:Arial;}
-h2
- {margin-top:12.0pt;
- margin-right:0in;
- margin-bottom:3.0pt;
- margin-left:0in;
- text-align:justify;
- page-break-after:avoid;
- font-size:14.0pt;
- font-family:Arial;
- font-style:italic;}
-h3
- {margin-top:12.0pt;
- margin-right:0in;
- margin-bottom:3.0pt;
- margin-left:0in;
- text-align:justify;
- page-break-after:avoid;
- font-size:13.0pt;
- font-family:Arial;}
-span.Typewch
- {font-family:"Courier New";
- font-weight:bold;}
-@page Section1
- {size:595.3pt 841.9pt;
- margin:56.7pt 88.0pt 63.2pt 85.05pt;}
-div.Section1
- {page:Section1;}
- /* List Definitions */
- ol
- {margin-bottom:0in;}
-ul
- {margin-bottom:0in;}
--->
-</style>
-
-</head>
-
-<body lang=RU>
-
-<div class=Section1>
-
-<h1><span lang=EN-US>Rapid Object Detection With A Cascade of Boosted
-Classifiers Based on Haar-like Features</span></h1>
-
-<h2><span lang=EN-US>Introduction</span></h2>
-
-<p class=MsoNormal><span lang=EN-US>This document describes how to train and
-use a cascade of boosted classifiers for rapid object detection. A large set of
-over-complete haar-like features provide the basis for the simple individual
-classifiers. Examples of object detection tasks are face, eye and nose
-detection, as well as logo detection. </span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>The sample detection task in this document
-is logo detection, since logo detection does not require the collection of
-large set of registered and carefully marked object samples. Instead we assume
-that from one prototype image, a very large set of derived object examples can
-be derived (</span><span class=Typewch><span lang=EN-US>createsamples</span></span><span
-lang=EN-US> utility, see below).</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>A detailed description of the training/evaluation
-algorithm can be found in [1] and [2].</span></p>
-
-<h2><span lang=EN-US>Samples Creation</span></h2>
-
-<p class=MsoNormal><span lang=EN-US>For training a training samples must be
-collected. There are two sample types: negative samples and positive samples.
-Negative samples correspond to non-object images. Positive samples correspond
-to object images.</span></p>
-
-<h3><span lang=EN-US>Negative Samples</span></h3>
-
-<p class=MsoNormal><span lang=EN-US>Negative samples are taken from arbitrary
-images. These images must not contain object representations. Negative samples
-are passed through background description file. It is a text file in which each
-text line contains the filename (relative to the directory of the description
-file) of negative sample image. This file must be created manually. Note that
-the negative samples and sample images are also called background samples or
-background samples images, and are used interchangeably in this document</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Example of negative description file:</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Directory structure:</span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>/img</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US> img1.jpg</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US> img2.jpg</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>bg.txt</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US> </span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span style='font-family:"Times New Roman";
-font-weight:normal'>File </span></span><span class=Typewch><span lang=EN-US>bg.txt:</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>img/img1.jpg</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>img/img2.jpg</span></span></p>
-
-<h3><span lang=EN-US>Positive Samples</span></h3>
-
-<p class=MsoNormal><span lang=EN-US>Positive samples are created by </span><span
-class=Typewch><span lang=EN-US>createsamples</span></span><span lang=EN-US>
-utility. They may be created from single object image or from collection of
-previously marked up images.<br>
-<br>
-</span></p>
-
-<p class=MsoNormal><span lang=EN-US>The single object image may for instance
-contain a company logo. Then are large set of positive samples are created from
-the given object image by randomly rotating, changing the logo color as well as
-placing the logo on arbitrary background.</span></p>
-
-<p class=MsoNormal><span lang=EN-US>The amount and range of randomness can be
-controlled by command line arguments. </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Command line arguments:</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- vec <vec_file_name></span></span><span
-lang=EN-US> </span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt'><span lang=EN-US>name of the
-output file containing the positive samples for training</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- img <image_file_name></span></span><span
-lang=EN-US> </span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt'><span lang=EN-US>source object
-image (e.g., a company logo)</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- bg <background_file_name></span></span><span
-lang=EN-US> </span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt'><span lang=EN-US>background
-description file; contains a list of images into which randomly distorted
-versions of the object are pasted for positive sample generation</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- num <number_of_samples></span></span><span
-lang=EN-US> </span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt'><span lang=EN-US>number of
-positive samples to generate </span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- bgcolor <background_color></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-lang=EN-US> background color (currently grayscale images are assumed); the
-background color denotes the transparent color. Since there might be
-compression artifacts, the amount of color tolerance can be specified by </span><span
-class=Typewch><span lang=EN-US>\96bgthresh</span></span><span class=Typewch><span
-lang=EN-US style='font-family:Arial;font-weight:normal'>. </span></span><span
-lang=EN-US>All pixels between </span><span class=Typewch><span lang=EN-US>bgcolor-bgthresh</span></span><span
-lang=EN-US> and </span><span class=Typewch><span lang=EN-US>bgcolor+bgthresh</span></span><span
-lang=EN-US> are regarded as transparent.</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- bgthresh <background_color_threshold></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- inv</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-lang=EN-US> if specified, the colors will be inverted</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- randinv</span></span><span lang=EN-US> </span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-lang=EN-US> if specified, the colors will be inverted randomly</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- maxidev <max_intensity_deviation></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US> </span></span><span lang=EN-US>maximal
-intensity deviation of foreground samples pixels</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- maxxangle <max_x_rotation_angle>,</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- maxyangle <max_y_rotation_angle>,</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- maxzangle <max_z_rotation_angle></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-lang=EN-US> maximum rotation angles in radians</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>-show</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-lang=EN-US> if specified, each sample will be shown. Pressing \91Esc\92 will
-continue creation process without samples showing. Useful debugging option.</span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- w <sample_width></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US> </span></span><span class=Typewch><span
-lang=EN-US style='font-family:"Times New Roman";font-weight:normal'>width (in
-pixels) of the output samples</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- h <sample_height></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US> </span></span><span class=Typewch><span
-lang=EN-US style='font-family:"Times New Roman";font-weight:normal'>height (in
-pixels) of the output samples</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US> </span></span></p>
-
-<p class=MsoNormal><span lang=EN-US>For following procedure is used to create a
-sample object instance:</span></p>
-
-<p class=MsoNormal><span lang=EN-US>The source image is rotated random around
-all three axes. The chosen angle is limited my</span><span class=Typewch><span
-lang=EN-US> -max?angle</span></span><span lang=EN-US>. Next pixels of
-intensities in the range of </span><span class=Typewch><span lang=EN-US>[bg_color-bg_color_threshold;
-bg_color+bg_color_threshold]</span></span><span lang=EN-US> are regarded as
-transparent. White noise is added to the intensities of the foreground. If </span><span
-class=Typewch><span lang=EN-US>\96inv</span></span><span lang=EN-US> key is
-specified then foreground pixel intensities are inverted. If </span><span
-class=Typewch><span lang=EN-US>\96randinv</span></span><span lang=EN-US> key is
-specified then it is randomly selected whether for this sample inversion will
-be applied. Finally, the obtained image is placed onto arbitrary background
-from the background description file, resized to the pixel size specified by </span><span
-class=Typewch><span lang=EN-US>\96w</span></span><span lang=EN-US> and </span><span
-class=Typewch><span lang=EN-US>\96h</span></span><span lang=EN-US> and stored
-into the file specified by the </span><span class=Typewch><span lang=EN-US>\96vec</span></span><span
-lang=EN-US> command line parameter.</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Positive samples also may be obtained from
-a collection of previously marked up images. This collection is described by
-text file similar to background description file. Each line of this file
-corresponds to collection image. The first element of the line is image file
-name. It is followed by number of object instances. The following numbers are
-the coordinates of bounding rectangles (x, y, width, height).</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Example of description file:</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Directory structure:</span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>/img</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US> img1.jpg</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US> img2.jpg</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>info.dat</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US> </span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US style='font-family:
-"Times New Roman";font-weight:normal'>File </span></span><span class=Typewch><span
-lang=EN-US>info.dat:</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>img/img1.jpg 1 140
-100 45 45</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>img/img2.jpg 2 100
-200 50 50 50 30 25 25</span></span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Image </span><span class=Typewch><span
-lang=EN-US>img1.jpg</span></span><span lang=EN-US> contains single object
-instance with bounding rectangle (140, 100, 45, 45). Image </span><span
-class=Typewch><span lang=EN-US>img2.jpg</span></span><span lang=EN-US> contains
-two object instances.</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>In order to create positive samples from
-such collection </span><span class=Typewch><span lang=EN-US>\96info</span></span><span
-lang=EN-US> argument should be specified instead of </span><span class=Typewch><span
-lang=EN-US>\96img</span></span><span class=Typewch><span style='font-family:"Times New Roman";
-font-weight:normal'>:</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- info <collection_file_name></span></span><span
-lang=EN-US> </span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt'><span lang=EN-US>description file
-of marked up images collection</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>The scheme of sample creation in this case
-is as follows. The object instances are taken from images. Then they are
-resized to samples size and stored in output file. No distortion is applied, so
-the only affecting arguments are </span><span class=Typewch><span lang=EN-US>\96w</span></span><span
-lang=EN-US>, </span><span class=Typewch><span lang=EN-US>-h</span></span><span
-lang=EN-US>, </span><span class=Typewch><span lang=EN-US>-show</span></span><span
-lang=EN-US> and </span><span class=Typewch><span lang=EN-US>\96num</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'>.</span></span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>createsamples</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> utility may be used for examining samples stored in positive samples
-file. In order to do this only </span></span><span class=Typewch><span
-lang=EN-US>\96vec</span></span><span class=Typewch><span lang=EN-US
-style='font-family:"Times New Roman";font-weight:normal'>, </span></span><span
-class=Typewch><span lang=EN-US>\96w</span></span><span class=Typewch><span
-lang=EN-US style='font-family:"Times New Roman";font-weight:normal'> and </span></span><span
-class=Typewch><span lang=EN-US>\96h</span></span><span class=Typewch><span
-lang=EN-US style='font-family:"Times New Roman";font-weight:normal'> parameters
-should be specified.</span></span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Note that for training, it does not matter
-how positive samples files are generated. So the </span><span class=Typewch><span
-lang=EN-US>createsamples</span></span><span lang=EN-US> utility is only one way
-to collect/create a vector file of positive samples.</span></p>
-
-<h2><span lang=EN-US>Training</span></h2>
-
-<p class=MsoNormal><span lang=EN-US>The next step after samples creation is
-training of classifier. It is performed by the </span><span class=Typewch><span
-lang=EN-US>haartraining</span></span><span lang=EN-US> utility.</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Command line arguments:</span><span
-class=Typewch><span lang=EN-US> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- data <dir_name></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> directory name in which the trained classifier is stored</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- vec <vec_file_name></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> file name of positive sample file (created by </span></span><span
-class=Typewch><span lang=EN-US>trainingsamples</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> utility or by any other means)</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- bg <background_file_name></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> background description file</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- npos <number_of_positive_samples>,</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- nneg <number_of_negative_samples></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> number of positive/negative samples used in training of each
-classifier stage. Reasonable values are npos = 7000 and nneg = 3000.</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- nstages <number_of_stages></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US> </span></span><span class=Typewch><span
-lang=EN-US style='font-family:"Times New Roman";font-weight:normal'>number of
-stages to be trained</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- nsplits <number_of_splits></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> determines the weak classifier used in stage classifiers. If </span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman"'>1</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'>, then a simple stump classifier is used, if </span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman"'>2</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> and more, then CART classifier with </span></span><span class=Typewch><span
-lang=EN-US>number_of_splits</span></span><span class=Typewch><span lang=EN-US
-style='font-family:"Times New Roman";font-weight:normal'> internal (split)
-nodes is used</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- mem <memory_in_MB></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> Available memory in MB for precalculation. The more memory you
-have the faster the training process</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- sym (default),</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- nonsym</span></span><span class=Typewch><span
-lang=EN-US style='font-family:"Times New Roman";font-weight:normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> specifies whether the object class under training has vertical
-symmetry or not. Vertical symmetry speeds up training process. For instance,
-frontal faces show off vertical symmetry</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- minhitrate <min_hit_rate></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> minimal desired hit rate for each stage classifier. Overall hit
-rate may be estimated as </span></span><span class=Typewch><span lang=EN-US>(min_hit_rate^number_of_stages)</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- maxfalsealarm <max_false_alarm_rate></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> maximal desired false alarm rate for each stage classifier. </span></span><span
-class=Typewch><span style='font-family:"Times New Roman";font-weight:normal'>Overall
-false alarm rate may be estimated as</span></span><span class=Typewch><span
-lang=EN-US> (max_false_alarm_rate^number_of_stages)</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- weighttrimming <weight_trimming></span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US> </span></span><span class=Typewch><span
-lang=EN-US style='font-family:"Times New Roman";font-weight:normal'>Specifies
-whether and how much weight trimming should be used. A decent choice is 0.90.</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- eqw</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- mode <BASIC (default) | CORE | ALL></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> selects the type of haar features set used in training. BASIC use
-only upright features, while ALL uses the full set of upright and 45 degree
-rotated feature set. See [1] for more details.</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- w <sample_width>,</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- h <sample_height></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> Size of training samples (in pixels). Must have exactly the same
-values as used during training samples creation (utility </span></span><span
-class=Typewch><span lang=EN-US>trainingsamples</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'>)</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US style='font-family:
-"Times New Roman";font-weight:normal'> </span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US style='font-family:
-"Times New Roman";font-weight:normal'>Note: in order to use multiprocessor
-advantage a compiler that supports OpenMP 1.0 standard should be used.</span></span></p>
-
-<h2><span lang=EN-US>Application</span></h2>
-
-<p class=MsoNormal><span lang=EN-US>OpenCV cvHaarDetectObjects() function (in
-particular haarFaceDetect demo) is used for detection.</span></p>
-
-<h3><span lang=EN-US>Test Samples</span></h3>
-
-<p class=MsoNormal><span lang=EN-US>In order to evaluate the performance of
-trained classifier a collection of marked up images is needed. When such
-collection is not available test samples may be created from single object
-image by </span><span class=Typewch><span lang=EN-US>createsamples</span></span><span
-lang=EN-US> utility. The scheme of test samples creation in this case is
-similar to training samples creation since each test sample is a background
-image into which a randomly distorted and randomly scaled instance of the
-object picture is pasted at a random position. </span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>If both </span><span class=Typewch><span
-lang=EN-US>\96img</span></span><span lang=EN-US> and </span><span class=Typewch><span
-lang=EN-US>\96info</span></span><span lang=EN-US> arguments are specified then
-test samples will be created by </span><span class=Typewch><span lang=EN-US>createsamples</span></span><span
-lang=EN-US> utility. The sample image is arbitrary distorted as it was
-described below, then it is placed at random location to background image and
-stored. The corresponding description line is added to the file specified by </span><span
-class=Typewch><span lang=EN-US>\96info</span></span><span lang=EN-US> argument.</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>The </span><span class=Typewch><span
-lang=EN-US>\96w</span></span><span lang=EN-US> and </span><span class=Typewch><span
-lang=EN-US>\96h</span></span><span lang=EN-US> keys determine the minimal size of
-placed object picture.</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>The test image file name format is as
-follows:</span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US>imageOrderNumber_x_y_width_height.jpg</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'>, where </span></span><span class=Typewch><span lang=EN-US>x</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'>, </span></span><span class=Typewch><span lang=EN-US>y</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'>, </span></span><span class=Typewch><span lang=EN-US>width</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> and </span></span><span class=Typewch><span lang=EN-US>height</span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> are the coordinates of placed object bounding rectangle.</span></span></p>
-
-<p class=MsoNormal><span class=Typewch><span lang=EN-US style='font-family:
-"Times New Roman";font-weight:normal'>Note that you should use a background
-images set different from the background image set used during training.</span></span></p>
-
-<h3><span class=Typewch><span lang=EN-US style='font-family:"Times New Roman"'>Performance
-Evaluation</span></span></h3>
-
-<p class=MsoNormal><span lang=EN-US>In order to evaluate the performance of the
-classifier </span><span class=Typewch><span lang=EN-US>performance</span></span><span
-lang=EN-US> utility may be used. It takes a collection of marked up images,
-applies the classifier and outputs the performance, i.e. number of found
-objects, number of missed objects, number of false alarms and other
-information.</span></p>
-
-<p class=MsoNormal><span lang=EN-US> </span></p>
-
-<p class=MsoNormal><span lang=EN-US>Command line arguments:</span><span
-class=Typewch><span lang=EN-US> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- data <dir_name></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> directory name in which the trained classifier is stored</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- info <collection_file_name></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> file with test samples description</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- maxSizeDiff <max_size_difference></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'>,</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- maxPosDiff <max_position_difference></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> determine the criterion of reference and detected rectangles
-coincidence. Default values are 1.5 and 0.3 respectively.</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- sf <scale_factor></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'>,</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> detection parameter. Default value is 1.2.</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- w <sample_width>,</span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US>- h <sample_height></span></span><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> </span></span></p>
-
-<p class=MsoNormal style='margin-left:17.1pt;text-indent:-17.1pt'><span
-class=Typewch><span lang=EN-US style='font-family:"Times New Roman";font-weight:
-normal'> Size of training samples (in pixels). Must have exactly the same
-values as used during training (utility </span></span><span class=Typewch><span
-lang=EN-US>haartraining</span></span><span class=Typewch><span lang=EN-US
-style='font-family:"Times New Roman";font-weight:normal'>)</span></span></p>
-
-<h2><span lang=EN-US>References</span></h2>
-
-<p class=MsoNormal><span lang=EN-US>[1] Rainer Lienhart and Jochen Maydt. An
-Extended Set of Haar-like Features for Rapid Object Detection. Submitted to
-ICIP2002.</span></p>
-
-<p class=MsoNormal><span lang=EN-US>[2] Alexander Kuranov, Rainer Lienhart, and
-Vadim Pisarevsky. An Empirical Analysis of Boosting Algorithms for Rapid
-Objects With an Extended Set of Haar-like Features. Intel Technical Report
-MRL-TR-July02-01, 2002.</span></p>
-
-</div>
-
-</body>
-
-</html>
+++ /dev/null
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-"""
- ocv domain, a modified copy of sphinx.domains.cpp + shpinx.domains.python.
- The original copyright is below
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- The OpenCV C/C++/Python/Java/... language domain.
-
- :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
- :license: BSD, see LICENSE for details.
-"""
-
-import re
-from copy import deepcopy
-
-from docutils import nodes
-from docutils.parsers.rst import directives
-
-from sphinx import addnodes
-from sphinx.roles import XRefRole
-from sphinx.locale import l_, _
-from sphinx.domains import Domain, ObjType
-from sphinx.directives import ObjectDescription
-from sphinx.util.nodes import make_refnode
-from sphinx.util.compat import Directive
-from sphinx.util.docfields import Field, GroupedField, TypedField
-
-########################### Python Part ###########################
-
-# REs for Python signatures
-py_sig_re = re.compile(
- r'''^ ([\w.]*\.)? # class name(s)
- (\w+) \s* # thing name
- (?: \((.*)\) # optional: arguments
- (?:\s* -> \s* (.*))? # return annotation
- )? $ # and nothing more
- ''', re.VERBOSE)
-
-
-def _pseudo_parse_arglist(signode, arglist):
- """"Parse" a list of arguments separated by commas.
-
- Arguments can have "optional" annotations given by enclosing them in
- brackets. Currently, this will split at any comma, even if it's inside a
- string literal (e.g. default argument value).
- """
- paramlist = addnodes.desc_parameterlist()
- stack = [paramlist]
- try:
- for argument in arglist.split(','):
- argument = argument.strip()
- ends_open = ends_close = 0
- while argument.startswith('['):
- stack.append(addnodes.desc_optional())
- stack[-2] += stack[-1]
- argument = argument[1:].strip()
- while argument.startswith(']'):
- stack.pop()
- argument = argument[1:].strip()
- while argument.endswith(']'):
- ends_close += 1
- argument = argument[:-1].strip()
- while argument.endswith('['):
- ends_open += 1
- argument = argument[:-1].strip()
- if argument:
- stack[-1] += addnodes.desc_parameter(argument, argument, noemph=True)
- while ends_open:
- stack.append(addnodes.desc_optional())
- stack[-2] += stack[-1]
- ends_open -= 1
- while ends_close:
- stack.pop()
- ends_close -= 1
- if len(stack) != 1:
- raise IndexError
- except IndexError:
- # if there are too few or too many elements on the stack, just give up
- # and treat the whole argument list as one argument, discarding the
- # already partially populated paramlist node
- signode += addnodes.desc_parameterlist()
- signode[-1] += addnodes.desc_parameter(arglist, arglist)
- else:
- signode += paramlist
-
-
-class OCVPyObject(ObjectDescription):
- """
- Description of a general Python object.
- """
- option_spec = {
- 'noindex': directives.flag,
- 'module': directives.unchanged,
- }
-
- doc_field_types = [
- TypedField('parameter', label=l_('Parameters'),
- names=('param', 'parameter', 'arg', 'argument',
- 'keyword', 'kwarg', 'kwparam'),
- typerolename='obj', typenames=('paramtype', 'type'),
- can_collapse=True),
- TypedField('variable', label=l_('Variables'), rolename='obj',
- names=('var', 'ivar', 'cvar'),
- typerolename='obj', typenames=('vartype',),
- can_collapse=True),
- GroupedField('exceptions', label=l_('Raises'), rolename='exc',
- names=('raises', 'raise', 'exception', 'except'),
- can_collapse=True),
- Field('returnvalue', label=l_('Returns'), has_arg=False,
- names=('returns', 'return')),
- Field('returntype', label=l_('Return type'), has_arg=False,
- names=('rtype',)),
- ]
-
- def get_signature_prefix(self, sig):
- """
- May return a prefix to put before the object name in the signature.
- """
- return ''
-
- def needs_arglist(self):
- """
- May return true if an empty argument list is to be generated even if
- the document contains none.
- """
- return False
-
- def handle_signature(self, sig, signode):
- """
- Transform a Python signature into RST nodes.
- Returns (fully qualified name of the thing, classname if any).
-
- If inside a class, the current class name is handled intelligently:
- * it is stripped from the displayed name if present
- * it is added to the full name (return value) if not present
- """
- signode += nodes.strong("Python:", "Python:")
- signode += addnodes.desc_name(" ", " ")
- m = py_sig_re.match(sig)
- if m is None:
- raise ValueError
- name_prefix, name, arglist, retann = m.groups()
-
- # determine module and class name (if applicable), as well as full name
- modname = self.options.get(
- 'module', self.env.temp_data.get('py:module'))
- classname = self.env.temp_data.get('py:class')
- if classname:
- add_module = False
- if name_prefix and name_prefix.startswith(classname):
- fullname = name_prefix + name
- # class name is given again in the signature
- name_prefix = name_prefix[len(classname):].lstrip('.')
- elif name_prefix:
- # class name is given in the signature, but different
- # (shouldn't happen)
- fullname = classname + '.' + name_prefix + name
- else:
- # class name is not given in the signature
- fullname = classname + '.' + name
- else:
- add_module = True
- if name_prefix:
- classname = name_prefix.rstrip('.')
- fullname = name_prefix + name
- else:
- classname = ''
- fullname = name
-
- signode['module'] = modname
- signode['class'] = classname
- signode['fullname'] = fullname
-
- sig_prefix = self.get_signature_prefix(sig)
- if sig_prefix:
- signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
-
- if name_prefix:
- signode += addnodes.desc_addname(name_prefix, name_prefix)
- # exceptions are a special case, since they are documented in the
- # 'exceptions' module.
- elif add_module and self.env.config.add_module_names:
- modname = self.options.get(
- 'module', self.env.temp_data.get('py:module'))
- if modname and modname != 'exceptions':
- nodetext = modname + '.'
- signode += addnodes.desc_addname(nodetext, nodetext)
-
- signode += addnodes.desc_name(name, name)
- if not arglist:
- if self.needs_arglist():
- # for callables, add an empty parameter list
- signode += addnodes.desc_parameterlist()
- if retann:
- signode += addnodes.desc_returns(retann, retann)
- return fullname, name_prefix
- _pseudo_parse_arglist(signode, arglist)
- if retann:
- signode += addnodes.desc_returns(retann, retann)
- return fullname, name_prefix
-
- def get_index_text(self, modname, name):
- """
- Return the text for the index entry of the object.
- """
- raise NotImplementedError('must be implemented in subclasses')
-
- def add_target_and_index(self, name_cls, sig, signode):
- modname = self.options.get(
- 'module', self.env.temp_data.get('py:module'))
- fullname = (modname and modname + '.' or '') + name_cls[0]
- # note target
- if fullname not in self.state.document.ids:
- signode['names'].append(fullname)
- signode['ids'].append(fullname)
- signode['first'] = (not self.names)
- self.state.document.note_explicit_target(signode)
- objects = self.env.domaindata['ocv']['objects']
- if fullname in objects:
- self.env.warn(
- self.env.docname,
- 'duplicate object description of %s, ' % fullname +
- 'other instance in ' +
- self.env.doc2path(objects[fullname][0]) +
- ', use :noindex: for one of them',
- self.lineno)
- objects.setdefault(fullname, (self.env.docname, self.objtype, name_cls[0]))
-
- indextext = self.get_index_text(modname, name_cls)
- if indextext:
- self.indexnode['entries'].append(('single', indextext,
- fullname, fullname))
-
- def before_content(self):
- # needed for automatic qualification of members (reset in subclasses)
- self.clsname_set = False
-
- def after_content(self):
- if self.clsname_set:
- self.env.temp_data['py:class'] = None
-
-class OCVPyModulelevel(OCVPyObject):
- """
- Description of an object on module level (functions, data).
- """
- directive_prefix = 'py'
-
- def needs_arglist(self):
- return self.objtype == self.__class__.directive_prefix + 'function'
-
- def get_index_text(self, modname, name_cls):
- if self.objtype == self.__class__.directive_prefix + 'function':
- if not modname:
- fname = name_cls[0]
- if not fname.startswith("cv") and not fname.startswith("cv2"):
- return _('%s() (Python function)') % fname
- pos = fname.find(".")
- modname = fname[:pos]
- fname = fname[pos+1:]
- return _('%s() (Python function in %s)') % (fname, modname)
- return _('%s() (Python function in %s)') % (name_cls[0], modname)
- elif self.objtype == 'pydata':
- if not modname:
- return _('%s (Python variable)') % name_cls[0]
- return _('%s (in module %s)') % (name_cls[0], modname)
- else:
- return ''
-
-class OCVPyXRefRole(XRefRole):
- def process_link(self, env, refnode, has_explicit_title, title, target):
- refnode['ocv:module'] = env.temp_data.get('ocv:module')
- refnode['ocv:class'] = env.temp_data.get('ocv:class')
- if not has_explicit_title:
- title = title.lstrip('.') # only has a meaning for the target
- target = target.lstrip('~') # only has a meaning for the title
- # if the first character is a tilde, don't display the module/class
- # parts of the contents
- if title[0:1] == '~':
- title = title[1:]
- dot = title.rfind('.')
- if dot != -1:
- title = title[dot+1:]
- # if the first character is a dot, search more specific namespaces first
- # else search builtins first
- if target[0:1] == '.':
- target = target[1:]
- refnode['refspecific'] = True
- return title, target
-
-
-########################### C/C++/Java Part ###########################
-
-_identifier_re = re.compile(r'(~?\b[a-zA-Z_][a-zA-Z0-9_]*\b)')
-_argument_name_re = re.compile(r'(~?\b[a-zA-Z_][a-zA-Z0-9_]*\b(?:\[\d*\])?|\.\.\.)')
-_whitespace_re = re.compile(r'\s+(?u)')
-_string_re = re.compile(r"[LuU8]?('([^'\\]*(?:\\.[^'\\]*)*)'"
- r'|"([^"\\]*(?:\\.[^"\\]*)*)")', re.S)
-_visibility_re = re.compile(r'\b(public|private|protected)\b')
-_operator_re = re.compile(r'''(?x)
- \[\s*\]
- | \(\s*\)
- | (<<|>>)=?
- | \+\+ | -- | ->\*?
- | [!<>=/*%+|&^-]=?
- | ~ | && | \| | \|\|
- | \,
-''')
-
-_id_shortwords = {
- 'char': 'c',
- 'signed char': 'c',
- 'unsigned char': 'C',
- 'int': 'i',
- 'signed int': 'i',
- 'unsigned int': 'U',
- 'long': 'l',
- 'signed long': 'l',
- 'unsigned long': 'L',
- 'bool': 'b',
- 'size_t': 's',
- 'std::string': 'ss',
- 'std::ostream': 'os',
- 'std::istream': 'is',
- 'std::iostream': 'ios',
- 'std::vector': 'v',
- 'std::map': 'm',
- 'operator[]': 'subscript-operator',
- 'operator()': 'call-operator',
- 'operator!': 'not-operator',
- 'operator<': 'lt-operator',
- 'operator<=': 'lte-operator',
- 'operator>': 'gt-operator',
- 'operator>=': 'gte-operator',
- 'operator=': 'assign-operator',
- 'operator/': 'div-operator',
- 'operator*': 'mul-operator',
- 'operator%': 'mod-operator',
- 'operator+': 'add-operator',
- 'operator-': 'sub-operator',
- 'operator|': 'or-operator',
- 'operator&': 'and-operator',
- 'operator^': 'xor-operator',
- 'operator&&': 'sand-operator',
- 'operator||': 'sor-operator',
- 'operator==': 'eq-operator',
- 'operator!=': 'neq-operator',
- 'operator<<': 'lshift-operator',
- 'operator>>': 'rshift-operator',
- 'operator-=': 'sub-assign-operator',
- 'operator+=': 'add-assign-operator',
- 'operator*-': 'mul-assign-operator',
- 'operator/=': 'div-assign-operator',
- 'operator%=': 'mod-assign-operator',
- 'operator&=': 'and-assign-operator',
- 'operator|=': 'or-assign-operator',
- 'operator<<=': 'lshift-assign-operator',
- 'operator>>=': 'rshift-assign-operator',
- 'operator^=': 'xor-assign-operator',
- 'operator,': 'comma-operator',
- 'operator->': 'pointer-operator',
- 'operator->*': 'pointer-by-pointer-operator',
- 'operator~': 'inv-operator',
- 'operator++': 'inc-operator',
- 'operator--': 'dec-operator',
- 'operator new': 'new-operator',
- 'operator new[]': 'new-array-operator',
- 'operator delete': 'delete-operator',
- 'operator delete[]': 'delete-array-operator'
-}
-
-
-class DefinitionError(Exception):
-
- def __init__(self, description):
- self.description = description
-
- def __unicode__(self):
- return self.description
-
- def __str__(self):
- return unicode(self.encode('utf-8'))
-
-
-class DefExpr(object):
-
- def __unicode__(self):
- raise NotImplementedError()
-
- def __eq__(self, other):
- if type(self) is not type(other):
- return False
- try:
- for key, value in self.__dict__.iteritems():
- if value != getattr(other, value):
- return False
- except AttributeError:
- return False
- return True
-
- def __ne__(self, other):
- return not self.__eq__(other)
-
- def clone(self):
- """Close a definition expression node"""
- return deepcopy(self)
-
- def get_id(self):
- """Returns the id for the node"""
- return u''
-
- def get_name(self):
- """Returns the name. Returns either `None` or a node with
- a name you might call :meth:`split_owner` on.
- """
- return None
-
- def split_owner(self):
- """Nodes returned by :meth:`get_name` can split off their
- owning parent. This function returns the owner and the
- name as a tuple of two items. If a node does not support
- it, it returns None as owner and self as name.
- """
- return None, self
-
- def prefix(self, prefix):
- """Prefixes a name node (a node returned by :meth:`get_name`)."""
- raise NotImplementedError()
-
- def __str__(self):
- return unicode(self).encode('utf-8')
-
- def __repr__(self):
- return '<%s %s>' % (self.__class__.__name__, self)
-
-
-class PrimaryDefExpr(DefExpr):
-
- def get_name(self):
- return self
-
- def prefix(self, prefix):
- if isinstance(prefix, PathDefExpr):
- prefix = prefix.clone()
- prefix.path.append(self)
- return prefix
- return PathDefExpr([prefix, self])
-
-
-class NameDefExpr(PrimaryDefExpr):
-
- def __init__(self, name):
- self.name = name
-
- def get_id(self):
- name = _id_shortwords.get(self.name)
- if name is not None:
- return name
- return self.name.replace(u' ', u'-')
-
- def __unicode__(self):
- return unicode(self.name)
-
-
-class PathDefExpr(PrimaryDefExpr):
-
- def __init__(self, parts):
- self.path = parts
-
- def get_id(self):
- rv = u'::'.join(x.get_id() for x in self.path)
- return _id_shortwords.get(rv, rv)
-
- def split_owner(self):
- if len(self.path) > 1:
- return PathDefExpr(self.path[:-1]), self.path[-1]
- return None, self
-
- def prefix(self, prefix):
- if isinstance(prefix, PathDefExpr):
- prefix = prefix.clone()
- prefix.path.extend(self.path)
- return prefix
- return PathDefExpr([prefix] + self.path)
-
- def __unicode__(self):
- return u'::'.join(map(unicode, self.path))
-
-
-class TemplateDefExpr(PrimaryDefExpr):
-
- def __init__(self, typename, args):
- self.typename = typename
- self.args = args
-
- def split_owner(self):
- owner, typename = self.typename.split_owner()
- return owner, TemplateDefExpr(typename, self.args)
-
- def get_id(self):
- return u'%s:%s:' % (self.typename.get_id(),
- u'.'.join(x.get_id() for x in self.args))
-
- def __unicode__(self):
- return u'%s<%s>' % (self.typename, u', '.join(map(unicode, self.args)))
-
-
-class WrappingDefExpr(DefExpr):
-
- def __init__(self, typename):
- self.typename = typename
-
- def get_name(self):
- return self.typename.get_name()
-
-
-class ModifierDefExpr(WrappingDefExpr):
-
- def __init__(self, typename, modifiers):
- WrappingDefExpr.__init__(self, typename)
- self.modifiers = modifiers
-
- def get_id(self):
- pieces = [_id_shortwords.get(unicode(x), unicode(x))
- for x in self.modifiers]
- pieces.append(self.typename.get_id())
- return u'-'.join(pieces)
-
- def __unicode__(self):
- return u' '.join(map(unicode, list(self.modifiers) + [self.typename]))
-
-
-class PtrDefExpr(WrappingDefExpr):
-
- def get_id(self):
- return self.typename.get_id() + u'P'
-
- def __unicode__(self):
- return u'%s*' % self.typename
-
-
-class RefDefExpr(WrappingDefExpr):
-
- def get_id(self):
- return self.typename.get_id() + u'R'
-
- def __unicode__(self):
- return u'%s&' % self.typename
-
-
-class ConstDefExpr(WrappingDefExpr):
-
- def __init__(self, typename, prefix=False):
- WrappingDefExpr.__init__(self, typename)
- self.prefix = prefix
-
- def get_id(self):
- return self.typename.get_id() + u'C'
-
- def __unicode__(self):
- return (self.prefix and u'const %s' or u'%s const') % self.typename
-
-class ConstTemplateDefExpr(WrappingDefExpr):
-
- def __init__(self, typename, prefix=False):
- WrappingDefExpr.__init__(self, typename)
- self.prefix = prefix
-
- def get_id(self):
- return self.typename.get_id() + u'C'
-
- def __unicode__(self):
- return (self.prefix and u'const %s' or u'%s const') % self.typename
-
-
-class CastOpDefExpr(PrimaryDefExpr):
-
- def __init__(self, typename):
- self.typename = typename
-
- def get_id(self):
- return u'castto-%s-operator' % self.typename.get_id()
-
- def __unicode__(self):
- return u'operator %s' % self.typename
-
-
-class ArgumentDefExpr(DefExpr):
-
- def __init__(self, type, name, default=None):
- self.name = name
- self.type = type
- self.default = default
-
- def get_name(self):
- return self.name.get_name()
-
- def get_id(self):
- if self.type is None:
- return 'X'
- return self.type.get_id()
-
- def __unicode__(self):
- return (u'%s %s' % (self.type or u'', self.name or u'')).strip() + \
- (self.default is not None and u'=%s' % self.default or u'')
-
-
-class NamedDefExpr(DefExpr):
-
- def __init__(self, name, visibility, static):
- self.name = name
- self.visibility = visibility
- self.static = static
-
- def get_name(self):
- return self.name.get_name()
-
- def get_modifiers(self):
- rv = []
- if self.visibility != 'public':
- rv.append(self.visibility)
- if self.static:
- rv.append(u'static')
- return rv
-
-
-class TypeObjDefExpr(NamedDefExpr):
-
- def __init__(self, name, visibility, static, typename):
- NamedDefExpr.__init__(self, name, visibility, static)
- self.typename = typename
-
- def get_id(self):
- if self.typename is None:
- return self.name.get_id()
- return u'%s__%s' % (self.name.get_id(), self.typename.get_id())
-
- def __unicode__(self):
- buf = self.get_modifiers()
- if self.typename is None:
- buf.append(unicode(self.name))
- else:
- buf.extend(map(unicode, (self.typename, self.name)))
- return u' '.join(buf)
-
-
-class MemberObjDefExpr(NamedDefExpr):
-
- def __init__(self, name, visibility, static, typename, value):
- NamedDefExpr.__init__(self, name, visibility, static)
- self.typename = typename
- self.value = value
-
- def get_id(self):
- return u'%s__%s' % (self.name.get_id(), self.typename.get_id())
-
- def __unicode__(self):
- buf = self.get_modifiers()
- buf.append(u'%s %s' % (self.typename, self.name))
- if self.value is not None:
- buf.append(u'= %s' % self.value)
- return u' '.join(buf)
-
-
-class FuncDefExpr(NamedDefExpr):
-
- def __init__(self, name, visibility, static, explicit, rv,
- signature, const, pure_virtual, virtual):
- NamedDefExpr.__init__(self, name, visibility, static)
- self.rv = rv
- self.signature = signature
- self.explicit = explicit
- self.const = const
- self.pure_virtual = pure_virtual
- self.virtual = virtual
-
- def get_id(self):
- return u'%s%s%s' % (
- self.name.get_id(),
- self.signature and u'__' +
- u'.'.join(x.get_id() for x in self.signature) or u'',
- self.const and u'C' or u''
- )
-
- def __unicode__(self):
- buf = self.get_modifiers()
- if self.explicit:
- buf.append(u'explicit')
- if self.virtual:
- buf.append(u'virtual')
- if self.rv is not None:
- buf.append(unicode(self.rv))
- buf.append(u'%s(%s)' % (self.name, u', '.join(
- map(unicode, self.signature))))
- if self.const:
- buf.append(u'const')
- if self.pure_virtual:
- buf.append(u'= 0')
- return u' '.join(buf)
-
-
-class ClassDefExpr(NamedDefExpr):
-
- def __init__(self, name, visibility, static, parents = None):
- NamedDefExpr.__init__(self, name, visibility, static)
- self.parents = parents
-
- def get_id(self):
- return self.name.get_id()
-
- def __unicode__(self):
- buf = self.get_modifiers()
- buf.append(unicode(self.name))
- return u' '.join(buf)
-
-
-class DefinitionParser(object):
-
- # mapping of valid type modifiers. if the set is None it means
- # the modifier can prefix all types, otherwise only the types
- # (actually more keywords) in the set. Also check
- # _guess_typename when changing this.
- _modifiers = {
- 'volatile': None,
- 'register': None,
- 'mutable': None,
- 'const': None,
- 'typename': None,
- 'unsigned': set(('char', 'short', 'int', 'long')),
- 'signed': set(('char', 'short', 'int', 'long')),
- 'short': set(('int',)),
- 'long': set(('int', 'long', 'double'))
- }
-
- def __init__(self, definition):
- self.definition = definition.strip()
- self.pos = 0
- self.end = len(self.definition)
- self.last_match = None
- self._previous_state = (0, None)
-
- def fail(self, msg):
- raise DefinitionError('Invalid definition: %s [error at %d]\n %s' %
- (msg, self.pos, self.definition))
-
- def match(self, regex):
- match = regex.match(self.definition, self.pos)
- if match is not None:
- self._previous_state = (self.pos, self.last_match)
- self.pos = match.end()
- self.last_match = match
- return True
- return False
-
- def backout(self):
- self.pos, self.last_match = self._previous_state
-
- def skip_string(self, string):
- strlen = len(string)
- if self.definition[self.pos:self.pos + strlen] == string:
- self.pos += strlen
- return True
- return False
-
- def skip_word(self, word):
- return self.match(re.compile(r'\b%s\b' % re.escape(word)))
-
- def skip_ws(self):
- return self.match(_whitespace_re)
-
- @property
- def eof(self):
- return self.pos >= self.end
-
- @property
- def current_char(self):
- try:
- return self.definition[self.pos]
- except IndexError:
- return 'EOF'
-
- @property
- def matched_text(self):
- if self.last_match is not None:
- return self.last_match.group()
-
- def _parse_operator(self):
- self.skip_ws()
- # thank god, a regular operator definition
- if self.match(_operator_re):
- return NameDefExpr('operator' +
- _whitespace_re.sub('', self.matched_text))
- # new/delete operator?
- for allocop in 'new', 'delete':
- if not self.skip_word(allocop):
- continue
- self.skip_ws()
- if self.skip_string('['):
- self.skip_ws()
- if not self.skip_string(']'):
- self.fail('expected "]" for ' + allocop)
- allocop += '[]'
- return NameDefExpr('operator ' + allocop)
-
- # oh well, looks like a cast operator definition.
- # In that case, eat another type.
- type = self._parse_type()
- return CastOpDefExpr(type)
-
- def _parse_name(self):
- if not self.match(_argument_name_re):
- self.fail('expected name')
- identifier = self.matched_text
-
- # strictly speaking, operators are not regular identifiers
- # but because operator is a keyword, it might not be used
- # for variable names anyways, so we can safely parse the
- # operator here as identifier
- if identifier == 'operator':
- return self._parse_operator()
-
- return NameDefExpr(identifier)
-
- def _guess_typename(self, path):
- if not path:
- return [], 'int'
- # for the long type, we don't want the int in there
- if 'long' in path:
- path = [x for x in path if x != 'int']
- # remove one long
- path.remove('long')
- return path, 'long'
- if path[-1] in ('int', 'char'):
- return path[:-1], path[-1]
- return path, 'int'
-
- def _attach_crefptr(self, expr, is_const=False):
- if is_const:
- expr = ConstDefExpr(expr, prefix=True)
- while 1:
- self.skip_ws()
- if self.skip_word('const'):
- expr = ConstDefExpr(expr)
- elif self.skip_string('*'):
- expr = PtrDefExpr(expr)
- elif self.skip_string('&'):
- expr = RefDefExpr(expr)
- else:
- return expr
-
- def _peek_const(self, path):
- try:
- path.remove('const')
- return True
- except ValueError:
- return False
-
- def _parse_builtin(self, modifier):
- path = [modifier]
- following = self._modifiers[modifier]
- while 1:
- self.skip_ws()
- if not self.match(_identifier_re):
- break
- identifier = self.matched_text
- if identifier in following:
- path.append(identifier)
- following = self._modifiers[modifier]
- assert following
- else:
- self.backout()
- break
-
- is_const = self._peek_const(path)
- modifiers, typename = self._guess_typename(path)
- rv = ModifierDefExpr(NameDefExpr(typename), modifiers)
- return self._attach_crefptr(rv, is_const)
-
- def _parse_type_expr(self):
- typename = self._parse_name()
- if typename and self.skip_string('['):
- typename.name += '['
- if self.match(re.compile(r'\d*')):
- typename.name += self.last_match.group(0)
- typename.name += ']'
- if not self.skip_string(']'):
- self.fail('expected type')
- self.skip_ws()
- if not self.skip_string('<'):
- return typename
-
- args = []
- while 1:
- self.skip_ws()
- if self.skip_string('>'):
- break
- if args:
- if not self.skip_string(','):
- self.fail('"," or ">" in template expected')
- self.skip_ws()
- args.append(self._parse_type(True))
- return TemplateDefExpr(typename, args)
-
- def _parse_type(self, in_template=False):
- self.skip_ws()
- result = []
- modifiers = []
-
- if self.match(re.compile(r'template\w*<([^>]*)>')):
- args = self.last_match.group(1).split(',')
- args = [a.strip() for a in args]
- modifiers.append(TemplateDefExpr('template', args))
-
- # if there is a leading :: or not, we don't care because we
- # treat them exactly the same. Buf *if* there is one, we
- # don't have to check for type modifiers
- if not self.skip_string('::'):
- self.skip_ws()
- while self.match(_identifier_re):
- modifier = self.matched_text
- if modifier in self._modifiers:
- following = self._modifiers[modifier]
- # if the set is not none, there is a limited set
- # of types that might follow. It is technically
- # impossible for a template to follow, so what
- # we do is go to a different function that just
- # eats types
- if following is not None:
- return self._parse_builtin(modifier)
- modifiers.append(modifier)
- else:
- self.backout()
- break
-
- while 1:
- self.skip_ws()
- if (in_template and self.current_char in ',>') or \
- (result and not self.skip_string('::')) or \
- self.eof:
- break
- result.append(self._parse_type_expr())
-
- if not result:
- self.fail('expected type')
- if len(result) == 1:
- rv = result[0]
- else:
- rv = PathDefExpr(result)
- is_const = self._peek_const(modifiers)
- if is_const:
- rv = ConstDefExpr(rv, prefix=True)
- if modifiers:
- rv = ModifierDefExpr(rv, modifiers)
- return self._attach_crefptr(rv, False)
-
- def _parse_default_expr(self):
- self.skip_ws()
- if self.match(_string_re):
- return self.matched_text
- paren_stack_depth = 0
- max_pos = len(self.definition)
- rv_start = self.pos
- while 1:
- idx0 = self.definition.find('(', self.pos)
- idx1 = self.definition.find(',', self.pos)
- idx2 = self.definition.find(')', self.pos)
- if idx0 < 0:
- idx0 = max_pos
- if idx1 < 0:
- idx1 = max_pos
- if idx2 < 0:
- idx2 = max_pos
- idx = min(idx0, idx1, idx2)
- if idx >= max_pos:
- self.fail('unexpected end in default expression')
- if idx == idx0:
- paren_stack_depth += 1
- elif idx == idx2:
- paren_stack_depth -= 1
- if paren_stack_depth < 0:
- break
- elif paren_stack_depth == 0:
- break
- self.pos = idx+1
-
- rv = self.definition[rv_start:idx]
- self.pos = idx
- return rv
-
- def _parse_signature(self):
- if r'CvStatModel::train' in self.definition:
- # hack to skip parsing of problematic definition
- self.pos = self.end
- return [ArgumentDefExpr("const Mat&", "train_data", None), ArgumentDefExpr(None, self.definition[self.definition.find("["):-1], None)], False, True
-
- self.skip_ws()
- if not self.skip_string('('):
- self.fail('expected parentheses for function')
-
- args = []
- while 1:
- self.skip_ws()
- if self.eof:
- self.fail('missing closing parentheses')
- if self.skip_string(')'):
- break
- if args:
- if not self.skip_string(','):
- self.fail('expected comma between arguments')
- self.skip_ws()
-
- argtype = self._parse_type()
- self.skip_ws()
- if unicode(argtype) == u"...":
- if not self.skip_string(')'):
- self.fail("var arg must be the last argument")
- args.append(ArgumentDefExpr(None, argtype, None))
- break
- argname = default = None
- if self.skip_string('='):
- self.pos += 1
- default = self._parse_default_expr()
- elif self.current_char not in ',)':
- argname = self._parse_name()
- self.skip_ws()
- if self.skip_string('='):
- default = self._parse_default_expr()
-
- args.append(ArgumentDefExpr(argtype, argname, default))
- self.skip_ws()
- const = self.skip_word('const')
- if const:
- self.skip_ws()
- if self.skip_string('='):
- self.skip_ws()
- if not (self.skip_string('0') or \
- self.skip_word('NULL') or \
- self.skip_word('nullptr')):
- self.fail('pure virtual functions must be defined with '
- 'either 0, NULL or nullptr, other macros are '
- 'not allowed')
- pure_virtual = True
- else:
- pure_virtual = False
- return args, const, pure_virtual
-
- def _parse_visibility_static(self):
- visibility = 'public'
- if self.match(_visibility_re):
- visibility = self.matched_text
- static = self.skip_word('static')
- return visibility, static
-
- def parse_type(self):
- return self._parse_type()
-
- def parse_type_object(self):
- visibility, static = self._parse_visibility_static()
- typename = self._parse_type()
- self.skip_ws()
- if not self.eof:
- name = self._parse_type()
- else:
- name = typename
- typename = None
- return TypeObjDefExpr(name, visibility, static, typename)
-
- def parse_member_object(self):
- visibility, static = self._parse_visibility_static()
- typename = self._parse_type()
- name = self._parse_type()
- self.skip_ws()
- if self.skip_string('='):
- value = self.read_rest().strip()
- else:
- value = None
- return MemberObjDefExpr(name, visibility, static, typename, value)
-
- def parse_enum_member_object(self):
- visibility, static = self._parse_visibility_static()
- typename = None
- name = self._parse_type()
- self.skip_ws()
- if self.skip_string('='):
- value = self.read_rest().strip()
- else:
- value = None
- return MemberObjDefExpr(name, visibility, static, typename, value)
-
- def parse_function(self):
- visibility, static = self._parse_visibility_static()
- if self.skip_word('explicit'):
- explicit = True
- self.skip_ws()
- else:
- explicit = False
- if self.skip_word('virtual'):
- virtual = True
- self.skip_ws()
- else:
- virtual = False
- rv = self._parse_type()
- self.skip_ws()
- # some things just don't have return values
- if self.current_char == '(':
- name = rv
- rv = None
- else:
- name = self._parse_type()
- return FuncDefExpr(name, visibility, static, explicit, rv,
- *self._parse_signature(), virtual = virtual)
-
- def parse_class(self):
- visibility, static = self._parse_visibility_static()
- typename = self._parse_type()
- parent = None
- self.skip_ws()
- parents = []
- if self.skip_string(':'):
- while not self.eof:
- self.skip_ws()
- classname_pos = self.pos
- pvisibility, pstatic = self._parse_visibility_static()
- if pstatic:
- self.fail('unsepected static keyword, got %r' %
- self.definition[self.classname_pos:])
- parents.append(ClassDefExpr(self._parse_type(), pvisibility, pstatic))
- if not self.skip_string(','):
- break
- return ClassDefExpr(typename, visibility, static, parents)
-
- def read_rest(self):
- rv = self.definition[self.pos:]
- self.pos = self.end
- return rv
-
- def assert_end(self):
- self.skip_ws()
- if not self.eof:
- self.fail('expected end of definition, got %r' %
- self.definition[self.pos:])
-
-
-class OCVObject(ObjectDescription):
- """Description of a C++ language object."""
-
- langname = "C++"
- ismember = False
-
- doc_field_types = [
- TypedField('parameter', label=l_('Parameters'),
- names=('param', 'parameter', 'arg', 'argument'),
- typerolename='type', typenames=('type',)),
- Field('returnvalue', label=l_('Returns'), has_arg=False,
- names=('returns', 'return')),
- Field('returntype', label=l_('Return type'), has_arg=False,
- names=('rtype',)),
- ]
-
- def attach_name(self, node, name):
- owner, name = name.split_owner()
- varname = unicode(name)
- if owner is not None:
- owner = unicode(owner) + '::'
- node += addnodes.desc_addname(owner, owner)
- node += addnodes.desc_name(varname, varname)
-
- def attach_type(self, node, type):
- # XXX: link to c?
- text = unicode(type)
- pnode = addnodes.pending_xref(
- '', refdomain='ocv', reftype='type',
- reftarget=text, modname=None, classname=None)
- pnode['ocv:parent'] = self.env.temp_data.get('ocv:parent')
- pnode += nodes.Text(text)
- node += pnode
-
- def attach_modifiers(self, node, obj):
- if not self.__class__.ismember:
- lname = self.__class__.langname
- node += nodes.strong(lname + ":", lname + ":")
- node += addnodes.desc_name(" ", " ")
-
- if obj.visibility != 'public':
- node += addnodes.desc_annotation(obj.visibility,
- obj.visibility)
- node += nodes.Text(' ')
- if obj.static:
- node += addnodes.desc_annotation('static', 'static')
- node += nodes.Text(' ')
-
- def add_target_and_index(self, sigobj, sig, signode):
- theid = sig#obj.get_id()
- theid = re.sub(r" +", " ", theid)
- if self.objtype == 'emember':
- theid = re.sub(r" ?=.*", "", theid)
- theid = re.sub(r"=[^,()]+\([^)]*?\)[^,)]*(,|\))", "\\1", theid)
- theid = re.sub(r"=\w*[^,)(]+(,|\))", "\\1", theid)
- theid = theid.replace("( ", "(").replace(" )", ")")
- name = unicode(sigobj.name)
- if theid not in self.state.document.ids:
- signode['names'].append(theid)
- signode['ids'].append(theid)
- signode['first'] = (not self.names)
- self.state.document.note_explicit_target(signode)
-
- #self.env.domaindata['ocv']['objects'].setdefault(name,
- #(self.env.docname, self.objtype, theid))
- self.env.domaindata['ocv']['objects'].setdefault(theid,
- (self.env.docname, self.objtype, theid))
- self.env.domaindata['ocv']['objects2'].setdefault(name,
- (self.env.docname, self.objtype, theid))
-
- indextext = self.get_index_text(name)
- if indextext:
- self.indexnode['entries'].append(('single', indextext, theid, name))
-
- def before_content(self):
- lastname = self.names and self.names[-1]
- if lastname and not self.env.temp_data.get('ocv:parent'):
- assert isinstance(lastname, NamedDefExpr)
- self.env.temp_data['ocv:parent'] = lastname.name
- self.parentname_set = True
- else:
- self.parentname_set = False
-
- def after_content(self):
- if self.parentname_set:
- self.env.temp_data['ocv:parent'] = None
-
- def parse_definition(self, parser):
- raise NotImplementedError()
-
- def describe_signature(self, signode, arg):
- raise NotImplementedError()
-
- def handle_signature(self, sig, signode):
- parser = DefinitionParser(sig)
- try:
- rv = self.parse_definition(parser)
- parser.assert_end()
- except DefinitionError, e:
- self.env.warn(self.env.docname,
- e.description, self.lineno)
- raise ValueError
- self.describe_signature(signode, rv)
-
- parent = self.env.temp_data.get('ocv:parent')
- if parent is not None:
- rv = rv.clone()
- rv.name = rv.name.prefix(parent)
- return rv
-
-
-class OCVClassObject(OCVObject):
- object_annotation = "class "
- object_long_name = "class"
-
- def attach_modifiers(self, node, obj, skip_visibility = 'public'):
- if obj.visibility != skip_visibility:
- node += addnodes.desc_annotation(obj.visibility,
- obj.visibility)
- node += nodes.Text(' ')
- if obj.static:
- node += addnodes.desc_annotation('static', 'static')
- node += nodes.Text(' ')
-
- def get_index_text(self, name):
- return _('%s (C++ %s)') % (name, self.__class__.object_long_name)
-
- def parse_definition(self, parser):
- return parser.parse_class()
-
- def describe_signature(self, signode, cls):
- self.attach_modifiers(signode, cls)
- signode += addnodes.desc_annotation(self.__class__.object_annotation, self.__class__.object_annotation)
- self.attach_name(signode, cls.name)
- first_parent = True
- for p in cls.parents:
- if first_parent:
- signode += nodes.Text(' : ')
- first_parent = False
- else:
- signode += nodes.Text(', ')
- self.attach_modifiers(signode, p, None)
- self.attach_name(signode, p.name)
-
-class OCVStructObject(OCVClassObject):
- object_annotation = "struct "
- object_long_name = "structure"
-
-class OCVTypeObject(OCVObject):
-
- def get_index_text(self, name):
- if self.objtype == 'type':
- return _('%s (C++ type)') % name
- return ''
-
- def parse_definition(self, parser):
- return parser.parse_type_object()
-
- def describe_signature(self, signode, obj):
- self.attach_modifiers(signode, obj)
- signode += addnodes.desc_annotation('type ', 'type ')
- if obj.typename is not None:
- self.attach_type(signode, obj.typename)
- signode += nodes.Text(' ')
- self.attach_name(signode, obj.name)
-
-class OCVEnumObject(OCVObject):
-
- def get_index_text(self, name):
- if self.objtype == 'enum':
- return _('%s (enum)') % name
- return ''
-
- def parse_definition(self, parser):
- return parser.parse_type_object()
-
- def describe_signature(self, signode, obj):
- self.attach_modifiers(signode, obj)
- signode += addnodes.desc_annotation('enum ', 'enum ')
- if obj.typename is not None:
- self.attach_type(signode, obj.typename)
- signode += nodes.Text(' ')
- self.attach_name(signode, obj.name)
-
-
-class OCVMemberObject(OCVObject):
- ismember = True
-
- def get_index_text(self, name):
- if self.objtype == 'member':
- return _('%s (C++ member)') % name
- return ''
-
- def parse_definition(self, parser):
- parent_class = self.env.temp_data.get('ocv:parent')
- if parent_class is None:
- parser.fail("missing parent structure/class")
- return parser.parse_member_object()
-
- def describe_signature(self, signode, obj):
- self.attach_modifiers(signode, obj)
- if obj.typename:
- self.attach_type(signode, obj.typename)
- signode += nodes.Text(' ')
- self.attach_name(signode, obj.name)
- if obj.value is not None:
- signode += nodes.Text(u' = ' + obj.value)
-
-class OCVEnumMemberObject(OCVMemberObject):
- def parse_definition(self, parser):
- # parent_class = self.env.temp_data.get('ocv:parent')
- # if parent_class is None:
- # parser.fail("missing parent structure/class")
- return parser.parse_enum_member_object()
-
-class OCVFunctionObject(OCVObject):
-
- def attach_function(self, node, func):
- owner, name = func.name.split_owner()
- if owner is not None:
- owner = unicode(owner) + '::'
- node += addnodes.desc_addname(owner, owner)
-
- # cast operator is special. in this case the return value
- # is reversed.
- if isinstance(name, CastOpDefExpr):
- node += addnodes.desc_name('operator', 'operator')
- node += nodes.Text(u' ')
- self.attach_type(node, name.typename)
- else:
- funcname = unicode(name)
- node += addnodes.desc_name(funcname, funcname)
-
- paramlist = addnodes.desc_parameterlist()
- for arg in func.signature:
- param = addnodes.desc_parameter('', '', noemph=True)
- if arg.type is not None:
- self.attach_type(param, arg.type)
- param += nodes.Text(u' ')
- #param += nodes.emphasis(unicode(arg.name), unicode(arg.name))
- sbrIdx = unicode(arg.name).find("[")
- if sbrIdx < 0:
- param += nodes.strong(unicode(arg.name), unicode(arg.name))
- else:
- param += nodes.strong(unicode(arg.name)[:sbrIdx], unicode(arg.name)[:sbrIdx])
- param += nodes.Text(unicode(arg.name)[sbrIdx:])
- if arg.default is not None:
- def_ = u'=' + unicode(arg.default)
- #param += nodes.emphasis(def_, def_)
- param += nodes.Text(def_)
- paramlist += param
-
- node += paramlist
- if func.const:
- node += addnodes.desc_addname(' const', ' const')
- if func.pure_virtual:
- node += addnodes.desc_addname(' = 0', ' = 0')
-
- def get_index_text(self, name):
- lname = self.__class__.langname
- if lname == "C" and name.startswith("cv"):
- name = name[2:]
- return _('%s (%s function)') % (name, lname)
-
- def parse_definition(self, parser):
- return parser.parse_function()
-
- def describe_signature(self, signode, func):
- self.attach_modifiers(signode, func)
- if func.explicit:
- signode += addnodes.desc_annotation('explicit', 'explicit')
- signode += nodes.Text(' ')
- if func.virtual:
- signode += addnodes.desc_annotation('virtual', 'virtual')
- signode += nodes.Text(' ')
- # return value is None for things with a reverse return value
- # such as casting operator definitions or constructors
- # and destructors.
- if func.rv is not None:
- self.attach_type(signode, func.rv)
- signode += nodes.Text(u' ')
- self.attach_function(signode, func)
-
-
-class OCVCurrentNamespace(Directive):
- """This directive is just to tell Sphinx that we're documenting
- stuff in namespace foo.
- """
-
- has_content = False
- required_arguments = 1
- optional_arguments = 0
- final_argument_whitespace = True
- option_spec = {}
-
- def run(self):
- env = self.state.document.settings.env
- if self.arguments[0].strip() in ('NULL', '0', 'nullptr'):
- env.temp_data['ocv:prefix'] = None
- else:
- parser = DefinitionParser(self.arguments[0])
- try:
- prefix = parser.parse_type()
- parser.assert_end()
- except DefinitionError, e:
- self.env.warn(self.env.docname,
- e.description, self.lineno)
- else:
- env.temp_data['ocv:prefix'] = prefix
- return []
-
-
-class OCVXRefRole(XRefRole):
-
- def process_link(self, env, refnode, has_explicit_title, title, target):
- refnode['ocv:parent'] = env.temp_data.get('ocv:parent')
- if not has_explicit_title:
- target = target.lstrip('~') # only has a meaning for the title
- # if the first character is a tilde, don't display the module/class
- # parts of the contents
- if title[:1] == '~':
- title = title[1:]
- dcolon = title.rfind('::')
- if dcolon != -1:
- title = title[dcolon + 2:]
- return title, target
-
-
-class OCVCFunctionObject(OCVFunctionObject):
- langname = "C"
-
-class OCVJavaFunctionObject(OCVFunctionObject):
- langname = "Java"
-
-
-class OCVDomain(Domain):
- """OpenCV C++ language domain."""
- name = 'ocv'
- label = 'C++'
- object_types = {
- 'class': ObjType(l_('class'), 'class'),
- 'struct': ObjType(l_('struct'), 'struct'),
- 'function': ObjType(l_('function'), 'func', 'funcx'),
- 'cfunction': ObjType(l_('cfunction'), 'cfunc', 'cfuncx'),
- 'jfunction': ObjType(l_('jfunction'), 'jfunc', 'jfuncx'),
- 'pyfunction': ObjType(l_('pyfunction'), 'pyfunc'),
- 'member': ObjType(l_('member'), 'member'),
- 'emember': ObjType(l_('emember'), 'emember'),
- 'type': ObjType(l_('type'), 'type'),
- 'enum': ObjType(l_('enum'), 'enum')
- }
-
- directives = {
- 'class': OCVClassObject,
- 'struct': OCVStructObject,
- 'function': OCVFunctionObject,
- 'cfunction': OCVCFunctionObject,
- 'jfunction': OCVJavaFunctionObject,
- 'pyfunction': OCVPyModulelevel,
- 'member': OCVMemberObject,
- 'emember': OCVEnumMemberObject,
- 'type': OCVTypeObject,
- 'enum': OCVEnumObject,
- 'namespace': OCVCurrentNamespace
- }
- roles = {
- 'class': OCVXRefRole(),
- 'struct': OCVXRefRole(),
- 'func' : OCVXRefRole(fix_parens=True),
- 'funcx' : OCVXRefRole(),
- 'cfunc' : OCVXRefRole(fix_parens=True),
- 'cfuncx' : OCVXRefRole(),
- 'jfunc' : OCVXRefRole(fix_parens=True),
- 'jfuncx' : OCVXRefRole(),
- 'pyfunc' : OCVPyXRefRole(),
- 'member': OCVXRefRole(),
- 'emember': OCVXRefRole(),
- 'type': OCVXRefRole(),
- 'enum': OCVXRefRole()
- }
- initial_data = {
- 'objects': {}, # fullname -> docname, objtype
- }
-
- def __init__(self, env):
- Domain.__init__(self, env)
- self.data['objects2'] = {}
-
- def clear_doc(self, docname):
- for fullname, (fn, _, _) in self.data['objects'].items():
- if fn == docname:
- del self.data['objects'][fullname]
-
- def resolve_xref(self, env, fromdocname, builder,
- typ, target, node, contnode):
- def _create_refnode(expr):
- name = unicode(expr)
- if "type" in self.objtypes_for_role(typ):
- return None
- if "cfunction" in self.objtypes_for_role(typ):
- if not name.startswith(u'cv'):
- name = u'cv' + name
- dict = self.data['objects']
- if name not in dict:
- dict = self.data['objects2']
- if name not in dict:
- refdoc = node.get('refdoc', fromdocname)
- env.warn(refdoc, 'unresolved reference: %r - %r' % (target, typ), node.line)
- return None
- obj = dict[name]
- if obj[1] not in self.objtypes_for_role(typ):
- return None
- title = obj[2]
- if "class" in self.objtypes_for_role(typ):
- title = u"class " + title
- elif "struct" in self.objtypes_for_role(typ):
- title = u"struct " + title
- return make_refnode(builder, fromdocname, obj[0], obj[2],
- contnode, title)
-
- parser = DefinitionParser(target)
- try:
- expr = parser.parse_type().get_name()
- parser.skip_ws()
- if not parser.eof or expr is None:
- raise DefinitionError('')
- except DefinitionError:
- refdoc = node.get('refdoc', fromdocname)
- env.warn(refdoc, 'unparseable C++ definition: %r' % target,
- node.line)
- return None
-
- parent = node['ocv:parent']
-
- rv = _create_refnode(expr)
- if rv is not None or parent is None:
- return rv
- parent = parent.get_name()
-
- rv = _create_refnode(expr.prefix(parent))
- if rv is not None:
- return rv
-
- parent, name = parent.split_owner()
- return _create_refnode(expr.prefix(parent))
-
- def get_objects(self):
- for refname, (docname, type, theid) in self.data['objects'].iteritems():
- yield (refname, refname, type, docname, refname, 1)
-
- def get_type_name(self, type, primary=False):
- """
- Return full name for given ObjType.
- """
- if primary:
- return type.lname
-
- return {
- 'class': _('C++ class'),
- 'struct': _('C/C++ struct'),
- 'function': _('C++ function'),
- 'cfunction': _('C function'),
- 'jfunction': _('Java method'),
- 'pyfunction': _('Python function'),
- 'member': _('C++ member'),
- 'emember': _('enum member'),
- 'type': _('C/C++ type'),
- 'enum': _('C/C++ enum'),
- 'namespace': _('C++ namespace'),
- }.get(type.lname, _('%s %s') % (self.label, type.lname))
-
-def setup(app):
- app.add_domain(OCVDomain)
+++ /dev/null
-%
-% The OpenCV cheatsheet structure:
-%
-% opencv data structures
-% point, rect
-% matrix
-%
-% creating matrices
-% from scratch
-% from previously allocated data: plain arrays, vectors
-% converting to/from old-style structures
-%
-% element access, iteration through matrix elements
-%
-% copying & shuffling matrix data
-% copying & converting the whole matrices
-% extracting matrix parts & copying them
-% split, merge & mixchannels
-% flip, transpose, repeat
-%
-% matrix & image operations:
-% arithmetics & logic
-% matrix multiplication, inversion, determinant, trace, SVD
-% statistical functions
-%
-% basic image processing:
-% image filtering with predefined & custom filters
-% example: finding local maxima
-% geometrical transformations, resize, warpaffine, perspective & remap.
-% color space transformations
-% histograms & back projections
-% contours
-%
-% i/o:
-% displaying images
-% saving/loading to/from file (XML/YAML & image file formats)
-% reading videos & camera feed, writing videos
-%
-% operations on point sets:
-% findcontours, bounding box, convex hull, min area rect,
-% transformations, to/from homogeneous coordinates
-% matching point sets: homography, fundamental matrix, rigid transforms
-%
-% 3d:
-% camera calibration, pose estimation.
-% uncalibrated case
-% stereo: rectification, running stereo correspondence, obtaining the depth.
-%
-% feature detection:
-% features2d toolbox
-%
-% object detection:
-% using a classifier running on a sliding window: cascadeclassifier + hog.
-% using salient point features: features2d -> matching
-%
-% statistical data processing:
-% clustering (k-means),
-% classification + regression (SVM, boosting, k-nearest),
-% compressing data (PCA)
-%
-
-\documentclass[10pt,landscape]{article}
-\usepackage[usenames,dvips,pdftex]{color}
-\usepackage{multicol}
-\usepackage{calc}
-\usepackage{ifthen}
-\usepackage[pdftex]{color,graphicx}
-\usepackage[landscape]{geometry}
-\usepackage{hyperref}
-\usepackage[T1]{fontenc}
-\hypersetup{colorlinks=true, filecolor=black, linkcolor=black, urlcolor=blue, citecolor=black}
-\graphicspath{{./images/}}
-
-% This sets page margins to .5 inch if using letter paper, and to 1cm
-% if using A4 paper. (This probably isn't strictly necessary.)
-% If using another size paper, use default 1cm margins.
-\ifthenelse{\lengthtest { \paperwidth = 11in}}
- { \geometry{top=.5in,left=.5in,right=.5in,bottom=.5in} }
- {\ifthenelse{ \lengthtest{ \paperwidth = 297mm}}
- {\geometry{top=1cm,left=1cm,right=1cm,bottom=1cm} }
- {\geometry{top=1cm,left=1cm,right=1cm,bottom=1cm} }
- }
-
-% Turn off header and footer
-% \pagestyle{empty}
-
-% Redefine section commands to use less space
-\makeatletter
-\renewcommand{\section}{\@startsection{section}{1}{0mm}%
- {-1ex plus -.5ex minus -.2ex}%
- {0.5ex plus .2ex}%x
- {\normalfont\large\bfseries}}
-\renewcommand{\subsection}{\@startsection{subsection}{2}{0mm}%
- {-1explus -.5ex minus -.2ex}%
- {0.5ex plus .2ex}%
- {\normalfont\normalsize\bfseries}}
-\renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{0mm}%
- {-1ex plus -.5ex minus -.2ex}%
- {1ex plus .2ex}%
- {\normalfont\small\bfseries}}
-\makeatother
-
-% Define BibTeX command
-\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em
- T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}
-
-% Don't print section numbers
-\setcounter{secnumdepth}{0}
-
-
-%\setlength{\parindent}{0pt}
-%\setlength{\parskip}{0pt plus 0.5ex}
-
-\newcommand{\ccode}[1]{
-\begin{alltt}
-#1
-\end{alltt}
-}
-
-% -----------------------------------------------------------------------
-
-\begin{document}
-
-\raggedright
-\footnotesize
-\begin{multicols}{3}
-
-
-% multicol parameters
-% These lengths are set only within the two main columns
-%\setlength{\columnseprule}{0.25pt}
-\setlength{\premulticols}{1pt}
-\setlength{\postmulticols}{1pt}
-\setlength{\multicolsep}{1pt}
-\setlength{\columnsep}{2pt}
-
-\begin{center}
- \Large{\textbf{OpenCV 2.4 Cheat Sheet (C++)}} \\
-\end{center}
-\newlength{\MyLen}
-\settowidth{\MyLen}{\texttt{letterpaper}/\texttt{a4paper} \ }
-
-%\section{Filesystem Concepts}
-%\begin{tabular}{@{}p{\the\MyLen}%
- % @{}p{\linewidth-\the\MyLen}@{}}
-%\texttt{\href{http://www.ros.org/wiki/Packages}{package}} & The lowest level of ROS software organization. \\
-%\texttt{\href{http://www.ros.org/wiki/Manifest}{manifest}} & Description of a ROS package. \\
-%\texttt{\href{http://www.ros.org/wiki/Stack}{stack}} & Collections of ROS packages that form a higher-level library. \\
-%\texttt{\href{http://www.ros.org/wiki/Stack Manifest}{stack manifest}} & Description of a ROS stack.
-%\end{tabular}
-
-\emph{The OpenCV C++ reference manual is here: \url{http://docs.opencv.org}. Use \textbf{Quick Search} to find descriptions of the particular functions and classes}
-
-\section{Key OpenCV Classes}
-\begin{tabular}{@{}p{\the\MyLen}%
- @{}p{\linewidth-\the\MyLen}@{}}
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Point_}{Point\_}} & Template 2D point class \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Point3_}{Point3\_}} & Template 3D point class \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Size_}{Size\_}} & Template size (width, height) class \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Vec}{Vec}} & Template short vector class \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Matx}{Matx}} & Template small matrix class \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Scalar_}{Scalar}} & 4-element vector \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Rect_}{Rect}} & Rectangle \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Range}{Range}} & Integer value range \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Mat}{Mat}} & 2D or multi-dimensional dense array (can be used to store matrices, images, histograms, feature descriptors, voxel volumes etc.)\\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#sparsemat}{SparseMat}} & Multi-dimensional sparse array \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Ptr}{Ptr}} & Template smart pointer class
-\end{tabular}
-
-\section{Matrix Basics}
-\begin{tabbing}
-
-\textbf{Cr}\=\textbf{ea}\=\textbf{te}\={} \textbf{a matrix} \\
-\> \texttt{Mat image(240, 320, CV\_8UC3);} \\
-
-\textbf{[Re]allocate a pre-declared matrix}\\
-\> \texttt{image.\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-create}{create}(480, 640, CV\_8UC3);}\\
-
-\textbf{Create a matrix initialized with a constant}\\
-\> \texttt{Mat A33(3, 3, CV\_32F, Scalar(5));} \\
-\> \texttt{Mat B33(3, 3, CV\_32F); B33 = Scalar(5);} \\
-\> \texttt{Mat C33 = Mat::ones(3, 3, CV\_32F)*5.;} \\
-\> \texttt{Mat D33 = Mat::zeros(3, 3, CV\_32F) + 5.;} \\
-
-\textbf{Create a matrix initialized with specified values}\\
-\> \texttt{double a = CV\_PI/3;} \\
-\> \texttt{Mat A22 = (Mat\_<float>(2, 2) <<} \\
-\> \> \texttt{cos(a), -sin(a), sin(a), cos(a));} \\
-\> \texttt{float B22data[] = \{cos(a), -sin(a), sin(a), cos(a)\};} \\
-\> \texttt{Mat B22 = Mat(2, 2, CV\_32F, B22data).clone();}\\
-
-\textbf{Initialize a random matrix}\\
-\> \texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#randu}{randu}(image, Scalar(0), Scalar(256)); }\textit{// uniform dist}\\
-\> \texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#randn}{randn}(image, Scalar(128), Scalar(10)); }\textit{// Gaussian dist}\\
-
-\textbf{Convert matrix to/from other structures}\\
-\>\textbf{(without copying the data)}\\
-\> \texttt{Mat image\_alias = image;}\\
-\> \texttt{float* Idata=new float[480*640*3];}\\
-\> \texttt{Mat I(480, 640, CV\_32FC3, Idata);}\\
-\> \texttt{vector<Point> iptvec(10);}\\
-\> \texttt{Mat iP(iptvec); }\textit{// iP -- 10x1 CV\_32SC2 matrix}\\
-\> \texttt{IplImage* oldC0 = cvCreateImage(cvSize(320,240),16,1);}\\
-\> \texttt{Mat newC = cvarrToMat(oldC0);}\\
-\> \texttt{IplImage oldC1 = newC; CvMat oldC2 = newC;}\\
-
-\textbf{... (with copying the data)}\\
-\> \texttt{Mat newC2 = cvarrToMat(oldC0).clone();}\\
-\> \texttt{vector<Point2f> ptvec = Mat\_<Point2f>(iP);}\\
-
-\>\\
-\textbf{Access matrix elements}\\
-\> \texttt{A33.at<float>(i,j) = A33.at<float>(j,i)+1;}\\
-\> \texttt{Mat dyImage(image.size(), image.type());}\\
-\> \texttt{for(int y = 1; y < image.rows-1; y++) \{}\\
-\> \> \texttt{Vec3b* prevRow = image.ptr<Vec3b>(y-1);}\\
-\> \> \texttt{Vec3b* nextRow = image.ptr<Vec3b>(y+1);}\\
-\> \> \texttt{for(int x = 0; x < image.cols; x++)}\\
-\> \> \> \texttt{for(int c = 0; c < 3; c++)}\\
-\> \> \> \texttt{ dyImage.at<Vec3b>(y,x)[c] =}\\
-\> \> \> \texttt{ saturate\_cast<uchar>(}\\
-\> \> \> \texttt{ nextRow[x][c] - prevRow[x][c]);}\\
-\> \texttt{\} }\\
-\> \texttt{Mat\_<Vec3b>::iterator it = image.begin<Vec3b>(),}\\
-\> \> \texttt{itEnd = image.end<Vec3b>();}\\
-\> \texttt{for(; it != itEnd; ++it)}\\
-\> \> \texttt{(*it)[1] \textasciicircum{}= 255;}\\
-
-\end{tabbing}
-
-\section{Matrix Manipulations: Copying, Shuffling, Part Access}
-\begin{tabular}{@{}p{\the\MyLen}%
- @{}p{\linewidth-\the\MyLen}@{}}
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-copyto}{src.copyTo(dst)}} & Copy matrix to another one \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-convertto}{src.convertTo(dst,type,scale,shift)}} & \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Scale and convert to another datatype \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-clone}{m.clone()}} & Make deep copy of a matrix \\
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-reshape}{m.reshape(nch,nrows)}} & Change matrix dimensions and/or number of channels without copying data \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-row}{m.row(i)}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-col}{m.col(i)}} & Take a matrix row/column \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-rowrange}{m.rowRange(Range(i1,i2))}}
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-colrange}{m.colRange(Range(j1,j2))}} & \ \ \ \ \ \ \ Take a matrix row/column span \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#mat-diag}{m.diag(i)}} & Take a matrix diagonal \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#Mat}{m(Range(i1,i2),Range(j1,j2)), m(roi)}} & \ \ \ \ \ \ \ \ \ \ \ \ \ Take a submatrix \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#repeat}{m.repeat(ny,nx)}} & Make a bigger matrix from a smaller one \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#flip}{flip(src,dst,dir)}} & Reverse the order of matrix rows and/or columns \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#split}{split(...)}} & Split multi-channel matrix into separate channels \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#merge}{merge(...)}} & Make a multi-channel matrix out of the separate channels \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#mixchannels}{mixChannels(...)}} & Generalized form of split() and merge() \\
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#randshuffle}{randShuffle(...)}} & Randomly shuffle matrix elements \\
-
-\end{tabular}
-
-\begin{tabbing}
-Exa\=mple 1. Smooth image ROI in-place\\
-\>\texttt{Mat imgroi = image(Rect(10, 20, 100, 100));}\\
-\>\texttt{GaussianBlur(imgroi, imgroi, Size(5, 5), 1.2, 1.2);}\\
-Example 2. Somewhere in a linear algebra algorithm \\
-\>\texttt{m.row(i) += m.row(j)*alpha;}\\
-Example 3. Copy image ROI to another image with conversion\\
-\>\texttt{Rect r(1, 1, 10, 20);}\\
-\>\texttt{Mat dstroi = dst(Rect(0,10,r.width,r.height));}\\
-\>\texttt{src(r).convertTo(dstroi, dstroi.type(), 1, 0);}\\
-\end{tabbing}
-
-\section{Simple Matrix Operations}
-
-OpenCV implements most common arithmetical, logical and
-other matrix operations, such as
-
-\begin{itemize}
-\item
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#add}{add()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#subtract}{subtract()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#multiply}{multiply()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#divide}{divide()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#absdiff}{absdiff()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#bitwise-and}{bitwise\_and()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#bitwise-or}{bitwise\_or()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#bitwise-xor}{bitwise\_xor()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#max}{max()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#min}{min()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#compare}{compare()}}
-
--- correspondingly, addition, subtraction, element-wise multiplication ... comparison of two matrices or a matrix and a scalar.
-
-\begin{tabbing}
-Exa\=mple. \href{http://en.wikipedia.org/wiki/Alpha_compositing}{Alpha compositing} function:\\
-\texttt{void alphaCompose(const Mat\& rgba1,}\\
-\> \texttt{const Mat\& rgba2, Mat\& rgba\_dest)}\\
-\texttt{\{ }\\
-\> \texttt{Mat a1(rgba1.size(), rgba1.type()), ra1;}\\
-\> \texttt{Mat a2(rgba2.size(), rgba2.type());}\\
-\> \texttt{int mixch[]=\{3, 0, 3, 1, 3, 2, 3, 3\};}\\
-\> \texttt{mixChannels(\&rgba1, 1, \&a1, 1, mixch, 4);}\\
-\> \texttt{mixChannels(\&rgba2, 1, \&a2, 1, mixch, 4);}\\
-\> \texttt{subtract(Scalar::all(255), a1, ra1);}\\
-\> \texttt{bitwise\_or(a1, Scalar(0,0,0,255), a1);}\\
-\> \texttt{bitwise\_or(a2, Scalar(0,0,0,255), a2);}\\
-\> \texttt{multiply(a2, ra1, a2, 1./255);}\\
-\> \texttt{multiply(a1, rgba1, a1, 1./255);}\\
-\> \texttt{multiply(a2, rgba2, a2, 1./255);}\\
-\> \texttt{add(a1, a2, rgba\_dest);}\\
-\texttt{\}}
-\end{tabbing}
-
-\item
-
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#sum}{sum()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#mean}{mean()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#meanstddev}{meanStdDev()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#norm}{norm()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#countnonzero}{countNonZero()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#minmaxloc}{minMaxLoc()}},
-
--- various statistics of matrix elements.
-
-\item
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#exp}{exp()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#log}{log()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#pow}{pow()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#sqrt}{sqrt()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#carttopolar}{cartToPolar()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#polartocart}{polarToCart()}}
-
--- the classical math functions.
-
-\item
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#scaleadd}{scaleAdd()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#transpose}{transpose()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#gemm}{gemm()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#invert}{invert()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#solve}{solve()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#determinant}{determinant()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#trace}{trace()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#eigen}{eigen()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#SVD}{SVD}},
-
--- the algebraic functions + SVD class.
-
-\item
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#dft}{dft()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#idft}{idft()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#dct}{dct()}},
-\texttt{\href{http://docs.opencv.org/modules/core/doc/operations_on_arrays.html\#idct}{idct()}},
-
--- discrete Fourier and cosine transformations
-
-\end{itemize}
-
-For some operations a more convenient \href{http://docs.opencv.org/modules/core/doc/basic_structures.html\#matrix-expressions}{algebraic notation} can be used, for example:
-\begin{tabbing}
-\texttt{Mat}\={} \texttt{delta = (J.t()*J + lambda*}\\
-\>\texttt{Mat::eye(J.cols, J.cols, J.type()))}\\
-\>\texttt{.inv(CV\_SVD)*(J.t()*err);}
-\end{tabbing}
-implements the core of Levenberg-Marquardt optimization algorithm.
-
-\section{Image Processsing}
-
-\subsection{Filtering}
-
-\begin{tabular}{@{}p{\the\MyLen}%
- @{}p{\linewidth-\the\MyLen}@{}}
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#filter2d}{filter2D()}} & Non-separable linear filter \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#sepfilter2d}{sepFilter2D()}} & Separable linear filter \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#blur}{boxFilter()}}, \texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#gaussianblur}{GaussianBlur()}},
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#medianblur}{medianBlur()}},
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#bilateralfilter}{bilateralFilter()}}
-& Smooth the image with one of the linear or non-linear filters \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#sobel}{Sobel()}}, \texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#scharr}{Scharr()}}
-& Compute the spatial image derivatives \\
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#laplacian}{Laplacian()}} & compute Laplacian: $\Delta I = \frac{\partial ^ 2 I}{\partial x^2} + \frac{\partial ^ 2 I}{\partial y^2}$ \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#erode}{erode()}}, \texttt{\href{http://docs.opencv.org/modules/imgproc/doc/filtering.html\#dilate}{dilate()}} & Morphological operations \\
-
-\end{tabular}
-
-\begin{tabbing}
-Exa\=mple. Filter image in-place with a 3x3 high-pass kernel\\
-\> (preserve negative responses by shifting the result by 128):\\
-\texttt{filter2D(image, image, image.depth(), (Mat\_<float>(3,3)<<}\\
-\> \texttt{-1, -1, -1, -1, 9, -1, -1, -1, -1), Point(1,1), 128);}\\
-\end{tabbing}
-
-\subsection{Geometrical Transformations}
-
-\begin{tabular}{@{}p{\the\MyLen}%
- @{}p{\linewidth-\the\MyLen}@{}}
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html\#resize}{resize()}} & Resize image \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html\#getrectsubpix}{getRectSubPix()}} & Extract an image patch \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html\#warpaffine}{warpAffine()}} & Warp image affinely\\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html\#warpperspective}{warpPerspective()}} & Warp image perspectively\\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html\#remap}{remap()}} & Generic image warping\\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html\#convertmaps}{convertMaps()}} & Optimize maps for a faster remap() execution\\
-
-\end{tabular}
-
-\begin{tabbing}
-Example. Decimate image by factor of $\sqrt{2}$:\\
-\texttt{Mat dst; resize(src, dst, Size(), 1./sqrt(2), 1./sqrt(2));}
-\end{tabbing}
-
-\subsection{Various Image Transformations}
-
-\begin{tabular}{@{}p{\the\MyLen}%
- @{}p{\linewidth-\the\MyLen}@{}}
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html\#cvtcolor}{cvtColor()}} & Convert image from one color space to another \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html\#threshold}{threshold()}}, \texttt{\href{http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html\#adaptivethreshold}{adaptivethreshold()}} & Convert grayscale image to binary image using a fixed or a variable threshold \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html\#floodfill}{floodFill()}} & Find a connected component using region growing algorithm\\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html\#integral}{integral()}} & Compute integral image \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html\#distancetransform}{distanceTransform()}}
- & build distance map or discrete Voronoi diagram for a binary image. \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html\#watershed}{watershed()}},
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html\#grabcut}{grabCut()}}
- & marker-based image segmentation algorithms.
- See the samples \texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/cpp/watershed.cpp}{watershed.cpp}} and \texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/cpp/grabcut.cpp}{grabcut.cpp}}.
-
-\end{tabular}
-
-\subsection{Histograms}
-
-\begin{tabular}{@{}p{\the\MyLen}%
- @{}p{\linewidth-\the\MyLen}@{}}
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/histograms.html\#calchist}{calcHist()}} & Compute image(s) histogram \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/histograms.html\#calcbackproject}{calcBackProject()}} & Back-project the histogram \\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/histograms.html\#equalizehist}{equalizeHist()}} & Normalize image brightness and contrast\\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/histograms.html\#comparehist}{compareHist()}} & Compare two histograms\\
-
-\end{tabular}
-
-\begin{tabbing}
-Example. Compute Hue-Saturation histogram of an image:\\
-\texttt{Mat hsv, H;}\\
-\texttt{cvtColor(image, hsv, CV\_BGR2HSV);}\\
-\texttt{int planes[]=\{0, 1\}, hsize[] = \{32, 32\};}\\
-\texttt{calcHist(\&hsv, 1, planes, Mat(), H, 2, hsize, 0);}\\
-\end{tabbing}
-
-\subsection{Contours}
-See \texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/cpp/contours2.cpp}{contours2.cpp}} and \texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/cpp/squares.cpp}{squares.cpp}}
-samples on what are the contours and how to use them.
-
-\section{Data I/O}
-
-\href{http://docs.opencv.org/modules/core/doc/xml_yaml_persistence.html\#xml-yaml-file-storages-writing-to-a-file-storage}{XML/YAML storages} are collections (possibly nested) of scalar values, structures and heterogeneous lists.
-
-\begin{tabbing}
-\textbf{Wr}\=\textbf{iting data to YAML (or XML)}\\
-\texttt{// Type of the file is determined from the extension}\\
-\texttt{FileStorage fs("test.yml", FileStorage::WRITE);}\\
-\texttt{fs << "i" << 5 << "r" << 3.1 << "str" << "ABCDEFGH";}\\
-\texttt{fs << "mtx" << Mat::eye(3,3,CV\_32F);}\\
-\texttt{fs << "mylist" << "[" << CV\_PI << "1+1" <<}\\
-\>\texttt{"\{:" << "month" << 12 << "day" << 31 << "year"}\\
-\>\texttt{<< 1969 << "\}" << "]";}\\
-\texttt{fs << "mystruct" << "\{" << "x" << 1 << "y" << 2 <<}\\
-\>\texttt{"width" << 100 << "height" << 200 << "lbp" << "[:";}\\
-\texttt{const uchar arr[] = \{0, 1, 1, 0, 1, 1, 0, 1\};}\\
-\texttt{fs.writeRaw("u", arr, (int)(sizeof(arr)/sizeof(arr[0])));}\\
-\texttt{fs << "]" << "\}";}
-\end{tabbing}
-
-\emph{Scalars (integers, floating-point numbers, text strings), matrices, STL vectors of scalars and some other types can be written to the file storages using \texttt{<<} operator}
-
-\begin{tabbing}
-\textbf{Re}\=\textbf{ading the data back}\\
-\texttt{// Type of the file is determined from the content}\\
-\texttt{FileStorage fs("test.yml", FileStorage::READ);}\\
-\texttt{int i1 = (int)fs["i"]; double r1 = (double)fs["r"];}\\
-\texttt{string str1 = (string)fs["str"];}\\
-
-\texttt{Mat M; fs["mtx"] >> M;}\\
-
-\texttt{FileNode tl = fs["mylist"];}\\
-\texttt{CV\_Assert(tl.type() == FileNode::SEQ \&\& tl.size() == 3);}\\
-\texttt{double tl0 = (double)tl[0]; string tl1 = (string)tl[1];}\\
-
-\texttt{int m = (int)tl[2]["month"], d = (int)tl[2]["day"];}\\
-\texttt{int year = (int)tl[2]["year"];}\\
-
-\texttt{FileNode tm = fs["mystruct"];}\\
-
-\texttt{Rect r; r.x = (int)tm["x"], r.y = (int)tm["y"];}\\
-\texttt{r.width = (int)tm["width"], r.height = (int)tm["height"];}\\
-
-\texttt{int lbp\_val = 0;}\\
-\texttt{FileNodeIterator it = tm["lbp"].begin();}\\
-
-\texttt{for(int k = 0; k < 8; k++, ++it)}\\
-\>\texttt{lbp\_val |= ((int)*it) << k;}\\
-\end{tabbing}
-
-\emph{Scalars are read using the corresponding FileNode's cast operators. Matrices and some other types are read using \texttt{>>} operator. Lists can be read using FileNodeIterator's.}
-
-\begin{tabbing}
-\textbf{Wr}\=\textbf{iting and reading raster images}\\
-\texttt{\href{http://docs.opencv.org/modules/imgcodecs/doc/reading_and_writing_images.html\#imwrite}{imwrite}("myimage.jpg", image);}\\
-\texttt{Mat image\_color\_copy = \href{http://docs.opencv.org/modules/imgcodecs/doc/reading_and_writing_images.html\#imread}{imread}("myimage.jpg", 1);}\\
-\texttt{Mat image\_grayscale\_copy = \href{http://docs.opencv.org/modules/imgcodecs/doc/reading_and_writing_images.html\#imread}{imread}("myimage.jpg", 0);}\\
-\end{tabbing}
-
-\emph{The functions can read/write images in the following formats: \textbf{BMP (.bmp), JPEG (.jpg, .jpeg), TIFF (.tif, .tiff), PNG (.png), PBM/PGM/PPM (.p?m), Sun Raster (.sr), JPEG 2000 (.jp2)}. Every format supports 8-bit, 1- or 3-channel images. Some formats (PNG, JPEG 2000) support 16 bits per channel.}
-
-\begin{tabbing}
-\textbf{Re}\=\textbf{ading video from a file or from a camera}\\
-\texttt{VideoCapture cap;}\\
-\texttt{if(argc > 1) cap.open(string(argv[1])); else cap.open(0)};\\
-\texttt{Mat frame; namedWindow("video", 1);}\\
-\texttt{for(;;) \{}\\
-\>\texttt{cap >> frame; if(!frame.data) break;}\\
-\>\texttt{imshow("video", frame); if(waitKey(30) >= 0) break;}\\
-\texttt{\} }
-\end{tabbing}
-
-\section{Simple GUI (highgui module)}
-
-\begin{tabular}{@{}p{\the\MyLen}%
- @{}p{\linewidth-\the\MyLen}@{}}
-
-\texttt{\href{http://docs.opencv.org/modules/highgui/doc/user_interface.html\#namedwindow}{namedWindow(winname,flags)}} & \ \ \ \ \ \ \ \ \ \ Create named highgui window \\
-
-\texttt{\href{http://docs.opencv.org/modules/highgui/doc/user_interface.html\#destroywindow}{destroyWindow(winname)}} & \ \ \ Destroy the specified window \\
-
-\texttt{\href{http://docs.opencv.org/modules/highgui/doc/user_interface.html\#imshow}{imshow(winname, mtx)}} & Show image in the window \\
-
-\texttt{\href{http://docs.opencv.org/modules/highgui/doc/user_interface.html\#waitkey}{waitKey(delay)}} & Wait for a key press during the specified time interval (or forever). Process events while waiting. \emph{Do not forget to call this function several times a second in your code.} \\
-
-\texttt{\href{http://docs.opencv.org/modules/highgui/doc/user_interface.html\#createtrackbar}{createTrackbar(...)}} & Add trackbar (slider) to the specified window \\
-
-\texttt{\href{http://docs.opencv.org/modules/highgui/doc/user_interface.html\#setmousecallback}{setMouseCallback(...)}} & \ \ Set the callback on mouse clicks and movements in the specified window \\
-
-\end{tabular}
-
-See \texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/cpp/camshiftdemo.cpp}{camshiftdemo.cpp}} and other \href{https://github.com/Itseez/opencv/tree/master/samples/}{OpenCV samples} on how to use the GUI functions.
-
-\section{Camera Calibration, Pose Estimation and Depth Estimation}
-
-\begin{tabular}{@{}p{\the\MyLen}%
- @{}p{\linewidth-\the\MyLen}@{}}
-
-\texttt{\href{http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html\#calibratecamera}{calibrateCamera()}} & Calibrate camera from several views of a calibration pattern. \\
-
-\texttt{\href{http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html\#findchessboardcorners}{findChessboardCorners()}} & \ \ \ \ \ \ Find feature points on the checkerboard calibration pattern. \\
-
-\texttt{\href{http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html\#solvepnp}{solvePnP()}} & Find the object pose from the known projections of its feature points. \\
-
-\texttt{\href{http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html\#stereocalibrate}{stereoCalibrate()}} & Calibrate stereo camera. \\
-
-\texttt{\href{http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html\#stereorectify}{stereoRectify()}} & Compute the rectification transforms for a calibrated stereo camera.\\
-
-\texttt{\href{http://docs.opencv.org/modules/imgproc/doc/geometric_transformations.html\#initundistortrectifymap}{initUndistortRectifyMap()}} & \ \ \ \ \ \ Compute rectification map (for \texttt{remap()}) for each stereo camera head.\\
-
-\texttt{\href{http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html\#StereoBM}{StereoBM}}, \texttt{\href{http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html\#StereoSGBM}{StereoSGBM}} & The stereo correspondence engines to be run on rectified stereo pairs.\\
-
-\texttt{\href{http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html\#reprojectimageto3d}{reprojectImageTo3D()}} & Convert disparity map to 3D point cloud.\\
-
-\texttt{\href{http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html\#findhomography}{findHomography()}} & Find best-fit perspective transformation between two 2D point sets. \\
-
-\end{tabular}
-
-To calibrate a camera, you can use \texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/cpp/calibration.cpp}{calibration.cpp}} or
-\texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/cpp/stereo\_calib.cpp}{stereo\_calib.cpp}} samples.
-To get the disparity maps and the point clouds, use
-\texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/cpp/stereo\_match.cpp}{stereo\_match.cpp}} sample.
-
-\section{Object Detection}
-
-\begin{tabular}{@{}p{\the\MyLen}%
- @{}p{\linewidth-\the\MyLen}@{}}
- \texttt{\href{http://docs.opencv.org/modules/imgproc/doc/object_detection.html\#matchtemplate}{matchTemplate}} & Compute proximity map for given template.\\
-
-\texttt{\href{http://docs.opencv.org/modules/objdetect/doc/cascade_classification.html\#cascadeclassifier}{CascadeClassifier}} & Viola's Cascade of Boosted classifiers using Haar or LBP features. Suits for detecting faces, facial features and some other objects without diverse textures. See \texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/c/facedetect.cpp}{facedetect.cpp}}\\
-
-\texttt{{HOGDescriptor}} & N. Dalal's object detector using Histogram-of-Oriented-Gradients (HOG) features. Suits for detecting people, cars and other objects with well-defined silhouettes. See \texttt{\href{https://github.com/Itseez/opencv/tree/master/samples/cpp/peopledetect.cpp}{peopledetect.cpp}}\\
-
-\end{tabular}
-
-%
-% feature detection:
-% features2d toolbox
-%
-% object detection:
-% using a classifier running on a sliding window: cascadeclassifier + hog.
-% using salient point features: features2d -> matching
-%
-% statistical data processing:
-% clustering (k-means),
-% classification + regression (SVM, boosting, k-nearest),
-% compressing data (PCA)
-
-\end{multicols}
-\end{document}
+++ /dev/null
-#!/usr/bin/env python
-
-import sys
-
-f=open(sys.argv[1], "rt")
-ll = list(f.readlines())
-f.close()
-f=open(sys.argv[1], "wt")
-singleparam = False
-
-for l in ll:
- l = l.replace("\\code{~const}}{}", "}{\\code{~const}}")
- if l.startswith("\\item[{Parameters}] \\leavevmode"):
- if not l.startswith("\\item[{Parameters}] \\leavevmode\\begin{itemize}"):
- singleparam = True
- l = "\\item[{Parameters}] \\leavevmode\\begin{itemize}[label=]\n"
- if singleparam:
- l += "\\item {}\n"
- elif singleparam and l.startswith("\\end{description}\\end{quote}"):
- l = "\\end{itemize}\n" + l
- singleparam = False
- f.write(l)
-
-f.close()
+++ /dev/null
-.. _Bindings_Basics:
-
-How OpenCV-Python Bindings Works?
-************************************
-
-Goal
-=====
-
-Learn:
-
- * How OpenCV-Python bindings are generated?
- * How to extend new OpenCV modules to Python?
-
-How OpenCV-Python bindings are generated?
-=========================================
-
-In OpenCV, all algorithms are implemented in C++. But these algorithms can be used from different languages like Python, Java etc. This is made possible by the bindings generators. These generators create a bridge between C++ and Python which enables users to call C++ functions from Python. To get a complete picture of what is happening in background, a good knowledge of Python/C API is required. A simple example on extending C++ functions to Python can be found in official Python documentation[1]. So extending all functions in OpenCV to Python by writing their wrapper functions manually is a time-consuming task. So OpenCV does it in a more intelligent way. OpenCV generates these wrapper functions automatically from the C++ headers using some Python scripts which are located in ``modules/python/src2``. We will look into what they do.
-
-First, ``modules/python/CMakeFiles.txt`` is a CMake script which checks the modules to be extended to Python. It will automatically check all the modules to be extended and grab their header files. These header files contain list of all classes, functions, constants etc. for that particular modules.
-
-Second, these header files are passed to a Python script, ``modules/python/src2/gen2.py``. This is the Python bindings generator script. It calls another Python script ``modules/python/src2/hdr_parser.py``. This is the header parser script. This header parser splits the complete header file into small Python lists. So these lists contain all details about a particular function, class etc. For example, a function will be parsed to get a list containing function name, return type, input arguments, argument types etc. Final list contains details of all the functions, structs, classes etc. in that header file.
-
-But header parser doesn't parse all the functions/classes in the header file. The developer has to specify which functions should be exported to Python. For that, there are certain macros added to the beginning of these declarations which enables the header parser to identify functions to be parsed. These macros are added by the developer who programs the particular function. In short, the developer decides which functions should be extended to Python and which are not. Details of those macros will be given in next session.
-
-So header parser returns a final big list of parsed functions. Our generator script (gen2.py) will create wrapper functions for all the functions/classes/enums/structs parsed by header parser (You can find these header files during compilation in the ``build/modules/python/`` folder as ``pyopencv_generated_*.h`` files). But there may be some basic OpenCV datatypes like Mat, Vec4i, Size. They need to be extended manually. For example, a Mat type should be extended to Numpy array, Size should be extended to a tuple of two integers etc. Similarly, there may be some complex structs/classes/functions etc. which need to be extended manually. All such manual wrapper functions are placed in ``modules/python/src2/pycv2.hpp``.
-
-So now only thing left is the compilation of these wrapper files which gives us **cv2** module. So when you call a function, say ``res = equalizeHist(img1,img2)`` in Python, you pass two numpy arrays and you expect another numpy array as the output. So these numpy arrays are converted to ``cv::Mat`` and then calls the ``equalizeHist()`` function in C++. Final result, ``res`` will be converted back into a Numpy array. So in short, almost all operations are done in C++ which gives us almost same speed as that of C++.
-
-So this is the basic version of how OpenCV-Python bindings are generated.
-
-
-How to extend new modules to Python?
-=====================================
-
-Header parser parse the header files based on some wrapper macros added to function declaration. Enumeration constants don't need any wrapper macros. They are automatically wrapped. But remaining functions, classes etc. need wrapper macros.
-
-Functions are extended using ``CV_EXPORTS_W`` macro. An example is shown below.
-
-.. code-block:: cpp
-
- CV_EXPORTS_W void equalizeHist( InputArray src, OutputArray dst );
-
-Header parser can understand the input and output arguments from keywords like ``InputArray, OutputArray`` etc. But sometimes, we may need to hardcode inputs and outputs. For that, macros like ``CV_OUT, CV_IN_OUT`` etc. are used.
-
-.. code-block:: cpp
-
- CV_EXPORTS_W void minEnclosingCircle( InputArray points,
- CV_OUT Point2f& center, CV_OUT float& radius );
-
-For large classes also, ``CV_EXPORTS_W`` is used. To extend class methods, ``CV_WRAP`` is used. Similarly, ``CV_PROP`` is used for class fields.
-
-.. code-block:: cpp
-
- class CV_EXPORTS_W CLAHE : public Algorithm
- {
- public:
- CV_WRAP virtual void apply(InputArray src, OutputArray dst) = 0;
-
- CV_WRAP virtual void setClipLimit(double clipLimit) = 0;
- CV_WRAP virtual double getClipLimit() const = 0;
- }
-
-Overloaded functions can be extended using ``CV_EXPORTS_AS``. But we need to pass a new name so that each function will be called by that name in Python. Take the case of integral function below. Three functions are available, so each one is named with a suffix in Python. Similarly ``CV_WRAP_AS`` can be used to wrap overloaded methods.
-
-.. code-block:: cpp
-
- //! computes the integral image
- CV_EXPORTS_W void integral( InputArray src, OutputArray sum, int sdepth = -1 );
-
- //! computes the integral image and integral for the squared image
- CV_EXPORTS_AS(integral2) void integral( InputArray src, OutputArray sum,
- OutputArray sqsum, int sdepth = -1, int sqdepth = -1 );
-
- //! computes the integral image, integral for the squared image and the tilted integral image
- CV_EXPORTS_AS(integral3) void integral( InputArray src, OutputArray sum,
- OutputArray sqsum, OutputArray tilted,
- int sdepth = -1, int sqdepth = -1 );
-
-Small classes/structs are extended using ``CV_EXPORTS_W_SIMPLE``. These structs are passed by value to C++ functions. Examples are KeyPoint, Match etc. Their methods are extended by ``CV_WRAP`` and fields are extended by ``CV_PROP_RW``.
-
-.. code-block:: cpp
-
- class CV_EXPORTS_W_SIMPLE DMatch
- {
- public:
- CV_WRAP DMatch();
- CV_WRAP DMatch(int _queryIdx, int _trainIdx, float _distance);
- CV_WRAP DMatch(int _queryIdx, int _trainIdx, int _imgIdx, float _distance);
-
- CV_PROP_RW int queryIdx; // query descriptor index
- CV_PROP_RW int trainIdx; // train descriptor index
- CV_PROP_RW int imgIdx; // train image index
-
- CV_PROP_RW float distance;
- };
-
-Some other small classes/structs can be exported using ``CV_EXPORTS_W_MAP`` where it is exported to a Python native dictionary. Moments() is an example of it.
-
-.. code-block:: cpp
-
- class CV_EXPORTS_W_MAP Moments
- {
- public:
- //! spatial moments
- CV_PROP_RW double m00, m10, m01, m20, m11, m02, m30, m21, m12, m03;
- //! central moments
- CV_PROP_RW double mu20, mu11, mu02, mu30, mu21, mu12, mu03;
- //! central normalized moments
- CV_PROP_RW double nu20, nu11, nu02, nu30, nu21, nu12, nu03;
- };
-
-So these are the major extension macros available in OpenCV. Typically, a developer has to put proper macros in their appropriate positions. Rest is done by generator scripts. Sometimes, there may be an exceptional cases where generator scripts cannot create the wrappers. Such functions need to be handled manually. But most of the time, a code written according to OpenCV coding guidelines will be automatically wrapped by generator scripts.
+++ /dev/null
-.. _PY_Table-Of-Content-Bindings:
-
-
-OpenCV-Python Bindings
---------------------------------
-
-Here, you will learn how OpenCV-Python bindings are generated.
-
-
-* :ref:`Bindings_Basics`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |bind1| Learn how OpenCV-Python bindings are generated.
-
- =========== ======================================================
-
- .. |bind1| image:: images/nlm_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_bindings_basics/py_bindings_basics
+++ /dev/null
-.. _calibration:
-
-
-Camera Calibration
-********************
-
-Goal
-=======
-
-In this section,
- * We will learn about distortions in camera, intrinsic and extrinsic parameters of camera etc.
- * We will learn to find these parameters, undistort images etc.
-
-
-Basics
-========
-
-Today's cheap pinhole cameras introduces a lot of distortion to images. Two major distortions are radial distortion and tangential distortion.
-
-Due to radial distortion, straight lines will appear curved. Its effect is more as we move away from the center of image. For example, one image is shown below, where two edges of a chess board are marked with red lines. But you can see that border is not a straight line and doesn't match with the red line. All the expected straight lines are bulged out. Visit `Distortion (optics) <http://en.wikipedia.org/wiki/Distortion_%28optics%29>`_ for more details.
-
- .. image:: images/calib_radial.jpg
- :alt: Radial Distortion
- :align: center
-
-This distortion is solved as follows:
-
-.. math::
-
- x_{corrected} = x( 1 + k_1 r^2 + k_2 r^4 + k_3 r^6) \\
- y_{corrected} = y( 1 + k_1 r^2 + k_2 r^4 + k_3 r^6)
-
-
-Similarly, another distortion is the tangential distortion which occurs because image taking lense is not aligned perfectly parallel to the imaging plane. So some areas in image may look nearer than expected. It is solved as below:
-
-
-.. math::
-
- x_{corrected} = x + [ 2p_1xy + p_2(r^2+2x^2)] \\
- y_{corrected} = y + [ p_1(r^2+ 2y^2)+ 2p_2xy]
-
-
-In short, we need to find five parameters, known as distortion coefficients given by:
-
-.. math::
-
- Distortion \; coefficients=(k_1 \hspace{10pt} k_2 \hspace{10pt} p_1 \hspace{10pt} p_2 \hspace{10pt} k_3)
-
-
-In addition to this, we need to find a few more information, like intrinsic and extrinsic parameters of a camera. Intrinsic parameters are specific to a camera. It includes information like focal length (:math:`f_x,f_y`), optical centers (:math:`c_x, c_y`) etc. It is also called camera matrix. It depends on the camera only, so once calculated, it can be stored for future purposes. It is expressed as a 3x3 matrix:
-
-.. math::
-
- camera \; matrix = \left [ \begin{matrix} f_x & 0 & c_x \\ 0 & f_y & c_y \\ 0 & 0 & 1 \end{matrix} \right ]
-
-
-Extrinsic parameters corresponds to rotation and translation vectors which translates a coordinates of a 3D point to a coordinate system.
-
-
-For stereo applications, these distortions need to be corrected first. To find all these parameters, what we have to do is to provide some sample images of a well defined pattern (eg, chess board). We find some specific points in it ( square corners in chess board). We know its coordinates in real world space and we know its coordinates in image. With these data, some mathematical problem is solved in background to get the distortion coefficients. That is the summary of the whole story. For better results, we need atleast 10 test patterns.
-
-
-Code
-========
-
-As mentioned above, we need atleast 10 test patterns for camera calibration. OpenCV comes with some images of chess board (see ``samples/cpp/left01.jpg -- left14.jpg``), so we will utilize it. For sake of understanding, consider just one image of a chess board. Important input datas needed for camera calibration is a set of 3D real world points and its corresponding 2D image points. 2D image points are OK which we can easily find from the image. (These image points are locations where two black squares touch each other in chess boards)
-
-What about the 3D points from real world space? Those images are taken from a static camera and chess boards are placed at different locations and orientations. So we need to know :math:`(X,Y,Z)` values. But for simplicity, we can say chess board was kept stationary at XY plane, (so Z=0 always) and camera was moved accordingly. This consideration helps us to find only X,Y values. Now for X,Y values, we can simply pass the points as (0,0), (1,0), (2,0), ... which denotes the location of points. In this case, the results we get will be in the scale of size of chess board square. But if we know the square size, (say 30 mm), and we can pass the values as (0,0),(30,0),(60,0),..., we get the results in mm. (In this case, we don't know square size since we didn't take those images, so we pass in terms of square size).
-
-3D points are called **object points** and 2D image points are called **image points.**
-
-Setup
----------
-
-So to find pattern in chess board, we use the function, **cv2.findChessboardCorners()**. We also need to pass what kind of pattern we are looking, like 8x8 grid, 5x5 grid etc. In this example, we use 7x6 grid. (Normally a chess board has 8x8 squares and 7x7 internal corners). It returns the corner points and retval which will be True if pattern is obtained. These corners will be placed in an order (from left-to-right, top-to-bottom)
-
-.. seealso:: This function may not be able to find the required pattern in all the images. So one good option is to write the code such that, it starts the camera and check each frame for required pattern. Once pattern is obtained, find the corners and store it in a list. Also provides some interval before reading next frame so that we can adjust our chess board in different direction. Continue this process until required number of good patterns are obtained. Even in the example provided here, we are not sure out of 14 images given, how many are good. So we read all the images and take the good ones.
-
-.. seealso:: Instead of chess board, we can use some circular grid, but then use the function **cv2.findCirclesGrid()** to find the pattern. It is said that less number of images are enough when using circular grid.
-
-Once we find the corners, we can increase their accuracy using **cv2.cornerSubPix()**. We can also draw the pattern using **cv2.drawChessboardCorners()**. All these steps are included in below code:
-
-::
-
- import numpy as np
- import cv2
- import glob
-
- # termination criteria
- criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001)
-
- # prepare object points, like (0,0,0), (1,0,0), (2,0,0) ....,(6,5,0)
- objp = np.zeros((6*7,3), np.float32)
- objp[:,:2] = np.mgrid[0:7,0:6].T.reshape(-1,2)
-
- # Arrays to store object points and image points from all the images.
- objpoints = [] # 3d point in real world space
- imgpoints = [] # 2d points in image plane.
-
- images = glob.glob('*.jpg')
-
- for fname in images:
- img = cv2.imread(fname)
- gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
-
- # Find the chess board corners
- ret, corners = cv2.findChessboardCorners(gray, (7,6),None)
-
- # If found, add object points, image points (after refining them)
- if ret == True:
- objpoints.append(objp)
-
- cv2.cornerSubPix(gray,corners,(11,11),(-1,-1),criteria)
- imgpoints.append(corners)
-
- # Draw and display the corners
- cv2.drawChessboardCorners(img, (7,6), corners2,ret)
- cv2.imshow('img',img)
- cv2.waitKey(500)
-
- cv2.destroyAllWindows()
-
-One image with pattern drawn on it is shown below:
-
- .. image:: images/calib_pattern.jpg
- :alt: Calibration Pattern
- :align: center
-
-
-Calibration
-------------
-
-So now we have our object points and image points we are ready to go for calibration. For that we use the function, **cv2.calibrateCamera()**. It returns the camera matrix, distortion coefficients, rotation and translation vectors etc.
-::
-
- ret, mtx, dist, rvecs, tvecs = cv2.calibrateCamera(objpoints, imgpoints, gray.shape[::-1],None,None)
-
-
-Undistortion
----------------
-
-We have got what we were trying. Now we can take an image and undistort it. OpenCV comes with two methods, we will see both. But before that, we can refine the camera matrix based on a free scaling parameter using **cv2.getOptimalNewCameraMatrix()**. If the scaling parameter ``alpha=0``, it returns undistorted image with minimum unwanted pixels. So it may even remove some pixels at image corners. If ``alpha=1``, all pixels are retained with some extra black images. It also returns an image ROI which can be used to crop the result.
-
-So we take a new image (``left12.jpg`` in this case. That is the first image in this chapter)
-::
-
- img = cv2.imread('left12.jpg')
- h, w = img.shape[:2]
- newcameramtx, roi=cv2.getOptimalNewCameraMatrix(mtx,dist,(w,h),1,(w,h))
-
-1. Using **cv2.undistort()**
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is the shortest path. Just call the function and use ROI obtained above to crop the result.
-::
-
- # undistort
- dst = cv2.undistort(img, mtx, dist, None, newcameramtx)
-
- # crop the image
- x,y,w,h = roi
- dst = dst[y:y+h, x:x+w]
- cv2.imwrite('calibresult.png',dst)
-
-
-2. Using **remapping**
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is curved path. First find a mapping function from distorted image to undistorted image. Then use the remap function.
-::
-
- # undistort
- mapx,mapy = cv2.initUndistortRectifyMap(mtx,dist,None,newcameramtx,(w,h),5)
- dst = cv2.remap(img,mapx,mapy,cv2.INTER_LINEAR)
-
- # crop the image
- x,y,w,h = roi
- dst = dst[y:y+h, x:x+w]
- cv2.imwrite('calibresult.png',dst)
-
-Both the methods give the same result. See the result below:
-
- .. image:: images/calib_result.jpg
- :alt: Calibration Result
- :align: center
-
-You can see in the result that all the edges are straight.
-
-Now you can store the camera matrix and distortion coefficients using write functions in Numpy (np.savez, np.savetxt etc) for future uses.
-
-Re-projection Error
-=======================
-Re-projection error gives a good estimation of just how exact is the found parameters. This should be as close to zero as possible. Given the intrinsic, distortion, rotation and translation matrices, we first transform the object point to image point using **cv2.projectPoints()**. Then we calculate the absolute norm between what we got with our transformation and the corner finding algorithm. To find the average error we calculate the arithmetical mean of the errors calculate for all the calibration images.
-::
-
- mean_error = 0
- for i in xrange(len(objpoints)):
- imgpoints2, _ = cv2.projectPoints(objpoints[i], rvecs[i], tvecs[i], mtx, dist)
- error = cv2.norm(imgpoints[i],imgpoints2, cv2.NORM_L2)/len(imgpoints2)
- tot_error += error
-
- print "total error: ", mean_error/len(objpoints)
-
-
-Additional Resources
-======================
-
-
-
-Exercises
-============
-
-#. Try camera calibration with circular grid.
+++ /dev/null
-.. _py_depthmap:
-
-
-Depth Map from Stereo Images
-******************************
-
-Goal
-=======
-
-In this session,
- * We will learn to create depth map from stereo images.
-
-
-Basics
-===========
-In last session, we saw basic concepts like epipolar constraints and other related terms. We also saw that if we have two images of same scene, we can get depth information from that in an intuitive way. Below is an image and some simple mathematical formulas which proves that intuition. (Image Courtesy :
-
- .. image:: images/stereo_depth.jpg
- :alt: Calculating depth
- :align: center
-
-The above diagram contains equivalent triangles. Writing their equivalent equations will yield us following result:
-
-.. math::
-
- disparity = x - x' = \frac{Bf}{Z}
-
-:math:`x` and :math:`x'` are the distance between points in image plane corresponding to the scene point 3D and their camera center. :math:`B` is the distance between two cameras (which we know) and :math:`f` is the focal length of camera (already known). So in short, above equation says that the depth of a point in a scene is inversely proportional to the difference in distance of corresponding image points and their camera centers. So with this information, we can derive the depth of all pixels in an image.
-
-So it finds corresponding matches between two images. We have already seen how epiline constraint make this operation faster and accurate. Once it finds matches, it finds the disparity. Let's see how we can do it with OpenCV.
-
-
-Code
-========
-
-Below code snippet shows a simple procedure to create disparity map.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- imgL = cv2.imread('tsukuba_l.png',0)
- imgR = cv2.imread('tsukuba_r.png',0)
-
- stereo = cv2.createStereoBM(numDisparities=16, blockSize=15)
- disparity = stereo.compute(imgL,imgR)
- plt.imshow(disparity,'gray')
- plt.show()
-
-Below image contains the original image (left) and its disparity map (right). As you can see, result is contaminated with high degree of noise. By adjusting the values of numDisparities and blockSize, you can get a better result.
-
- .. image:: images/disparity_map.jpg
- :alt: Disparity Map
- :align: center
-
-.. note:: More details to be added
-
-
-Additional Resources
-=============================
-
-
-Exercises
-============
-
-1. OpenCV samples contain an example of generating disparity map and its 3D reconstruction. Check ``stereo_match.py`` in OpenCV-Python samples.
+++ /dev/null
-.. _epipolar_geometry:
-
-
-Epipolar Geometry
-*********************
-
-
-Goal
-========
-In this section,
-
- * We will learn about the basics of multiview geometry
- * We will see what is epipole, epipolar lines, epipolar constraint etc.
-
-
-Basic Concepts
-=================
-
-When we take an image using pin-hole camera, we loose an important information, ie depth of the image. Or how far is each point in the image from the camera because it is a 3D-to-2D conversion. So it is an important question whether we can find the depth information using these cameras. And the answer is to use more than one camera. Our eyes works in similar way where we use two cameras (two eyes) which is called stereo vision. So let's see what OpenCV provides in this field.
-
-(*Learning OpenCV* by Gary Bradsky has a lot of information in this field.)
-
-Before going to depth images, let's first understand some basic concepts in multiview geometry. In this section we will deal with epipolar geometry. See the image below which shows a basic setup with two cameras taking the image of same scene.
-
- .. image:: images/epipolar.jpg
- :alt: Epipolar geometry
- :align: center
-
-
-If we are using only the left camera, we can't find the 3D point corresponding to the point :math:`x` in image because every point on the line :math:`OX` projects to the same point on the image plane. But consider the right image also. Now different points on the line :math:`OX` projects to different points (:math:`x'`) in right plane. So with these two images, we can triangulate the correct 3D point. This is the whole idea.
-
-The projection of the different points on :math:`OX` form a line on right plane (line :math:`l'`). We call it **epiline** corresponding to the point :math:`x`. It means, to find the point :math:`x` on the right image, search along this epiline. It should be somewhere on this line (Think of it this way, to find the matching point in other image, you need not search the whole image, just search along the epiline. So it provides better performance and accuracy). This is called **Epipolar Constraint**. Similarly all points will have its corresponding epilines in the other image. The plane :math:`XOO'` is called **Epipolar Plane**.
-
-:math:`O` and :math:`O'` are the camera centers. From the setup given above, you can see that projection of right camera :math:`O'` is seen on the left image at the point, :math:`e`. It is called the **epipole**. Epipole is the point of intersection of line through camera centers and the image planes. Similarly :math:`e'` is the epipole of the left camera. In some cases, you won't be able to locate the epipole in the image, they may be outside the image (which means, one camera doesn't see the other).
-
-All the epilines pass through its epipole. So to find the location of epipole, we can find many epilines and find their intersection point.
-
-So in this session, we focus on finding epipolar lines and epipoles. But to find them, we need two more ingredients, **Fundamental Matrix (F)** and **Essential Matrix (E)**. Essential Matrix contains the information about translation and rotation, which describe the location of the second camera relative to the first in global coordinates. See the image below (Image courtesy: Learning OpenCV by Gary Bradsky):
-
- .. image:: images/essential_matrix.jpg
- :alt: Essential Matrix
- :align: center
-
-But we prefer measurements to be done in pixel coordinates, right? Fundamental Matrix contains the same information as Essential Matrix in addition to the information about the intrinsics of both cameras so that we can relate the two cameras in pixel coordinates. (If we are using rectified images and normalize the point by dividing by the focal lengths, :math:`F=E`). In simple words, Fundamental Matrix F, maps a point in one image to a line (epiline) in the other image. This is calculated from matching points from both the images. A minimum of 8 such points are required to find the fundamental matrix (while using 8-point algorithm). More points are preferred and use RANSAC to get a more robust result.
-
-
-Code
-=========
-
-So first we need to find as many possible matches between two images to find the fundamental matrix. For this, we use SIFT descriptors with FLANN based matcher and ratio test.
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img1 = cv2.imread('myleft.jpg',0) #queryimage # left image
- img2 = cv2.imread('myright.jpg',0) #trainimage # right image
-
- sift = cv2.SIFT()
-
- # find the keypoints and descriptors with SIFT
- kp1, des1 = sift.detectAndCompute(img1,None)
- kp2, des2 = sift.detectAndCompute(img2,None)
-
- # FLANN parameters
- FLANN_INDEX_KDTREE = 0
- index_params = dict(algorithm = FLANN_INDEX_KDTREE, trees = 5)
- search_params = dict(checks=50)
-
- flann = cv2.FlannBasedMatcher(index_params,search_params)
- matches = flann.knnMatch(des1,des2,k=2)
-
- good = []
- pts1 = []
- pts2 = []
-
- # ratio test as per Lowe's paper
- for i,(m,n) in enumerate(matches):
- if m.distance < 0.8*n.distance:
- good.append(m)
- pts2.append(kp2[m.trainIdx].pt)
- pts1.append(kp1[m.queryIdx].pt)
-
-
-Now we have the list of best matches from both the images. Let's find the Fundamental Matrix.
-::
-
- pts1 = np.int32(pts1)
- pts2 = np.int32(pts2)
- F, mask = cv2.findFundamentalMat(pts1,pts2,cv2.FM_LMEDS)
-
- # We select only inlier points
- pts1 = pts1[mask.ravel()==1]
- pts2 = pts2[mask.ravel()==1]
-
-
-Next we find the epilines. Epilines corresponding to the points in first image is drawn on second image. So mentioning of correct images are important here. We get an array of lines. So we define a new function to draw these lines on the images.
-::
-
- def drawlines(img1,img2,lines,pts1,pts2):
- ''' img1 - image on which we draw the epilines for the points in img2
- lines - corresponding epilines '''
- r,c = img1.shape
- img1 = cv2.cvtColor(img1,cv2.COLOR_GRAY2BGR)
- img2 = cv2.cvtColor(img2,cv2.COLOR_GRAY2BGR)
- for r,pt1,pt2 in zip(lines,pts1,pts2):
- color = tuple(np.random.randint(0,255,3).tolist())
- x0,y0 = map(int, [0, -r[2]/r[1] ])
- x1,y1 = map(int, [c, -(r[2]+r[0]*c)/r[1] ])
- img1 = cv2.line(img1, (x0,y0), (x1,y1), color,1)
- img1 = cv2.circle(img1,tuple(pt1),5,color,-1)
- img2 = cv2.circle(img2,tuple(pt2),5,color,-1)
- return img1,img2
-
-
-Now we find the epilines in both the images and draw them.
-::
-
- # Find epilines corresponding to points in right image (second image) and
- # drawing its lines on left image
- lines1 = cv2.computeCorrespondEpilines(pts2.reshape(-1,1,2), 2,F)
- lines1 = lines1.reshape(-1,3)
- img5,img6 = drawlines(img1,img2,lines1,pts1,pts2)
-
- # Find epilines corresponding to points in left image (first image) and
- # drawing its lines on right image
- lines2 = cv2.computeCorrespondEpilines(pts1.reshape(-1,1,2), 1,F)
- lines2 = lines2.reshape(-1,3)
- img3,img4 = drawlines(img2,img1,lines2,pts2,pts1)
-
- plt.subplot(121),plt.imshow(img5)
- plt.subplot(122),plt.imshow(img3)
- plt.show()
-
-
-Below is the result we get:
-
- .. image:: images/epiresult.jpg
- :alt: Epilines
- :align: center
-
-
-You can see in the left image that all epilines are converging at a point outside the image at right side. That meeting point is the epipole.
-
-For better results, images with good resolution and many non-planar points should be used.
-
-
-Additional Resources
-==========================
-
-
-Exercises
-=============
-
-#. One important topic is the forward movement of camera. Then epipoles will be seen at the same locations in both with epilines emerging from a fixed point. `See this discussion <http://answers.opencv.org/question/17912/location-of-epipole/>`_.
-
-#. Fundamental Matrix estimation is sensitive to quality of matches, outliers etc. It becomes worse when all selected matches lie on the same plane. `Check this discussion <http://answers.opencv.org/question/18125/epilines-not-correct/>`_.
+++ /dev/null
-.. _pose_estimation:
-
-
-Pose Estimation
-*********************
-
-Goal
-==========
-
-In this section,
- * We will learn to exploit calib3d module to create some 3D effects in images.
-
-
-Basics
-========
-
-This is going to be a small section. During the last session on camera calibration, you have found the camera matrix, distortion coefficients etc. Given a pattern image, we can utilize the above information to calculate its pose, or how the object is situated in space, like how it is rotated, how it is displaced etc. For a planar object, we can assume Z=0, such that, the problem now becomes how camera is placed in space to see our pattern image. So, if we know how the object lies in the space, we can draw some 2D diagrams in it to simulate the 3D effect. Let's see how to do it.
-
-Our problem is, we want to draw our 3D coordinate axis (X, Y, Z axes) on our chessboard's first corner. X axis in blue color, Y axis in green color and Z axis in red color. So in-effect, Z axis should feel like it is perpendicular to our chessboard plane.
-
-First, let's load the camera matrix and distortion coefficients from the previous calibration result.
-::
-
- import cv2
- import numpy as np
- import glob
-
- # Load previously saved data
- with np.load('B.npz') as X:
- mtx, dist, _, _ = [X[i] for i in ('mtx','dist','rvecs','tvecs')]
-
-
-Now let's create a function, ``draw`` which takes the corners in the chessboard (obtained using **cv2.findChessboardCorners()**) and **axis points** to draw a 3D axis.
-::
-
- def draw(img, corners, imgpts):
- corner = tuple(corners[0].ravel())
- img = cv2.line(img, corner, tuple(imgpts[0].ravel()), (255,0,0), 5)
- img = cv2.line(img, corner, tuple(imgpts[1].ravel()), (0,255,0), 5)
- img = cv2.line(img, corner, tuple(imgpts[2].ravel()), (0,0,255), 5)
- return img
-
-Then as in previous case, we create termination criteria, object points (3D points of corners in chessboard) and axis points. Axis points are points in 3D space for drawing the axis. We draw axis of length 3 (units will be in terms of chess square size since we calibrated based on that size). So our X axis is drawn from (0,0,0) to (3,0,0), so for Y axis. For Z axis, it is drawn from (0,0,0) to (0,0,-3). Negative denotes it is drawn towards the camera.
-::
-
- criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001)
- objp = np.zeros((6*7,3), np.float32)
- objp[:,:2] = np.mgrid[0:7,0:6].T.reshape(-1,2)
-
- axis = np.float32([[3,0,0], [0,3,0], [0,0,-3]]).reshape(-1,3)
-
-
-Now, as usual, we load each image. Search for 7x6 grid. If found, we refine it with subcorner pixels. Then to calculate the rotation and translation, we use the function, **cv2.solvePnPRansac()**. Once we those transformation matrices, we use them to project our **axis points** to the image plane. In simple words, we find the points on image plane corresponding to each of (3,0,0),(0,3,0),(0,0,3) in 3D space. Once we get them, we draw lines from the first corner to each of these points using our ``draw()`` function. Done !!!
-
-::
-
- for fname in glob.glob('left*.jpg'):
- img = cv2.imread(fname)
- gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
- ret, corners = cv2.findChessboardCorners(gray, (7,6),None)
-
- if ret == True:
- corners2 = cv2.cornerSubPix(gray,corners,(11,11),(-1,-1),criteria)
-
- # Find the rotation and translation vectors.
- rvecs, tvecs, inliers = cv2.solvePnPRansac(objp, corners2, mtx, dist)
-
- # project 3D points to image plane
- imgpts, jac = cv2.projectPoints(axis, rvecs, tvecs, mtx, dist)
-
- img = draw(img,corners2,imgpts)
- cv2.imshow('img',img)
- k = cv2.waitKey(0) & 0xff
- if k == 's':
- cv2.imwrite(fname[:6]+'.png', img)
-
- cv2.destroyAllWindows()
-
-See some results below. Notice that each axis is 3 squares long.:
-
- .. image:: images/pose_1.jpg
- :alt: Pose Estimation
- :align: center
-
-
-Render a Cube
----------------
-
-If you want to draw a cube, modify the draw() function and axis points as follows.
-
-Modified draw() function:
-::
-
- def draw(img, corners, imgpts):
- imgpts = np.int32(imgpts).reshape(-1,2)
-
- # draw ground floor in green
- img = cv2.drawContours(img, [imgpts[:4]],-1,(0,255,0),-3)
-
- # draw pillars in blue color
- for i,j in zip(range(4),range(4,8)):
- img = cv2.line(img, tuple(imgpts[i]), tuple(imgpts[j]),(255),3)
-
- # draw top layer in red color
- img = cv2.drawContours(img, [imgpts[4:]],-1,(0,0,255),3)
-
- return img
-
-
-Modified axis points. They are the 8 corners of a cube in 3D space:
-::
-
- axis = np.float32([[0,0,0], [0,3,0], [3,3,0], [3,0,0],
- [0,0,-3],[0,3,-3],[3,3,-3],[3,0,-3] ])
-
-
-And look at the result below:
-
- .. image:: images/pose_2.jpg
- :alt: Pose Estimation
- :align: center
-
-
-If you are interested in graphics, augmented reality etc, you can use OpenGL to render more complicated figures.
-
-
-Additional Resources
-===========================
-
-
-Exercises
-===========
+++ /dev/null
-.. _PY_Table-Of-Content-Calib:
-
-
-Camera Calibration and 3D Reconstruction
-----------------------------------------------
-
-* :ref:`calibration`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |calib_1| Let's find how good is our camera. Is there any distortion in images taken with it? If so how to correct it?
-
- =========== ======================================================
-
- .. |calib_1| image:: images/calibration_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`pose_estimation`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |calib_2| This is a small section which will help you to create some cool 3D effects with calib module.
-
- =========== ======================================================
-
- .. |calib_2| image:: images/pose_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`epipolar_geometry`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |calib_3| Let's understand epipolar geometry and epipolar constraint.
-
- =========== ======================================================
-
- .. |calib_3| image:: images/epipolar_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`py_depthmap`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |calib_4| Extract depth information from 2D images.
-
- =========== ======================================================
-
- .. |calib_4| image:: images/depthmap_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_calibration/py_calibration
- ../py_pose/py_pose
- ../py_epipolar_geometry/py_epipolar_geometry
- ../py_depthmap/py_depthmap
+++ /dev/null
-.. _Basic_Ops:
-
-Basic Operations on Images
-******************************
-
-Goal
-=======
-
-Learn to:
-
- * Access pixel values and modify them
- * Access image properties
- * Setting Region of Image (ROI)
- * Splitting and Merging images
-
- Almost all the operations in this section is mainly related to Numpy rather than OpenCV. A good knowledge of Numpy is required to write better optimized code with OpenCV.
-
- *( Examples will be shown in Python terminal since most of them are just single line codes )*
-
-Accessing and Modifying pixel values
-=======================================
-
-Let's load a color image first:
-::
-
- >>> import cv2
- >>> import numpy as np
-
- >>> img = cv2.imread('messi5.jpg')
-
-You can access a pixel value by its row and column coordinates. For BGR image, it returns an array of Blue, Green, Red values. For grayscale image, just corresponding intensity is returned.
-::
-
- >>> px = img[100,100]
- >>> print px
- [157 166 200]
-
- # accessing only blue pixel
- >>> blue = img[100,100,0]
- >>> print blue
- 157
-
-You can modify the pixel values the same way.
-::
-
- >>> img[100,100] = [255,255,255]
- >>> print img[100,100]
- [255 255 255]
-
-.. warning:: Numpy is a optimized library for fast array calculations. So simply accessing each and every pixel values and modifying it will be very slow and it is discouraged.
-
-.. note:: Above mentioned method is normally used for selecting a region of array, say first 5 rows and last 3 columns like that. For individual pixel access, Numpy array methods, ``array.item()`` and ``array.itemset()`` is considered to be better. But it always returns a scalar. So if you want to access all B,G,R values, you need to call ``array.item()`` separately for all.
-
-Better pixel accessing and editing method :
-
-.. code-block:: python
-
- # accessing RED value
- >>> img.item(10,10,2)
- 59
-
- # modifying RED value
- >>> img.itemset((10,10,2),100)
- >>> img.item(10,10,2)
- 100
-
-Accessing Image Properties
-=============================
-
-Image properties include number of rows, columns and channels, type of image data, number of pixels etc.
-
-Shape of image is accessed by ``img.shape``. It returns a tuple of number of rows, columns and channels (if image is color):
-::
-
- >>> print img.shape
- (342, 548, 3)
-
-.. note:: If image is grayscale, tuple returned contains only number of rows and columns. So it is a good method to check if loaded image is grayscale or color image.
-
-Total number of pixels is accessed by ``img.size``:
-::
-
- >>> print img.size
- 562248
-
-Image datatype is obtained by ``img.dtype``:
-::
-
- >>> print img.dtype
- uint8
-
-.. note:: ``img.dtype`` is very important while debugging because a large number of errors in OpenCV-Python code is caused by invalid datatype.
-
-Image ROI
-===========
-
-Sometimes, you will have to play with certain region of images. For eye detection in images, first face detection is done all over the image and when face is obtained, we select the face region alone and search for eyes inside it instead of searching whole image. It improves accuracy (because eyes are always on faces :D ) and performance (because we search for a small area)
-
-ROI is again obtained using Numpy indexing. Here I am selecting the ball and copying it to another region in the image:
-::
-
- >>> ball = img[280:340, 330:390]
- >>> img[273:333, 100:160] = ball
-
-Check the results below:
-
- .. image:: images/roi.jpg
- :alt: Image ROI
- :align: center
-
-Splitting and Merging Image Channels
-======================================
-
-Sometimes you will need to work separately on B,G,R channels of image. Then you need to split the BGR images to single planes. Or another time, you may need to join these individual channels to BGR image. You can do it simply by:
-::
-
- >>> b,g,r = cv2.split(img)
- >>> img = cv2.merge((b,g,r))
-
-Or
-
- >>> b = img[:,:,0]
-
-Suppose, you want to make all the red pixels to zero, you need not split like this and put it equal to zero. You can simply use Numpy indexing, and that is more faster.
-::
-
- >>> img[:,:,2] = 0
-
-.. warning:: ``cv2.split()`` is a costly operation (in terms of time). So do it only if you need it. Otherwise go for Numpy indexing.
-
-Making Borders for Images (Padding)
-====================================
-If you want to create a border around the image, something like a photo frame, you can use **cv2.copyMakeBorder()** function. But it has more applications for convolution operation, zero padding etc. This function takes following arguments:
-
- * **src** - input image
- * **top**, **bottom**, **left**, **right** - border width in number of pixels in corresponding directions
- * **borderType** - Flag defining what kind of border to be added. It can be following types:
- * **cv2.BORDER_CONSTANT** - Adds a constant colored border. The value should be given as next argument.
- * **cv2.BORDER_REFLECT** - Border will be mirror reflection of the border elements, like this : *fedcba|abcdefgh|hgfedcb*
- * **cv2.BORDER_REFLECT_101** or **cv2.BORDER_DEFAULT** - Same as above, but with a slight change, like this : *gfedcb|abcdefgh|gfedcba*
- * **cv2.BORDER_REPLICATE** - Last element is replicated throughout, like this: *aaaaaa|abcdefgh|hhhhhhh*
- * **cv2.BORDER_WRAP** - Can't explain, it will look like this : *cdefgh|abcdefgh|abcdefg*
- * **value** - Color of border if border type is ``cv2.BORDER_CONSTANT``
-
-Below is a sample code demonstrating all these border types for better understanding:
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- BLUE = [255,0,0]
-
- img1 = cv2.imread('opencv_logo.png')
-
- replicate = cv2.copyMakeBorder(img1,10,10,10,10,cv2.BORDER_REPLICATE)
- reflect = cv2.copyMakeBorder(img1,10,10,10,10,cv2.BORDER_REFLECT)
- reflect101 = cv2.copyMakeBorder(img1,10,10,10,10,cv2.BORDER_REFLECT_101)
- wrap = cv2.copyMakeBorder(img1,10,10,10,10,cv2.BORDER_WRAP)
- constant= cv2.copyMakeBorder(img1,10,10,10,10,cv2.BORDER_CONSTANT,value=BLUE)
-
- plt.subplot(231),plt.imshow(img1,'gray'),plt.title('ORIGINAL')
- plt.subplot(232),plt.imshow(replicate,'gray'),plt.title('REPLICATE')
- plt.subplot(233),plt.imshow(reflect,'gray'),plt.title('REFLECT')
- plt.subplot(234),plt.imshow(reflect101,'gray'),plt.title('REFLECT_101')
- plt.subplot(235),plt.imshow(wrap,'gray'),plt.title('WRAP')
- plt.subplot(236),plt.imshow(constant,'gray'),plt.title('CONSTANT')
-
- plt.show()
-
-See the result below. (Image is displayed with matplotlib. So RED and BLUE planes will be interchanged):
-
- .. image:: images/border.jpg
- :alt: Border Types
- :align: center
-
-Additional Resources
-=========================
-
-Exercises
-===========
+++ /dev/null
-.. _Image_Arithmetics:
-
-Arithmetic Operations on Images
-*********************************
-
-Goal
-=====
-
- * Learn several arithmetic operations on images like addition, subtraction, bitwise operations etc.
- * You will learn these functions : **cv2.add()**, **cv2.addWeighted()** etc.
-
-Image Addition
-================
-
-You can add two images by OpenCV function, ``cv2.add()`` or simply by numpy operation, ``res = img1 + img2``. Both images should be of same depth and type, or second image can just be a scalar value.
-
-.. note:: There is a difference between OpenCV addition and Numpy addition. OpenCV addition is a saturated operation while Numpy addition is a modulo operation.
-
-For example, consider below sample:
-::
-
- >>> x = np.uint8([250])
- >>> y = np.uint8([10])
-
- >>> print cv2.add(x,y) # 250+10 = 260 => 255
- [[255]]
-
- >>> print x+y # 250+10 = 260 % 256 = 4
- [4]
-
-It will be more visible when you add two images. OpenCV function will provide a better result. So always better stick to OpenCV functions.
-
-Image Blending
-=================
-
-This is also image addition, but different weights are given to images so that it gives a feeling of blending or transparency. Images are added as per the equation below:
-
-.. math::
-
- g(x) = (1 - \alpha)f_{0}(x) + \alpha f_{1}(x)
-
-By varying :math:`\alpha` from :math:`0 \rightarrow 1`, you can perform a cool transition between one image to another.
-
-Here I took two images to blend them together. First image is given a weight of 0.7 and second image is given 0.3. ``cv2.addWeighted()`` applies following equation on the image.
-
-.. math::
-
- dst = \alpha \cdot img1 + \beta \cdot img2 + \gamma
-
-Here :math:`\gamma` is taken as zero.
-::
-
- img1 = cv2.imread('ml.png')
- img2 = cv2.imread('opencv_logo.jpg')
-
- dst = cv2.addWeighted(img1,0.7,img2,0.3,0)
-
- cv2.imshow('dst',dst)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-Check the result below:
-
- .. image:: images/blending.jpg
- :alt: Image Blending
- :align: center
-
-Bitwise Operations
-===================
-
-This includes bitwise AND, OR, NOT and XOR operations. They will be highly useful while extracting any part of the image (as we will see in coming chapters), defining and working with non-rectangular ROI etc. Below we will see an example on how to change a particular region of an image.
-
-I want to put OpenCV logo above an image. If I add two images, it will change color. If I blend it, I get an transparent effect. But I want it to be opaque. If it was a rectangular region, I could use ROI as we did in last chapter. But OpenCV logo is a not a rectangular shape. So you can do it with bitwise operations as below:
-::
-
- # Load two images
- img1 = cv2.imread('messi5.jpg')
- img2 = cv2.imread('opencv_logo.png')
-
- # I want to put logo on top-left corner, So I create a ROI
- rows,cols,channels = img2.shape
- roi = img1[0:rows, 0:cols ]
-
- # Now create a mask of logo and create its inverse mask also
- img2gray = cv2.cvtColor(img2,cv2.COLOR_BGR2GRAY)
- ret, mask = cv2.threshold(img2gray, 10, 255, cv2.THRESH_BINARY)
- mask_inv = cv2.bitwise_not(mask)
-
- # Now black-out the area of logo in ROI
- img1_bg = cv2.bitwise_and(roi,roi,mask = mask_inv)
-
- # Take only region of logo from logo image.
- img2_fg = cv2.bitwise_and(img2,img2,mask = mask)
-
- # Put logo in ROI and modify the main image
- dst = cv2.add(img1_bg,img2_fg)
- img1[0:rows, 0:cols ] = dst
-
- cv2.imshow('res',img1)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-See the result below. Left image shows the mask we created. Right image shows the final result. For more understanding, display all the intermediate images in the above code, especially ``img1_bg`` and ``img2_fg``.
-
- .. image:: images/overlay.jpg
- :alt: Otsu's Thresholding
- :align: center
-
-
-Additional Resources
-======================
-
-Exercises
-============
-#. Create a slide show of images in a folder with smooth transition between images using ``cv2.addWeighted`` function
+++ /dev/null
-.. _Mathematical_Tools:
-
-Mathematical Tools in OpenCV
-********************************
+++ /dev/null
-.. _Optimization_Techniques:
-
-Performance Measurement and Improvement Techniques
-****************************************************
-
-Goal
-======
-
-In image processing, since you are dealing with large number of operations per second, it is mandatory that your code is not only providing the correct solution, but also in the fastest manner. So in this chapter, you will learn
-
- * To measure the performance of your code.
- * Some tips to improve the performance of your code.
- * You will see these functions : **cv2.getTickCount**, **cv2.getTickFrequency** etc.
-
-Apart from OpenCV, Python also provides a module **time** which is helpful in measuring the time of execution. Another module **profile** helps to get detailed report on the code, like how much time each function in the code took, how many times the function was called etc. But, if you are using IPython, all these features are integrated in an user-friendly manner. We will see some important ones, and for more details, check links in **Additional Resouces** section.
-
-Measuring Performance with OpenCV
-==================================
-
-**cv2.getTickCount** function returns the number of clock-cycles after a reference event (like the moment machine was switched ON) to the moment this function is called. So if you call it before and after the function execution, you get number of clock-cycles used to execute a function.
-
-**cv2.getTickFrequency** function returns the frequency of clock-cycles, or the number of clock-cycles per second. So to find the time of execution in seconds, you can do following:
-::
-
- e1 = cv2.getTickCount()
- # your code execution
- e2 = cv2.getTickCount()
- time = (e2 - e1)/ cv2.getTickFrequency()
-
-We will demonstrate with following example. Following example apply median filtering with a kernel of odd size ranging from 5 to 49. (Don't worry about what will the result look like, that is not our goal):
-::
-
- img1 = cv2.imread('messi5.jpg')
-
- e1 = cv2.getTickCount()
- for i in xrange(5,49,2):
- img1 = cv2.medianBlur(img1,i)
- e2 = cv2.getTickCount()
- t = (e2 - e1)/cv2.getTickFrequency()
- print t
-
- # Result I got is 0.521107655 seconds
-
-.. note:: You can do the same with ``time`` module. Instead of ``cv2.getTickCount``, use ``time.time()`` function. Then take the difference of two times.
-
-
-Default Optimization in OpenCV
-================================
-
-Many of the OpenCV functions are optimized using SSE2, AVX etc. It contains unoptimized code also. So if our system support these features, we should exploit them (almost all modern day processors support them). It is enabled by default while compiling. So OpenCV runs the optimized code if it is enabled, else it runs the unoptimized code. You can use **cv2.useOptimized()** to check if it is enabled/disabled and **cv2.setUseOptimized()** to enable/disable it. Let's see a simple example.
-::
-
- # check if optimization is enabled
- In [5]: cv2.useOptimized()
- Out[5]: True
-
- In [6]: %timeit res = cv2.medianBlur(img,49)
- 10 loops, best of 3: 34.9 ms per loop
-
- # Disable it
- In [7]: cv2.setUseOptimized(False)
-
- In [8]: cv2.useOptimized()
- Out[8]: False
-
- In [9]: %timeit res = cv2.medianBlur(img,49)
- 10 loops, best of 3: 64.1 ms per loop
-
-
-See, optimized median filtering is ~2x faster than unoptimized version. If you check its source, you can see median filtering is SIMD optimized. So you can use this to enable optimization at the top of your code (remember it is enabled by default).
-
-
-Measuring Performance in IPython
-============================================================
-
-Sometimes you may need to compare the performance of two similar operations. IPython gives you a magic command ``%timeit`` to perform this. It runs the code several times to get more accurate results. Once again, they are suitable to measure single line codes.
-
-For example, do you know which of the following addition operation is better, ``x = 5; y = x**2``, ``x = 5; y = x*x``, ``x = np.uint8([5]); y = x*x`` or ``y = np.square(x)`` ? We will find it with %timeit in IPython shell.
-::
-
- In [10]: x = 5
-
- In [11]: %timeit y=x**2
- 10000000 loops, best of 3: 73 ns per loop
-
- In [12]: %timeit y=x*x
- 10000000 loops, best of 3: 58.3 ns per loop
-
- In [15]: z = np.uint8([5])
-
- In [17]: %timeit y=z*z
- 1000000 loops, best of 3: 1.25 us per loop
-
- In [19]: %timeit y=np.square(z)
- 1000000 loops, best of 3: 1.16 us per loop
-
-You can see that, ``x = 5 ; y = x*x`` is fastest and it is around 20x faster compared to Numpy. If you consider the array creation also, it may reach upto 100x faster. Cool, right? *(Numpy devs are working on this issue)*
-
-.. note:: Python scalar operations are faster than Numpy scalar operations. So for operations including one or two elements, Python scalar is better than Numpy arrays. Numpy takes advantage when size of array is a little bit bigger.
-
-We will try one more example. This time, we will compare the performance of **cv2.countNonZero()** and **np.count_nonzero()** for same image.
-::
-
- In [35]: %timeit z = cv2.countNonZero(img)
- 100000 loops, best of 3: 15.8 us per loop
-
- In [36]: %timeit z = np.count_nonzero(img)
- 1000 loops, best of 3: 370 us per loop
-
-See, OpenCV function is nearly 25x faster than Numpy function.
-
-.. note:: Normally, OpenCV functions are faster than Numpy functions. So for same operation, OpenCV functions are preferred. But, there can be exceptions, especially when Numpy works with views instead of copies.
-
-
-More IPython magic commands
-=============================
-
-There are several other magic commands to measure the performance, profiling, line profiling, memory measurement etc. They all are well documented. So only links to those docs are provided here. Interested readers are recommended to try them out.
-
-Performance Optimization Techniques
-=====================================
-
-There are several techniques and coding methods to exploit maximum performance of Python and Numpy. Only relevant ones are noted here and links are given to important sources. The main thing to be noted here is that, first try to implement the algorithm in a simple manner. Once it is working, profile it, find the bottlenecks and optimize them.
-
- #. Avoid using loops in Python as far as possible, especially double/triple loops etc. They are inherently slow.
- #. Vectorize the algorithm/code to the maximum possible extent because Numpy and OpenCV are optimized for vector operations.
- #. Exploit the cache coherence.
- #. Never make copies of array unless it is needed. Try to use views instead. Array copying is a costly operation.
-
-Even after doing all these operations, if your code is still slow, or use of large loops are inevitable, use additional libraries like Cython to make it faster.
-
-Additional Resources
-======================
-
-1. `Python Optimization Techniques <http://wiki.python.org/moin/PythonSpeed/PerformanceTips>`_
-2. Scipy Lecture Notes - `Advanced Numpy <http://scipy-lectures.github.io/advanced/advanced_numpy/index.html#advanced-numpy>`_
-3. `Timing and Profiling in IPython <http://pynash.org/2013/03/06/timing-and-profiling.html>`_
-
-
-Exercises
-============
+++ /dev/null
-.. _PY_Table-Of-Content-Core:
-
-Core Operations
------------------------------------------------------------
-
-
-* :ref:`Basic_Ops`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |core_1| Learn to read and edit pixel values, working with image ROI and other basic operations.
-
- =========== ======================================================
-
- .. |core_1| image:: images/pixel_ops.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Image_Arithmetics`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |core_2| Perform arithmetic operations on images
-
- =========== ======================================================
-
- .. |core_2| image:: images/image_arithmetic.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Optimization_Techniques`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |core_4| Getting a solution is important. But getting it in the fastest way is more important. Learn to check the speed of your code, optimize the code etc.
-
- =========== ======================================================
-
- .. |core_4| image:: images/speed.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Mathematical_Tools`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |core_5| Learn some of the mathematical tools provided by OpenCV like PCA, SVD etc.
-
- =========== ======================================================
-
- .. |core_5| image:: images/maths_tools.jpg
- :height: 90pt
- :width: 90pt
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_basic_ops/py_basic_ops
- ../py_image_arithmetics/py_image_arithmetics
- ../py_optimization/py_optimization
- ../py_maths_tools/py_maths_tools
+++ /dev/null
-.. _BRIEF:
-
-
-BRIEF (Binary Robust Independent Elementary Features)
-***********************************************************
-
-Goal
-=======
-In this chapter
- * We will see the basics of BRIEF algorithm
-
-
-Theory
-=============
-
-We know SIFT uses 128-dim vector for descriptors. Since it is using floating point numbers, it takes basically 512 bytes. Similarly SURF also takes minimum of 256 bytes (for 64-dim). Creating such a vector for thousands of features takes a lot of memory which are not feasible for resouce-constraint applications especially for embedded systems. Larger the memory, longer the time it takes for matching.
-
-But all these dimensions may not be needed for actual matching. We can compress it using several methods like PCA, LDA etc. Even other methods like hashing using LSH (Locality Sensitive Hashing) is used to convert these SIFT descriptors in floating point numbers to binary strings. These binary strings are used to match features using Hamming distance. This provides better speed-up because finding hamming distance is just applying XOR and bit count, which are very fast in modern CPUs with SSE instructions. But here, we need to find the descriptors first, then only we can apply hashing, which doesn't solve our initial problem on memory.
-
-BRIEF comes into picture at this moment. It provides a shortcut to find the binary strings directly without finding descriptors. It takes smoothened image patch and selects a set of :math:`n_d` (x,y) location pairs in an unique way (explained in paper). Then some pixel intensity comparisons are done on these location pairs. For eg, let first location pairs be :math:`p` and :math:`q`. If :math:`I(p) < I(q)`, then its result is 1, else it is 0. This is applied for all the :math:`n_d` location pairs to get a :math:`n_d`-dimensional bitstring.
-
-This :math:`n_d` can be 128, 256 or 512. OpenCV supports all of these, but by default, it would be 256 (OpenCV represents it in bytes. So the values will be 16, 32 and 64). So once you get this, you can use Hamming Distance to match these descriptors.
-
-One important point is that BRIEF is a feature descriptor, it doesn't provide any method to find the features. So you will have to use any other feature detectors like SIFT, SURF etc. The paper recommends to use CenSurE which is a fast detector and BRIEF works even slightly better for CenSurE points than for SURF points.
-
-In short, BRIEF is a faster method feature descriptor calculation and matching. It also provides high recognition rate unless there is large in-plane rotation.
-
-BRIEF in OpenCV
-=====================
-
-Below code shows the computation of BRIEF descriptors with the help of CenSurE detector. (CenSurE detector is called STAR detector in OpenCV)
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('simple.jpg',0)
-
- # Initiate STAR detector
- star = cv2.FeatureDetector_create("STAR")
-
- # Initiate BRIEF extractor
- brief = cv2.DescriptorExtractor_create("BRIEF")
-
- # find the keypoints with STAR
- kp = star.detect(img,None)
-
- # compute the descriptors with BRIEF
- kp, des = brief.compute(img, kp)
-
- print brief.getInt('bytes')
- print des.shape
-
-The function ``brief.getInt('bytes')`` gives the :math:`n_d` size used in bytes. By default it is 32. Next one is matching, which will be done in another chapter.
-
-
-Additional Resources
-==========================
-
-#. Michael Calonder, Vincent Lepetit, Christoph Strecha, and Pascal Fua, "BRIEF: Binary Robust Independent Elementary Features", 11th European Conference on Computer Vision (ECCV), Heraklion, Crete. LNCS Springer, September 2010.
-
-#. LSH (Locality Sensitive Hasing) at wikipedia.
+++ /dev/null
-.. _FAST:
-
-FAST Algorithm for Corner Detection
-*************************************
-
-Goal
-=======
-
-In this chapter,
- * We will understand the basics of FAST algorithm
- * We will find corners using OpenCV functionalities for FAST algorithm.
-
-
-Theory
-=========
-
-We saw several feature detectors and many of them are really good. But when looking from a real-time application point of view, they are not fast enough. One best example would be SLAM (Simultaneous Localization and Mapping) mobile robot which have limited computational resources.
-
-As a solution to this, FAST (Features from Accelerated Segment Test) algorithm was proposed by Edward Rosten and Tom Drummond in their paper "Machine learning for high-speed corner detection" in 2006 (Later revised it in 2010). A basic summary of the algorithm is presented below. Refer original paper for more details (All the images are taken from original paper).
-
-
-Feature Detection using FAST
-------------------------------
-
-1. Select a pixel :math:`p` in the image which is to be identified as an interest point or not. Let its intensity be :math:`I_p`.
-2. Select appropriate threshold value :math:`t`.
-3. Consider a circle of 16 pixels around the pixel under test. (See the image below)
-
- .. image:: images/fast_speedtest.jpg
- :alt: A corner in the image
- :align: center
-
-4. Now the pixel :math:`p` is a corner if there exists a set of :math:`n` contiguous pixels in the circle (of 16 pixels) which are all brighter than :math:`I_p + t`, or all darker than :math:`I_p − t`. (Shown as white dash lines in the above image). :math:`n` was chosen to be 12.
-5. A **high-speed test** was proposed to exclude a large number of non-corners. This test examines only the four pixels at 1, 9, 5 and 13 (First 1 and 9 are tested if they are too brighter or darker. If so, then checks 5 and 13). If :math:`p` is a corner, then at least three of these must all be brighter than :math:`I_p + t` or darker than :math:`I_p − t`. If neither of these is the case, then :math:`p` cannot be a corner. The full segment test criterion can then be applied to the passed candidates by examining all pixels in the circle. This detector in itself exhibits high performance, but there are several weaknesses:
-
- * It does not reject as many candidates for n < 12.
- * The choice of pixels is not optimal because its efficiency depends on ordering of the questions and distribution of corner appearances.
- * Results of high-speed tests are thrown away.
- * Multiple features are detected adjacent to one another.
-
-First 3 points are addressed with a machine learning approach. Last one is addressed using non-maximal suppression.
-
-
-Machine Learning a Corner Detector
-------------------------------------
-
-1. Select a set of images for training (preferably from the target application domain)
-2. Run FAST algorithm in every images to find feature points.
-3. For every feature point, store the 16 pixels around it as a vector. Do it for all the images to get feature vector :math:`P`.
-4. Each pixel (say :math:`x`) in these 16 pixels can have one of the following three states:
-
- .. image:: images/fast_eqns.jpg
- :alt: FAST equation
- :align: center
-
-5. Depending on these states, the feature vector :math:`P` is subdivided into 3 subsets, :math:`P_d`, :math:`P_s`, :math:`P_b`.
-6. Define a new boolean variable, :math:`K_p`, which is true if :math:`p` is a corner and false otherwise.
-7. Use the ID3 algorithm (decision tree classifier) to query each subset using the variable :math:`K_p` for the knowledge about the true class. It selects the :math:`x` which yields the most information about whether the candidate pixel is a corner, measured by the entropy of :math:`K_p`.
-8. This is recursively applied to all the subsets until its entropy is zero.
-9. The decision tree so created is used for fast detection in other images.
-
-
-Non-maximal Suppression
----------------------------
-
-Detecting multiple interest points in adjacent locations is another problem. It is solved by using Non-maximum Suppression.
-
-1. Compute a score function, :math:`V` for all the detected feature points. :math:`V` is the sum of absolute difference between :math:`p` and 16 surrounding pixels values.
-2. Consider two adjacent keypoints and compute their :math:`V` values.
-3. Discard the one with lower :math:`V` value.
-
-
-Summary
------------
-
-It is several times faster than other existing corner detectors.
-
-But it is not robust to high levels of noise. It is dependant on a threshold.
-
-
-FAST Feature Detector in OpenCV
-==================================
-
-It is called as any other feature detector in OpenCV. If you want, you can specify the threshold, whether non-maximum suppression to be applied or not, the neighborhood to be used etc.
-
-For the neighborhood, three flags are defined, ``cv2.FAST_FEATURE_DETECTOR_TYPE_5_8``, ``cv2.FAST_FEATURE_DETECTOR_TYPE_7_12`` and ``cv2.FAST_FEATURE_DETECTOR_TYPE_9_16``. Below is a simple code on how to detect and draw the FAST feature points.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('simple.jpg',0)
-
- # Initiate FAST object with default values
- fast = cv2.FastFeatureDetector()
-
- # find and draw the keypoints
- kp = fast.detect(img,None)
- img2 = cv2.drawKeypoints(img, kp, color=(255,0,0))
-
- # Print all default params
- print "Threshold: ", fast.getInt('threshold')
- print "nonmaxSuppression: ", fast.getBool('nonmaxSuppression')
- print "neighborhood: ", fast.getInt('type')
- print "Total Keypoints with nonmaxSuppression: ", len(kp)
-
- cv2.imwrite('fast_true.png',img2)
-
- # Disable nonmaxSuppression
- fast.setBool('nonmaxSuppression',0)
- kp = fast.detect(img,None)
-
- print "Total Keypoints without nonmaxSuppression: ", len(kp)
-
- img3 = cv2.drawKeypoints(img, kp, color=(255,0,0))
-
- cv2.imwrite('fast_false.png',img3)
-
-See the results. First image shows FAST with nonmaxSuppression and second one without nonmaxSuppression:
-
- .. image:: images/fast_kp.jpg
- :alt: FAST Keypoints
- :align: center
-
-
-Additional Resources
-=========================
-
-#. Edward Rosten and Tom Drummond, “Machine learning for high speed corner detection” in 9th European Conference on Computer Vision, vol. 1, 2006, pp. 430–443.
-
-#. Edward Rosten, Reid Porter, and Tom Drummond, "Faster and better: a machine learning approach to corner detection" in IEEE Trans. Pattern Analysis and Machine Intelligence, 2010, vol 32, pp. 105-119.
-
-
-Exercises
-============
+++ /dev/null
-.. _PY_feature_homography:
-
-
-Feature Matching + Homography to find Objects
-***********************************************
-
-Goal
-======
-In this chapter,
- * We will mix up the feature matching and findHomography from calib3d module to find known objects in a complex image.
-
-
-Basics
-=========
-
-So what we did in last session? We used a queryImage, found some feature points in it, we took another trainImage, found the features in that image too and we found the best matches among them. In short, we found locations of some parts of an object in another cluttered image. This information is sufficient to find the object exactly on the trainImage.
-
-For that, we can use a function from calib3d module, ie **cv2.findHomography()**. If we pass the set of points from both the images, it will find the perpective transformation of that object. Then we can use **cv2.perspectiveTransform()** to find the object. It needs atleast four correct points to find the transformation.
-
-We have seen that there can be some possible errors while matching which may affect the result. To solve this problem, algorithm uses RANSAC or LEAST_MEDIAN (which can be decided by the flags). So good matches which provide correct estimation are called inliers and remaining are called outliers. **cv2.findHomography()** returns a mask which specifies the inlier and outlier points.
-
-So let's do it !!!
-
-
-Code
-=========
-
-First, as usual, let's find SIFT features in images and apply the ratio test to find the best matches.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- MIN_MATCH_COUNT = 10
-
- img1 = cv2.imread('box.png',0) # queryImage
- img2 = cv2.imread('box_in_scene.png',0) # trainImage
-
- # Initiate SIFT detector
- sift = cv2.SIFT()
-
- # find the keypoints and descriptors with SIFT
- kp1, des1 = sift.detectAndCompute(img1,None)
- kp2, des2 = sift.detectAndCompute(img2,None)
-
- FLANN_INDEX_KDTREE = 0
- index_params = dict(algorithm = FLANN_INDEX_KDTREE, trees = 5)
- search_params = dict(checks = 50)
-
- flann = cv2.FlannBasedMatcher(index_params, search_params)
-
- matches = flann.knnMatch(des1,des2,k=2)
-
- # store all the good matches as per Lowe's ratio test.
- good = []
- for m,n in matches:
- if m.distance < 0.7*n.distance:
- good.append(m)
-
-
-Now we set a condition that atleast 10 matches (defined by MIN_MATCH_COUNT) are to be there to find the object. Otherwise simply show a message saying not enough matches are present.
-
-If enough matches are found, we extract the locations of matched keypoints in both the images. They are passed to find the perpective transformation. Once we get this 3x3 transformation matrix, we use it to transform the corners of queryImage to corresponding points in trainImage. Then we draw it.
-::
-
- if len(good)>MIN_MATCH_COUNT:
- src_pts = np.float32([ kp1[m.queryIdx].pt for m in good ]).reshape(-1,1,2)
- dst_pts = np.float32([ kp2[m.trainIdx].pt for m in good ]).reshape(-1,1,2)
-
- M, mask = cv2.findHomography(src_pts, dst_pts, cv2.RANSAC,5.0)
- matchesMask = mask.ravel().tolist()
-
- h,w = img1.shape
- pts = np.float32([ [0,0],[0,h-1],[w-1,h-1],[w-1,0] ]).reshape(-1,1,2)
- dst = cv2.perspectiveTransform(pts,M)
-
- img2 = cv2.polylines(img2,[np.int32(dst)],True,255,3, cv2.LINE_AA)
-
- else:
- print "Not enough matches are found - %d/%d" % (len(good),MIN_MATCH_COUNT)
- matchesMask = None
-
-
-Finally we draw our inliers (if successfully found the object) or matching keypoints (if failed).
-::
-
- draw_params = dict(matchColor = (0,255,0), # draw matches in green color
- singlePointColor = None,
- matchesMask = matchesMask, # draw only inliers
- flags = 2)
-
- img3 = cv2.drawMatches(img1,kp1,img2,kp2,good,None,**draw_params)
-
- plt.imshow(img3, 'gray'),plt.show()
-
-
-See the result below. Object is marked in white color in cluttered image:
-
- .. image:: images/homography_findobj.jpg
- :alt: Finding object with feature homography
- :align: center
-
-
-Additional Resources
-============================
-
-
-Exercises
-==================
+++ /dev/null
-.. _Harris_Corners:
-
-Harris Corner Detection
-****************************
-
-Goal
-=======
-
-In this chapter,
-
- * We will understand the concepts behind Harris Corner Detection.
- * We will see the functions: **cv2.cornerHarris()**, **cv2.cornerSubPix()**
-
-Theory
-==========
-
-In last chapter, we saw that corners are regions in the image with large variation in intensity in all the directions. One early attempt to find these corners was done by **Chris Harris & Mike Stephens** in their paper **A Combined Corner and Edge Detector** in 1988, so now it is called Harris Corner Detector. He took this simple idea to a mathematical form. It basically finds the difference in intensity for a displacement of :math:`(u,v)` in all directions. This is expressed as below:
-
-.. math::
-
- E(u,v) = \sum_{x,y} \underbrace{w(x,y)}_\text{window function} \, [\underbrace{I(x+u,y+v)}_\text{shifted intensity}-\underbrace{I(x,y)}_\text{intensity}]^2
-
-Window function is either a rectangular window or gaussian window which gives weights to pixels underneath.
-
-We have to maximize this function :math:`E(u,v)` for corner detection. That means, we have to maximize the second term. Applying Taylor Expansion to above equation and using some mathematical steps (please refer any standard text books you like for full derivation), we get the final equation as:
-
-.. math::
-
- E(u,v) \approx \begin{bmatrix} u & v \end{bmatrix} M \begin{bmatrix} u \\ v \end{bmatrix}
-
-where
-
-.. math::
-
- M = \sum_{x,y} w(x,y) \begin{bmatrix}I_x I_x & I_x I_y \\
- I_x I_y & I_y I_y \end{bmatrix}
-
-Here, :math:`I_x` and :math:`I_y` are image derivatives in x and y directions respectively. (Can be easily found out using **cv2.Sobel()**).
-
-Then comes the main part. After this, they created a score, basically an equation, which will determine if a window can contain a corner or not.
-
-.. math::
-
- R = det(M) - k(trace(M))^2
-
-where
- * :math:`det(M) = \lambda_1 \lambda_2`
- * :math:`trace(M) = \lambda_1 + \lambda_2`
- * :math:`\lambda_1` and :math:`\lambda_2` are the eigen values of M
-
-So the values of these eigen values decide whether a region is corner, edge or flat.
-
- * When :math:`|R|` is small, which happens when :math:`\lambda_1` and :math:`\lambda_2` are small, the region is flat.
- * When :math:`R<0`, which happens when :math:`\lambda_1 >> \lambda_2` or vice versa, the region is edge.
- * When :math:`R` is large, which happens when :math:`\lambda_1` and :math:`\lambda_2` are large and :math:`\lambda_1 \sim \lambda_2`, the region is a corner.
-
-It can be represented in a nice picture as follows:
-
- .. image:: images/harris_region.jpg
- :alt: Classification of Image Points
- :align: center
-
-So the result of Harris Corner Detection is a grayscale image with these scores. Thresholding for a suitable give you the corners in the image. We will do it with a simple image.
-
-
-Harris Corner Detector in OpenCV
-====================================
-
-OpenCV has the function **cv2.cornerHarris()** for this purpose. Its arguments are :
-
- * **img** - Input image, it should be grayscale and float32 type.
- * **blockSize** - It is the size of neighbourhood considered for corner detection
- * **ksize** - Aperture parameter of Sobel derivative used.
- * **k** - Harris detector free parameter in the equation.
-
-See the example below:
-::
-
- import cv2
- import numpy as np
-
- filename = 'chessboard.jpg'
- img = cv2.imread(filename)
- gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
-
- gray = np.float32(gray)
- dst = cv2.cornerHarris(gray,2,3,0.04)
-
- #result is dilated for marking the corners, not important
- dst = cv2.dilate(dst,None)
-
- # Threshold for an optimal value, it may vary depending on the image.
- img[dst>0.01*dst.max()]=[0,0,255]
-
- cv2.imshow('dst',img)
- if cv2.waitKey(0) & 0xff == 27:
- cv2.destroyAllWindows()
-
-
-Below are the three results:
-
- .. image:: images/harris_result.jpg
- :alt: Harris Corner Detection
- :align: center
-
-
-Corner with SubPixel Accuracy
-===============================
-
-Sometimes, you may need to find the corners with maximum accuracy. OpenCV comes with a function **cv2.cornerSubPix()** which further refines the corners detected with sub-pixel accuracy. Below is an example. As usual, we need to find the harris corners first. Then we pass the centroids of these corners (There may be a bunch of pixels at a corner, we take their centroid) to refine them. Harris corners are marked in red pixels and refined corners are marked in green pixels. For this function, we have to define the criteria when to stop the iteration. We stop it after a specified number of iteration or a certain accuracy is achieved, whichever occurs first. We also need to define the size of neighbourhood it would search for corners.
-::
-
- import cv2
- import numpy as np
-
- filename = 'chessboard2.jpg'
- img = cv2.imread(filename)
- gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
-
- # find Harris corners
- gray = np.float32(gray)
- dst = cv2.cornerHarris(gray,2,3,0.04)
- dst = cv2.dilate(dst,None)
- ret, dst = cv2.threshold(dst,0.01*dst.max(),255,0)
- dst = np.uint8(dst)
-
- # find centroids
- ret, labels, stats, centroids = cv2.connectedComponentsWithStats(dst)
-
- # define the criteria to stop and refine the corners
- criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 100, 0.001)
- corners = cv2.cornerSubPix(gray,np.float32(centroids),(5,5),(-1,-1),criteria)
-
- # Now draw them
- res = np.hstack((centroids,corners))
- res = np.int0(res)
- img[res[:,1],res[:,0]]=[0,0,255]
- img[res[:,3],res[:,2]] = [0,255,0]
-
- cv2.imwrite('subpixel5.png',img)
-
-Below is the result, where some important locations are shown in zoomed window to visualize:
-
- .. image:: images/subpixel3.png
- :alt: Corner Detection with SubPixel Accuracy
- :align: center
-
-
-Additional Resources
-======================
-
-
-Exercises
-============
+++ /dev/null
-.. _Features_Meaning:
-
-Understanding Features
-************************
-
-Goal
-=====
-
-In this chapter, we will just try to understand what are features, why are they important, why corners are important etc.
-
-Explanation
-==============
-
-Most of you will have played the jigsaw puzzle games. You get a lot of small pieces of a images, where you need to assemble them correctly to form a big real image. **The question is, how you do it?** What about the projecting the same theory to a computer program so that computer can play jigsaw puzzles? If the computer can play jigsaw puzzles, why can't we give a lot of real-life images of a good natural scenery to computer and tell it to stitch all those images to a big single image? If the computer can stitch several natural images to one, what about giving a lot of pictures of a building or any structure and tell computer to create a 3D model out of it?
-
-Well, the questions and imaginations continue. But it all depends on the most basic question: How do you play jigsaw puzzles? How do you arrange lots of scrambled image pieces into a big single image? How can you stitch a lot of natural images to a single image?
-
-The answer is, we are looking for specific patterns or specific features which are unique, which can be easily tracked, which can be easily compared. If we go for a definition of such a feature, we may find it difficult to express it in words, but we know what are they. If some one asks you to point out one good feature which can be compared across several images, you can point out one. That is why, even small children can simply play these games. We search for these features in an image, we find them, we find the same features in other images, we align them. That's it. (In jigsaw puzzle, we look more into continuity of different images). All these abilities are present in us inherently.
-
-So our one basic question expands to more in number, but becomes more specific. **What are these features?**. *(The answer should be understandable to a computer also.)*
-
-Well, it is difficult to say how humans find these features. It is already programmed in our brain. But if we look deep into some pictures and search for different patterns, we will find something interesting. For example, take below image:
-
- .. image:: images/feature_building.jpg
- :alt: Understanding features
- :align: center
-
-Image is very simple. At the top of image, six small image patches are given. Question for you is to find the exact location of these patches in the original image. How many correct results you can find ?
-
-A and B are flat surfaces, and they are spread in a lot of area. It is difficult to find the exact location of these patches.
-
-C and D are much more simpler. They are edges of the building. You can find an approximate location, but exact location is still difficult. It is because, along the edge, it is same everywhere. Normal to the edge, it is different. So edge is a much better feature compared to flat area, but not good enough (It is good in jigsaw puzzle for comparing continuity of edges).
-
-Finally, E and F are some corners of the building. And they can be easily found out. Because at corners, wherever you move this patch, it will look different. So they can be considered as a good feature. So now we move into more simpler (and widely used image) for better understanding.
-
- .. image:: images/feature_simple.png
- :alt: Features
- :align: center
-
-Just like above, blue patch is flat area and difficult to find and track. Wherever you move the blue patch, it looks the same. For black patch, it is an edge. If you move it in vertical direction (i.e. along the gradient) it changes. Put along the edge (parallel to edge), it looks the same. And for red patch, it is a corner. Wherever you move the patch, it looks different, means it is unique. So basically, corners are considered to be good features in an image. (Not just corners, in some cases blobs are considered good features).
-
-So now we answered our question, "what are these features?". But next question arises. How do we find them? Or how do we find the corners?. That also we answered in an intuitive way, i.e., look for the regions in images which have maximum variation when moved (by a small amount) in all regions around it. This would be projected into computer language in coming chapters. So finding these image features is called **Feature Detection**.
-
-So we found the features in image (Assume you did it). Once you found it, you should find the same in the other images. What we do? We take a region around the feature, we explain it in our own words, like "upper part is blue sky, lower part is building region, on that building there are some glasses etc" and you search for the same area in other images. Basically, you are describing the feature. Similar way, computer also should describe the region around the feature so that it can find it in other images. So called description is called **Feature Description**. Once you have the features and its description, you can find same features in all images and align them, stitch them or do whatever you want.
-
-So in this module, we are looking to different algorithms in OpenCV to find features, describe them, match them etc.
-
-Additional Resources
-=======================
-
-Exercises
-===========
+++ /dev/null
-.. _Matcher:
-
-
-Feature Matching
-*********************************************
-
-Goal
-=====
-In this chapter
- * We will see how to match features in one image with others.
- * We will use the Brute-Force matcher and FLANN Matcher in OpenCV
-
-
-Basics of Brute-Force Matcher
-===================================
-
-Brute-Force matcher is simple. It takes the descriptor of one feature in first set and is matched with all other features in second set using some distance calculation. And the closest one is returned.
-
-For BF matcher, first we have to create the BFMatcher object using **cv2.BFMatcher()**. It takes two optional params. First one is ``normType``. It specifies the distance measurement to be used. By default, it is ``cv2.NORM_L2``. It is good for SIFT, SURF etc (``cv2.NORM_L1`` is also there). For binary string based descriptors like ORB, BRIEF, BRISK etc, ``cv2.NORM_HAMMING`` should be used, which used Hamming distance as measurement. If ORB is using ``WTA_K == 3 or 4``, ``cv2.NORM_HAMMING2`` should be used.
-
-Second param is boolean variable, ``crossCheck`` which is false by default. If it is true, Matcher returns only those matches with value (i,j) such that i-th descriptor in set A has j-th descriptor in set B as the best match and vice-versa. That is, the two features in both sets should match each other. It provides consistant result, and is a good alternative to ratio test proposed by D.Lowe in SIFT paper.
-
-Once it is created, two important methods are *BFMatcher.match()* and *BFMatcher.knnMatch()*. First one returns the best match. Second method returns `k` best matches where k is specified by the user. It may be useful when we need to do additional work on that.
-
-Like we used cv2.drawKeypoints() to draw keypoints, **cv2.drawMatches()** helps us to draw the matches. It stacks two images horizontally and draw lines from first image to second image showing best matches. There is also **cv2.drawMatchesKnn** which draws all the k best matches. If k=2, it will draw two match-lines for each keypoint. So we have to pass a mask if we want to selectively draw it.
-
-Let's see one example for each of SURF and ORB (Both use different distance measurements).
-
-
-
-Brute-Force Matching with ORB Descriptors
---------------------------------------------
-
-Here, we will see a simple example on how to match features between two images. In this case, I have a queryImage and a trainImage. We will try to find the queryImage in trainImage using feature matching. ( The images are ``/samples/c/box.png`` and ``/samples/c/box_in_scene.png``)
-
-We are using SIFT descriptors to match features. So let's start with loading images, finding descriptors etc.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img1 = cv2.imread('box.png',0) # queryImage
- img2 = cv2.imread('box_in_scene.png',0) # trainImage
-
- # Initiate SIFT detector
- orb = cv2.ORB()
-
- # find the keypoints and descriptors with SIFT
- kp1, des1 = orb.detectAndCompute(img1,None)
- kp2, des2 = orb.detectAndCompute(img2,None)
-
-
-Next we create a BFMatcher object with distance measurement ``cv2.NORM_HAMMING`` (since we are using ORB) and ``crossCheck`` is switched on for better results. Then we use Matcher.match() method to get the best matches in two images. We sort them in ascending order of their distances so that best matches (with low distance) come to front. Then we draw only first 10 matches (Just for sake of visibility. You can increase it as you like)
-::
-
- # create BFMatcher object
- bf = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=True)
-
- # Match descriptors.
- matches = bf.match(des1,des2)
-
- # Sort them in the order of their distance.
- matches = sorted(matches, key = lambda x:x.distance)
-
- # Draw first 10 matches.
- img3 = cv2.drawMatches(img1,kp1,img2,kp2,matches[:10], flags=2)
-
- plt.imshow(img3),plt.show()
-
-Below is the result I got:
-
- .. image:: images/matcher_result1.jpg
- :alt: ORB Feature Matching with Brute-Force
- :align: center
-
-
-What is this Matcher Object?
------------------------------------
-
-The result of ``matches = bf.match(des1,des2)`` line is a list of DMatch objects. This DMatch object has following attributes:
-
- * ``DMatch.distance`` - Distance between descriptors. The lower, the better it is.
- * ``DMatch.trainIdx`` - Index of the descriptor in train descriptors
- * ``DMatch.queryIdx`` - Index of the descriptor in query descriptors
- * ``DMatch.imgIdx`` - Index of the train image.
-
-
-Brute-Force Matching with SIFT Descriptors and Ratio Test
--------------------------------------------------------------
-
-This time, we will use ``BFMatcher.knnMatch()`` to get k best matches. In this example, we will take k=2 so that we can apply ratio test explained by D.Lowe in his paper.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img1 = cv2.imread('box.png',0) # queryImage
- img2 = cv2.imread('box_in_scene.png',0) # trainImage
-
- # Initiate SIFT detector
- sift = cv2.SIFT()
-
- # find the keypoints and descriptors with SIFT
- kp1, des1 = sift.detectAndCompute(img1,None)
- kp2, des2 = sift.detectAndCompute(img2,None)
-
- # BFMatcher with default params
- bf = cv2.BFMatcher()
- matches = bf.knnMatch(des1,des2, k=2)
-
- # Apply ratio test
- good = []
- for m,n in matches:
- if m.distance < 0.75*n.distance:
- good.append([m])
-
- # cv2.drawMatchesKnn expects list of lists as matches.
- img3 = cv2.drawMatchesKnn(img1,kp1,img2,kp2,good,flags=2)
-
- plt.imshow(img3),plt.show()
-
-See the result below:
-
- .. image:: images/matcher_result2.jpg
- :alt: SIFT Descriptor with ratio test
- :align: center
-
-
-FLANN based Matcher
-==========================
-
-FLANN stands for Fast Library for Approximate Nearest Neighbors. It contains a collection of algorithms optimized for fast nearest neighbor search in large datasets and for high dimensional features. It works more faster than BFMatcher for large datasets. We will see the second example with FLANN based matcher.
-
-For FLANN based matcher, we need to pass two dictionaries which specifies the algorithm to be used, its related parameters etc. First one is IndexParams. For various algorithms, the information to be passed is explained in FLANN docs. As a summary, for algorithms like SIFT, SURF etc. you can pass following:
-::
-
- index_params = dict(algorithm = FLANN_INDEX_KDTREE, trees = 5)
-
-While using ORB, you can pass the following. The commented values are recommended as per the docs, but it didn't provide required results in some cases. Other values worked fine.:
-::
-
- index_params= dict(algorithm = FLANN_INDEX_LSH,
- table_number = 6, # 12
- key_size = 12, # 20
- multi_probe_level = 1) #2
-
-Second dictionary is the SearchParams. It specifies the number of times the trees in the index should be recursively traversed. Higher values gives better precision, but also takes more time. If you want to change the value, pass ``search_params = dict(checks=100)``.
-
-With these informations, we are good to go.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img1 = cv2.imread('box.png',0) # queryImage
- img2 = cv2.imread('box_in_scene.png',0) # trainImage
-
- # Initiate SIFT detector
- sift = cv2.SIFT()
-
- # find the keypoints and descriptors with SIFT
- kp1, des1 = sift.detectAndCompute(img1,None)
- kp2, des2 = sift.detectAndCompute(img2,None)
-
- # FLANN parameters
- FLANN_INDEX_KDTREE = 0
- index_params = dict(algorithm = FLANN_INDEX_KDTREE, trees = 5)
- search_params = dict(checks=50) # or pass empty dictionary
-
- flann = cv2.FlannBasedMatcher(index_params,search_params)
-
- matches = flann.knnMatch(des1,des2,k=2)
-
- # Need to draw only good matches, so create a mask
- matchesMask = [[0,0] for i in xrange(len(matches))]
-
- # ratio test as per Lowe's paper
- for i,(m,n) in enumerate(matches):
- if m.distance < 0.7*n.distance:
- matchesMask[i]=[1,0]
-
- draw_params = dict(matchColor = (0,255,0),
- singlePointColor = (255,0,0),
- matchesMask = matchesMask,
- flags = 0)
-
- img3 = cv2.drawMatchesKnn(img1,kp1,img2,kp2,matches,None,**draw_params)
-
- plt.imshow(img3,),plt.show()
-
-
-See the result below:
-
- .. image:: images/matcher_flann.jpg
- :alt: FLANN based matching
- :align: center
-
-
-Additional Resources
-========================
-
-
-Exercises
-=================
+++ /dev/null
-.. _ORB:
-
-ORB (Oriented FAST and Rotated BRIEF)
-***************************************
-
-Goal
-======
-
-In this chapter,
- * We will see the basics of ORB
-
-
-Theory
-==========
-
-As an OpenCV enthusiast, the most important thing about the ORB is that it came from "OpenCV Labs". This algorithm was brought up by Ethan Rublee, Vincent Rabaud, Kurt Konolige and Gary R. Bradski in their paper **ORB: An efficient alternative to SIFT or SURF** in 2011. As the title says, it is a good alternative to SIFT and SURF in computation cost, matching performance and mainly the patents. Yes, SIFT and SURF are patented and you are supposed to pay them for its use. But ORB is not !!!
-
-ORB is basically a fusion of FAST keypoint detector and BRIEF descriptor with many modifications to enhance the performance. First it use FAST to find keypoints, then apply Harris corner measure to find top N points among them. It also use pyramid to produce multiscale-features. But one problem is that, FAST doesn't compute the orientation. So what about rotation invariance? Authors came up with following modification.
-
-It computes the intensity weighted centroid of the patch with located corner at center. The direction of the vector from this corner point to centroid gives the orientation. To improve the rotation invariance, moments are computed with x and y which should be in a circular region of radius :math:`r`, where :math:`r` is the size of the patch.
-
-Now for descriptors, ORB use BRIEF descriptors. But we have already seen that BRIEF performs poorly with rotation. So what ORB does is to "steer" BRIEF according to the orientation of keypoints. For any feature set of :math:`n` binary tests at location
-:math:`(x_i, y_i)`, define a :math:`2 \times n` matrix, :math:`S` which contains the coordinates of these pixels. Then using the orientation of patch, :math:`\theta`, its rotation matrix is found and rotates the :math:`S` to get steered(rotated) version :math:`S_\theta`.
-
-ORB discretize the angle to increments of :math:`2 \pi /30` (12 degrees), and construct a lookup table of precomputed BRIEF patterns. As long as the keypoint orientation :math:`\theta` is consistent across views, the correct set of points :math:`S_\theta` will be used to compute its descriptor.
-
-BRIEF has an important property that each bit feature has a large variance and a mean near 0.5. But once it is oriented along keypoint direction, it loses this property and become more distributed. High variance makes a feature more discriminative, since it responds differentially to inputs. Another desirable property is to have the tests uncorrelated, since then each test will contribute to the result. To resolve all these, ORB runs a greedy search among all possible binary tests to find the ones that have both high variance and means close to 0.5, as well as being uncorrelated. The result is called **rBRIEF**.
-
-For descriptor matching, multi-probe LSH which improves on the traditional LSH, is used. The paper says ORB is much faster than SURF and SIFT and ORB descriptor works better than SURF. ORB is a good choice in low-power devices for panorama stitching etc.
-
-
-ORB in OpenCV
-================
-
-As usual, we have to create an ORB object with the function, **cv2.ORB()** or using feature2d common interface. It has a number of optional parameters. Most useful ones are ``nFeatures`` which denotes maximum number of features to be retained (by default 500), ``scoreType`` which denotes whether Harris score or FAST score to rank the features (by default, Harris score) etc. Another parameter, ``WTA_K`` decides number of points that produce each element of the oriented BRIEF descriptor. By default it is two, ie selects two points at a time. In that case, for matching, ``NORM_HAMMING`` distance is used. If WTA_K is 3 or 4, which takes 3 or 4 points to produce BRIEF descriptor, then matching distance is defined by ``NORM_HAMMING2``.
-
-Below is a simple code which shows the use of ORB.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('simple.jpg',0)
-
- # Initiate STAR detector
- orb = cv2.ORB()
-
- # find the keypoints with ORB
- kp = orb.detect(img,None)
-
- # compute the descriptors with ORB
- kp, des = orb.compute(img, kp)
-
- # draw only keypoints location,not size and orientation
- img2 = cv2.drawKeypoints(img,kp,color=(0,255,0), flags=0)
- plt.imshow(img2),plt.show()
-
-See the result below:
-
- .. image:: images/orb_kp.jpg
- :alt: ORB Keypoints
- :align: center
-
-
-ORB feature matching, we will do in another chapter.
-
-Additional Resources
-==========================
-
-#. Ethan Rublee, Vincent Rabaud, Kurt Konolige, Gary R. Bradski: ORB: An efficient alternative to SIFT or SURF. ICCV 2011: 2564-2571.
-
-
-Exercises
-==============
+++ /dev/null
-.. _shi_tomasi:
-
-Shi-Tomasi Corner Detector & Good Features to Track
-*******************************************************
-
-Goal
-=======
-
-In this chapter,
-
- * We will learn about the another corner detector: Shi-Tomasi Corner Detector
- * We will see the function: **cv2.goodFeaturesToTrack()**
-
-Theory
-=========
-
-In last chapter, we saw Harris Corner Detector. Later in 1994, J. Shi and C. Tomasi made a small modification to it in their paper **Good Features to Track** which shows better results compared to Harris Corner Detector. The scoring function in Harris Corner Detector was given by:
-
-.. math::
-
- R = \lambda_1 \lambda_2 - k(\lambda_1+\lambda_2)^2
-
-Instead of this, Shi-Tomasi proposed:
-
-.. math::
-
- R = min(\lambda_1, \lambda_2)
-
-If it is a greater than a threshold value, it is considered as a corner. If we plot it in :math:`\lambda_1 - \lambda_2` space as we did in Harris Corner Detector, we get an image as below:
-
- .. image:: images/shitomasi_space.png
- :alt: Shi-Tomasi Corner Space
- :align: center
-
-From the figure, you can see that only when :math:`\lambda_1` and :math:`\lambda_2` are above a minimum value, :math:`\lambda_{min}`, it is conidered as a corner(green region).
-
-Code
-=======
-
-OpenCV has a function, **cv2.goodFeaturesToTrack()**. It finds N strongest corners in the image by Shi-Tomasi method (or Harris Corner Detection, if you specify it). As usual, image should be a grayscale image. Then you specify number of corners you want to find. Then you specify the quality level, which is a value between 0-1, which denotes the minimum quality of corner below which everyone is rejected. Then we provide the minimum euclidean distance between corners detected.
-
-With all these informations, the function finds corners in the image. All corners below quality level are rejected. Then it sorts the remaining corners based on quality in the descending order. Then function takes first strongest corner, throws away all the nearby corners in the range of minimum distance and returns N strongest corners.
-
-In below example, we will try to find 25 best corners:
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('simple.jpg')
- gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
-
- corners = cv2.goodFeaturesToTrack(gray,25,0.01,10)
- corners = np.int0(corners)
-
- for i in corners:
- x,y = i.ravel()
- cv2.circle(img,(x,y),3,255,-1)
-
- plt.imshow(img),plt.show()
-
-See the result below:
-
- .. image:: images/shitomasi_block1.jpg
- :alt: Shi-Tomasi Corners
- :align: center
-
-
-This function is more appropriate for tracking. We will see that when its time comes.
-
-Additional Resources
-======================
-
-
-Exercises
-============
+++ /dev/null
-.. _sift_intro:
-
-
-Introduction to SIFT (Scale-Invariant Feature Transform)
-*************************************************************
-
-Goal
-======
-
-In this chapter,
- * We will learn about the concepts of SIFT algorithm
- * We will learn to find SIFT Keypoints and Descriptors.
-
-
-Theory
-========
-
-In last couple of chapters, we saw some corner detectors like Harris etc. They are rotation-invariant, which means, even if the image is rotated, we can find the same corners. It is obvious because corners remain corners in rotated image also. But what about scaling? A corner may not be a corner if the image is scaled. For example, check a simple image below. A corner in a small image within a small window is flat when it is zoomed in the same window. So Harris corner is not scale invariant.
-
- .. image:: images/sift_scale_invariant.jpg
- :alt: Scale-Invariance
- :align: center
-
-So, in 2004, **D.Lowe**, University of British Columbia, came up with a new algorithm, Scale Invariant Feature Transform (SIFT) in his paper, **Distinctive Image Features from Scale-Invariant Keypoints**, which extract keypoints and compute its descriptors. *(This paper is easy to understand and considered to be best material available on SIFT. So this explanation is just a short summary of this paper)*.
-
-There are mainly four steps involved in SIFT algorithm. We will see them one-by-one.
-
-1. Scale-space Extrema Detection
---------------------------------------
-
-From the image above, it is obvious that we can't use the same window to detect keypoints with different scale. It is OK with small corner. But to detect larger corners we need larger windows. For this, scale-space filtering is used. In it, Laplacian of Gaussian is found for the image with various :math:`\sigma` values. LoG acts as a blob detector which detects blobs in various sizes due to change in :math:`\sigma`. In short, :math:`\sigma` acts as a scaling parameter. For eg, in the above image, gaussian kernel with low :math:`\sigma` gives high value for small corner while guassian kernel with high :math:`\sigma` fits well for larger corner. So, we can find the local maxima across the scale and space which gives us a list of :math:`(x,y,\sigma)` values which means there is a potential keypoint at (x,y) at :math:`\sigma` scale.
-
-But this LoG is a little costly, so SIFT algorithm uses Difference of Gaussians which is an approximation of LoG. Difference of Gaussian is obtained as the difference of Gaussian blurring of an image with two different :math:`\sigma`, let it be :math:`\sigma` and :math:`k\sigma`. This process is done for different octaves of the image in Gaussian Pyramid. It is represented in below image:
-
-
- .. image:: images/sift_dog.jpg
- :alt: Difference of Gaussian
- :align: center
-
-Once this DoG are found, images are searched for local extrema over scale and space. For eg, one pixel in an image is compared with its 8 neighbours as well as 9 pixels in next scale and 9 pixels in previous scales. If it is a local extrema, it is a potential keypoint. It basically means that keypoint is best represented in that scale. It is shown in below image:
-
- .. image:: images/sift_local_extrema.jpg
- :alt: Difference of Gaussian
- :align: center
-
-Regarding different parameters, the paper gives some empirical data which can be summarized as, number of octaves = 4, number of scale levels = 5, initial :math:`\sigma=1.6`, :math:`k=\sqrt{2}` etc as optimal values.
-
-
-2. Keypoint Localization
-------------------------------------
-
-Once potential keypoints locations are found, they have to be refined to get more accurate results. They used Taylor series expansion of scale space to get more accurate location of extrema, and if the intensity at this extrema is less than a threshold value (0.03 as per the paper), it is rejected. This threshold is called **contrastThreshold** in OpenCV
-
-DoG has higher response for edges, so edges also need to be removed. For this, a concept similar to Harris corner detector is used. They used a 2x2 Hessian matrix (H) to compute the pricipal curvature. We know from Harris corner detector that for edges, one eigen value is larger than the other. So here they used a simple function,
-
-.. math:
-
- \frac{Tr(H)^2}{Det(H)} < \frac{(r+1)^2}{r} \; \text{where} \; r = \frac{\lambda_1}{\lambda_2}; \; \lambda_1 > \lambda_2
-
-If this ratio is greater than a threshold, called **edgeThreshold** in OpenCV, that keypoint is discarded. It is given as 10 in paper.
-
-So it eliminates any low-contrast keypoints and edge keypoints and what remains is strong interest points.
-
-3. Orientation Assignment
------------------------------------
-
-Now an orientation is assigned to each keypoint to achieve invariance to image rotation. A neigbourhood is taken around the keypoint location depending on the scale, and the gradient magnitude and direction is calculated in that region. An orientation histogram with 36 bins covering 360 degrees is created. (It is weighted by gradient magnitude and gaussian-weighted circular window with :math:`\sigma` equal to 1.5 times the scale of keypoint. The highest peak in the histogram is taken and any peak above 80% of it is also considered to calculate the orientation. It creates keypoints with same location and scale, but different directions. It contribute to stability of matching.
-
-
-4. Keypoint Descriptor
------------------------------------------
-
-Now keypoint descriptor is created. A 16x16 neighbourhood around the keypoint is taken. It is devided into 16 sub-blocks of 4x4 size. For each sub-block, 8 bin orientation histogram is created. So a total of 128 bin values are available. It is represented as a vector to form keypoint descriptor. In addition to this, several measures are taken to achieve robustness against illumination changes, rotation etc.
-
-5. Keypoint Matching
-----------------------------------------
-
-Keypoints between two images are matched by identifying their nearest neighbours. But in some cases, the second closest-match may be very near to the first. It may happen due to noise or some other reasons. In that case, ratio of closest-distance to second-closest distance is taken. If it is greater than 0.8, they are rejected. It eliminaters around 90% of false matches while discards only 5% correct matches, as per the paper.
-
-So this is a summary of SIFT algorithm. For more details and understanding, reading the original paper is highly recommended. Remember one thing, this algorithm is patented. So this algorithm is included in Non-free module in OpenCV.
-
-
-SIFT in OpenCV
-=================
-
-So now let's see SIFT functionalities available in OpenCV. Let's start with keypoint detection and draw them. First we have to construct a SIFT object. We can pass different parameters to it which are optional and they are well explained in docs.
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('home.jpg')
- gray= cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
-
- sift = cv2.SIFT()
- kp = sift.detect(gray,None)
-
- img=cv2.drawKeypoints(gray,kp)
-
- cv2.imwrite('sift_keypoints.jpg',img)
-
-**sift.detect()** function finds the keypoint in the images. You can pass a mask if you want to search only a part of image. Each keypoint is a special structure which has many attributes like its (x,y) coordinates, size of the meaningful neighbourhood, angle which specifies its orientation, response that specifies strength of keypoints etc.
-
-OpenCV also provides **cv2.drawKeyPoints()** function which draws the small circles on the locations of keypoints. If you pass a flag, **cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS** to it, it will draw a circle with size of keypoint and it will even show its orientation. See below example.
-::
-
- img=cv2.drawKeypoints(gray,kp,flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS)
- cv2.imwrite('sift_keypoints.jpg',img)
-
-See the two results below:
-
- .. image:: images/sift_keypoints.jpg
- :alt: SIFT Keypoints
- :align: center
-
-Now to calculate the descriptor, OpenCV provides two methods.
-
-1. Since you already found keypoints, you can call **sift.compute()** which computes the descriptors from the keypoints we have found. Eg: ``kp,des = sift.compute(gray,kp)``
-
-2. If you didn't find keypoints, directly find keypoints and descriptors in a single step with the function, **sift.detectAndCompute()**.
-
-We will see the second method:
-::
-
- sift = cv2.SIFT()
- kp, des = sift.detectAndCompute(gray,None)
-
-Here kp will be a list of keypoints and des is a numpy array of shape :math:`Number\_of\_Keypoints \times 128`.
-
-So we got keypoints, descriptors etc. Now we want to see how to match keypoints in different images. That we will learn in coming chapters.
-
-
-Additional Resources
-=====================
-
-
-
-Exercises
-=============
+++ /dev/null
-.. _SURF:
-
-
-Introduction to SURF (Speeded-Up Robust Features)
-*****************************************************
-
-Goal
-======
-
-In this chapter,
- * We will see the basics of SURF
- * We will see SURF functionalities in OpenCV
-
-
-Theory
-==========
-
-In last chapter, we saw SIFT for keypoint detection and description. But it was comparatively slow and people needed more speeded-up version. In 2006, three people, Bay, H., Tuytelaars, T. and Van Gool, L, published another paper, "SURF: Speeded Up Robust Features" which introduced a new algorithm called SURF. As name suggests, it is a speeded-up version of SIFT.
-
-In SIFT, Lowe approximated Laplacian of Gaussian with Difference of Gaussian for finding scale-space. SURF goes a little further and approximates LoG with Box Filter. Below image shows a demonstration of such an approximation. One big advantage of this approximation is that, convolution with box filter can be easily calculated with the help of integral images. And it can be done in parallel for different scales. Also the SURF rely on determinant of Hessian matrix for both scale and location.
-
- .. image:: images/surf_boxfilter.jpg
- :alt: Box Filter approximation of Laplacian
- :align: center
-
-
-For orientation assignment, SURF uses wavelet responses in horizontal and vertical direction for a neighbourhood of size 6s. Adequate guassian weights are also applied to it. Then they are plotted in a space as given in below image. The dominant orientation is estimated by calculating the sum of all responses within a sliding orientation window of angle 60 degrees. Interesting thing is that, wavelet response can be found out using integral images very easily at any scale. For many applications, rotation invariance is not required, so no need of finding this orientation, which speeds up the process. SURF provides such a functionality called Upright-SURF or U-SURF. It improves speed and is robust upto :math:`\pm 15^{\circ}`. OpenCV supports both, depending upon the flag, **upright**. If it is 0, orientation is calculated. If it is 1, orientation is not calculated and it is more faster.
-
- .. image:: images/surf_orientation.jpg
- :alt: Orientation Assignment in SURF
- :align: center
-
-For feature description, SURF uses Wavelet responses in horizontal and vertical direction (again, use of integral images makes things easier). A neighbourhood of size 20sX20s is taken around the keypoint where s is the size. It is divided into 4x4 subregions. For each subregion, horizontal and vertical wavelet responses are taken and a vector is formed like this, :math:`v=( \sum{d_x}, \sum{d_y}, \sum{|d_x|}, \sum{|d_y|})`. This when represented as a vector gives SURF feature descriptor with total 64 dimensions. Lower the dimension, higher the speed of computation and matching, but provide better distinctiveness of features.
-
-For more distinctiveness, SURF feature descriptor has an extended 128 dimension version. The sums of :math:`d_x` and :math:`|d_x|` are computed separately for :math:`d_y < 0` and :math:`d_y \geq 0`. Similarly, the sums of :math:`d_y` and :math:`|d_y|` are split
-up according to the sign of :math:`d_x` , thereby doubling the number of features. It doesn't add much computation complexity. OpenCV supports both by setting the value of flag **extended** with 0 and 1 for 64-dim and 128-dim respectively (default is 128-dim)
-
-Another important improvement is the use of sign of Laplacian (trace of Hessian Matrix) for underlying interest point. It adds no computation cost since it is already computed during detection. The sign of the Laplacian distinguishes bright blobs on dark backgrounds from the reverse situation. In the matching stage, we only compare features if they have the same type of contrast (as shown in image below). This minimal information allows for faster matching, without reducing the descriptor's performance.
-
- .. image:: images/surf_matching.jpg
- :alt: Fast Indexing for Matching
- :align: center
-
-In short, SURF adds a lot of features to improve the speed in every step. Analysis shows it is 3 times faster than SIFT while performance is comparable to SIFT. SURF is good at handling images with blurring and rotation, but not good at handling viewpoint change and illumination change.
-
-
-SURF in OpenCV
-====================
-
-OpenCV provides SURF functionalities just like SIFT. You initiate a SURF object with some optional conditions like 64/128-dim descriptors, Upright/Normal SURF etc. All the details are well explained in docs. Then as we did in SIFT, we can use SURF.detect(), SURF.compute() etc for finding keypoints and descriptors.
-
-First we will see a simple demo on how to find SURF keypoints and descriptors and draw it. All examples are shown in Python terminal since it is just same as SIFT only.
-::
-
- >>> img = cv2.imread('fly.png',0)
-
- # Create SURF object. You can specify params here or later.
- # Here I set Hessian Threshold to 400
- >>> surf = cv2.SURF(400)
-
- # Find keypoints and descriptors directly
- >>> kp, des = surf.detectAndCompute(img,None)
-
- >>> len(kp)
- 699
-
-
-1199 keypoints is too much to show in a picture. We reduce it to some 50 to draw it on an image. While matching, we may need all those features, but not now. So we increase the Hessian Threshold.
-::
-
- # Check present Hessian threshold
- >>> print surf.hessianThreshold
- 400.0
-
- # We set it to some 50000. Remember, it is just for representing in picture.
- # In actual cases, it is better to have a value 300-500
- >>> surf.hessianThreshold = 50000
-
- # Again compute keypoints and check its number.
- >>> kp, des = surf.detectAndCompute(img,None)
-
- >>> print len(kp)
- 47
-
-It is less than 50. Let's draw it on the image.
-::
-
- >>> img2 = cv2.drawKeypoints(img,kp,None,(255,0,0),4)
-
- >>> plt.imshow(img2),plt.show()
-
-See the result below. You can see that SURF is more like a blob detector. It detects the white blobs on wings of butterfly. You can test it with other images.
-
- .. image:: images/surf_kp1.jpg
- :alt: SURF Keypoints with Orientation
- :align: center
-
-Now I want to apply U-SURF, so that it won't find the orientation.
-::
-
- # Check upright flag, if it False, set it to True
- >>> print surf.upright
- False
-
- >>> surf.upright = True
-
- # Recompute the feature points and draw it
- >>> kp = surf.detect(img,None)
- >>> img2 = cv2.drawKeypoints(img,kp,None,(255,0,0),4)
-
- >>> plt.imshow(img2),plt.show()
-
-See the results below. All the orientations are shown in same direction. It is more faster than previous. If you are working on cases where orientation is not a problem (like panorama stitching) etc, this is better.
-
- .. image:: images/surf_kp2.jpg
- :alt: Upright-SURF
- :align: center
-
-Finally we check the descriptor size and change it to 128 if it is only 64-dim.
-::
-
- # Find size of descriptor
- >>> print surf.descriptorSize()
- 64
-
- # That means flag, "extended" is False.
- >>> surf.extended
- False
-
- # So we make it to True to get 128-dim descriptors.
- >>> surf.extended = True
- >>> kp, des = surf.detectAndCompute(img,None)
- >>> print surf.descriptorSize()
- 128
- >>> print des.shape
- (47, 128)
-
-Remaining part is matching which we will do in another chapter.
-
-Additional Resources
-=======================
-
-
-Exercises
-==============
+++ /dev/null
-.. _PY_Table-Of-Content-Feature2D:
-
-Feature Detection and Description
-------------------------------------------
-
-* :ref:`Features_Meaning`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_1| What are the main features in an image? How can finding those features be useful to us?
-
- =========== ======================================================
-
- .. |f2d_1| image:: images/features_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`Harris_Corners`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_2| Okay, Corners are good features? But how do we find them?
-
- =========== ======================================================
-
- .. |f2d_2| image:: images/harris_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`shi_tomasi`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_3| We will look into Shi-Tomasi corner detection
-
- =========== ======================================================
-
- .. |f2d_3| image:: images/shi_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`sift_intro`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_4| Harris corner detector is not good enough when scale of image changes. Lowe developed a breakthrough method to find scale-invariant features and it is called SIFT
-
- =========== ======================================================
-
- .. |f2d_4| image:: images/sift_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`SURF`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_5| SIFT is really good, but not fast enough, so people came up with a speeded-up version called SURF.
-
- =========== ======================================================
-
- .. |f2d_5| image:: images/surf_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`FAST`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_06| All the above feature detection methods are good in some way. But they are not fast enough to work in real-time applications like SLAM. There comes the FAST algorithm, which is really "FAST".
-
- =========== ======================================================
-
- .. |f2d_06| image:: images/fast_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`BRIEF`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_07| SIFT uses a feature descriptor with 128 floating point numbers. Consider thousands of such features. It takes lots of memory and more time for matching. We can compress it to make it faster. But still we have to calculate it first. There comes BRIEF which gives the shortcut to find binary descriptors with less memory, faster matching, still higher recognition rate.
-
- =========== ======================================================
-
- .. |f2d_07| image:: images/brief.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`ORB`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_08| SIFT and SURF are good in what they do, but what if you have to pay a few dollars every year to use them in your applications? Yeah, they are patented!!! To solve that problem, OpenCV devs came up with a new "FREE" alternative to SIFT & SURF, and that is ORB.
- =========== ======================================================
-
- .. |f2d_08| image:: images/orb.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`Matcher`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_09| We know a great deal about feature detectors and descriptors. It is time to learn how to match different descriptors. OpenCV provides two techniques, Brute-Force matcher and FLANN based matcher.
- =========== ======================================================
-
- .. |f2d_09| image:: images/matching.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`PY_feature_homography`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |f2d_10| Now we know about feature matching. Let's mix it up with `calib3d` module to find objects in a complex image.
- =========== ======================================================
-
- .. |f2d_10| image:: images/homography_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_features_meaning/py_features_meaning
- ../py_features_harris/py_features_harris
- ../py_shi_tomasi/py_shi_tomasi
- ../py_sift_intro/py_sift_intro
- ../py_surf_intro/py_surf_intro
- ../py_fast/py_fast
- ../py_brief/py_brief
- ../py_orb/py_orb
- ../py_matcher/py_matcher
- ../py_feature_homography/py_feature_homography
+++ /dev/null
-.. _Drawing_Functions:
-
-Drawing Functions in OpenCV
-******************************
-
-Goal
-=====
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Learn to draw different geometric shapes with OpenCV
- * You will learn these functions : **cv2.line()**, **cv2.circle()** , **cv2.rectangle()**, **cv2.ellipse()**, **cv2.putText()** etc.
-
-Code
-=====
-
-In all the above functions, you will see some common arguments as given below:
-
- * img : The image where you want to draw the shapes
- * color : Color of the shape. for BGR, pass it as a tuple, eg: ``(255,0,0)`` for blue. For grayscale, just pass the scalar value.
- * thickness : Thickness of the line or circle etc. If **-1** is passed for closed figures like circles, it will fill the shape. *default thickness = 1*
- * lineType : Type of line, whether 8-connected, anti-aliased line etc. *By default, it is 8-connected.* ``cv2.LINE_AA`` gives anti-aliased line which looks great for curves.
-
-Drawing Line
--------------
-To draw a line, you need to pass starting and ending coordinates of line. We will create a black image and draw a blue line on it from top-left to bottom-right corners.
-::
-
- import numpy as np
- import cv2
-
- # Create a black image
- img = np.zeros((512,512,3), np.uint8)
-
- # Draw a diagonal blue line with thickness of 5 px
- cv2.line(img,(0,0),(511,511),(255,0,0),5)
-
-Drawing Rectangle
--------------------
-To draw a rectangle, you need top-left corner and bottom-right corner of rectangle. This time we will draw a green rectangle at the top-right corner of image.
-::
-
- cv2.rectangle(img,(384,0),(510,128),(0,255,0),3)
-
-Drawing Circle
-----------------
-To draw a circle, you need its center coordinates and radius. We will draw a circle inside the rectangle drawn above.
-::
-
- cv2.circle(img,(447,63), 63, (0,0,255), -1)
-
-Drawing Ellipse
---------------------
-
-To draw the ellipse, we need to pass several arguments. One argument is the center location (x,y). Next argument is axes lengths (major axis length, minor axis length). ``angle`` is the angle of rotation of ellipse in anti-clockwise direction. ``startAngle`` and ``endAngle`` denotes the starting and ending of ellipse arc measured in clockwise direction from major axis. i.e. giving values 0 and 360 gives the full ellipse. For more details, check the documentation of **cv2.ellipse()**. Below example draws a half ellipse at the center of the image.
-::
-
- cv2.ellipse(img,(256,256),(100,50),0,0,180,255,-1)
-
-
-Drawing Polygon
-------------------
-To draw a polygon, first you need coordinates of vertices. Make those points into an array of shape ``ROWSx1x2`` where ROWS are number of vertices and it should be of type ``int32``. Here we draw a small polygon of with four vertices in yellow color.
-::
-
- pts = np.array([[10,5],[20,30],[70,20],[50,10]], np.int32)
- pts = pts.reshape((-1,1,2))
- cv2.polylines(img,[pts],True,(0,255,255))
-
-.. Note:: If third argument is ``False``, you will get a polylines joining all the points, not a closed shape.
-
-.. Note:: ``cv2.polylines()`` can be used to draw multiple lines. Just create a list of all the lines you want to draw and pass it to the function. All lines will be drawn individually. It is a much better and faster way to draw a group of lines than calling ``cv2.line()`` for each line.
-
-Adding Text to Images:
-------------------------
-To put texts in images, you need specify following things.
- * Text data that you want to write
- * Position coordinates of where you want put it (i.e. bottom-left corner where data starts).
- * Font type (Check **cv2.putText()** docs for supported fonts)
- * Font Scale (specifies the size of font)
- * regular things like color, thickness, lineType etc. For better look, ``lineType = cv2.LINE_AA`` is recommended.
-
-We will write **OpenCV** on our image in white color.
-::
-
- font = cv2.FONT_HERSHEY_SIMPLEX
- cv2.putText(img,'OpenCV',(10,500), font, 4,(255,255,255),2,cv2.LINE_AA)
-
-Result
-----------
-So it is time to see the final result of our drawing. As you studied in previous articles, display the image to see it.
-
- .. image:: images/drawing_result.jpg
- :alt: Drawing Functions in OpenCV
- :align: center
-
-
-Additional Resources
-========================
-
-1. The angles used in ellipse function is not our circular angles. For more details, visit `this discussion <http://answers.opencv.org/question/14541/angles-in-ellipse-function/>`_.
-
-
-Exercises
-==============
-#. Try to create the logo of OpenCV using drawing functions available in OpenCV.
+++ /dev/null
-.. _PY_Display_Image:
-
-Getting Started with Images
-*****************************
-
-Goals
-======
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Here, you will learn how to read an image, how to display it and how to save it back
- * You will learn these functions : **cv2.imread()**, **cv2.imshow()** , **cv2.imwrite()**
- * Optionally, you will learn how to display images with Matplotlib
-
-Using OpenCV
-=============
-
-Read an image
---------------
-
-Use the function **cv2.imread()** to read an image. The image should be in the working directory or a full path of image should be given.
-
-Second argument is a flag which specifies the way image should be read.
-
-* cv2.IMREAD_COLOR : Loads a color image. Any transparency of image will be neglected. It is the default flag.
-* cv2.IMREAD_GRAYSCALE : Loads image in grayscale mode
-* cv2.IMREAD_UNCHANGED : Loads image as such including alpha channel
-
-.. note:: Instead of these three flags, you can simply pass integers 1, 0 or -1 respectively.
-
-See the code below:
-::
-
- import numpy as np
- import cv2
-
- # Load an color image in grayscale
- img = cv2.imread('messi5.jpg',0)
-
-.. warning:: Even if the image path is wrong, it won't throw any error, but ``print img`` will give you ``None``
-
-Display an image
------------------
-
-Use the function **cv2.imshow()** to display an image in a window. The window automatically fits to the image size.
-
-First argument is a window name which is a string. second argument is our image. You can create as many windows as you wish, but with different window names.
-::
-
- cv2.imshow('image',img)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-A screenshot of the window will look like this (in Fedora-Gnome machine):
-
- .. image:: images/opencv_screenshot.jpg
- :alt: Screenshot of Image Window in OpenCV
- :align: center
-
-**cv2.waitKey()** is a keyboard binding function. Its argument is the time in milliseconds. The function waits for specified milliseconds for any keyboard event. If you press any key in that time, the program continues. If **0** is passed, it waits indefinitely for a key stroke. It can also be set to detect specific key strokes like, if key `a` is pressed etc which we will discuss below.
-
-.. note:: Besides binding keyboard events this function also processes many other GUI events, so you MUST use it to actually display the image.
-
-**cv2.destroyAllWindows()** simply destroys all the windows we created. If you want to destroy any specific window, use the function **cv2.destroyWindow()** where you pass the exact window name as the argument.
-
-.. note:: There is a special case where you can already create a window and load image to it later. In that case, you can specify whether window is resizable or not. It is done with the function **cv2.namedWindow()**. By default, the flag is ``cv2.WINDOW_AUTOSIZE``. But if you specify flag to be ``cv2.WINDOW_NORMAL``, you can resize window. It will be helpful when image is too large in dimension and adding track bar to windows.
-
-See the code below:
-::
-
- cv2.namedWindow('image', cv2.WINDOW_NORMAL)
- cv2.imshow('image',img)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-Write an image
----------------
-
-Use the function **cv2.imwrite()** to save an image.
-
-First argument is the file name, second argument is the image you want to save.
-::
-
- cv2.imwrite('messigray.png',img)
-
-This will save the image in PNG format in the working directory.
-
-Sum it up
----------------
-
-Below program loads an image in grayscale, displays it, save the image if you press 's' and exit, or simply exit without saving if you press `ESC` key.
-::
-
- import numpy as np
- import cv2
-
- img = cv2.imread('messi5.jpg',0)
- cv2.imshow('image',img)
- k = cv2.waitKey(0)
- if k == 27: # wait for ESC key to exit
- cv2.destroyAllWindows()
- elif k == ord('s'): # wait for 's' key to save and exit
- cv2.imwrite('messigray.png',img)
- cv2.destroyAllWindows()
-
-.. warning:: If you are using a 64-bit machine, you will have to modify ``k = cv2.waitKey(0)`` line as follows : ``k = cv2.waitKey(0) & 0xFF``
-
-Using Matplotlib
-=================
-
-Matplotlib is a plotting library for Python which gives you wide variety of plotting methods. You will see them in coming articles. Here, you will learn how to display image with Matplotlib. You can zoom images, save it etc using Matplotlib.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('messi5.jpg',0)
- plt.imshow(img, cmap = 'gray', interpolation = 'bicubic')
- plt.xticks([]), plt.yticks([]) # to hide tick values on X and Y axis
- plt.show()
-
-A screen-shot of the window will look like this :
-
- .. image:: images/matplotlib_screenshot.jpg
- :alt: Screenshot of Image Window in Matplotlib
- :align: center
-
-.. seealso:: Plenty of plotting options are available in Matplotlib. Please refer to Matplotlib docs for more details. Some, we will see on the way.
-
-.. warning:: Color image loaded by OpenCV is in BGR mode. But Matplotlib displays in RGB mode. So color images will not be displayed correctly in Matplotlib if image is read with OpenCV. Please see the exercises for more details.
-
-Additional Resources
-======================
-
-#. `Matplotlib Plotting Styles and Features <http://matplotlib.org/api/pyplot_api.html>`_
-
-Exercises
-==========
-
-#. There is some problem when you try to load color image in OpenCV and display it in Matplotlib. Read `this discussion <http://stackoverflow.com/a/15074748/1134940>`_ and understand it.
+++ /dev/null
-.. _Mouse_Handling:
-
-Mouse as a Paint-Brush
-***********************
-
-Goal
-======
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Learn to handle mouse events in OpenCV
- * You will learn these functions : **cv2.setMouseCallback()**
-
-Simple Demo
-=============
-
-Here, we create a simple application which draws a circle on an image wherever we double-click on it.
-
-First we create a mouse callback function which is executed when a mouse event take place. Mouse event can be anything related to mouse like left-button down, left-button up, left-button double-click etc. It gives us the coordinates (x,y) for every mouse event. With this event and location, we can do whatever we like. To list all available events available, run the following code in Python terminal:
-::
-
- >>> import cv2
- >>> events = [i for i in dir(cv2) if 'EVENT' in i]
- >>> print events
-
-Creating mouse callback function has a specific format which is same everywhere. It differs only in what the function does. So our mouse callback function does one thing, it draws a circle where we double-click. So see the code below. Code is self-explanatory from comments :
-::
-
- import cv2
- import numpy as np
-
- # mouse callback function
- def draw_circle(event,x,y,flags,param):
- if event == cv2.EVENT_LBUTTONDBLCLK:
- cv2.circle(img,(x,y),100,(255,0,0),-1)
-
- # Create a black image, a window and bind the function to window
- img = np.zeros((512,512,3), np.uint8)
- cv2.namedWindow('image')
- cv2.setMouseCallback('image',draw_circle)
-
- while(1):
- cv2.imshow('image',img)
- if cv2.waitKey(20) & 0xFF == 27:
- break
- cv2.destroyAllWindows()
-
-More Advanced Demo
-===================
-
-Now we go for a much better application. In this, we draw either rectangles or circles (depending on the mode we select) by dragging the mouse like we do in Paint application. So our mouse callback function has two parts, one to draw rectangle and other to draw the circles. This specific example will be really helpful in creating and understanding some interactive applications like object tracking, image segmentation etc.
-::
-
- import cv2
- import numpy as np
-
- drawing = False # true if mouse is pressed
- mode = True # if True, draw rectangle. Press 'm' to toggle to curve
- ix,iy = -1,-1
-
- # mouse callback function
- def draw_circle(event,x,y,flags,param):
- global ix,iy,drawing,mode
-
- if event == cv2.EVENT_LBUTTONDOWN:
- drawing = True
- ix,iy = x,y
-
- elif event == cv2.EVENT_MOUSEMOVE:
- if drawing == True:
- if mode == True:
- cv2.rectangle(img,(ix,iy),(x,y),(0,255,0),-1)
- else:
- cv2.circle(img,(x,y),5,(0,0,255),-1)
-
- elif event == cv2.EVENT_LBUTTONUP:
- drawing = False
- if mode == True:
- cv2.rectangle(img,(ix,iy),(x,y),(0,255,0),-1)
- else:
- cv2.circle(img,(x,y),5,(0,0,255),-1)
-
-Next we have to bind this mouse callback function to OpenCV window. In the main loop, we should set a keyboard binding for key 'm' to toggle between rectangle and circle.
-::
-
- img = np.zeros((512,512,3), np.uint8)
- cv2.namedWindow('image')
- cv2.setMouseCallback('image',draw_circle)
-
- while(1):
- cv2.imshow('image',img)
- k = cv2.waitKey(1) & 0xFF
- if k == ord('m'):
- mode = not mode
- elif k == 27:
- break
-
- cv2.destroyAllWindows()
-
-
-Additional Resources
-========================
-
-
-Exercises
-==========
-
-#. In our last example, we drew filled rectangle. You modify the code to draw an unfilled rectangle.
+++ /dev/null
-.. _PY_Table-Of-Content-Gui:
-
-Gui Features in OpenCV
------------------------------------------------------------
-
-
-* :ref:`PY_Display_Image`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |gui_1| Learn to load an image, display it and save it back
-
- =========== ======================================================
-
- .. |gui_1| image:: images/image_display.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Display_Video`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |gui_2| Learn to play videos, capture videos from Camera and write it as a video
-
- =========== ======================================================
-
- .. |gui_2| image:: images/video_display.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Drawing_Functions`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |gui_5| Learn to draw lines, rectangles, ellipses, circles etc with OpenCV
-
- =========== ======================================================
-
- .. |gui_5| image:: images/drawing.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Mouse_Handling`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |gui_3| Draw stuffs with your mouse
-
- =========== ======================================================
-
- .. |gui_3| image:: images/mouse_drawing.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Trackbar`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |gui_4| Create trackbar to control certain parameters
-
- =========== ======================================================
-
- .. |gui_4| image:: images/trackbar.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_image_display/py_image_display
- ../py_video_display/py_video_display
- ../py_drawing_functions/py_drawing_functions
- ../py_mouse_handling/py_mouse_handling
- ../py_trackbar/py_trackbar
+++ /dev/null
-.. _Trackbar:
-
-Trackbar as the Color Palette
-********************************
-
-Goal
-=====
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Learn to bind trackbar to OpenCV windows
- * You will learn these functions : **cv2.getTrackbarPos()**, **cv2.createTrackbar()** etc.
-
-Code Demo
-==========
-
-Here we will create a simple application which shows the color you specify. You have a window which shows the color and three trackbars to specify each of B,G,R colors. You slide the trackbar and correspondingly window color changes. By default, initial color will be set to Black.
-
-For cv2.getTrackbarPos() function, first argument is the trackbar name, second one is the window name to which it is attached, third argument is the default value, fourth one is the maximum value and fifth one is the callback function which is executed everytime trackbar value changes. The callback function always has a default argument which is the trackbar position. In our case, function does nothing, so we simply pass.
-
-Another important application of trackbar is to use it as a button or switch. OpenCV, by default, doesn't have button functionality. So you can use trackbar to get such functionality. In our application, we have created one switch in which application works only if switch is ON, otherwise screen is always black.
-::
-
- import cv2
- import numpy as np
-
- def nothing(x):
- pass
-
- # Create a black image, a window
- img = np.zeros((300,512,3), np.uint8)
- cv2.namedWindow('image')
-
- # create trackbars for color change
- cv2.createTrackbar('R','image',0,255,nothing)
- cv2.createTrackbar('G','image',0,255,nothing)
- cv2.createTrackbar('B','image',0,255,nothing)
-
- # create switch for ON/OFF functionality
- switch = '0 : OFF \n1 : ON'
- cv2.createTrackbar(switch, 'image',0,1,nothing)
-
- while(1):
- cv2.imshow('image',img)
- k = cv2.waitKey(1) & 0xFF
- if k == 27:
- break
-
- # get current positions of four trackbars
- r = cv2.getTrackbarPos('R','image')
- g = cv2.getTrackbarPos('G','image')
- b = cv2.getTrackbarPos('B','image')
- s = cv2.getTrackbarPos(switch,'image')
-
- if s == 0:
- img[:] = 0
- else:
- img[:] = [b,g,r]
-
- cv2.destroyAllWindows()
-
-The screenshot of the application looks like below :
-
- .. image:: images/trackbar_screenshot.jpg
- :alt: Screenshot of Image with Trackbars
- :align: center
-
-Exercises
-===========
-
-#. Create a Paint application with adjustable colors and brush radius using trackbars. For drawing, refer previous tutorial on mouse handling.
+++ /dev/null
-.. _Display_Video:
-
-Getting Started with Videos
-*****************************
-
-Goal
-=====
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Learn to read video, display video and save video.
- * Learn to capture from Camera and display it.
- * You will learn these functions : **cv2.VideoCapture()**, **cv2.VideoWriter()**
-
-
-Capture Video from Camera
-===========================
-
-Often, we have to capture live stream with camera. OpenCV provides a very simple interface to this. Let's capture a video from the camera (I am using the in-built webcam of my laptop), convert it into grayscale video and display it. Just a simple task to get started.
-
-To capture a video, you need to create a **VideoCapture** object. Its argument can be either the device index or the name of a video file. Device index is just the number to specify which camera. Normally one camera will be connected (as in my case). So I simply pass 0 (or -1). You can select the second camera by passing 1 and so on. After that, you can capture frame-by-frame. But at the end, don't forget to release the capture.
-::
-
- import numpy as np
- import cv2
-
- cap = cv2.VideoCapture(0)
-
- while(True):
- # Capture frame-by-frame
- ret, frame = cap.read()
-
- # Our operations on the frame come here
- gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
-
- # Display the resulting frame
- cv2.imshow('frame',gray)
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
-
- # When everything done, release the capture
- cap.release()
- cv2.destroyAllWindows()
-
-``cap.read()`` returns a bool (True/False). If frame is read correctly, it will be True. So you can check end of the video by checking this return value.
-
-Sometimes, ``cap`` may not have initialized the capture. In that case, this code shows error. You can check whether it is initialized or not by the method **cap.isOpened()**. If it is True, OK. Otherwise open it using **cap.open()**.
-
-You can also access some of the features of this video using **cap.get(propId)** method where propId is a number from 0 to 18. Each number denotes a property of the video (if it is applicable to that video) and full details can be seen here: `Property Identifier <http://docs.opencv.org/modules/highgui/doc/reading_and_writing_video.html#videocapture-get>`_. Some of these values can be modified using **cap.set(propId, value)**. Value is the new value you want.
-
-For example, I can check the frame width and height by ``cap.get(3)`` and ``cap.get(4)``. It gives me 640x480 by default. But I want to modify it to 320x240. Just use ``ret = cap.set(3,320)`` and ``ret = cap.set(4,240)``.
-
-.. Note:: If you are getting error, make sure camera is working fine using any other camera application (like Cheese in Linux).
-
-Playing Video from file
-========================
-
-It is same as capturing from Camera, just change camera index with video file name. Also while displaying the frame, use appropriate time for ``cv2.waitKey()``. If it is too less, video will be very fast and if it is too high, video will be slow (Well, that is how you can display videos in slow motion). 25 milliseconds will be OK in normal cases.
-::
-
- import numpy as np
- import cv2
-
- cap = cv2.VideoCapture('vtest.avi')
-
- while(cap.isOpened()):
- ret, frame = cap.read()
-
- gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
-
- cv2.imshow('frame',gray)
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-.. Note:: Make sure proper versions of ffmpeg or gstreamer is installed. Sometimes, it is a headache to work with Video Capture mostly due to wrong installation of ffmpeg/gstreamer.
-
-
-Saving a Video
-================
-
-So we capture a video, process it frame-by-frame and we want to save that video. For images, it is very simple, just use ``cv2.imwrite()``. Here a little more work is required.
-
-This time we create a **VideoWriter** object. We should specify the output file name (eg: output.avi). Then we should specify the **FourCC** code (details in next paragraph). Then number of frames per second (fps) and frame size should be passed. And last one is **isColor** flag. If it is True, encoder expect color frame, otherwise it works with grayscale frame.
-
-`FourCC <http://en.wikipedia.org/wiki/FourCC>`_ is a 4-byte code used to specify the video codec. The list of available codes can be found in `fourcc.org <http://www.fourcc.org/codecs.php>`_. It is platform dependent. Following codecs works fine for me.
-
-* In Fedora: DIVX, XVID, MJPG, X264, WMV1, WMV2. (XVID is more preferable. MJPG results in high size video. X264 gives very small size video)
-* In Windows: DIVX (More to be tested and added)
-* In OSX : *(I don't have access to OSX. Can some one fill this?)*
-
-FourCC code is passed as ``cv2.VideoWriter_fourcc('M','J','P','G')`` or ``cv2.VideoWriter_fourcc(*'MJPG)`` for MJPG.
-
-Below code capture from a Camera, flip every frame in vertical direction and saves it.
-::
-
- import numpy as np
- import cv2
-
- cap = cv2.VideoCapture(0)
-
- # Define the codec and create VideoWriter object
- fourcc = cv2.VideoWriter_fourcc(*'XVID')
- out = cv2.VideoWriter('output.avi',fourcc, 20.0, (640,480))
-
- while(cap.isOpened()):
- ret, frame = cap.read()
- if ret==True:
- frame = cv2.flip(frame,0)
-
- # write the flipped frame
- out.write(frame)
-
- cv2.imshow('frame',frame)
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
- else:
- break
-
- # Release everything if job is finished
- cap.release()
- out.release()
- cv2.destroyAllWindows()
-
-
-Additional Resources
-==========================
-
-Exercises
-=================
+++ /dev/null
-.. _Canny:
-
-Canny Edge Detection
-***********************
-
-Goal
-======
-
-In this chapter, we will learn about
-
- * Concept of Canny edge detection
- * OpenCV functions for that : **cv2.Canny()**
-
-Theory
-=========
-
-Canny Edge Detection is a popular edge detection algorithm. It was developed by John F. Canny in 1986. It is a multi-stage algorithm and we will go through each stages.
-
-1. **Noise Reduction**
-
-Since edge detection is susceptible to noise in the image, first step is to remove the noise in the image with a 5x5 Gaussian filter. We have already seen this in previous chapters.
-
-2. **Finding Intensity Gradient of the Image**
-
-Smoothened image is then filtered with a Sobel kernel in both horizontal and vertical direction to get first derivative in horizontal direction (:math:`G_x`) and vertical direction (:math:`G_y`). From these two images, we can find edge gradient and direction for each pixel as follows:
-
-.. math::
-
- Edge\_Gradient \; (G) = \sqrt{G_x^2 + G_y^2}
-
- Angle \; (\theta) = \tan^{-1} \bigg(\frac{G_y}{G_x}\bigg)
-
-Gradient direction is always perpendicular to edges. It is rounded to one of four angles representing vertical, horizontal and two diagonal directions.
-
-3. **Non-maximum Suppression**
-
-After getting gradient magnitude and direction, a full scan of image is done to remove any unwanted pixels which may not constitute the edge. For this, at every pixel, pixel is checked if it is a local maximum in its neighborhood in the direction of gradient. Check the image below:
-
- .. image:: images/nms.jpg
- :alt: Non-Maximum Suppression
- :align: center
-
-Point A is on the edge ( in vertical direction). Gradient direction is normal to the edge. Point B and C are in gradient directions. So point A is checked with point B and C to see if it forms a local maximum. If so, it is considered for next stage, otherwise, it is suppressed ( put to zero).
-
-In short, the result you get is a binary image with "thin edges".
-
-4. **Hysteresis Thresholding**
-
-This stage decides which are all edges are really edges and which are not. For this, we need two threshold values, `minVal` and `maxVal`. Any edges with intensity gradient more than `maxVal` are sure to be edges and those below `minVal` are sure to be non-edges, so discarded. Those who lie between these two thresholds are classified edges or non-edges based on their connectivity. If they are connected to "sure-edge" pixels, they are considered to be part of edges. Otherwise, they are also discarded. See the image below:
-
- .. image:: images/hysteresis.jpg
- :alt: Hysteresis Thresholding
- :align: center
-
-The edge A is above the `maxVal`, so considered as "sure-edge". Although edge C is below `maxVal`, it is connected to edge A, so that also considered as valid edge and we get that full curve. But edge B, although it is above `minVal` and is in same region as that of edge C, it is not connected to any "sure-edge", so that is discarded. So it is very important that we have to select `minVal` and `maxVal` accordingly to get the correct result.
-
-This stage also removes small pixels noises on the assumption that edges are long lines.
-
-So what we finally get is strong edges in the image.
-
-Canny Edge Detection in OpenCV
-===============================
-
-OpenCV puts all the above in single function, **cv2.Canny()**. We will see how to use it. First argument is our input image. Second and third arguments are our `minVal` and `maxVal` respectively. Third argument is `aperture_size`. It is the size of Sobel kernel used for find image gradients. By default it is 3. Last argument is `L2gradient` which specifies the equation for finding gradient magnitude. If it is ``True``, it uses the equation mentioned above which is more accurate, otherwise it uses this function: :math:`Edge\_Gradient \; (G) = |G_x| + |G_y|`. By default, it is ``False``.
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('messi5.jpg',0)
- edges = cv2.Canny(img,100,200)
-
- plt.subplot(121),plt.imshow(img,cmap = 'gray')
- plt.title('Original Image'), plt.xticks([]), plt.yticks([])
- plt.subplot(122),plt.imshow(edges,cmap = 'gray')
- plt.title('Edge Image'), plt.xticks([]), plt.yticks([])
-
- plt.show()
-
-See the result below:
-
- .. image:: images/canny1.jpg
- :alt: Canny Edge Detection
- :align: center
-
-Additional Resources
-=======================
-
-#. Canny edge detector at `Wikipedia <http://en.wikipedia.org/wiki/Canny_edge_detector>`_
-#. `Canny Edge Detection Tutorial <http://dasl.mem.drexel.edu/alumni/bGreen/www.pages.drexel.edu/_weg22/can_tut.html>`_ by Bill Green, 2002.
-
-
-Exercises
-===========
-
-#. Write a small application to find the Canny edge detection whose threshold values can be varied using two trackbars. This way, you can understand the effect of threshold values.
+++ /dev/null
-.. _Converting_colorspaces:
-
-Changing Colorspaces
-****************************
-
-Goal
-=========
-
- * In this tutorial, you will learn how to convert images from one color-space to another, like BGR :math:`\leftrightarrow` Gray, BGR :math:`\leftrightarrow` HSV etc.
- * In addition to that, we will create an application which extracts a colored object in a video
- * You will learn following functions : **cv2.cvtColor()**, **cv2.inRange()** etc.
-
-Changing Color-space
-======================
-
-There are more than 150 color-space conversion methods available in OpenCV. But we will look into only two which are most widely used ones, BGR :math:`\leftrightarrow` Gray and BGR :math:`\leftrightarrow` HSV.
-
-For color conversion, we use the function ``cv2.cvtColor(input_image, flag)`` where ``flag`` determines the type of conversion.
-
-For BGR :math:`\rightarrow` Gray conversion we use the flags ``cv2.COLOR_BGR2GRAY``. Similarly for BGR :math:`\rightarrow` HSV, we use the flag ``cv2.COLOR_BGR2HSV``. To get other flags, just run following commands in your Python terminal :
-::
-
- >>> import cv2
- >>> flags = [i for i in dir(cv2) if i.startswith('COLOR_')]
- >>> print flags
-
-
-.. note:: For HSV, Hue range is [0,179], Saturation range is [0,255] and Value range is [0,255]. Different softwares use different scales. So if you are comparing OpenCV values with them, you need to normalize these ranges.
-
-Object Tracking
-==================
-
-Now we know how to convert BGR image to HSV, we can use this to extract a colored object. In HSV, it is more easier to represent a color than RGB color-space. In our application, we will try to extract a blue colored object. So here is the method:
-
- * Take each frame of the video
- * Convert from BGR to HSV color-space
- * We threshold the HSV image for a range of blue color
- * Now extract the blue object alone, we can do whatever on that image we want.
-
-Below is the code which are commented in detail :
-::
-
- import cv2
- import numpy as np
-
- cap = cv2.VideoCapture(0)
-
- while(1):
-
- # Take each frame
- _, frame = cap.read()
-
- # Convert BGR to HSV
- hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)
-
- # define range of blue color in HSV
- lower_blue = np.array([110,50,50])
- upper_blue = np.array([130,255,255])
-
- # Threshold the HSV image to get only blue colors
- mask = cv2.inRange(hsv, lower_blue, upper_blue)
-
- # Bitwise-AND mask and original image
- res = cv2.bitwise_and(frame,frame, mask= mask)
-
- cv2.imshow('frame',frame)
- cv2.imshow('mask',mask)
- cv2.imshow('res',res)
- k = cv2.waitKey(5) & 0xFF
- if k == 27:
- break
-
- cv2.destroyAllWindows()
-
-Below image shows tracking of the blue object:
-
- .. image:: images/frame.jpg
- :width: 780 pt
- :alt: Blue Object Tracking
- :align: center
-
-.. note:: There are some noises in the image. We will see how to remove them in later chapters.
-
-.. note:: This is the simplest method in object tracking. Once you learn functions of contours, you can do plenty of things like find centroid of this object and use it to track the object, draw diagrams just by moving your hand in front of camera and many other funny stuffs.
-
-How to find HSV values to track?
------------------------------------
-This is a common question found in `stackoverflow.com <www.stackoverflow.com>`_. It is very simple and you can use the same function, `cv2.cvtColor()`. Instead of passing an image, you just pass the BGR values you want. For example, to find the HSV value of Green, try following commands in Python terminal:
-::
-
- >>> green = np.uint8([[[0,255,0 ]]])
- >>> hsv_green = cv2.cvtColor(green,cv2.COLOR_BGR2HSV)
- >>> print hsv_green
- [[[ 60 255 255]]]
-
-Now you take [H-10, 100,100] and [H+10, 255, 255] as lower bound and upper bound respectively. Apart from this method, you can use any image editing tools like GIMP or any online converters to find these values, but don't forget to adjust the HSV ranges.
-
-
-Additional Resources
-========================
-
-Exercises
-============
-#. Try to find a way to extract more than one colored objects, for eg, extract red, blue, green objects simultaneously.
+++ /dev/null
-.. _Contour_Features:
-
-Contour Features
-******************
-
-Goal
-======
-
-In this article, we will learn
-
- * To find the different features of contours, like area, perimeter, centroid, bounding box etc
- * You will see plenty of functions related to contours.
-
-1. Moments
-===========
-
-Image moments help you to calculate some features like center of mass of the object, area of the object etc. Check out the wikipedia page on `Image Moments <http://en.wikipedia.org/wiki/Image_moment>`_
-
-The function **cv2.moments()** gives a dictionary of all moment values calculated. See below:
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('star.jpg',0)
- ret,thresh = cv2.threshold(img,127,255,0)
- contours,hierarchy = cv2.findContours(thresh, 1, 2)
-
- cnt = contours[0]
- M = cv2.moments(cnt)
- print M
-
-From this moments, you can extract useful data like area, centroid etc. Centroid is given by the relations, :math:`C_x = \frac{M_{10}}{M_{00}}` and :math:`C_y = \frac{M_{01}}{M_{00}}`. This can be done as follows:
-::
-
- cx = int(M['m10']/M['m00'])
- cy = int(M['m01']/M['m00'])
-
-
-2. Contour Area
-=================
-
-Contour area is given by the function **cv2.contourArea()** or from moments, **M['m00']**.
-::
-
- area = cv2.contourArea(cnt)
-
-3. Contour Perimeter
-=======================
-
-It is also called arc length. It can be found out using **cv2.arcLength()** function. Second argument specify whether shape is a closed contour (if passed ``True``), or just a curve.
-::
-
- perimeter = cv2.arcLength(cnt,True)
-
-4. Contour Approximation
-=========================
-
-It approximates a contour shape to another shape with less number of vertices depending upon the precision we specify. It is an implementation of `Douglas-Peucker algorithm <http://en.wikipedia.org/wiki/Ramer-Douglas-Peucker_algorithm>`_. Check the wikipedia page for algorithm and demonstration.
-
-To understand this, suppose you are trying to find a square in an image, but due to some problems in the image, you didn't get a perfect square, but a "bad shape" (As shown in first image below). Now you can use this function to approximate the shape. In this, second argument is called ``epsilon``, which is maximum distance from contour to approximated contour. It is an accuracy parameter. A wise selection of ``epsilon`` is needed to get the correct output.
-::
-
- epsilon = 0.1*cv2.arcLength(cnt,True)
- approx = cv2.approxPolyDP(cnt,epsilon,True)
-
-Below, in second image, green line shows the approximated curve for ``epsilon = 10% of arc length``. Third image shows the same for ``epsilon = 1% of the arc length``. Third argument specifies whether curve is closed or not.
-
- .. image:: images/approx.jpg
- :alt: Contour Approximation
- :align: center
-
-5. Convex Hull
-=================
-
-Convex Hull will look similar to contour approximation, but it is not (Both may provide same results in some cases). Here, **cv2.convexHull()** function checks a curve for convexity defects and corrects it. Generally speaking, convex curves are the curves which are always bulged out, or at-least flat. And if it is bulged inside, it is called convexity defects. For example, check the below image of hand. Red line shows the convex hull of hand. The double-sided arrow marks shows the convexity defects, which are the local maximum deviations of hull from contours.
-
- .. image:: images/convexitydefects.jpg
- :alt: Convex Hull
- :align: center
-
-There is a little bit things to discuss about it its syntax:
-::
-
- hull = cv2.convexHull(points[, hull[, clockwise[, returnPoints]]
-
-Arguments details:
-
- * **points** are the contours we pass into.
- * **hull** is the output, normally we avoid it.
- * **clockwise** : Orientation flag. If it is ``True``, the output convex hull is oriented clockwise. Otherwise, it is oriented counter-clockwise.
- * **returnPoints** : By default, ``True``. Then it returns the coordinates of the hull points. If ``False``, it returns the indices of contour points corresponding to the hull points.
-
-So to get a convex hull as in above image, following is sufficient:
-::
-
- hull = cv2.convexHull(cnt)
-
-But if you want to find convexity defects, you need to pass ``returnPoints = False``. To understand it, we will take the rectangle image above. First I found its contour as ``cnt``. Now I found its convex hull with ``returnPoints = True``, I got following values: ``[[[234 202]], [[ 51 202]], [[ 51 79]], [[234 79]]]`` which are the four corner points of rectangle. Now if do the same with ``returnPoints = False``, I get following result: ``[[129],[ 67],[ 0],[142]]``. These are the indices of corresponding points in contours. For eg, check the first value: ``cnt[129] = [[234, 202]]`` which is same as first result (and so on for others).
-
-You will see it again when we discuss about convexity defects.
-
-6. Checking Convexity
-=========================
-There is a function to check if a curve is convex or not, **cv2.isContourConvex()**. It just return whether True or False. Not a big deal.
-::
-
- k = cv2.isContourConvex(cnt)
-
-7. Bounding Rectangle
-======================
-There are two types of bounding rectangles.
-
-7.a. Straight Bounding Rectangle
-----------------------------------
-It is a straight rectangle, it doesn't consider the rotation of the object. So area of the bounding rectangle won't be minimum. It is found by the function **cv2.boundingRect()**.
-
-Let (x,y) be the top-left coordinate of the rectangle and (w,h) be its width and height.
-::
-
- x,y,w,h = cv2.boundingRect(cnt)
- cv2.rectangle(img,(x,y),(x+w,y+h),(0,255,0),2)
-
-7.b. Rotated Rectangle
------------------------
-Here, bounding rectangle is drawn with minimum area, so it considers the rotation also. The function used is **cv2.minAreaRect()**. It returns a Box2D structure which contains following detals - ( center (x,y), (width, height), angle of rotation ). But to draw this rectangle, we need 4 corners of the rectangle. It is obtained by the function **cv2.boxPoints()**
-::
-
- rect = cv2.minAreaRect(cnt)
- box = cv2.boxPoints(rect)
- box = np.int0(box)
- cv2.drawContours(img,[box],0,(0,0,255),2)
-
-Both the rectangles are shown in a single image. Green rectangle shows the normal bounding rect. Red rectangle is the rotated rect.
-
- .. image:: images/boundingrect.png
- :alt: Bounding Rectangle
- :align: center
-
-8. Minimum Enclosing Circle
-===============================
-Next we find the circumcircle of an object using the function **cv2.minEnclosingCircle()**. It is a circle which completely covers the object with minimum area.
-::
-
- (x,y),radius = cv2.minEnclosingCircle(cnt)
- center = (int(x),int(y))
- radius = int(radius)
- cv2.circle(img,center,radius,(0,255,0),2)
-
-.. image:: images/circumcircle.png
- :alt: Minimum Enclosing Circle
- :align: center
-
-9. Fitting an Ellipse
-=========================
-
-Next one is to fit an ellipse to an object. It returns the rotated rectangle in which the ellipse is inscribed.
-::
-
- ellipse = cv2.fitEllipse(cnt)
- cv2.ellipse(img,ellipse,(0,255,0),2)
-
-.. image:: images/fitellipse.png
- :alt: Fitting an Ellipse
- :align: center
-
-
-10. Fitting a Line
-=======================
-
-Similarly we can fit a line to a set of points. Below image contains a set of white points. We can approximate a straight line to it.
-::
-
- rows,cols = img.shape[:2]
- [vx,vy,x,y] = cv2.fitLine(cnt, cv2.DIST_L2,0,0.01,0.01)
- lefty = int((-x*vy/vx) + y)
- righty = int(((cols-x)*vy/vx)+y)
- cv2.line(img,(cols-1,righty),(0,lefty),(0,255,0),2)
-
-.. image:: images/fitline.jpg
- :alt: Fitting a Line
- :align: center
-
-Additional Resources
-======================
-
-Exercises
-=============
+++ /dev/null
-.. _Contour_Properties:
-
-Contour Properties
-*********************
-
-Here we will learn to extract some frequently used properties of objects like Solidity, Equivalent Diameter, Mask image, Mean Intensity etc. More features can be found at `Matlab regionprops documentation <http://www.mathworks.in/help/images/ref/regionprops.html>`_.
-
-*(NB : Centroid, Area, Perimeter etc also belong to this category, but we have seen it in last chapter)*
-
-1. Aspect Ratio
-================
-
-It is the ratio of width to height of bounding rect of the object.
-
-.. math::
-
- Aspect \; Ratio = \frac{Width}{Height}
-
-.. code-block:: python
-
- x,y,w,h = cv2.boundingRect(cnt)
- aspect_ratio = float(w)/h
-
-2. Extent
-==========
-
-Extent is the ratio of contour area to bounding rectangle area.
-
-.. math::
- Extent = \frac{Object \; Area}{Bounding \; Rectangle \; Area}
-
-.. code-block:: python
-
- area = cv2.contourArea(cnt)
- x,y,w,h = cv2.boundingRect(cnt)
- rect_area = w*h
- extent = float(area)/rect_area
-
-3. Solidity
-============
-
-Solidity is the ratio of contour area to its convex hull area.
-
-.. math::
- Solidity = \frac{Contour \; Area}{Convex \; Hull \; Area}
-
-.. code-block:: python
-
- area = cv2.contourArea(cnt)
- hull = cv2.convexHull(cnt)
- hull_area = cv2.contourArea(hull)
- solidity = float(area)/hull_area
-
-4. Equivalent Diameter
-=======================
-
-Equivalent Diameter is the diameter of the circle whose area is same as the contour area.
-
-.. math::
- Equivalent \; Diameter = \sqrt{\frac{4 \times Contour \; Area}{\pi}}
-
-.. code-block:: python
-
- area = cv2.contourArea(cnt)
- equi_diameter = np.sqrt(4*area/np.pi)
-
-5. Orientation
-================
-
-Orientation is the angle at which object is directed. Following method also gives the Major Axis and Minor Axis lengths.
-::
-
- (x,y),(MA,ma),angle = cv2.fitEllipse(cnt)
-
-6. Mask and Pixel Points
-=========================
-
-In some cases, we may need all the points which comprises that object. It can be done as follows:
-::
-
- mask = np.zeros(imgray.shape,np.uint8)
- cv2.drawContours(mask,[cnt],0,255,-1)
- pixelpoints = np.transpose(np.nonzero(mask))
- #pixelpoints = cv2.findNonZero(mask)
-
-Here, two methods, one using Numpy functions, next one using OpenCV function (last commented line) are given to do the same. Results are also same, but with a slight difference. Numpy gives coordinates in **(row, column)** format, while OpenCV gives coordinates in **(x,y)** format. So basically the answers will be interchanged. Note that, **row = x** and **column = y**.
-
-7. Maximum Value, Minimum Value and their locations
-=======================================================
-
-We can find these parameters using a mask image.
-::
-
- min_val, max_val, min_loc, max_loc = cv2.minMaxLoc(imgray,mask = mask)
-
-8. Mean Color or Mean Intensity
-===================================
-
-Here, we can find the average color of an object. Or it can be average intensity of the object in grayscale mode. We again use the same mask to do it.
-::
-
- mean_val = cv2.mean(im,mask = mask)
-
-9. Extreme Points
-==================
-
-Extreme Points means topmost, bottommost, rightmost and leftmost points of the object.
-::
-
- leftmost = tuple(cnt[cnt[:,:,0].argmin()][0])
- rightmost = tuple(cnt[cnt[:,:,0].argmax()][0])
- topmost = tuple(cnt[cnt[:,:,1].argmin()][0])
- bottommost = tuple(cnt[cnt[:,:,1].argmax()][0])
-
-For eg, if I apply it to an Indian map, I get the following result :
-
- .. image:: images/extremepoints.jpg
- :alt: Extreme Points
- :align: center
-
-Additional Resources
-======================
-
-Exercises
-===========
-#. There are still some features left in matlab regionprops doc. Try to implement them.
+++ /dev/null
-.. _Contours_Getting_Started:
-
-Contours : Getting Started
-****************************
-
-Goal
-======
-
- * Understand what contours are.
- * Learn to find contours, draw contours etc
- * You will see these functions : **cv2.findContours()**, **cv2.drawContours()**
-
-What are contours?
-===================
-
-Contours can be explained simply as a curve joining all the continuous points (along the boundary), having same color or intensity. The contours are a useful tool for shape analysis and object detection and recognition.
-
- * For better accuracy, use binary images. So before finding contours, apply threshold or canny edge detection.
- * findContours function modifies the source image. So if you want source image even after finding contours, already store it to some other variables.
- * In OpenCV, finding contours is like finding white object from black background. So remember, object to be found should be white and background should be black.
-
-Let's see how to find contours of a binary image:
-::
-
- import numpy as np
- import cv2
-
- im = cv2.imread('test.jpg')
- imgray = cv2.cvtColor(im,cv2.COLOR_BGR2GRAY)
- ret,thresh = cv2.threshold(imgray,127,255,0)
- contours, hierarchy = cv2.findContours(thresh,cv2.RETR_TREE,cv2.CHAIN_APPROX_SIMPLE)
-
-See, there are three arguments in **cv2.findContours()** function, first one is source image, second is contour retrieval mode, third is contour approximation method. And it outputs the contours and hierarchy. ``contours`` is a Python list of all the contours in the image. Each individual contour is a Numpy array of (x,y) coordinates of boundary points of the object.
-
-.. note:: We will discuss second and third arguments and about hierarchy in details later. Until then, the values given to them in code sample will work fine for all images.
-
-
-How to draw the contours?
-===========================
-
-To draw the contours, ``cv2.drawContours`` function is used. It can also be used to draw any shape provided you have its boundary points. Its first argument is source image, second argument is the contours which should be passed as a Python list, third argument is index of contours (useful when drawing individual contour. To draw all contours, pass -1) and remaining arguments are color, thickness etc.
-
-To draw all the contours in an image:
-::
-
- cv2.drawContours(img, contours, -1, (0,255,0), 3)
-
-To draw an individual contour, say 4th contour:
-::
-
- cv2.drawContours(img, contours, 3, (0,255,0), 3)
-
-But most of the time, below method will be useful:
-::
-
- cnt = contours[4]
- cv2.drawContours(img, [cnt], 0, (0,255,0), 3)
-
-.. note:: Last two methods are same, but when you go forward, you will see last one is more useful.
-
-Contour Approximation Method
-================================
-
-This is the third argument in ``cv2.findContours`` function. What does it denote actually?
-
-Above, we told that contours are the boundaries of a shape with same intensity. It stores the (x,y) coordinates of the boundary of a shape. But does it store all the coordinates ? That is specified by this contour approximation method.
-
-If you pass ``cv2.CHAIN_APPROX_NONE``, all the boundary points are stored. But actually do we need all the points? For eg, you found the contour of a straight line. Do you need all the points on the line to represent that line? No, we need just two end points of that line. This is what ``cv2.CHAIN_APPROX_SIMPLE`` does. It removes all redundant points and compresses the contour, thereby saving memory.
-
-Below image of a rectangle demonstrate this technique. Just draw a circle on all the coordinates in the contour array (drawn in blue color). First image shows points I got with ``cv2.CHAIN_APPROX_NONE`` (734 points) and second image shows the one with ``cv2.CHAIN_APPROX_SIMPLE`` (only 4 points). See, how much memory it saves!!!
-
- .. image:: images/none.jpg
- :alt: Contour Retrieval Method
- :align: center
-
-Additional Resources
-========================
-
-Exercises
-=============
+++ /dev/null
-.. _Contours_Hierarchy:
-
-Contours Hierarchy
-*************************
-
-Goal
-=======
-
-This time, we learn about the hierarchy of contours, i.e. the parent-child relationship in Contours.
-
-Theory
-=========
-
-In the last few articles on contours, we have worked with several functions related to contours provided by OpenCV. But when we found the contours in image using **cv2.findContours()** function, we have passed an argument, **Contour Retrieval Mode**. We usually passed **cv2.RETR_LIST** or **cv2.RETR_TREE** and it worked nice. But what does it actually mean ?
-
-Also, in the output, we got three arrays, first is the image, second is our contours, and one more output which we named as **hierarchy** (Please checkout the codes in previous articles). But we never used this hierarchy anywhere. Then what is this hierarchy and what is it for ? What is its relationship with the previous mentioned function argument ?
-
-That is what we are going to deal in this article.
-
-What is Hierarchy?
--------------------
-
-Normally we use the **cv2.findContours()** function to detect objects in an image, right ? Sometimes objects are in different locations. But in some cases, some shapes are inside other shapes. Just like nested figures. In this case, we call outer one as **parent** and inner one as **child**. This way, contours in an image has some relationship to each other. And we can specify how one contour is connected to each other, like, is it child of some other contour, or is it a parent etc. Representation of this relationship is called the **Hierarchy**.
-
-Consider an example image below :
-
- .. image:: images/hierarchy.png
- :alt: Hierarchy Representation
- :align: center
-
-In this image, there are a few shapes which I have numbered from **0-5**. *2 and 2a* denotes the external and internal contours of the outermost box.
-
-Here, contours 0,1,2 are **external or outermost**. We can say, they are in **hierarchy-0** or simply they are in **same hierarchy level**.
-
-Next comes **contour-2a**. It can be considered as a **child of contour-2** (or in opposite way, contour-2 is parent of contour-2a). So let it be in **hierarchy-1**. Similarly contour-3 is child of contour-2 and it comes in next hierarchy. Finally contours 4,5 are the children of contour-3a, and they come in the last hierarchy level. From the way I numbered the boxes, I would say contour-4 is the first child of contour-3a (It can be contour-5 also).
-
-I mentioned these things to understand terms like **same hierarchy level**, **external contour**, **child contour**, **parent contour**, **first child** etc. Now let's get into OpenCV.
-
-Hierarchy Representation in OpenCV
-------------------------------------
-
-So each contour has its own information regarding what hierarchy it is, who is its child, who is its parent etc. OpenCV represents it as an array of four values : **[Next, Previous, First_Child, Parent]**
-
-.. centered:: *"Next denotes next contour at the same hierarchical level."*
-
-For eg, take contour-0 in our picture. Who is next contour in its same level ? It is contour-1. So simply put ``Next = 1``. Similarly for Contour-1, next is contour-2. So ``Next = 2``.
-
-What about contour-2? There is no next contour in the same level. So simply, put ``Next = -1``. What about contour-4? It is in same level with contour-5. So its next contour is contour-5, so ``Next = 5``.
-
-.. centered:: *"Previous denotes previous contour at the same hierarchical level."*
-
-It is same as above. Previous contour of contour-1 is contour-0 in the same level. Similarly for contour-2, it is contour-1. And for contour-0, there is no previous, so put it as -1.
-
-.. centered:: *"First_Child denotes its first child contour."*
-
-There is no need of any explanation. For contour-2, child is contour-2a. So it gets the corresponding index value of contour-2a. What about contour-3a? It has two children. But we take only first child. And it is contour-4. So ``First_Child = 4`` for contour-3a.
-
-.. centered:: *"Parent denotes index of its parent contour."*
-
-It is just opposite of **First_Child**. Both for contour-4 and contour-5, parent contour is contour-3a. For contour-3a, it is contour-3 and so on.
-
-.. note:: If there is no child or parent, that field is taken as -1
-
-So now we know about the hierarchy style used in OpenCV, we can check into Contour Retrieval Modes in OpenCV with the help of same image given above. ie what do flags like cv2.RETR_LIST, cv2.RETR_TREE, cv2.RETR_CCOMP, cv2.RETR_EXTERNAL etc mean?
-
-Contour Retrieval Mode
-=======================
-
-1. RETR_LIST
---------------
-
-This is the simplest of the four flags (from explanation point of view). It simply retrieves all the contours, but doesn't create any parent-child relationship. **Parents and kids are equal under this rule, and they are just contours**. ie they all belongs to same hierarchy level.
-
-So here, 3rd and 4th term in hierarchy array is always -1. But obviously, Next and Previous terms will have their corresponding values. Just check it yourself and verify it.
-
-Below is the result I got, and each row is hierarchy details of corresponding contour. For eg, first row corresponds to contour 0. Next contour is contour 1. So Next = 1. There is no previous contour, so Previous = 0. And the remaining two, as told before, it is -1.
-::
-
- >>> hierarchy
- array([[[ 1, -1, -1, -1],
- [ 2, 0, -1, -1],
- [ 3, 1, -1, -1],
- [ 4, 2, -1, -1],
- [ 5, 3, -1, -1],
- [ 6, 4, -1, -1],
- [ 7, 5, -1, -1],
- [-1, 6, -1, -1]]])
-
-This is the good choice to use in your code, if you are not using any hierarchy features.
-
-2. RETR_EXTERNAL
-------------------
-
-If you use this flag, it returns only extreme outer flags. All child contours are left behind. **We can say, under this law, Only the eldest in every family is taken care of. It doesn't care about other members of the family :)**.
-
-So, in our image, how many extreme outer contours are there? ie at hierarchy-0 level?. Only 3, ie contours 0,1,2, right? Now try to find the contours using this flag. Here also, values given to each element is same as above. Compare it with above result. Below is what I got :
-::
-
- >>> hierarchy
- array([[[ 1, -1, -1, -1],
- [ 2, 0, -1, -1],
- [-1, 1, -1, -1]]])
-
-You can use this flag if you want to extract only the outer contours. It might be useful in some cases.
-
-3. RETR_CCOMP
-------------------
-
-This flag retrieves all the contours and arranges them to a 2-level hierarchy. ie external contours of the object (ie its boundary) are placed in hierarchy-1. And the contours of holes inside object (if any) is placed in hierarchy-2. If any object inside it, its contour is placed again in hierarchy-1 only. And its hole in hierarchy-2 and so on.
-
-Just consider the image of a "big white zero" on a black background. Outer circle of zero belongs to first hierarchy, and inner circle of zero belongs to second hierarchy.
-
-We can explain it with a simple image. Here I have labelled the order of contours in red color and the hierarchy they belongs to, in green color (either 1 or 2). The order is same as the order OpenCV detects contours.
-
- .. image:: images/ccomp_hierarchy.png
- :alt: CCOMP Hierarchy
- :align: center
-
-So consider first contour, ie contour-0. It is hierarchy-1. It has two holes, contours 1&2, and they belong to hierarchy-2. So for contour-0, Next contour in same hierarchy level is contour-3. And there is no previous one. And its first is child is contour-1 in hierarchy-2. It has no parent, because it is in hierarchy-1. So its hierarchy array is [3,-1,1,-1]
-
-Now take contour-1. It is in hierarchy-2. Next one in same hierarchy (under the parenthood of contour-1) is contour-2. No previous one. No child, but parent is contour-0. So array is [2,-1,-1,0].
-
-Similarly contour-2 : It is in hierarchy-2. There is not next contour in same hierarchy under contour-0. So no Next. Previous is contour-1. No child, parent is contour-0. So array is [-1,1,-1,0].
-
-Contour - 3 : Next in hierarchy-1 is contour-5. Previous is contour-0. Child is contour-4 and no parent. So array is [5,0,4,-1].
-
-Contour - 4 : It is in hierarchy 2 under contour-3 and it has no sibling. So no next, no previous, no child, parent is contour-3. So array is [-1,-1,-1,3].
-
-Remaining you can fill up. This is the final answer I got:
-::
-
- >>> hierarchy
- array([[[ 3, -1, 1, -1],
- [ 2, -1, -1, 0],
- [-1, 1, -1, 0],
- [ 5, 0, 4, -1],
- [-1, -1, -1, 3],
- [ 7, 3, 6, -1],
- [-1, -1, -1, 5],
- [ 8, 5, -1, -1],
- [-1, 7, -1, -1]]])
-
-
-4. RETR_TREE
-------------------
-
-And this is the final guy, Mr.Perfect. It retrieves all the contours and creates a full family hierarchy list. **It even tells, who is the grandpa, father, son, grandson and even beyond... :)**.
-
-For examle, I took above image, rewrite the code for cv2.RETR_TREE, reorder the contours as per the result given by OpenCV and analyze it. Again, red letters give the contour number and green letters give the hierarchy order.
-
- .. image:: images/tree_hierarchy.png
- :alt: CCOMP Hierarchy
- :align: center
-
-Take contour-0 : It is in hierarchy-0. Next contour in same hierarchy is contour-7. No previous contours. Child is contour-1. And no parent. So array is [7,-1,1,-1].
-
-Take contour-2 : It is in hierarchy-1. No contour in same level. No previous one. Child is contour-2. Parent is contour-0. So array is [-1,-1,2,0].
-
-And remaining, try yourself. Below is the full answer:
-::
-
- >>> hierarchy
- array([[[ 7, -1, 1, -1],
- [-1, -1, 2, 0],
- [-1, -1, 3, 1],
- [-1, -1, 4, 2],
- [-1, -1, 5, 3],
- [ 6, -1, -1, 4],
- [-1, 5, -1, 4],
- [ 8, 0, -1, -1],
- [-1, 7, -1, -1]]])
-
-Additional Resources
-=======================
-
-Exercises
-==========
+++ /dev/null
-.. _Contours_More_Functions:
-
-Contours : More Functions
-******************************
-
-Goal
-======
-
-In this chapter, we will learn about
- * Convexity defects and how to find them.
- * Finding shortest distance from a point to a polygon
- * Matching different shapes
-
-Theory and Code
-================
-
-1. Convexity Defects
------------------------
-
-We saw what is convex hull in second chapter about contours. Any deviation of the object from this hull can be considered as convexity defect.
-
-OpenCV comes with a ready-made function to find this, **cv2.convexityDefects()**. A basic function call would look like below:
-::
-
- hull = cv2.convexHull(cnt,returnPoints = False)
- defects = cv2.convexityDefects(cnt,hull)
-
-.. note:: Remember we have to pass ``returnPoints = False`` while finding convex hull, in order to find convexity defects.
-
-It returns an array where each row contains these values - **[ start point, end point, farthest point, approximate distance to farthest point ]**. We can visualize it using an image. We draw a line joining start point and end point, then draw a circle at the farthest point. Remember first three values returned are indices of ``cnt``. So we have to bring those values from ``cnt``.
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('star.jpg')
- img_gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
- ret, thresh = cv2.threshold(img_gray, 127, 255,0)
- contours,hierarchy = cv2.findContours(thresh,2,1)
- cnt = contours[0]
-
- hull = cv2.convexHull(cnt,returnPoints = False)
- defects = cv2.convexityDefects(cnt,hull)
-
- for i in range(defects.shape[0]):
- s,e,f,d = defects[i,0]
- start = tuple(cnt[s][0])
- end = tuple(cnt[e][0])
- far = tuple(cnt[f][0])
- cv2.line(img,start,end,[0,255,0],2)
- cv2.circle(img,far,5,[0,0,255],-1)
-
- cv2.imshow('img',img)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-And see the result:
-
- .. image:: images/defects.jpg
- :alt: Convexity Defects
- :align: center
-
-2. Point Polygon Test
------------------------
-
-This function finds the shortest distance between a point in the image and a contour. It returns the distance which is negative when point is outside the contour, positive when point is inside and zero if point is on the contour.
-
-For example, we can check the point (50,50) as follows:
-::
-
- dist = cv2.pointPolygonTest(cnt,(50,50),True)
-
-In the function, third argument is ``measureDist``. If it is ``True``, it finds the signed distance. If ``False``, it finds whether the point is inside or outside or on the contour (it returns +1, -1, 0 respectively).
-
-.. note:: If you don't want to find the distance, make sure third argument is ``False``, because, it is a time consuming process. So, making it ``False`` gives about 2-3X speedup.
-
-3. Match Shapes
------------------
-
-OpenCV comes with a function **cv2.matchShapes()** which enables us to compare two shapes, or two contours and returns a metric showing the similarity. The lower the result, the better match it is. It is calculated based on the hu-moment values. Different measurement methods are explained in the docs.
-::
-
- import cv2
- import numpy as np
-
- img1 = cv2.imread('star.jpg',0)
- img2 = cv2.imread('star2.jpg',0)
-
- ret, thresh = cv2.threshold(img1, 127, 255,0)
- ret, thresh2 = cv2.threshold(img2, 127, 255,0)
- contours,hierarchy = cv2.findContours(thresh,2,1)
- cnt1 = contours[0]
- contours,hierarchy = cv2.findContours(thresh2,2,1)
- cnt2 = contours[0]
-
- ret = cv2.matchShapes(cnt1,cnt2,1,0.0)
- print ret
-
-I tried matching shapes with different shapes given below:
-
- .. image:: images/matchshapes.jpg
- :alt: Match Shapes
- :align: center
-
-I got following results:
-
- * Matching Image A with itself = 0.0
- * Matching Image A with Image B = 0.001946
- * Matching Image A with Image C = 0.326911
-
-See, even image rotation doesn't affect much on this comparison.
-
-.. seealso:: `Hu-Moments <http://en.wikipedia.org/wiki/Image_moment#Rotation_invariant_moments>`_ are seven moments invariant to translation, rotation and scale. Seventh one is skew-invariant. Those values can be found using **cv2.HuMoments()** function.
-
-Additional Resources
-=====================
-
-Exercises
-============
-#. Check the documentation for **cv2.pointPolygonTest()**, you can find a nice image in Red and Blue color. It represents the distance from all pixels to the white curve on it. All pixels inside curve is blue depending on the distance. Similarly outside points are red. Contour edges are marked with White. So problem is simple. Write a code to create such a representation of distance.
-
-#. Compare images of digits or letters using **cv2.matchShapes()**. ( That would be a simple step towards OCR )
+++ /dev/null
-.. _Table-Of-Content-Contours:
-
-Contours in OpenCV
------------------------------------------------------------
-
-* :ref:`Contours_Getting_Started`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |contour_1| Learn to find and draw Contours
-
-
- =========== ===================================================================
-
- .. |contour_1| image:: images/contour_starting.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Contour_Features`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |contour_2| Learn to find different features of contours like area, perimeter, bounding rectangle etc.
-
- =========== ===================================================================
-
- .. |contour_2| image:: images/contour_features.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Contour_Properties`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |contour_3| Learn to find different properties of contours like Solidity, Mean Intensity etc.
-
- =========== ===================================================================
-
- .. |contour_3| image:: images/contour_properties.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Contours_More_Functions`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |contour_4| Learn to find convexity defects, pointPolygonTest, match different shapes etc.
-
- =========== ===================================================================
-
- .. |contour_4| image:: images/contour_defects.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Contours_Hierarchy`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |contour_5| Learn about Contour Hierarchy
-
- =========== ===================================================================
-
- .. |contour_5| image:: images/contour_hierarchy.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_contours_begin/py_contours_begin
- ../py_contour_features/py_contour_features
- ../py_contour_properties/py_contour_properties
- ../py_contours_more_functions/py_contours_more_functions
- ../py_contours_hierarchy/py_contours_hierarchy
+++ /dev/null
-.. _Filtering:
-
-Smoothing Images
-***********************
-
-Goals
-=======
-
-Learn to:
- * Blur the images with various low pass filters
- * Apply custom-made filters to images (2D convolution)
-
-2D Convolution ( Image Filtering )
-====================================
-
-As in one-dimensional signals, images also can be filtered with various low-pass filters(LPF), high-pass filters(HPF) etc. LPF helps in removing noises, blurring the images etc. HPF filters helps in finding edges in the images.
-
-OpenCV provides a function **cv2.filter2D()** to convolve a kernel with an image. As an example, we will try an averaging filter on an image. A 5x5 averaging filter kernel will look like below:
-
-.. math::
-
- K = \frac{1}{25} \begin{bmatrix} 1 & 1 & 1 & 1 & 1 \\ 1 & 1 & 1 & 1 & 1 \\ 1 & 1 & 1 & 1 & 1 \\ 1 & 1 & 1 & 1 & 1 \\ 1 & 1 & 1 & 1 & 1 \end{bmatrix}
-
-Operation is like this: keep this kernel above a pixel, add all the 25 pixels below this kernel, take its average and replace the central pixel with the new average value. It continues this operation for all the pixels in the image. Try this code and check the result:
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('opencv_logo.png')
-
- kernel = np.ones((5,5),np.float32)/25
- dst = cv2.filter2D(img,-1,kernel)
-
- plt.subplot(121),plt.imshow(img),plt.title('Original')
- plt.xticks([]), plt.yticks([])
- plt.subplot(122),plt.imshow(dst),plt.title('Averaging')
- plt.xticks([]), plt.yticks([])
- plt.show()
-
-Result:
-
- .. image:: images/filter.jpg
- :alt: Averaging Filter
- :align: center
-
-Image Blurring (Image Smoothing)
-==================================
-
-Image blurring is achieved by convolving the image with a low-pass filter kernel. It is useful for removing noises. It actually removes high frequency content (eg: noise, edges) from the image. So edges are blurred a little bit in this operation. (Well, there are blurring techniques which doesn't blur the edges too). OpenCV provides mainly four types of blurring techniques.
-
-1. Averaging
---------------
-
-This is done by convolving image with a normalized box filter. It simply takes the average of all the pixels under kernel area and replace the central element. This is done by the function **cv2.blur()** or **cv2.boxFilter()**. Check the docs for more details about the kernel. We should specify the width and height of kernel. A 3x3 normalized box filter would look like below:
-
-.. math::
-
- K = \frac{1}{9} \begin{bmatrix} 1 & 1 & 1 \\ 1 & 1 & 1 \\ 1 & 1 & 1 \end{bmatrix}
-
-.. note:: If you don't want to use normalized box filter, use **cv2.boxFilter()**. Pass an argument ``normalize=False`` to the function.
-
-Check a sample demo below with a kernel of 5x5 size:
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('opencv_logo.png')
-
- blur = cv2.blur(img,(5,5))
-
- plt.subplot(121),plt.imshow(img),plt.title('Original')
- plt.xticks([]), plt.yticks([])
- plt.subplot(122),plt.imshow(blur),plt.title('Blurred')
- plt.xticks([]), plt.yticks([])
- plt.show()
-
-Result:
-
- .. image:: images/blur.jpg
- :alt: Averaging Filter
- :align: center
-
-
-2. Gaussian Blurring
-----------------------
-
-In this, instead of box filter, gaussian kernel is used. It is done with the function, **cv2.GaussianBlur()**. We should specify the width and height of kernel which should be positive and odd. We also should specify the standard deviation in X and Y direction, sigmaX and sigmaY respectively. If only sigmaX is specified, sigmaY is taken as same as sigmaX. If both are given as zeros, they are calculated from kernel size. Gaussian blurring is highly effective in removing gaussian noise from the image.
-
-If you want, you can create a Gaussian kernel with the function, **cv2.getGaussianKernel()**.
-
-The above code can be modified for Gaussian blurring:
-::
-
- blur = cv2.GaussianBlur(img,(5,5),0)
-
-
-Result:
-
- .. image:: images/gaussian.jpg
- :alt: Gaussian Blurring
- :align: center
-
-
-3. Median Blurring
---------------------
-
-Here, the function **cv2.medianBlur()** takes median of all the pixels under kernel area and central element is replaced with this median value. This is highly effective against salt-and-pepper noise in the images. Interesting thing is that, in the above filters, central element is a newly calculated value which may be a pixel value in the image or a new value. But in median blurring, central element is always replaced by some pixel value in the image. It reduces the noise effectively. Its kernel size should be a positive odd integer.
-
-In this demo, I added a 50% noise to our original image and applied median blur. Check the result:
-::
-
- median = cv2.medianBlur(img,5)
-
-Result:
-
- .. image:: images/median.jpg
- :alt: Median Blurring
- :align: center
-
-
-4. Bilateral Filtering
------------------------
-
-**cv2.bilateralFilter()** is highly effective in noise removal while keeping edges sharp. But the operation is slower compared to other filters. We already saw that gaussian filter takes the a neighbourhood around the pixel and find its gaussian weighted average. This gaussian filter is a function of space alone, that is, nearby pixels are considered while filtering. It doesn't consider whether pixels have almost same intensity. It doesn't consider whether pixel is an edge pixel or not. So it blurs the edges also, which we don't want to do.
-
-Bilateral filter also takes a gaussian filter in space, but one more gaussian filter which is a function of pixel difference. Gaussian function of space make sure only nearby pixels are considered for blurring while gaussian function of intensity difference make sure only those pixels with similar intensity to central pixel is considered for blurring. So it preserves the edges since pixels at edges will have large intensity variation.
-
-Below samples shows use bilateral filter (For details on arguments, visit docs).
-::
-
- blur = cv2.bilateralFilter(img,9,75,75)
-
-Result:
-
- .. image:: images/bilateral.jpg
- :alt: Bilateral Filtering
- :align: center
-
-See, the texture on the surface is gone, but edges are still preserved.
-
-Additional Resources
-======================
-
-1. Details about the `bilateral filtering <http://people.csail.mit.edu/sparis/bf_course/>`_
-
-Exercises
-===========
+++ /dev/null
-.. _Geometric_Transformations:
-
-Geometric Transformations of Images
-*************************************
-
-Goals
-========
-
- * Learn to apply different geometric transformation to images like translation, rotation, affine transformation etc.
- * You will see these functions: **cv2.getPerspectiveTransform**
-
-Transformations
-=================
-
-OpenCV provides two transformation functions, **cv2.warpAffine** and **cv2.warpPerspective**, with which you can have all kinds of transformations. **cv2.warpAffine** takes a 2x3 transformation matrix while **cv2.warpPerspective** takes a 3x3 transformation matrix as input.
-
-Scaling
----------
-
-Scaling is just resizing of the image. OpenCV comes with a function **cv2.resize()** for this purpose. The size of the image can be specified manually, or you can specify the scaling factor. Different interpolation methods are used. Preferable interpolation methods are **cv2.INTER_AREA** for shrinking and **cv2.INTER_CUBIC** (slow) & **cv2.INTER_LINEAR** for zooming. By default, interpolation method used is **cv2.INTER_LINEAR** for all resizing purposes. You can resize an input image either of following methods:
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('messi5.jpg')
-
- res = cv2.resize(img,None,fx=2, fy=2, interpolation = cv2.INTER_CUBIC)
-
- #OR
-
- height, width = img.shape[:2]
- res = cv2.resize(img,(2*width, 2*height), interpolation = cv2.INTER_CUBIC)
-
-Translation
--------------
-
-Translation is the shifting of object's location. If you know the shift in (x,y) direction, let it be :math:`(t_x,t_y)`, you can create the transformation matrix :math:`\textbf{M}` as follows:
-
-.. math::
-
- M = \begin{bmatrix} 1 & 0 & t_x \\ 0 & 1 & t_y \end{bmatrix}
-
-You can take make it into a Numpy array of type ``np.float32`` and pass it into **cv2.warpAffine()** function. See below example for a shift of (100,50):
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('messi5.jpg',0)
- rows,cols = img.shape
-
- M = np.float32([[1,0,100],[0,1,50]])
- dst = cv2.warpAffine(img,M,(cols,rows))
-
- cv2.imshow('img',dst)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-.. warning:: Third argument of the **cv2.warpAffine()** function is the size of the output image, which should be in the form of **(width, height)**. Remember width = number of columns, and height = number of rows.
-
-See the result below:
-
- .. image:: images/translation.jpg
- :alt: Translation
- :align: center
-
-Rotation
-----------
-
-Rotation of an image for an angle :math:`\theta` is achieved by the transformation matrix of the form
-
-.. math::
-
- M = \begin{bmatrix} cos\theta & -sin\theta \\ sin\theta & cos\theta \end{bmatrix}
-
-But OpenCV provides scaled rotation with adjustable center of rotation so that you can rotate at any location you prefer. Modified transformation matrix is given by
-
-.. math::
-
- \begin{bmatrix} \alpha & \beta & (1- \alpha ) \cdot center.x - \beta \cdot center.y \\ - \beta & \alpha & \beta \cdot center.x + (1- \alpha ) \cdot center.y \end{bmatrix}
-
-where:
-
-.. math::
-
- \begin{array}{l} \alpha = scale \cdot \cos \theta , \\ \beta = scale \cdot \sin \theta \end{array}
-
-To find this transformation matrix, OpenCV provides a function, **cv2.getRotationMatrix2D**. Check below example which rotates the image by 90 degree with respect to center without any scaling.
-::
-
- img = cv2.imread('messi5.jpg',0)
- rows,cols = img.shape
-
- M = cv2.getRotationMatrix2D((cols/2,rows/2),90,1)
- dst = cv2.warpAffine(img,M,(cols,rows))
-
-See the result:
-
- .. image:: images/rotation.jpg
- :alt: Rotation of Image
- :align: center
-
-
-Affine Transformation
-------------------------
-
-In affine transformation, all parallel lines in the original image will still be parallel in the output image. To find the transformation matrix, we need three points from input image and their corresponding locations in output image. Then **cv2.getAffineTransform** will create a 2x3 matrix which is to be passed to **cv2.warpAffine**.
-
-Check below example, and also look at the points I selected (which are marked in Green color):
-::
-
- img = cv2.imread('drawing.png')
- rows,cols,ch = img.shape
-
- pts1 = np.float32([[50,50],[200,50],[50,200]])
- pts2 = np.float32([[10,100],[200,50],[100,250]])
-
- M = cv2.getAffineTransform(pts1,pts2)
-
- dst = cv2.warpAffine(img,M,(cols,rows))
-
- plt.subplot(121),plt.imshow(img),plt.title('Input')
- plt.subplot(122),plt.imshow(dst),plt.title('Output')
- plt.show()
-
-See the result:
-
- .. image:: images/affine.jpg
- :alt: Affine Transformation
- :align: center
-
-Perspective Transformation
-----------------------------
-
-For perspective transformation, you need a 3x3 transformation matrix. Straight lines will remain straight even after the transformation. To find this transformation matrix, you need 4 points on the input image and corresponding points on the output image. Among these 4 points, 3 of them should not be collinear. Then transformation matrix can be found by the function **cv2.getPerspectiveTransform**. Then apply **cv2.warpPerspective** with this 3x3 transformation matrix.
-
-See the code below:
-::
-
- img = cv2.imread('sudokusmall.png')
- rows,cols,ch = img.shape
-
- pts1 = np.float32([[56,65],[368,52],[28,387],[389,390]])
- pts2 = np.float32([[0,0],[300,0],[0,300],[300,300]])
-
- M = cv2.getPerspectiveTransform(pts1,pts2)
-
- dst = cv2.warpPerspective(img,M,(300,300))
-
- plt.subplot(121),plt.imshow(img),plt.title('Input')
- plt.subplot(122),plt.imshow(dst),plt.title('Output')
- plt.show()
-
-Result:
-
- .. image:: images/perspective.jpg
- :alt: Perspective Transformation
- :align: center
-
-Additional Resources
-=====================
-#. "Computer Vision: Algorithms and Applications", Richard Szeliski
-
-Exercises
-===========
+++ /dev/null
-.. _grabcut:
-
-Interactive Foreground Extraction using GrabCut Algorithm
-*************************************************************
-
-Goal
-======
-
-In this chapter
- * We will see GrabCut algorithm to extract foreground in images
- * We will create an interactive application for this.
-
-Theory
-=========
-
-GrabCut algorithm was designed by Carsten Rother, Vladimir Kolmogorov & Andrew Blake from Microsoft Research Cambridge, UK. in their paper, `"GrabCut": interactive foreground extraction using iterated graph cuts <http://dl.acm.org/citation.cfm?id=1015720>`_ . An algorithm was needed for foreground extraction with minimal user interaction, and the result was GrabCut.
-
-How it works from user point of view ? Initially user draws a rectangle around the foreground region (foreground region shoule be completely inside the rectangle). Then algorithm segments it iteratively to get the best result. Done. But in some cases, the segmentation won't be fine, like, it may have marked some foreground region as background and vice versa. In that case, user need to do fine touch-ups. Just give some strokes on the images where some faulty results are there. Strokes basically says *"Hey, this region should be foreground, you marked it background, correct it in next iteration"* or its opposite for background. Then in the next iteration, you get better results.
-
-See the image below. First player and football is enclosed in a blue rectangle. Then some final touchups with white strokes (denoting foreground) and black strokes (denoting background) is made. And we get a nice result.
-
- .. image:: images/grabcut_output1.jpg
- :alt: GrabCut in Action
- :align: center
-
-So what happens in background ?
-
- * User inputs the rectangle. Everything outside this rectangle will be taken as sure background (That is the reason it is mentioned before that your rectangle should include all the objects). Everything inside rectangle is unknown. Similarly any user input specifying foreground and background are considered as hard-labelling which means they won't change in the process.
- * Computer does an initial labelling depeding on the data we gave. It labels the foreground and background pixels (or it hard-labels)
- * Now a Gaussian Mixture Model(GMM) is used to model the foreground and background.
- * Depending on the data we gave, GMM learns and create new pixel distribution. That is, the unknown pixels are labelled either probable foreground or probable background depending on its relation with the other hard-labelled pixels in terms of color statistics (It is just like clustering).
- * A graph is built from this pixel distribution. Nodes in the graphs are pixels. Additional two nodes are added, **Source node** and **Sink node**. Every foreground pixel is connected to Source node and every background pixel is connected to Sink node.
- * The weights of edges connecting pixels to source node/end node are defined by the probability of a pixel being foreground/background. The weights between the pixels are defined by the edge information or pixel similarity. If there is a large difference in pixel color, the edge between them will get a low weight.
- * Then a mincut algorithm is used to segment the graph. It cuts the graph into two separating source node and sink node with minimum cost function. The cost function is the sum of all weights of the edges that are cut. After the cut, all the pixels connected to Source node become foreground and those connected to Sink node become background.
- * The process is continued until the classification converges.
-
-It is illustrated in below image (Image Courtesy: http://www.cs.ru.ac.za/research/g02m1682/)
-
- .. image:: images/grabcut_scheme.jpg
- :alt: Simplified Diagram of GrabCut Algorithm
- :align: center
-
-Demo
-=======
-
-Now we go for grabcut algorithm with OpenCV. OpenCV has the function, **cv2.grabCut()** for this. We will see its arguments first:
-
- * *img* - Input image
- * *mask* - It is a mask image where we specify which areas are background, foreground or probable background/foreground etc. It is done by the following flags, **cv2.GC_BGD, cv2.GC_FGD, cv2.GC_PR_BGD, cv2.GC_PR_FGD**, or simply pass 0,1,2,3 to image.
- * *rect* - It is the coordinates of a rectangle which includes the foreground object in the format (x,y,w,h)
- * *bdgModel*, *fgdModel* - These are arrays used by the algorithm internally. You just create two np.float64 type zero arrays of size (1,65).
- * *iterCount* - Number of iterations the algorithm should run.
- * *mode* - It should be **cv2.GC_INIT_WITH_RECT** or **cv2.GC_INIT_WITH_MASK** or combined which decides whether we are drawing rectangle or final touchup strokes.
-
-First let's see with rectangular mode. We load the image, create a similar mask image. We create *fgdModel* and *bgdModel*. We give the rectangle parameters. It's all straight-forward. Let the algorithm run for 5 iterations. Mode should be *cv2.GC_INIT_WITH_RECT* since we are using rectangle. Then run the grabcut. It modifies the mask image. In the new mask image, pixels will be marked with four flags denoting background/foreground as specified above. So we modify the mask such that all 0-pixels and 2-pixels are put to 0 (ie background) and all 1-pixels and 3-pixels are put to 1(ie foreground pixels). Now our final mask is ready. Just multiply it with input image to get the segmented image.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('messi5.jpg')
- mask = np.zeros(img.shape[:2],np.uint8)
-
- bgdModel = np.zeros((1,65),np.float64)
- fgdModel = np.zeros((1,65),np.float64)
-
- rect = (50,50,450,290)
- cv2.grabCut(img,mask,rect,bgdModel,fgdModel,5,cv2.GC_INIT_WITH_RECT)
-
- mask2 = np.where((mask==2)|(mask==0),0,1).astype('uint8')
- img = img*mask2[:,:,np.newaxis]
-
- plt.imshow(img),plt.colorbar(),plt.show()
-
-See the results below:
-
- .. image:: images/grabcut_rect.jpg
- :alt: Segmentation in rect mode
- :align: center
-
-Oops, Messi's hair is gone. *Who likes Messi without his hair?* We need to bring it back. So we will give there a fine touchup with 1-pixel (sure foreground). At the same time, Some part of ground has come to picture which we don't want, and also some logo. We need to remove them. There we give some 0-pixel touchup (sure background). So we modify our resulting mask in previous case as we told now.
-
-*What I actually did is that, I opened input image in paint application and added another layer to the image. Using brush tool in the paint, I marked missed foreground (hair, shoes, ball etc) with white and unwanted background (like logo, ground etc) with black on this new layer. Then filled remaining background with gray. Then loaded that mask image in OpenCV, edited original mask image we got with corresponding values in newly added mask image. Check the code below:*
-::
-
- # newmask is the mask image I manually labelled
- newmask = cv2.imread('newmask.png',0)
-
- # whereever it is marked white (sure foreground), change mask=1
- # whereever it is marked black (sure background), change mask=0
- mask[newmask == 0] = 0
- mask[newmask == 255] = 1
-
- mask, bgdModel, fgdModel = cv2.grabCut(img,mask,None,bgdModel,fgdModel,5,cv2.GC_INIT_WITH_MASK)
-
- mask = np.where((mask==2)|(mask==0),0,1).astype('uint8')
- img = img*mask[:,:,np.newaxis]
- plt.imshow(img),plt.colorbar(),plt.show()
-
-See the result below:
-
- .. image:: images/grabcut_mask.jpg
- :alt: Segmentation in mask mode
- :align: center
-
-So that's it. Here instead of initializing in rect mode, you can directly go into mask mode. Just mark the rectangle area in mask image with 2-pixel or 3-pixel (probable background/foreground). Then mark our sure_foreground with 1-pixel as we did in second example. Then directly apply the grabCut function with mask mode.
-
-Additional Resources
-=======================
-
-
-
-Exercises
-============
-
-#. OpenCV samples contain a sample ``grabcut.py`` which is an interactive tool using grabcut. Check it. Also watch this `youtube video <http://www.youtube.com/watch?v=kAwxLTDDAwU>`_ on how to use it.
-#. Here, you can make this into a interactive sample with drawing rectangle and strokes with mouse, create trackbar to adjust stroke width etc.
+++ /dev/null
-.. _Gradients:
-
-Image Gradients
-**********************
-
-Goal
-======
-
-In this chapter, we will learn to:
-
- * Find Image gradients, edges etc
- * We will see following functions : **cv2.Sobel()**, **cv2.Scharr()**, **cv2.Laplacian()** etc
-
-Theory
-=======
-
-OpenCV provides three types of gradient filters or High-pass filters, Sobel, Scharr and Laplacian. We will see each one of them.
-
-1. Sobel and Scharr Derivatives
----------------------------------
-
-Sobel operators is a joint Gausssian smoothing plus differentiation operation, so it is more resistant to noise. You can specify the direction of derivatives to be taken, vertical or horizontal (by the arguments, ``yorder`` and ``xorder`` respectively). You can also specify the size of kernel by the argument ``ksize``. If ksize = -1, a 3x3 Scharr filter is used which gives better results than 3x3 Sobel filter. Please see the docs for kernels used.
-
-2. Laplacian Derivatives
---------------------------
-
-It calculates the Laplacian of the image given by the relation, :math:`\Delta src = \frac{\partial ^2{src}}{\partial x^2} + \frac{\partial ^2{src}}{\partial y^2}` where each derivative is found using Sobel derivatives. If ``ksize = 1``, then following kernel is used for filtering:
-
-.. math::
-
- kernel = \begin{bmatrix} 0 & 1 & 0 \\ 1 & -4 & 1 \\ 0 & 1 & 0 \end{bmatrix}
-
-Code
-=======
-
-Below code shows all operators in a single diagram. All kernels are of 5x5 size. Depth of output image is passed -1 to get the result in np.uint8 type.
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('dave.jpg',0)
-
- laplacian = cv2.Laplacian(img,cv2.CV_64F)
- sobelx = cv2.Sobel(img,cv2.CV_64F,1,0,ksize=5)
- sobely = cv2.Sobel(img,cv2.CV_64F,0,1,ksize=5)
-
- plt.subplot(2,2,1),plt.imshow(img,cmap = 'gray')
- plt.title('Original'), plt.xticks([]), plt.yticks([])
- plt.subplot(2,2,2),plt.imshow(laplacian,cmap = 'gray')
- plt.title('Laplacian'), plt.xticks([]), plt.yticks([])
- plt.subplot(2,2,3),plt.imshow(sobelx,cmap = 'gray')
- plt.title('Sobel X'), plt.xticks([]), plt.yticks([])
- plt.subplot(2,2,4),plt.imshow(sobely,cmap = 'gray')
- plt.title('Sobel Y'), plt.xticks([]), plt.yticks([])
-
- plt.show()
-
-Result:
-
- .. image:: images/gradients.jpg
- :alt: Image Gradients
- :align: center
-
-One Important Matter!
-=======================
-
-In our last example, output datatype is cv2.CV_8U or np.uint8. But there is a slight problem with that. Black-to-White transition is taken as Positive slope (it has a positive value) while White-to-Black transition is taken as a Negative slope (It has negative value). So when you convert data to np.uint8, all negative slopes are made zero. In simple words, you miss that edge.
-
-If you want to detect both edges, better option is to keep the output datatype to some higher forms, like cv2.CV_16S, cv2.CV_64F etc, take its absolute value and then convert back to cv2.CV_8U. Below code demonstrates this procedure for a horizontal Sobel filter and difference in results.
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('box.png',0)
-
- # Output dtype = cv2.CV_8U
- sobelx8u = cv2.Sobel(img,cv2.CV_8U,1,0,ksize=5)
-
- # Output dtype = cv2.CV_64F. Then take its absolute and convert to cv2.CV_8U
- sobelx64f = cv2.Sobel(img,cv2.CV_64F,1,0,ksize=5)
- abs_sobel64f = np.absolute(sobelx64f)
- sobel_8u = np.uint8(abs_sobel64f)
-
- plt.subplot(1,3,1),plt.imshow(img,cmap = 'gray')
- plt.title('Original'), plt.xticks([]), plt.yticks([])
- plt.subplot(1,3,2),plt.imshow(sobelx8u,cmap = 'gray')
- plt.title('Sobel CV_8U'), plt.xticks([]), plt.yticks([])
- plt.subplot(1,3,3),plt.imshow(sobel_8u,cmap = 'gray')
- plt.title('Sobel abs(CV_64F)'), plt.xticks([]), plt.yticks([])
-
- plt.show()
-
-Check the result below:
-
- .. image:: images/double_edge.jpg
- :alt: Double Edges
- :align: center
-
-Additional Resources
-======================
-
-Exercises
-===========
+++ /dev/null
-.. _TwoD_Histogram:
-
-Histograms - 3 : 2D Histograms
-*************************************
-
-Goal
-=======
-
-In this chapter, we will learn to find and plot 2D histograms. It will be helpful in coming chapters.
-
-Introduction
-===============
-
-In the first article, we calculated and plotted one-dimensional histogram. It is called one-dimensional because we are taking only one feature into our consideration, ie grayscale intensity value of the pixel. But in two-dimensional histograms, you consider two features. Normally it is used for finding color histograms where two features are Hue & Saturation values of every pixel.
-
-There is a `python sample in the official samples <https://github.com/Itseez/opencv/blob/master/samples/python2/color_histogram.py>`_ already for finding color histograms. We will try to understand how to create such a color histogram, and it will be useful in understanding further topics like Histogram Back-Projection.
-
-2D Histogram in OpenCV
-=======================
-
-It is quite simple and calculated using the same function, **cv2.calcHist()**. For color histograms, we need to convert the image from BGR to HSV. (Remember, for 1D histogram, we converted from BGR to Grayscale). For 2D histograms, its parameters will be modified as follows:
-
-* **channels = [0,1]** *because we need to process both H and S plane.*
-* **bins = [180,256]** *180 for H plane and 256 for S plane.*
-* **range = [0,180,0,256]** *Hue value lies between 0 and 180 & Saturation lies between 0 and 256.*
-
-Now check the code below:
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('home.jpg')
- hsv = cv2.cvtColor(img,cv2.COLOR_BGR2HSV)
-
- hist = cv2.calcHist([hsv], [0, 1], None, [180, 256], [0, 180, 0, 256])
-
-That's it.
-
-2D Histogram in Numpy
-=======================
-Numpy also provides a specific function for this : **np.histogram2d()**. (Remember, for 1D histogram we used **np.histogram()** ).
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('home.jpg')
- hsv = cv2.cvtColor(img,cv2.COLOR_BGR2HSV)
-
- hist, xbins, ybins = np.histogram2d(h.ravel(),s.ravel(),[180,256],[[0,180],[0,256]])
-
-First argument is H plane, second one is the S plane, third is number of bins for each and fourth is their range.
-
-Now we can check how to plot this color histogram.
-
-Plotting 2D Histograms
-========================
-
-Method - 1 : Using cv2.imshow()
----------------------------------
-The result we get is a two dimensional array of size 180x256. So we can show them as we do normally, using cv2.imshow() function. It will be a grayscale image and it won't give much idea what colors are there, unless you know the Hue values of different colors.
-
-Method - 2 : Using Matplotlib
-------------------------------
-We can use **matplotlib.pyplot.imshow()** function to plot 2D histogram with different color maps. It gives us a much better idea about the different pixel density. But this also, doesn't gives us idea what color is there on a first look, unless you know the Hue values of different colors. Still I prefer this method. It is simple and better.
-
-.. note:: While using this function, remember, interpolation flag should be ``nearest`` for better results.
-
-Consider code:
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('home.jpg')
- hsv = cv2.cvtColor(img,cv2.COLOR_BGR2HSV)
- hist = cv2.calcHist( [hsv], [0, 1], None, [180, 256], [0, 180, 0, 256] )
-
- plt.imshow(hist,interpolation = 'nearest')
- plt.show()
-
-Below is the input image and its color histogram plot. X axis shows S values and Y axis shows Hue.
-
- .. image:: images/2dhist_matplotlib.jpg
- :alt: 2D Histograms
- :align: center
-
-In histogram, you can see some high values near H = 100 and S = 200. It corresponds to blue of sky. Similarly another peak can be seen near H = 25 and S = 100. It corresponds to yellow of the palace. You can verify it with any image editing tools like GIMP.
-
-Method 3 : OpenCV sample style !!
-------------------------------------
-
-There is a `sample code for color-histogram in OpenCV-Python2 samples <https://github.com/Itseez/opencv/blob/master/samples/python2/color_histogram.py>`_. If you run the code, you can see the histogram shows the corresponding color also. Or simply it outputs a color coded histogram. Its result is very good (although you need to add extra bunch of lines).
-
-In that code, the author created a color map in HSV. Then converted it into BGR. The resulting histogram image is multiplied with this color map. He also uses some preprocessing steps to remove small isolated pixels, resulting in a good histogram.
-
-I leave it to the readers to run the code, analyze it and have your own hack arounds. Below is the output of that code for the same image as above:
-
- .. image:: images/2dhist_opencv.jpg
- :alt: 2D Histograms using OpenCV-Python Samples
- :align: center
-
-You can clearly see in the histogram what colors are present, blue is there, yellow is there, and some white due to chessboard is there. Nice !!!
-
-Additional Resources
-=====================
-
-Exercises
-================
+++ /dev/null
-.. _Histogram_Backprojection:
-
-Histogram - 4 : Histogram Backprojection
-*******************************************
-
-Goal
-=======
-
-In this chapter, we will learn about histogram backprojection.
-
-Theory
-=======
-
-It was proposed by **Michael J. Swain , Dana H. Ballard** in their paper **Indexing via color histograms**.
-
-**What is it actually in simple words?** It is used for image segmentation or finding objects of interest in an image. In simple words, it creates an image of the same size (but single channel) as that of our input image, where each pixel corresponds to the probability of that pixel belonging to our object. In more simpler worlds, the output image will have our object of interest in more white compared to remaining part. Well, that is an intuitive explanation. (I can't make it more simpler). Histogram Backprojection is used with camshift algorithm etc.
-
-**How do we do it ?** We create a histogram of an image containing our object of interest (in our case, the ground, leaving player and other things). The object should fill the image as far as possible for better results. And a color histogram is preferred over grayscale histogram, because color of the object is a better way to define the object than its grayscale intensity. We then "back-project" this histogram over our test image where we need to find the object, ie in other words, we calculate the probability of every pixel belonging to the ground and show it. The resulting output on proper thresholding gives us the ground alone.
-
-Algorithm in Numpy
-====================
-
-1. First we need to calculate the color histogram of both the object we need to find (let it be 'M') and the image where we are going to search (let it be 'I').
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- #roi is the object or region of object we need to find
- roi = cv2.imread('rose_red.png')
- hsv = cv2.cvtColor(roi,cv2.COLOR_BGR2HSV)
-
- #target is the image we search in
- target = cv2.imread('rose.png')
- hsvt = cv2.cvtColor(target,cv2.COLOR_BGR2HSV)
-
- # Find the histograms using calcHist. Can be done with np.histogram2d also
- M = cv2.calcHist([hsv],[0, 1], None, [180, 256], [0, 180, 0, 256] )
- I = cv2.calcHist([hsvt],[0, 1], None, [180, 256], [0, 180, 0, 256] )
-
-2. Find the ratio :math:`R = \frac{M}{I}`. Then backproject R, ie use R as palette and create a new image with every pixel as its corresponding probability of being target. ie ``B(x,y) = R[h(x,y),s(x,y)]`` where h is hue and s is saturation of the pixel at (x,y). After that apply the condition :math:`B(x,y) = min[B(x,y), 1]`.
-::
-
- h,s,v = cv2.split(hsvt)
- B = R[h.ravel(),s.ravel()]
- B = np.minimum(B,1)
- B = B.reshape(hsvt.shape[:2])
-
-3. Now apply a convolution with a circular disc, :math:`B = D \ast B`, where D is the disc kernel.
-::
-
- disc = cv2.getStructuringElement(cv2.MORPH_ELLIPSE,(5,5))
- cv2.filter2D(B,-1,disc,B)
- B = np.uint8(B)
- cv2.normalize(B,B,0,255,cv2.NORM_MINMAX)
-
-4. Now the location of maximum intensity gives us the location of object. If we are expecting a region in the image, thresholding for a suitable value gives a nice result.
-::
-
- ret,thresh = cv2.threshold(B,50,255,0)
-
-That's it !!
-
-Backprojection in OpenCV
-==========================
-
-OpenCV provides an inbuilt function **cv2.calcBackProject()**. Its parameters are almost same as the **cv2.calcHist()** function. One of its parameter is histogram which is histogram of the object and we have to find it. Also, the object histogram should be normalized before passing on to the backproject function. It returns the probability image. Then we convolve the image with a disc kernel and apply threshold. Below is my code and output :
-::
-
- import cv2
- import numpy as np
-
- roi = cv2.imread('rose_red.png')
- hsv = cv2.cvtColor(roi,cv2.COLOR_BGR2HSV)
-
- target = cv2.imread('rose.png')
- hsvt = cv2.cvtColor(target,cv2.COLOR_BGR2HSV)
-
- # calculating object histogram
- roihist = cv2.calcHist([hsv],[0, 1], None, [180, 256], [0, 180, 0, 256] )
-
- # normalize histogram and apply backprojection
- cv2.normalize(roihist,roihist,0,255,cv2.NORM_MINMAX)
- dst = cv2.calcBackProject([hsvt],[0,1],roihist,[0,180,0,256],1)
-
- # Now convolute with circular disc
- disc = cv2.getStructuringElement(cv2.MORPH_ELLIPSE,(5,5))
- cv2.filter2D(dst,-1,disc,dst)
-
- # threshold and binary AND
- ret,thresh = cv2.threshold(dst,50,255,0)
- thresh = cv2.merge((thresh,thresh,thresh))
- res = cv2.bitwise_and(target,thresh)
-
- res = np.vstack((target,thresh,res))
- cv2.imwrite('res.jpg',res)
-
-Below is one example I worked with. I used the region inside blue rectangle as sample object and I wanted to extract the full ground.
-
- .. image:: images/backproject_opencv.jpg
- :alt: Histogram Backprojection in OpenCV
- :align: center
-
-Additional Resources
-=====================
-#. "Indexing via color histograms", Swain, Michael J. , Third international conference on computer vision,1990.
-
-
-Exercises
-============
+++ /dev/null
-.. _Histograms_Getting_Started:
-
-Histograms - 1 : Find, Plot, Analyze !!!
-******************************************
-
-Goal
-=======
-
-Learn to
- * Find histograms, using both OpenCV and Numpy functions
- * Plot histograms, using OpenCV and Matplotlib functions
- * You will see these functions : **cv2.calcHist()**, **np.histogram()** etc.
-
-Theory
-========
-
-So what is histogram ? You can consider histogram as a graph or plot, which gives you an overall idea about the intensity distribution of an image. It is a plot with pixel values (ranging from 0 to 255, not always) in X-axis and corresponding number of pixels in the image on Y-axis.
-
-It is just another way of understanding the image. By looking at the histogram of an image, you get intuition about contrast, brightness, intensity distribution etc of that image. Almost all image processing tools today, provides features on histogram. Below is an image from `Cambridge in Color website <http://www.cambridgeincolour.com/tutorials/histograms1.htm>`_, and I recommend you to visit the site for more details.
-
- .. image:: images/histogram_sample.jpg
- :alt: Histogram Example
- :align: center
-
-You can see the image and its histogram. (Remember, this histogram is drawn for grayscale image, not color image). Left region of histogram shows the amount of darker pixels in image and right region shows the amount of brighter pixels. From the histogram, you can see dark region is more than brighter region, and amount of midtones (pixel values in mid-range, say around 127) are very less.
-
-Find Histogram
-================
-
-Now we have an idea on what is histogram, we can look into how to find this. Both OpenCV and Numpy come with in-built function for this. Before using those functions, we need to understand some terminologies related with histograms.
-
-**BINS** :The above histogram shows the number of pixels for every pixel value, ie from 0 to 255. ie you need 256 values to show the above histogram. But consider, what if you need not find the number of pixels for all pixel values separately, but number of pixels in a interval of pixel values? say for example, you need to find the number of pixels lying between 0 to 15, then 16 to 31, ..., 240 to 255. You will need only 16 values to represent the histogram. And that is what is shown in example given in `OpenCV Tutorials on histograms <http://docs.opencv.org/doc/tutorials/imgproc/histograms/histogram_calculation/histogram_calculation.html#histogram-calculation>`_.
-
-So what you do is simply split the whole histogram to 16 sub-parts and value of each sub-part is the sum of all pixel count in it. This each sub-part is called "BIN". In first case, number of bins where 256 (one for each pixel) while in second case, it is only 16. BINS is represented by the term **histSize** in OpenCV docs.
-
-**DIMS** : It is the number of parameters for which we collect the data. In this case, we collect data regarding only one thing, intensity value. So here it is 1.
-
-**RANGE** : It is the range of intensity values you want to measure. Normally, it is [0,256], ie all intensity values.
-
-1. Histogram Calculation in OpenCV
---------------------------------------
-
-So now we use **cv2.calcHist()** function to find the histogram. Let's familiarize with the function and its parameters :
-
-.. centered:: *cv2.calcHist(images, channels, mask, histSize, ranges[, hist[, accumulate]])*
-
-#. images : it is the source image of type uint8 or float32. it should be given in square brackets, ie, "[img]".
-#. channels : it is also given in square brackets. It is the index of channel for which we calculate histogram. For example, if input is grayscale image, its value is [0]. For color image, you can pass [0], [1] or [2] to calculate histogram of blue, green or red channel respectively.
-#. mask : mask image. To find histogram of full image, it is given as "None". But if you want to find histogram of particular region of image, you have to create a mask image for that and give it as mask. (I will show an example later.)
-#. histSize : this represents our BIN count. Need to be given in square brackets. For full scale, we pass [256].
-#. ranges : this is our RANGE. Normally, it is [0,256].
-
-So let's start with a sample image. Simply load an image in grayscale mode and find its full histogram.
-
-::
-
- img = cv2.imread('home.jpg',0)
- hist = cv2.calcHist([img],[0],None,[256],[0,256])
-
-hist is a 256x1 array, each value corresponds to number of pixels in that image with its corresponding pixel value.
-
-2. Histogram Calculation in Numpy
-----------------------------------
-Numpy also provides you a function, **np.histogram()**. So instead of calcHist() function, you can try below line :
-::
-
- hist,bins = np.histogram(img.ravel(),256,[0,256])
-
-hist is same as we calculated before. But bins will have 257 elements, because Numpy calculates bins as 0-0.99, 1-1.99, 2-2.99 etc. So final range would be 255-255.99. To represent that, they also add 256 at end of bins. But we don't need that 256. Upto 255 is sufficient.
-
-.. seealso:: Numpy has another function, **np.bincount()** which is much faster than (around 10X) np.histogram(). So for one-dimensional histograms, you can better try that. Don't forget to set ``minlength = 256`` in np.bincount. For example, ``hist = np.bincount(img.ravel(),minlength=256)``
-
-.. note:: OpenCV function is more faster than (around 40X) than np.histogram(). So stick with OpenCV function.
-
-Now we should plot histograms, but how ?
-
-Plotting Histograms
-======================
-
-There are two ways for this,
- #. Short Way : use Matplotlib plotting functions
- #. Long Way : use OpenCV drawing functions
-
-1. Using Matplotlib
------------------------
-Matplotlib comes with a histogram plotting function : matplotlib.pyplot.hist()
-
-It directly finds the histogram and plot it. You need not use calcHist() or np.histogram() function to find the histogram. See the code below:
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('home.jpg',0)
- plt.hist(img.ravel(),256,[0,256]); plt.show()
-
-You will get a plot as below :
-
- .. image:: images/histogram_matplotlib.jpg
- :alt: Histogram Plotting in Matplotlib
- :align: center
-
-Or you can use normal plot of matplotlib, which would be good for BGR plot. For that, you need to find the histogram data first. Try below code:
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('home.jpg')
- color = ('b','g','r')
- for i,col in enumerate(color):
- histr = cv2.calcHist([img],[i],None,[256],[0,256])
- plt.plot(histr,color = col)
- plt.xlim([0,256])
- plt.show()
-
-Result:
-
- .. image:: images/histogram_rgb_plot.jpg
- :alt: Histogram Plotting in Matplotlib
- :align: center
-
-You can deduct from the above graph that, blue has some high value areas in the image (obviously it should be due to the sky)
-
-2. Using OpenCV
---------------------------
-
-Well, here you adjust the values of histograms along with its bin values to look like x,y coordinates so that you can draw it using cv2.line() or cv2.polyline() function to generate same image as above. This is already available with OpenCV-Python2 official samples. `Check the Code <https://github.com/Itseez/opencv/raw/master/samples/python2/hist.py>`_
-
-Application of Mask
-=====================
-
-We used cv2.calcHist() to find the histogram of the full image. What if you want to find histograms of some regions of an image? Just create a mask image with white color on the region you want to find histogram and black otherwise. Then pass this as the mask.
-::
-
- img = cv2.imread('home.jpg',0)
-
- # create a mask
- mask = np.zeros(img.shape[:2], np.uint8)
- mask[100:300, 100:400] = 255
- masked_img = cv2.bitwise_and(img,img,mask = mask)
-
- # Calculate histogram with mask and without mask
- # Check third argument for mask
- hist_full = cv2.calcHist([img],[0],None,[256],[0,256])
- hist_mask = cv2.calcHist([img],[0],mask,[256],[0,256])
-
- plt.subplot(221), plt.imshow(img, 'gray')
- plt.subplot(222), plt.imshow(mask,'gray')
- plt.subplot(223), plt.imshow(masked_img, 'gray')
- plt.subplot(224), plt.plot(hist_full), plt.plot(hist_mask)
- plt.xlim([0,256])
-
- plt.show()
-
-See the result. In the histogram plot, blue line shows histogram of full image while green line shows histogram of masked region.
-
- .. image:: images/histogram_masking.jpg
- :alt: Histogram Example
- :align: center
-
-Additional Resources
-=====================
-#. `Cambridge in Color website <http://www.cambridgeincolour.com/tutorials/histograms1.htm>`_
-
-Exercises
-==========
+++ /dev/null
-.. _PY_Histogram_Equalization:
-
-Histograms - 2: Histogram Equalization
-****************************************
-
-Goal
-======
-
-In this section,
-
- * We will learn the concepts of histogram equalization and use it to improve the contrast of our images.
-
-Theory
-=========
-
-Consider an image whose pixel values are confined to some specific range of values only. For eg, brighter image will have all pixels confined to high values. But a good image will have pixels from all regions of the image. So you need to stretch this histogram to either ends (as given in below image, from wikipedia) and that is what Histogram Equalization does (in simple words). This normally improves the contrast of the image.
-
- .. image:: images/histogram_equalization.png
- :alt: Histograms Equalization
- :align: center
-
-I would recommend you to read the wikipedia page on `Histogram Equalization <http://en.wikipedia.org/wiki/Histogram_equalization>`_ for more details about it. It has a very good explanation with worked out examples, so that you would understand almost everything after reading that. Instead, here we will see its Numpy implementation. After that, we will see OpenCV function.
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('wiki.jpg',0)
-
- hist,bins = np.histogram(img.flatten(),256,[0,256])
-
- cdf = hist.cumsum()
- cdf_normalized = cdf * hist.max()/ cdf.max()
-
- plt.plot(cdf_normalized, color = 'b')
- plt.hist(img.flatten(),256,[0,256], color = 'r')
- plt.xlim([0,256])
- plt.legend(('cdf','histogram'), loc = 'upper left')
- plt.show()
-
-.. image:: images/histeq_numpy1.jpg
- :alt: Histograms Equalization
- :align: center
-
-You can see histogram lies in brighter region. We need the full spectrum. For that, we need a transformation function which maps the input pixels in brighter region to output pixels in full region. That is what histogram equalization does.
-
-Now we find the minimum histogram value (excluding 0) and apply the histogram equalization equation as given in wiki page. But I have used here, the masked array concept array from Numpy. For masked array, all operations are performed on non-masked elements. You can read more about it from Numpy docs on masked arrays.
-::
-
- cdf_m = np.ma.masked_equal(cdf,0)
- cdf_m = (cdf_m - cdf_m.min())*255/(cdf_m.max()-cdf_m.min())
- cdf = np.ma.filled(cdf_m,0).astype('uint8')
-
-Now we have the look-up table that gives us the information on what is the output pixel value for every input pixel value. So we just apply the transform.
-::
-
- img2 = cdf[img]
-
-Now we calculate its histogram and cdf as before ( you do it) and result looks like below :
-
-.. image:: images/histeq_numpy2.jpg
- :alt: Histograms Equalization
- :align: center
-
-Another important feature is that, even if the image was a darker image (instead of a brighter one we used), after equalization we will get almost the same image as we got. As a result, this is used as a "reference tool" to make all images with same lighting conditions. This is useful in many cases. For example, in face recognition, before training the face data, the images of faces are histogram equalized to make them all with same lighting conditions.
-
-Histograms Equalization in OpenCV
-===================================
-
-OpenCV has a function to do this, **cv2.equalizeHist()**. Its input is just grayscale image and output is our histogram equalized image.
-
-Below is a simple code snippet showing its usage for same image we used :
-::
-
- img = cv2.imread('wiki.jpg',0)
- equ = cv2.equalizeHist(img)
- res = np.hstack((img,equ)) #stacking images side-by-side
- cv2.imwrite('res.png',res)
-
-.. image:: images/equalization_opencv.jpg
- :alt: Histograms Equalization
- :align: center
-
-So now you can take different images with different light conditions, equalize it and check the results.
-
-Histogram equalization is good when histogram of the image is confined to a particular region. It won't work good in places where there is large intensity variations where histogram covers a large region, ie both bright and dark pixels are present. Please check the SOF links in Additional Resources.
-
-
-CLAHE (Contrast Limited Adaptive Histogram Equalization)
-============================================================
-
-The first histogram equalization we just saw, considers the global contrast of the image. In many cases, it is not a good idea. For example, below image shows an input image and its result after global histogram equalization.
-
- .. image:: images/clahe_1.jpg
- :alt: Problem of Global HE
- :align: center
-
-It is true that the background contrast has improved after histogram equalization. But compare the face of statue in both images. We lost most of the information there due to over-brightness. It is because its histogram is not confined to a particular region as we saw in previous cases (Try to plot histogram of input image, you will get more intuition).
-
-So to solve this problem, **adaptive histogram equalization** is used. In this, image is divided into small blocks called "tiles" (tileSize is 8x8 by default in OpenCV). Then each of these blocks are histogram equalized as usual. So in a small area, histogram would confine to a small region (unless there is noise). If noise is there, it will be amplified. To avoid this, **contrast limiting** is applied. If any histogram bin is above the specified contrast limit (by default 40 in OpenCV), those pixels are clipped and distributed uniformly to other bins before applying histogram equalization. After equalization, to remove artifacts in tile borders, bilinear interpolation is applied.
-
-Below code snippet shows how to apply CLAHE in OpenCV:
-::
-
- import numpy as np
- import cv2
-
- img = cv2.imread('tsukuba_l.png',0)
-
- # create a CLAHE object (Arguments are optional).
- clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8,8))
- cl1 = clahe.apply(img)
-
- cv2.imwrite('clahe_2.jpg',cl1)
-
-See the result below and compare it with results above, especially the statue region:
-
- .. image:: images/clahe_2.jpg
- :alt: Result of CLAHE
- :align: center
-
-
-Additional Resources
-======================
-1. Wikipedia page on `Histogram Equalization <http://en.wikipedia.org/wiki/Histogram_equalization>`_
-2. `Masked Arrays in Numpy <http://docs.scipy.org/doc/numpy/reference/maskedarray.html>`_
-
-Also check these SOF questions regarding contrast adjustment:
-
-3. `How can I adjust contrast in OpenCV in C? <http://stackoverflow.com/questions/10549245/how-can-i-adjust-contrast-in-opencv-in-c>`_
-4. `How do I equalize contrast & brightness of images using opencv? <http://stackoverflow.com/questions/10561222/how-do-i-equalize-contrast-brightness-of-images-using-opencv>`_
-
-Exercises
-===========
+++ /dev/null
-.. _Table-Of-Content-Histograms:
-
-Histograms in OpenCV
------------------------------------------------------------
-
-* :ref:`Histograms_Getting_Started`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |hist_1| Learn to find and draw Contours
-
-
- =========== ===================================================================
-
- .. |hist_1| image:: images/histograms_1d.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`PY_Histogram_Equalization`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |hist_2| Learn to Equalize Histograms to get better contrast for images
-
-
- =========== ===================================================================
-
- .. |hist_2| image:: images/histograms_equ.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`TwoD_Histogram`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |hist_3| Learn to find and plot 2D Histograms
-
-
- =========== ===================================================================
-
- .. |hist_3| image:: images/histograms_2d.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Histogram_Backprojection`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |hist_4| Learn histogram backprojection to segment colored objects
-
-
- =========== ===================================================================
-
- .. |hist_4| image:: images/histograms_bp.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_histogram_begins/py_histogram_begins
- ../py_histogram_equalization/py_histogram_equalization
- ../py_2d_histogram/py_2d_histogram
- ../py_histogram_backprojection/py_histogram_backprojection
+++ /dev/null
-.. _Hough_Circles:
-
-Hough Circle Transform
-**************************
-
-Goal
-=====
-
-In this chapter,
- * We will learn to use Hough Transform to find circles in an image.
- * We will see these functions: **cv2.HoughCircles()**
-
-Theory
-========
-
-A circle is represented mathematically as :math:`(x-x_{center})^2 + (y - y_{center})^2 = r^2` where :math:`(x_{center},y_{center})` is the center of the circle, and :math:`r` is the radius of the circle. From equation, we can see we have 3 parameters, so we need a 3D accumulator for hough transform, which would be highly ineffective. So OpenCV uses more trickier method, **Hough Gradient Method** which uses the gradient information of edges.
-
-The function we use here is **cv2.HoughCircles()**. It has plenty of arguments which are well explained in the documentation. So we directly go to the code.
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('opencv_logo.png',0)
- img = cv2.medianBlur(img,5)
- cimg = cv2.cvtColor(img,cv2.COLOR_GRAY2BGR)
-
- circles = cv2.HoughCircles(img,cv2.HOUGH_GRADIENT,1,20,
- param1=50,param2=30,minRadius=0,maxRadius=0)
-
- circles = np.uint16(np.around(circles))
- for i in circles[0,:]:
- # draw the outer circle
- cv2.circle(cimg,(i[0],i[1]),i[2],(0,255,0),2)
- # draw the center of the circle
- cv2.circle(cimg,(i[0],i[1]),2,(0,0,255),3)
-
- cv2.imshow('detected circles',cimg)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-Result is shown below:
-
- .. image:: images/houghcircles2.jpg
- :alt: Hough Circles
- :align: center
-
-Additional Resources
-=====================
-
-Exercises
-===========
+++ /dev/null
-.. _PY_Hough_Lines:
-
-Hough Line Transform
-**********************
-
-Goal
-=====
-
-In this chapter,
- * We will understand the concept of Hough Tranform.
- * We will see how to use it detect lines in an image.
- * We will see following functions: **cv2.HoughLines()**, **cv2.HoughLinesP()**
-
-Theory
-========
-Hough Transform is a popular technique to detect any shape, if you can represent that shape in mathematical form. It can detect the shape even if it is broken or distorted a little bit. We will see how it works for a line.
-
-A line can be represented as :math:`y = mx+c` or in parametric form, as :math:`\rho = x \cos \theta + y \sin \theta` where :math:`\rho` is the perpendicular distance from origin to the line, and :math:`\theta` is the angle formed by this perpendicular line and horizontal axis measured in counter-clockwise ( That direction varies on how you represent the coordinate system. This representation is used in OpenCV). Check below image:
-
- .. image:: images/houghlines1.svg
- :alt: coordinate system
- :align: center
- :width: 200 pt
- :height: 200 pt
-
-So if line is passing below the origin, it will have a positive rho and angle less than 180. If it is going above the origin, instead of taking angle greater than 180, angle is taken less than 180, and rho is taken negative. Any vertical line will have 0 degree and horizontal lines will have 90 degree.
-
-Now let's see how Hough Transform works for lines. Any line can be represented in these two terms, :math:`(\rho, \theta)`. So first it creates a 2D array or accumulator (to hold values of two parameters) and it is set to 0 initially. Let rows denote the :math:`\rho` and columns denote the :math:`\theta`. Size of array depends on the accuracy you need. Suppose you want the accuracy of angles to be 1 degree, you need 180 columns. For :math:`\rho`, the maximum distance possible is the diagonal length of the image. So taking one pixel accuracy, number of rows can be diagonal length of the image.
-
-Consider a 100x100 image with a horizontal line at the middle. Take the first point of the line. You know its (x,y) values. Now in the line equation, put the values :math:`\theta = 0,1,2,....,180` and check the :math:`\rho` you get. For every :math:`(\rho, \theta)` pair, you increment value by one in our accumulator in its corresponding :math:`(\rho, \theta)` cells. So now in accumulator, the cell (50,90) = 1 along with some other cells.
-
-Now take the second point on the line. Do the same as above. Increment the the values in the cells corresponding to :math:`(\rho, \theta)` you got. This time, the cell (50,90) = 2. What you actually do is voting the :math:`(\rho, \theta)` values. You continue this process for every point on the line. At each point, the cell (50,90) will be incremented or voted up, while other cells may or may not be voted up. This way, at the end, the cell (50,90) will have maximum votes. So if you search the accumulator for maximum votes, you get the value (50,90) which says, there is a line in this image at distance 50 from origin and at angle 90 degrees. It is well shown in below animation (Image Courtesy: `Amos Storkey <http://homepages.inf.ed.ac.uk/amos/hough.html>`_ )
-
- .. image:: images/houghlinesdemo.gif
- :alt: Hough Transform Demo
- :align: center
-
-
-This is how hough transform for lines works. It is simple, and may be you can implement it using Numpy on your own. Below is an image which shows the accumulator. Bright spots at some locations denotes they are the parameters of possible lines in the image. (Image courtesy: `Wikipedia <http://en.wikipedia.org/wiki/Hough_transform>`_ )
-
- .. image:: images/houghlines2.jpg
- :alt: Hough Transform accumulator
- :align: center
-
-Hough Tranform in OpenCV
-=========================
-
-Everything explained above is encapsulated in the OpenCV function, **cv2.HoughLines()**. It simply returns an array of :math:`(\rho, \theta)` values. :math:`\rho` is measured in pixels and :math:`\theta` is measured in radians. First parameter, Input image should be a binary image, so apply threshold or use canny edge detection before finding applying hough transform. Second and third parameters are :math:`\rho` and :math:`\theta` accuracies respectively. Fourth argument is the `threshold`, which means minimum vote it should get for it to be considered as a line. Remember, number of votes depend upon number of points on the line. So it represents the minimum length of line that should be detected.
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('dave.jpg')
- gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
- edges = cv2.Canny(gray,50,150,apertureSize = 3)
-
- lines = cv2.HoughLines(edges,1,np.pi/180,200)
- for rho,theta in lines[0]:
- a = np.cos(theta)
- b = np.sin(theta)
- x0 = a*rho
- y0 = b*rho
- x1 = int(x0 + 1000*(-b))
- y1 = int(y0 + 1000*(a))
- x2 = int(x0 - 1000*(-b))
- y2 = int(y0 - 1000*(a))
-
- cv2.line(img,(x1,y1),(x2,y2),(0,0,255),2)
-
- cv2.imwrite('houghlines3.jpg',img)
-
-Check the results below:
-
- .. image:: images/houghlines3.jpg
- :alt: Hough Transform Line Detection
- :align: center
-
-Probabilistic Hough Transform
-==============================
-
-In the hough transform, you can see that even for a line with two arguments, it takes a lot of computation. Probabilistic Hough Transform is an optimization of Hough Transform we saw. It doesn't take all the points into consideration, instead take only a random subset of points and that is sufficient for line detection. Just we have to decrease the threshold. See below image which compare Hough Transform and Probabilistic Hough Transform in hough space. (Image Courtesy : `Franck Bettinger's home page <http://phdfb1.free.fr/robot/mscthesis/node14.html>`_
-
- .. image:: images/houghlines4.png
- :alt: Hough Transform and Probabilistic Hough Transform
- :align: center
-
-OpenCV implementation is based on Robust Detection of Lines Using the Progressive Probabilistic Hough Transform by Matas, J. and Galambos, C. and Kittler, J.V.. The function used is **cv2.HoughLinesP()**. It has two new arguments.
- * **minLineLength** - Minimum length of line. Line segments shorter than this are rejected.
- * **maxLineGap** - Maximum allowed gap between line segments to treat them as single line.
-
-Best thing is that, it directly returns the two endpoints of lines. In previous case, you got only the parameters of lines, and you had to find all the points. Here, everything is direct and simple.
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('dave.jpg')
- gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
- edges = cv2.Canny(gray,50,150,apertureSize = 3)
- minLineLength = 100
- maxLineGap = 10
- lines = cv2.HoughLinesP(edges,1,np.pi/180,100,minLineLength,maxLineGap)
- for x1,y1,x2,y2 in lines[0]:
- cv2.line(img,(x1,y1),(x2,y2),(0,255,0),2)
-
- cv2.imwrite('houghlines5.jpg',img)
-
-See the results below:
-
- .. image:: images/houghlines5.jpg
- :alt: Probabilistic Hough Transform
- :align: center
-
-Additional Resources
-=======================
-#. `Hough Transform on Wikipedia <http://en.wikipedia.org/wiki/Hough_transform>`_
-
-
-Exercises
-===========
+++ /dev/null
-.. _Morphological_Ops:
-
-Morphological Transformations
-*******************************
-
-Goal
-======
-
-In this chapter,
- * We will learn different morphological operations like Erosion, Dilation, Opening, Closing etc.
- * We will see different functions like : **cv2.erode()**, **cv2.dilate()**, **cv2.morphologyEx()** etc.
-
-Theory
-========
-
-Morphological transformations are some simple operations based on the image shape. It is normally performed on binary images. It needs two inputs, one is our original image, second one is called **structuring element** or **kernel** which decides the nature of operation. Two basic morphological operators are Erosion and Dilation. Then its variant forms like Opening, Closing, Gradient etc also comes into play. We will see them one-by-one with help of following image:
-
- .. image:: images/j.png
- :alt: Input Image
- :align: center
-
-1. Erosion
---------------
-The basic idea of erosion is just like soil erosion only, it erodes away the boundaries of foreground object (Always try to keep foreground in white). So what it does? The kernel slides through the image (as in 2D convolution). A pixel in the original image (either 1 or 0) will be considered 1 only if all the pixels under the kernel is 1, otherwise it is eroded (made to zero).
-
-So what happends is that, all the pixels near boundary will be discarded depending upon the size of kernel. So the thickness or size of the foreground object decreases or simply white region decreases in the image. It is useful for removing small white noises (as we have seen in colorspace chapter), detach two connected objects etc.
-
-Here, as an example, I would use a 5x5 kernel with full of ones. Let's see it how it works:
-::
-
- import cv2
- import numpy as np
-
- img = cv2.imread('j.png',0)
- kernel = np.ones((5,5),np.uint8)
- erosion = cv2.erode(img,kernel,iterations = 1)
-
-Result:
-
- .. image:: images/erosion.png
- :alt: Erosion
- :align: center
-
-2. Dilation
---------------
-It is just opposite of erosion. Here, a pixel element is '1' if atleast one pixel under the kernel is '1'. So it increases the white region in the image or size of foreground object increases. Normally, in cases like noise removal, erosion is followed by dilation. Because, erosion removes white noises, but it also shrinks our object. So we dilate it. Since noise is gone, they won't come back, but our object area increases. It is also useful in joining broken parts of an object.
-::
-
- dilation = cv2.dilate(img,kernel,iterations = 1)
-
-Result:
-
- .. image:: images/dilation.png
- :alt: Dilation
- :align: center
-
-3. Opening
---------------
-Opening is just another name of **erosion followed by dilation**. It is useful in removing noise, as we explained above. Here we use the function, **cv2.morphologyEx()**
-::
-
- opening = cv2.morphologyEx(img, cv2.MORPH_OPEN, kernel)
-
-Result:
-
- .. image:: images/opening.png
- :alt: Opening
- :align: center
-
-4. Closing
---------------
-Closing is reverse of Opening, **Dilation followed by Erosion**. It is useful in closing small holes inside the foreground objects, or small black points on the object.
-::
-
- closing = cv2.morphologyEx(img, cv2.MORPH_CLOSE, kernel)
-
-Result:
-
- .. image:: images/closing.png
- :alt: Closing
- :align: center
-
-5. Morphological Gradient
------------------------------
-It is the difference between dilation and erosion of an image.
-
-The result will look like the outline of the object.
-::
-
- gradient = cv2.morphologyEx(img, cv2.MORPH_GRADIENT, kernel)
-
-Result:
-
- .. image:: images/gradient.png
- :alt: Gradient
- :align: center
-
-6. Top Hat
---------------
-It is the difference between input image and Opening of the image. Below example is done for a 9x9 kernel.
-::
-
- tophat = cv2.morphologyEx(img, cv2.MORPH_TOPHAT, kernel)
-
-Result:
-
- .. image:: images/tophat.png
- :alt: Top Hat
- :align: center
-
-7. Black Hat
---------------
-It is the difference between the closing of the input image and input image.
-::
-
- blackhat = cv2.morphologyEx(img, cv2.MORPH_BLACKHAT, kernel)
-
-Result:
-
- .. image:: images/blackhat.png
- :alt: Black Hat
- :align: center
-
-Structuring Element
-========================
-
-We manually created a structuring elements in the previous examples with help of Numpy. It is rectangular shape. But in some cases, you may need elliptical/circular shaped kernels. So for this purpose, OpenCV has a function, **cv2.getStructuringElement()**. You just pass the shape and size of the kernel, you get the desired kernel.
-
-.. code-block:: python
-
- # Rectangular Kernel
- >>> cv2.getStructuringElement(cv2.MORPH_RECT,(5,5))
- array([[1, 1, 1, 1, 1],
- [1, 1, 1, 1, 1],
- [1, 1, 1, 1, 1],
- [1, 1, 1, 1, 1],
- [1, 1, 1, 1, 1]], dtype=uint8)
-
- # Elliptical Kernel
- >>> cv2.getStructuringElement(cv2.MORPH_ELLIPSE,(5,5))
- array([[0, 0, 1, 0, 0],
- [1, 1, 1, 1, 1],
- [1, 1, 1, 1, 1],
- [1, 1, 1, 1, 1],
- [0, 0, 1, 0, 0]], dtype=uint8)
-
- # Cross-shaped Kernel
- >>> cv2.getStructuringElement(cv2.MORPH_CROSS,(5,5))
- array([[0, 0, 1, 0, 0],
- [0, 0, 1, 0, 0],
- [1, 1, 1, 1, 1],
- [0, 0, 1, 0, 0],
- [0, 0, 1, 0, 0]], dtype=uint8)
-
-Additional Resources
-=======================
-
-#. `Morphological Operations <http://homepages.inf.ed.ac.uk/rbf/HIPR2/morops.htm>`_ at HIPR2
-
-Exercises
-==========
+++ /dev/null
-.. _PY_Pyramids:
-
-Image Pyramids
-***************
-
-Goal
-======
-In this chapter,
- * We will learn about Image Pyramids
- * We will use Image pyramids to create a new fruit, "Orapple"
- * We will see these functions: **cv2.pyrUp()**, **cv2.pyrDown()**
-
-Theory
-=========
-
-Normally, we used to work with an image of constant size. But in some occassions, we need to work with images of different resolution of the same image. For example, while searching for something in an image, like face, we are not sure at what size the object will be present in the image. In that case, we will need to create a set of images with different resolution and search for object in all the images. These set of images with different resolution are called Image Pyramids (because when they are kept in a stack with biggest image at bottom and smallest image at top look like a pyramid).
-
-There are two kinds of Image Pyramids. 1) Gaussian Pyramid and 2) Laplacian Pyramids
-
-Higher level (Low resolution) in a Gaussian Pyramid is formed by removing consecutive rows and columns in Lower level (higher resolution) image. Then each pixel in higher level is formed by the contribution from 5 pixels in underlying level with gaussian weights. By doing so, a :math:`M \times N` image becomes :math:`M/2 \times N/2` image. So area reduces to one-fourth of original area. It is called an Octave. The same pattern continues as we go upper in pyramid (ie, resolution decreases). Similarly while expanding, area becomes 4 times in each level. We can find Gaussian pyramids using **cv2.pyrDown()** and **cv2.pyrUp()** functions.
-::
-
- img = cv2.imread('messi5.jpg')
- lower_reso = cv2.pyrDown(higher_reso)
-
-Below is the 4 levels in an image pyramid.
-
- .. image:: images/messipyr.jpg
- :alt: Gaussian Pyramid
- :align: center
-
-Now you can go down the image pyramid with **cv2.pyrUp()** function.
-::
-
- higher_reso2 = cv2.pyrUp(lower_reso)
-
-Remember, `higher_reso2` is not equal to `higher_reso`, because once you decrease the resolution, you loose the information. Below image is 3 level down the pyramid created from smallest image in previous case. Compare it with original image:
-
- .. image:: images/messiup.jpg
- :alt: Gaussian Pyramid
- :align: center
-
-Laplacian Pyramids are formed from the Gaussian Pyramids. There is no exclusive function for that. Laplacian pyramid images are like edge images only. Most of its elements are zeros. They are used in image compression. A level in Laplacian Pyramid is formed by the difference between that level in Gaussian Pyramid and expanded version of its upper level in Gaussian Pyramid. The three levels of a Laplacian level will look like below (contrast is adjusted to enhance the contents):
-
- .. image:: images/lap.jpg
- :alt: Laplacian Pyramid
- :align: center
-
-Image Blending using Pyramids
-==============================
-
-One application of Pyramids is Image Blending. For example, in image stitching, you will need to stack two images together, but it may not look good due to discontinuities between images. In that case, image blending with Pyramids gives you seamless blending without leaving much data in the images. One classical example of this is the blending of two fruits, Orange and Apple. See the result now itself to understand what I am saying:
-
- .. image:: images/orapple.jpg
- :alt: Pyramid Blending
- :align: center
-
-Please check first reference in additional resources, it has full diagramatic details on image blending, Laplacian Pyramids etc. Simply it is done as follows:
-
- #. Load the two images of apple and orange
- #. Find the Gaussian Pyramids for apple and orange (in this particular example, number of levels is 6)
- #. From Gaussian Pyramids, find their Laplacian Pyramids
- #. Now join the left half of apple and right half of orange in each levels of Laplacian Pyramids
- #. Finally from this joint image pyramids, reconstruct the original image.
-
-Below is the full code. (For sake of simplicity, each step is done separately which may take more memory. You can optimize it if you want so).
-::
-
- import cv2
- import numpy as np,sys
-
- A = cv2.imread('apple.jpg')
- B = cv2.imread('orange.jpg')
-
- # generate Gaussian pyramid for A
- G = A.copy()
- gpA = [G]
- for i in xrange(6):
- G = cv2.pyrDown(G)
- gpA.append(G)
-
- # generate Gaussian pyramid for B
- G = B.copy()
- gpB = [G]
- for i in xrange(6):
- G = cv2.pyrDown(G)
- gpB.append(G)
-
- # generate Laplacian Pyramid for A
- lpA = [gpA[5]]
- for i in xrange(5,0,-1):
- GE = cv2.pyrUp(gpA[i])
- L = cv2.subtract(gpA[i-1],GE)
- lpA.append(L)
-
- # generate Laplacian Pyramid for B
- lpB = [gpB[5]]
- for i in xrange(5,0,-1):
- GE = cv2.pyrUp(gpB[i])
- L = cv2.subtract(gpB[i-1],GE)
- lpB.append(L)
-
- # Now add left and right halves of images in each level
- LS = []
- for la,lb in zip(lpA,lpB):
- rows,cols,dpt = la.shape
- ls = np.hstack((la[:,0:cols/2], lb[:,cols/2:]))
- LS.append(ls)
-
- # now reconstruct
- ls_ = LS[0]
- for i in xrange(1,6):
- ls_ = cv2.pyrUp(ls_)
- ls_ = cv2.add(ls_, LS[i])
-
- # image with direct connecting each half
- real = np.hstack((A[:,:cols/2],B[:,cols/2:]))
-
- cv2.imwrite('Pyramid_blending2.jpg',ls_)
- cv2.imwrite('Direct_blending.jpg',real)
-
-Additional Resources
-=========================
-
-#. `Image Blending <http://pages.cs.wisc.edu/~csverma/CS766_09/ImageMosaic/imagemosaic.html>`_
-
-Exercises
-==========
+++ /dev/null
-.. _PY_Table-Of-Content-ImgProc:
-
-Image Processing in OpenCV
------------------------------------------------------------
-
-* :ref:`Converting_colorspaces`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |imgproc_1| Learn to change images between different color spaces.
-
- Plus learn to track a colored object in a video.
- =========== ===================================================================
-
- .. |imgproc_1| image:: images/colorspace.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Geometric_Transformations`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ===================================================================
- |imgproc_gt| Learn to apply different geometric transformations to images like rotation, translation etc.
-
- ============ ===================================================================
-
- .. |imgproc_gt| image:: images/geometric.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Thresholding`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |imgproc_2| Learn to convert images to binary images using global thresholding,
- Adaptive thresholding, Otsu's binarization etc
-
- =========== ===================================================================
-
- .. |imgproc_2| image:: images/thresh.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Filtering`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |imgproc_4| Learn to blur the images, filter the images with custom kernels etc.
-
- =========== ===================================================================
-
- .. |imgproc_4| image:: images/blurring.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Morphological_Ops`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ===================================================================
- |imgproc_12| Learn about morphological transformations like Erosion, Dilation, Opening, Closing etc
-
- ============ ===================================================================
-
- .. |imgproc_12| image:: images/morphology.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Gradients`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |imgproc_5| Learn to find image gradients, edges etc.
-
- =========== ===================================================================
-
- .. |imgproc_5| image:: images/gradient.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Canny`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |imgproc_8| Learn to find edges with Canny Edge Detection
-
- =========== ===================================================================
-
- .. |imgproc_8| image:: images/canny.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`PY_Pyramids`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ===================================================================
- |imgproc_14| Learn about image pyramids and how to use them for image blending
-
- ============ ===================================================================
-
- .. |imgproc_14| image:: images/pyramid.png
- :height: 90pt
- :width: 90pt
-
-* :ref:`Table-Of-Content-Contours`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |imgproc_3| All about Contours in OpenCV
-
- =========== ===================================================================
-
- .. |imgproc_3| image:: images/contours.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Table-Of-Content-Histograms`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |imgproc_6| All about histograms in OpenCV
-
- =========== ===================================================================
-
- .. |imgproc_6| image:: images/histogram.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Table-Of-Content-Transforms`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |imgproc_7| Meet different Image Transforms in OpenCV like Fourier Transform, Cosine Transform etc.
-
- =========== ===================================================================
-
- .. |imgproc_7| image:: images/transforms.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`PY_Template_Matching`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |imgproc_9| Learn to search for an object in an image using Template Matching
-
- =========== ===================================================================
-
- .. |imgproc_9| image:: images/template.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`PY_Hough_Lines`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ===================================================================
- |imgproc_10| Learn to detect lines in an image
-
- ============ ===================================================================
-
- .. |imgproc_10| image:: images/houghlines.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Hough_Circles`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ===================================================================
- |imgproc_11| Learn to detect circles in an image
-
- ============ ===================================================================
-
- .. |imgproc_11| image:: images/houghcircles.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Watershed`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ===================================================================
- |imgproc_13| Learn to segment images with watershed segmentation
-
- ============ ===================================================================
-
- .. |imgproc_13| image:: images/watershed.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`grabcut`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ===================================================================
- |imgproc_15| Learn to extract foreground with GrabCut algorithm
-
- ============ ===================================================================
-
- .. |imgproc_15| image:: images/grabcut.jpg
- :height: 90pt
- :width: 90pt
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_colorspaces/py_colorspaces
- ../py_thresholding/py_thresholding
- ../py_geometric_transformations/py_geometric_transformations
- ../py_filtering/py_filtering
- ../py_morphological_ops/py_morphological_ops
- ../py_gradients/py_gradients
- ../py_canny/py_canny
- ../py_pyramids/py_pyramids
- ../py_contours/py_table_of_contents_contours/py_table_of_contents_contours
- ../py_histograms/py_table_of_contents_histograms/py_table_of_contents_histograms
- ../py_transforms/py_table_of_contents_transforms/py_table_of_contents_transforms
- ../py_template_matching/py_template_matching
- ../py_houghlines/py_houghlines
- ../py_houghcircles/py_houghcircles
- ../py_watershed/py_watershed
- ../py_grabcut/py_grabcut
+++ /dev/null
-.. _PY_Template_Matching:
-
-Template Matching
-**********************
-
-Goals
-=========
-
-In this chapter, you will learn
- * To find objects in an image using Template Matching
- * You will see these functions : **cv2.matchTemplate()**, **cv2.minMaxLoc()**
-
-Theory
-========
-
-Template Matching is a method for searching and finding the location of a template image in a larger image. OpenCV comes with a function **cv2.matchTemplate()** for this purpose. It simply slides the template image over the input image (as in 2D convolution) and compares the template and patch of input image under the template image. Several comparison methods are implemented in OpenCV. (You can check docs for more details). It returns a grayscale image, where each pixel denotes how much does the neighbourhood of that pixel match with template.
-
-If input image is of size `(WxH)` and template image is of size `(wxh)`, output image will have a size of `(W-w+1, H-h+1)`. Once you got the result, you can use **cv2.minMaxLoc()** function to find where is the maximum/minimum value. Take it as the top-left corner of rectangle and take `(w,h)` as width and height of the rectangle. That rectangle is your region of template.
-
-.. note:: If you are using ``cv2.TM_SQDIFF`` as comparison method, minimum value gives the best match.
-
-Template Matching in OpenCV
-============================
-
-Here, as an example, we will search for Messi's face in his photo. So I created a template as below:
-
- .. image:: images/messi_face.jpg
- :alt: Template Image
- :align: center
-
-We will try all the comparison methods so that we can see how their results look like:
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('messi5.jpg',0)
- img2 = img.copy()
- template = cv2.imread('template.jpg',0)
- w, h = template.shape[::-1]
-
- # All the 6 methods for comparison in a list
- methods = ['cv2.TM_CCOEFF', 'cv2.TM_CCOEFF_NORMED', 'cv2.TM_CCORR',
- 'cv2.TM_CCORR_NORMED', 'cv2.TM_SQDIFF', 'cv2.TM_SQDIFF_NORMED']
-
- for meth in methods:
- img = img2.copy()
- method = eval(meth)
-
- # Apply template Matching
- res = cv2.matchTemplate(img,template,method)
- min_val, max_val, min_loc, max_loc = cv2.minMaxLoc(res)
-
- # If the method is TM_SQDIFF or TM_SQDIFF_NORMED, take minimum
- if method in [cv2.TM_SQDIFF, cv2.TM_SQDIFF_NORMED]:
- top_left = min_loc
- else:
- top_left = max_loc
- bottom_right = (top_left[0] + w, top_left[1] + h)
-
- cv2.rectangle(img,top_left, bottom_right, 255, 2)
-
- plt.subplot(121),plt.imshow(res,cmap = 'gray')
- plt.title('Matching Result'), plt.xticks([]), plt.yticks([])
- plt.subplot(122),plt.imshow(img,cmap = 'gray')
- plt.title('Detected Point'), plt.xticks([]), plt.yticks([])
- plt.suptitle(meth)
-
- plt.show()
-
-See the results below:
-
- * cv2.TM_CCOEFF
-
- .. image:: images/template_ccoeff_1.jpg
- :alt: Template Image
- :align: center
-
- * cv2.TM_CCOEFF_NORMED
-
- .. image:: images/template_ccoeffn_2.jpg
- :alt: Template Image
- :align: center
-
- * cv2.TM_CCORR
-
- .. image:: images/template_ccorr_3.jpg
- :alt: Template Image
- :align: center
-
- * cv2.TM_CCORR_NORMED
-
- .. image:: images/template_ccorrn_4.jpg
- :alt: Template Image
- :align: center
-
- * cv2.TM_SQDIFF
-
- .. image:: images/template_sqdiff_5.jpg
- :alt: Template Image
- :align: center
-
- * cv2.TM_SQDIFF_NORMED
-
- .. image:: images/template_sqdiffn_6.jpg
- :alt: Template Image
- :align: center
-
-You can see that the result using **cv2.TM_CCORR** is not good as we expected.
-
-Template Matching with Multiple Objects
-==========================================
-
-In the previous section, we searched image for Messi's face, which occurs only once in the image. Suppose you are searching for an object which has multiple occurances, **cv2.minMaxLoc()** won't give you all the locations. In that case, we will use thresholding. So in this example, we will use a screenshot of the famous game **Mario** and we will find the coins in it.
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img_rgb = cv2.imread('mario.png')
- img_gray = cv2.cvtColor(img_rgb, cv2.COLOR_BGR2GRAY)
- template = cv2.imread('mario_coin.png',0)
- w, h = template.shape[::-1]
-
- res = cv2.matchTemplate(img_gray,template,cv2.TM_CCOEFF_NORMED)
- threshold = 0.8
- loc = np.where( res >= threshold)
- for pt in zip(*loc[::-1]):
- cv2.rectangle(img_rgb, pt, (pt[0] + w, pt[1] + h), (0,0,255), 2)
-
- cv2.imwrite('res.png',img_rgb)
-
-Result:
-
- .. image:: images/res_mario.jpg
- :alt: Template Matching
- :align: center
-
-Additional Resources
-=====================
-
-Exercises
-============
+++ /dev/null
-.. _Thresholding:
-
-Image Thresholding
-********************
-
-Goal
-======
-
-.. container:: enumeratevisibleitemswithsquare
-
- * In this tutorial, you will learn Simple thresholding, Adaptive thresholding, Otsu's thresholding etc.
- * You will learn these functions : **cv2.threshold**, **cv2.adaptiveThreshold** etc.
-
-Simple Thresholding
-=====================
-
-Here, the matter is straight forward. If pixel value is greater than a threshold value, it is assigned one value (may be white), else it is assigned another value (may be black). The function used is **cv2.threshold**. First argument is the source image, which **should be a grayscale image**. Second argument is the threshold value which is used to classify the pixel values. Third argument is the maxVal which represents the value to be given if pixel value is more than (sometimes less than) the threshold value. OpenCV provides different styles of thresholding and it is decided by the fourth parameter of the function. Different types are:
-
- * cv2.THRESH_BINARY
- * cv2.THRESH_BINARY_INV
- * cv2.THRESH_TRUNC
- * cv2.THRESH_TOZERO
- * cv2.THRESH_TOZERO_INV
-
-Documentation clearly explain what each type is meant for. Please check out the documentation.
-
-Two outputs are obtained. First one is a **retval** which will be explained later. Second output is our **thresholded image**.
-
-Code :
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('gradient.png',0)
- ret,thresh1 = cv2.threshold(img,127,255,cv2.THRESH_BINARY)
- ret,thresh2 = cv2.threshold(img,127,255,cv2.THRESH_BINARY_INV)
- ret,thresh3 = cv2.threshold(img,127,255,cv2.THRESH_TRUNC)
- ret,thresh4 = cv2.threshold(img,127,255,cv2.THRESH_TOZERO)
- ret,thresh5 = cv2.threshold(img,127,255,cv2.THRESH_TOZERO_INV)
-
- titles = ['Original Image','BINARY','BINARY_INV','TRUNC','TOZERO','TOZERO_INV']
- images = [img, thresh1, thresh2, thresh3, thresh4, thresh5]
-
- for i in xrange(6):
- plt.subplot(2,3,i+1),plt.imshow(images[i],'gray')
- plt.title(titles[i])
- plt.xticks([]),plt.yticks([])
-
- plt.show()
-
-.. note:: To plot multiple images, we have used `plt.subplot()` function. Please checkout Matplotlib docs for more details.
-
-Result is given below :
-
- .. image:: images/threshold.jpg
- :alt: Simple Thresholding
- :align: center
-
-Adaptive Thresholding
-========================
-
-In the previous section, we used a global value as threshold value. But it may not be good in all the conditions where image has different lighting conditions in different areas. In that case, we go for adaptive thresholding. In this, the algorithm calculate the threshold for a small regions of the image. So we get different thresholds for different regions of the same image and it gives us better results for images with varying illumination.
-
-It has three ‘special’ input params and only one output argument.
-
-**Adaptive Method** - It decides how thresholding value is calculated.
- * cv2.ADAPTIVE_THRESH_MEAN_C : threshold value is the mean of neighbourhood area.
- * cv2.ADAPTIVE_THRESH_GAUSSIAN_C : threshold value is the weighted sum of neighbourhood values where weights are a gaussian window.
-
-**Block Size** - It decides the size of neighbourhood area.
-
-**C** - It is just a constant which is subtracted from the mean or weighted mean calculated.
-
-Below piece of code compares global thresholding and adaptive thresholding for an image with varying illumination:
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('dave.jpg',0)
- img = cv2.medianBlur(img,5)
-
- ret,th1 = cv2.threshold(img,127,255,cv2.THRESH_BINARY)
- th2 = cv2.adaptiveThreshold(img,255,cv2.ADAPTIVE_THRESH_MEAN_C,\
- cv2.THRESH_BINARY,11,2)
- th3 = cv2.adaptiveThreshold(img,255,cv2.ADAPTIVE_THRESH_GAUSSIAN_C,\
- cv2.THRESH_BINARY,11,2)
-
- titles = ['Original Image', 'Global Thresholding (v = 127)',
- 'Adaptive Mean Thresholding', 'Adaptive Gaussian Thresholding']
- images = [img, th1, th2, th3]
-
- for i in xrange(4):
- plt.subplot(2,2,i+1),plt.imshow(images[i],'gray')
- plt.title(titles[i])
- plt.xticks([]),plt.yticks([])
- plt.show()
-
-Result :
-
- .. image:: images/ada_threshold.jpg
- :alt: Adaptive Thresholding
- :align: center
-
-Otsu’s Binarization
-=====================
-
-In the first section, I told you there is a second parameter **retVal**. Its use comes when we go for Otsu’s Binarization. So what is it?
-
-In global thresholding, we used an arbitrary value for threshold value, right? So, how can we know a value we selected is good or not? Answer is, trial and error method. But consider a **bimodal image** (*In simple words, bimodal image is an image whose histogram has two peaks*). For that image, we can approximately take a value in the middle of those peaks as threshold value, right ? That is what Otsu binarization does. So in simple words, it automatically calculates a threshold value from image histogram for a bimodal image. (For images which are not bimodal, binarization won’t be accurate.)
-
-For this, our cv2.threshold() function is used, but pass an extra flag, `cv2.THRESH_OTSU`. **For threshold value, simply pass zero**. Then the algorithm finds the optimal threshold value and returns you as the second output, ``retVal``. If Otsu thresholding is not used, retVal is same as the threshold value you used.
-
-Check out below example. Input image is a noisy image. In first case, I applied global thresholding for a value of 127. In second case, I applied Otsu’s thresholding directly. In third case, I filtered image with a 5x5 gaussian kernel to remove the noise, then applied Otsu thresholding. See how noise filtering improves the result.
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('noisy2.png',0)
-
- # global thresholding
- ret1,th1 = cv2.threshold(img,127,255,cv2.THRESH_BINARY)
-
- # Otsu's thresholding
- ret2,th2 = cv2.threshold(img,0,255,cv2.THRESH_BINARY+cv2.THRESH_OTSU)
-
- # Otsu's thresholding after Gaussian filtering
- blur = cv2.GaussianBlur(img,(5,5),0)
- ret3,th3 = cv2.threshold(blur,0,255,cv2.THRESH_BINARY+cv2.THRESH_OTSU)
-
- # plot all the images and their histograms
- images = [img, 0, th1,
- img, 0, th2,
- blur, 0, th3]
- titles = ['Original Noisy Image','Histogram','Global Thresholding (v=127)',
- 'Original Noisy Image','Histogram',"Otsu's Thresholding",
- 'Gaussian filtered Image','Histogram',"Otsu's Thresholding"]
-
- for i in xrange(3):
- plt.subplot(3,3,i*3+1),plt.imshow(images[i*3],'gray')
- plt.title(titles[i*3]), plt.xticks([]), plt.yticks([])
- plt.subplot(3,3,i*3+2),plt.hist(images[i*3].ravel(),256)
- plt.title(titles[i*3+1]), plt.xticks([]), plt.yticks([])
- plt.subplot(3,3,i*3+3),plt.imshow(images[i*3+2],'gray')
- plt.title(titles[i*3+2]), plt.xticks([]), plt.yticks([])
- plt.show()
-
-Result :
-
- .. image:: images/otsu.jpg
- :alt: Otsu's Thresholding
- :align: center
-
-How Otsu's Binarization Works?
-----------------------------------
-
-This section demonstrates a Python implementation of Otsu's binarization to show how it works actually. If you are not interested, you can skip this.
-
-Since we are working with bimodal images, Otsu's algorithm tries to find a threshold value (t) which minimizes the **weighted within-class variance** given by the relation :
-
-.. math::
- \sigma_w^2(t) = q_1(t)\sigma_1^2(t)+q_2(t)\sigma_2^2(t)
-
-where
-
-.. math::
- q_1(t) = \sum_{i=1}^{t} P(i) \quad \& \quad q_1(t) = \sum_{i=t+1}^{I} P(i)
-
- \mu_1(t) = \sum_{i=1}^{t} \frac{iP(i)}{q_1(t)} \quad \& \quad \mu_2(t) = \sum_{i=t+1}^{I} \frac{iP(i)}{q_2(t)}
-
- \sigma_1^2(t) = \sum_{i=1}^{t} [i-\mu_1(t)]^2 \frac{P(i)}{q_1(t)} \quad \& \quad \sigma_2^2(t) = \sum_{i=t+1}^{I} [i-\mu_1(t)]^2 \frac{P(i)}{q_2(t)}
-
-It actually finds a value of t which lies in between two peaks such that variances to both classes are minimum. It can be simply implemented in Python as follows:
-::
-
- img = cv2.imread('noisy2.png',0)
- blur = cv2.GaussianBlur(img,(5,5),0)
-
- # find normalized_histogram, and its cumulative distribution function
- hist = cv2.calcHist([blur],[0],None,[256],[0,256])
- hist_norm = hist.ravel()/hist.max()
- Q = hist_norm.cumsum()
-
- bins = np.arange(256)
-
- fn_min = np.inf
- thresh = -1
-
- for i in xrange(1,256):
- p1,p2 = np.hsplit(hist_norm,[i]) # probabilities
- q1,q2 = Q[i],Q[255]-Q[i] # cum sum of classes
- b1,b2 = np.hsplit(bins,[i]) # weights
-
- # finding means and variances
- m1,m2 = np.sum(p1*b1)/q1, np.sum(p2*b2)/q2
- v1,v2 = np.sum(((b1-m1)**2)*p1)/q1,np.sum(((b2-m2)**2)*p2)/q2
-
- # calculates the minimization function
- fn = v1*q1 + v2*q2
- if fn < fn_min:
- fn_min = fn
- thresh = i
-
- # find otsu's threshold value with OpenCV function
- ret, otsu = cv2.threshold(blur,0,255,cv2.THRESH_BINARY+cv2.THRESH_OTSU)
- print thresh,ret
-
-*(Some of the functions may be new here, but we will cover them in coming chapters)*
-
-Additional Resources
-=====================
-#. Digital Image Processing, Rafael C. Gonzalez
-
-Exercises
-===========
-#. There are some optimizations available for Otsu's binarization. You can search and implement it.
+++ /dev/null
-.. _Fourier_Transform:
-
-Fourier Transform
-*******************
-
-Goal
-======
-
-In this section, we will learn
- * To find the Fourier Transform of images using OpenCV
- * To utilize the FFT functions available in Numpy
- * Some applications of Fourier Transform
- * We will see following functions : **cv2.dft()**, **cv2.idft()** etc
-
-Theory
-========
-
-Fourier Transform is used to analyze the frequency characteristics of various filters. For images, **2D Discrete Fourier Transform (DFT)** is used to find the frequency domain. A fast algorithm called **Fast Fourier Transform (FFT)** is used for calculation of DFT. Details about these can be found in any image processing or signal processing textbooks. Please see `Additional Resources`_ section.
-
-For a sinusoidal signal, :math:`x(t) = A \sin(2 \pi ft)`, we can say :math:`f` is the frequency of signal, and if its frequency domain is taken, we can see a spike at :math:`f`. If signal is sampled to form a discrete signal, we get the same frequency domain, but is periodic in the range :math:`[- \pi, \pi]` or :math:`[0,2\pi]` (or :math:`[0,N]` for N-point DFT). You can consider an image as a signal which is sampled in two directions. So taking fourier transform in both X and Y directions gives you the frequency representation of image.
-
-More intuitively, for the sinusoidal signal, if the amplitude varies so fast in short time, you can say it is a high frequency signal. If it varies slowly, it is a low frequency signal. You can extend the same idea to images. Where does the amplitude varies drastically in images ? At the edge points, or noises. So we can say, edges and noises are high frequency contents in an image. If there is no much changes in amplitude, it is a low frequency component. ( Some links are added to `Additional Resources`_ which explains frequency transform intuitively with examples).
-
-Now we will see how to find the Fourier Transform.
-
-Fourier Transform in Numpy
-============================
-First we will see how to find Fourier Transform using Numpy. Numpy has an FFT package to do this. **np.fft.fft2()** provides us the frequency transform which will be a complex array. Its first argument is the input image, which is grayscale. Second argument is optional which decides the size of output array. If it is greater than size of input image, input image is padded with zeros before calculation of FFT. If it is less than input image, input image will be cropped. If no arguments passed, Output array size will be same as input.
-
-Now once you got the result, zero frequency component (DC component) will be at top left corner. If you want to bring it to center, you need to shift the result by :math:`\frac{N}{2}` in both the directions. This is simply done by the function, **np.fft.fftshift()**. (It is more easier to analyze). Once you found the frequency transform, you can find the magnitude spectrum.
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- img = cv2.imread('messi5.jpg',0)
- f = np.fft.fft2(img)
- fshift = np.fft.fftshift(f)
- magnitude_spectrum = 20*np.log(np.abs(fshift))
-
- plt.subplot(121),plt.imshow(img, cmap = 'gray')
- plt.title('Input Image'), plt.xticks([]), plt.yticks([])
- plt.subplot(122),plt.imshow(magnitude_spectrum, cmap = 'gray')
- plt.title('Magnitude Spectrum'), plt.xticks([]), plt.yticks([])
- plt.show()
-
-Result look like below:
-
- .. image:: images/fft1.jpg
- :alt: Magnitude Spectrum
- :align: center
-
-See, You can see more whiter region at the center showing low frequency content is more.
-
-So you found the frequency transform Now you can do some operations in frequency domain, like high pass filtering and reconstruct the image, ie find inverse DFT. For that you simply remove the low frequencies by masking with a rectangular window of size 60x60. Then apply the inverse shift using **np.fft.ifftshift()** so that DC component again come at the top-left corner. Then find inverse FFT using **np.ifft2()** function. The result, again, will be a complex number. You can take its absolute value.
-::
-
- rows, cols = img.shape
- crow,ccol = rows/2 , cols/2
- fshift[crow-30:crow+30, ccol-30:ccol+30] = 0
- f_ishift = np.fft.ifftshift(fshift)
- img_back = np.fft.ifft2(f_ishift)
- img_back = np.abs(img_back)
-
- plt.subplot(131),plt.imshow(img, cmap = 'gray')
- plt.title('Input Image'), plt.xticks([]), plt.yticks([])
- plt.subplot(132),plt.imshow(img_back, cmap = 'gray')
- plt.title('Image after HPF'), plt.xticks([]), plt.yticks([])
- plt.subplot(133),plt.imshow(img_back)
- plt.title('Result in JET'), plt.xticks([]), plt.yticks([])
-
- plt.show()
-
-Result look like below:
-
- .. image:: images/fft2.jpg
- :alt: High Pass Filtering
- :align: center
-
-The result shows High Pass Filtering is an edge detection operation. This is what we have seen in Image Gradients chapter. This also shows that most of the image data is present in the Low frequency region of the spectrum. Anyway we have seen how to find DFT, IDFT etc in Numpy. Now let's see how to do it in OpenCV.
-
-If you closely watch the result, especially the last image in JET color, you can see some artifacts (One instance I have marked in red arrow). It shows some ripple like structures there, and it is called **ringing effects**. It is caused by the rectangular window we used for masking. This mask is converted to sinc shape which causes this problem. So rectangular windows is not used for filtering. Better option is Gaussian Windows.
-
-Fourier Transform in OpenCV
-============================
-
-OpenCV provides the functions **cv2.dft()** and **cv2.idft()** for this. It returns the same result as previous, but with two channels. First channel will have the real part of the result and second channel will have the imaginary part of the result. The input image should be converted to np.float32 first. We will see how to do it.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('messi5.jpg',0)
-
- dft = cv2.dft(np.float32(img),flags = cv2.DFT_COMPLEX_OUTPUT)
- dft_shift = np.fft.fftshift(dft)
-
- magnitude_spectrum = 20*np.log(cv2.magnitude(dft_shift[:,:,0],dft_shift[:,:,1]))
-
- plt.subplot(121),plt.imshow(img, cmap = 'gray')
- plt.title('Input Image'), plt.xticks([]), plt.yticks([])
- plt.subplot(122),plt.imshow(magnitude_spectrum, cmap = 'gray')
- plt.title('Magnitude Spectrum'), plt.xticks([]), plt.yticks([])
- plt.show()
-
-.. note:: You can also use **cv2.cartToPolar()** which returns both magnitude and phase in a single shot
-
-So, now we have to do inverse DFT. In previous session, we created a HPF, this time we will see how to remove high frequency contents in the image, ie we apply LPF to image. It actually blurs the image. For this, we create a mask first with high value (1) at low frequencies, ie we pass the LF content, and 0 at HF region.
-::
-
- rows, cols = img.shape
- crow,ccol = rows/2 , cols/2
-
- # create a mask first, center square is 1, remaining all zeros
- mask = np.zeros((rows,cols,2),np.uint8)
- mask[crow-30:crow+30, ccol-30:ccol+30] = 1
-
- # apply mask and inverse DFT
- fshift = dft_shift*mask
- f_ishift = np.fft.ifftshift(fshift)
- img_back = cv2.idft(f_ishift)
- img_back = cv2.magnitude(img_back[:,:,0],img_back[:,:,1])
-
- plt.subplot(121),plt.imshow(img, cmap = 'gray')
- plt.title('Input Image'), plt.xticks([]), plt.yticks([])
- plt.subplot(122),plt.imshow(img_back, cmap = 'gray')
- plt.title('Magnitude Spectrum'), plt.xticks([]), plt.yticks([])
- plt.show()
-
-See the result:
-
- .. image:: images/fft4.jpg
- :alt: Magnitude Spectrum
- :align: center
-
-.. note:: As usual, OpenCV functions **cv2.dft()** and **cv2.idft()** are faster than Numpy counterparts. But Numpy functions are more user-friendly. For more details about performance issues, see below section.
-
-Performance Optimization of DFT
-==================================
-
-Performance of DFT calculation is better for some array size. It is fastest when array size is power of two. The arrays whose size is a product of 2’s, 3’s, and 5’s are also processed quite efficiently. So if you are worried about the performance of your code, you can modify the size of the array to any optimal size (by padding zeros) before finding DFT. For OpenCV, you have to manually pad zeros. But for Numpy, you specify the new size of FFT calculation, and it will automatically pad zeros for you.
-
-So how do we find this optimal size ? OpenCV provides a function, **cv2.getOptimalDFTSize()** for this. It is applicable to both **cv2.dft()** and **np.fft.fft2()**. Let's check their performance using IPython magic command ``%timeit``.
-::
-
- In [16]: img = cv2.imread('messi5.jpg',0)
- In [17]: rows,cols = img.shape
- In [18]: print rows,cols
- 342 548
-
- In [19]: nrows = cv2.getOptimalDFTSize(rows)
- In [20]: ncols = cv2.getOptimalDFTSize(cols)
- In [21]: print nrows, ncols
- 360 576
-
-See, the size (342,548) is modified to (360, 576). Now let's pad it with zeros (for OpenCV) and find their DFT calculation performance. You can do it by creating a new big zero array and copy the data to it, or use **cv2.copyMakeBorder()**.
-::
-
- nimg = np.zeros((nrows,ncols))
- nimg[:rows,:cols] = img
-
-OR:
-::
-
- right = ncols - cols
- bottom = nrows - rows
- bordertype = cv2.BORDER_CONSTANT #just to avoid line breakup in PDF file
- nimg = cv2.copyMakeBorder(img,0,bottom,0,right,bordertype, value = 0)
-
-Now we calculate the DFT performance comparison of Numpy function:
-::
-
- In [22]: %timeit fft1 = np.fft.fft2(img)
- 10 loops, best of 3: 40.9 ms per loop
- In [23]: %timeit fft2 = np.fft.fft2(img,[nrows,ncols])
- 100 loops, best of 3: 10.4 ms per loop
-
-It shows a 4x speedup. Now we will try the same with OpenCV functions.
-::
-
- In [24]: %timeit dft1= cv2.dft(np.float32(img),flags=cv2.DFT_COMPLEX_OUTPUT)
- 100 loops, best of 3: 13.5 ms per loop
- In [27]: %timeit dft2= cv2.dft(np.float32(nimg),flags=cv2.DFT_COMPLEX_OUTPUT)
- 100 loops, best of 3: 3.11 ms per loop
-
-It also shows a 4x speed-up. You can also see that OpenCV functions are around 3x faster than Numpy functions. This can be tested for inverse FFT also, and that is left as an exercise for you.
-
-Why Laplacian is a High Pass Filter?
-=======================================
-
-A similar question was asked in a forum. The question is, why Laplacian is a high pass filter? Why Sobel is a HPF? etc. And the first answer given to it was in terms of Fourier Transform. Just take the fourier transform of Laplacian for some higher size of FFT. Analyze it:
-::
-
- import cv2
- import numpy as np
- from matplotlib import pyplot as plt
-
- # simple averaging filter without scaling parameter
- mean_filter = np.ones((3,3))
-
- # creating a guassian filter
- x = cv2.getGaussianKernel(5,10)
- gaussian = x*x.T
-
- # different edge detecting filters
- # scharr in x-direction
- scharr = np.array([[-3, 0, 3],
- [-10,0,10],
- [-3, 0, 3]])
- # sobel in x direction
- sobel_x= np.array([[-1, 0, 1],
- [-2, 0, 2],
- [-1, 0, 1]])
- # sobel in y direction
- sobel_y= np.array([[-1,-2,-1],
- [0, 0, 0],
- [1, 2, 1]])
- # laplacian
- laplacian=np.array([[0, 1, 0],
- [1,-4, 1],
- [0, 1, 0]])
-
- filters = [mean_filter, gaussian, laplacian, sobel_x, sobel_y, scharr]
- filter_name = ['mean_filter', 'gaussian','laplacian', 'sobel_x', \
- 'sobel_y', 'scharr_x']
- fft_filters = [np.fft.fft2(x) for x in filters]
- fft_shift = [np.fft.fftshift(y) for y in fft_filters]
- mag_spectrum = [np.log(np.abs(z)+1) for z in fft_shift]
-
- for i in xrange(6):
- plt.subplot(2,3,i+1),plt.imshow(mag_spectrum[i],cmap = 'gray')
- plt.title(filter_name[i]), plt.xticks([]), plt.yticks([])
-
- plt.show()
-
-See the result:
-
- .. image:: images/fft5.jpg
- :alt: Frequency Spectrum of different Kernels
- :align: center
-
-From image, you can see what frequency region each kernel blocks, and what region it passes. From that information, we can say why each kernel is a HPF or a LPF
-
-Additional Resources
-=====================
-
-1. `An Intuitive Explanation of Fourier Theory <http://cns-alumni.bu.edu/~slehar/fourier/fourier.html>`_ by Steven Lehar
-2. `Fourier Transform <http://homepages.inf.ed.ac.uk/rbf/HIPR2/fourier.htm>`_ at HIPR
-3. `What does frequency domain denote in case of images? <http://dsp.stackexchange.com/q/1637/818>`_
-
-
-Exercises
-============
+++ /dev/null
-.. _Table-Of-Content-Transforms:
-
-Image Transforms in OpenCV
------------------------------------------------------------
-
-* :ref:`Fourier_Transform`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============= ===================================================================
- |transform_1| Learn to find the Fourier Transform of images
-
-
- ============= ===================================================================
-
- .. |transform_1| image:: images/transform_fourier.jpg
- :height: 90pt
- :width: 90pt
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_fourier_transform/py_fourier_transform
+++ /dev/null
-.. _Watershed:
-
-Image Segmentation with Watershed Algorithm
-*********************************************
-
-Goal
-=====
-
-In this chapter,
- * We will learn to use marker-based image segmentation using watershed algorithm
- * We will see: **cv2.watershed()**
-
-Theory
-========
-
-Any grayscale image can be viewed as a topographic surface where high intensity denotes peaks and hills while low intensity denotes valleys. You start filling every isolated valleys (local minima) with different colored water (labels). As the water rises, depending on the peaks (gradients) nearby, water from different valleys, obviously with different colors will start to merge. To avoid that, you build barriers in the locations where water merges. You continue the work of filling water and building barriers until all the peaks are under water. Then the barriers you created gives you the segmentation result. This is the "philosophy" behind the watershed. You can visit the `CMM webpage on watershed <http://cmm.ensmp.fr/~beucher/wtshed.html>`_ to understand it with the help of some animations.
-
-But this approach gives you oversegmented result due to noise or any other irregularities in the image. So OpenCV implemented a marker-based watershed algorithm where you specify which are all valley points are to be merged and which are not. It is an interactive image segmentation. What we do is to give different labels for our object we know. Label the region which we are sure of being the foreground or object with one color (or intensity), label the region which we are sure of being background or non-object with another color and finally the region which we are not sure of anything, label it with 0. That is our marker. Then apply watershed algorithm. Then our marker will be updated with the labels we gave, and the boundaries of objects will have a value of -1.
-
-Code
-========
-
-Below we will see an example on how to use the Distance Transform along with watershed to segment mutually touching objects.
-
-Consider the coins image below, the coins are touching each other. Even if you threshold it, it will be touching each other.
-
- .. image:: images/water_coins.jpg
- :alt: Coins
- :align: center
-
-We start with finding an approximate estimate of the coins. For that, we can use the Otsu's binarization.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('coins.png')
- gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
- ret, thresh = cv2.threshold(gray,0,255,cv2.THRESH_BINARY_INV+cv2.THRESH_OTSU)
-
-Result:
-
- .. image:: images/water_thresh.jpg
- :alt: Thresholding
- :align: center
-
-Now we need to remove any small white noises in the image. For that we can use morphological opening. To remove any small holes in the object, we can use morphological closing. So, now we know for sure that region near to center of objects are foreground and region much away from the object are background. Only region we are not sure is the boundary region of coins.
-
-So we need to extract the area which we are sure they are coins. Erosion removes the boundary pixels. So whatever remaining, we can be sure it is coin. That would work if objects were not touching each other. But since they are touching each other, another good option would be to find the distance transform and apply a proper threshold. Next we need to find the area which we are sure they are not coins. For that, we dilate the result. Dilation increases object boundary to background. This way, we can make sure whatever region in background in result is really a background, since boundary region is removed. See the image below.
-
- .. image:: images/water_fgbg.jpg
- :alt: Foreground and Background
- :align: center
-
-The remaining regions are those which we don't have any idea, whether it is coins or background. Watershed algorithm should find it. These areas are normally around the boundaries of coins where foreground and background meet (Or even two different coins meet). We call it border. It can be obtained from subtracting sure_fg area from sure_bg area.
-::
-
- # noise removal
- kernel = np.ones((3,3),np.uint8)
- opening = cv2.morphologyEx(thresh,cv2.MORPH_OPEN,kernel, iterations = 2)
-
- # sure background area
- sure_bg = cv2.dilate(opening,kernel,iterations=3)
-
- # Finding sure foreground area
- dist_transform = cv2.distanceTransform(opening,cv2.DIST_L2,5)
- ret, sure_fg = cv2.threshold(dist_transform,0.7*dist_transform.max(),255,0)
-
- # Finding unknown region
- sure_fg = np.uint8(sure_fg)
- unknown = cv2.subtract(sure_bg,sure_fg)
-
-See the result. In the thresholded image, we get some regions of coins which we are sure of coins and they are detached now. (In some cases, you may be interested in only foreground segmentation, not in separating the mutually touching objects. In that case, you need not use distance transform, just erosion is sufficient. Erosion is just another method to extract sure foreground area, that's all.)
-
- .. image:: images/water_dt.jpg
- :alt: Distance Transform
- :align: center
-
-Now we know for sure which are region of coins, which are background and all. So we create marker (it is an array of same size as that of original image, but with int32 datatype) and label the regions inside it. The regions we know for sure (whether foreground or background) are labelled with any positive integers, but different integers, and the area we don't know for sure are just left as zero. For this we use **cv2.connectedComponents()**. It labels background of the image with 0, then other objects are labelled with integers starting from 1.
-
-But we know that if background is marked with 0, watershed will consider it as unknown area. So we want to mark it with different integer. Instead, we will mark unknown region, defined by ``unknown``, with 0.
-::
-
- # Marker labelling
- ret, markers = cv2.connectedComponents(sure_fg)
-
- # Add one to all labels so that sure background is not 0, but 1
- markers = markers+1
-
- # Now, mark the region of unknown with zero
- markers[unknown==255] = 0
-
-See the result shown in JET colormap. The dark blue region shows unknown region. Sure coins are colored with different values. Remaining area which are sure background are shown in lighter blue compared to unknown region.
-
- .. image:: images/water_marker.jpg
- :alt: Marker Image
- :align: center
-
-Now our marker is ready. It is time for final step, apply watershed. Then marker image will be modified. The boundary region will be marked with -1.
-::
-
- markers = cv2.watershed(img,markers)
- img[markers == -1] = [255,0,0]
-
-See the result below. For some coins, the region where they touch are segmented properly and for some, they are not.
-
- .. image:: images/water_result.jpg
- :alt: Result
- :align: center
-
-
-Additional Resources
-======================
-
-#. CMM page on `Watershed Tranformation <http://cmm.ensmp.fr/~beucher/wtshed.html>`_
-
-Exercises
-==============
-
-#. OpenCV samples has an interactive sample on watershed segmentation, `watershed.py`. Run it, Enjoy it, then learn it.
+++ /dev/null
-.. _KMeans_Clustering:
-
-K-Means Clustering
-*********************
-
-* :ref:`KMeans_Clustering_Understanding`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |KM_1| Read to get an intuitive understanding of K-Means Clustering
- =========== ===================================================================
-
- .. |KM_1| image:: images/kmeans_begin.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`KMeans_OpenCV`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |KM_2| Now let's try K-Means functions in OpenCV
- =========== ===================================================================
-
- .. |KM_2| image:: images/kmeans_demo.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- py_kmeans_understanding/py_kmeans_understanding
- py_kmeans_opencv/py_kmeans_opencv
+++ /dev/null
-.. _KMeans_OpenCV:
-
-K-Means Clustering in OpenCV
-******************************
-
-Goal
-=======
-
- * Learn to use **cv2.kmeans()** function in OpenCV for data clustering
-
-Understanding Parameters
-==========================
-
-Input parameters
-------------------
- 1. **samples** : It should be of **np.float32** data type, and each feature should be put in a single column.
-
- 2. **nclusters(K)** : Number of clusters required at end
-
- 3. **criteria** : It is the iteration termination criteria. When this criteria is satisfied, algorithm iteration stops. Actually, it should be a tuple of 3 parameters. They are ``( type, max_iter, epsilon )``:
- * 3.a - type of termination criteria : It has 3 flags as below:
- **cv2.TERM_CRITERIA_EPS** - stop the algorithm iteration if specified accuracy, *epsilon*, is reached.
- **cv2.TERM_CRITERIA_MAX_ITER** - stop the algorithm after the specified number of iterations, *max_iter*.
- **cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER** - stop the iteration when any of the above condition is met.
-
- * 3.b - max_iter - An integer specifying maximum number of iterations.
- * 3.c - epsilon - Required accuracy
-
- 4. **attempts** : Flag to specify the number of times the algorithm is executed using different initial labellings. The algorithm returns the labels that yield the best compactness. This compactness is returned as output.
-
- 5. **flags** : This flag is used to specify how initial centers are taken. Normally two flags are used for this : **cv2.KMEANS_PP_CENTERS** and **cv2.KMEANS_RANDOM_CENTERS**.
-
-Output parameters
---------------------
- 1. **compactness** : It is the sum of squared distance from each point to their corresponding centers.
-
- 2. **labels** : This is the label array (same as 'code' in previous article) where each element marked '0', '1'.....
-
- 3. **centers** : This is array of centers of clusters.
-
-Now we will see how to apply K-Means algorithm with three examples.
-
-1. Data with Only One Feature
-===============================
-
-Consider, you have a set of data with only one feature, ie one-dimensional. For eg, we can take our t-shirt problem where you use only height of people to decide the size of t-shirt.
-
-So we start by creating data and plot it in Matplotlib
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- x = np.random.randint(25,100,25)
- y = np.random.randint(175,255,25)
- z = np.hstack((x,y))
- z = z.reshape((50,1))
- z = np.float32(z)
- plt.hist(z,256,[0,256]),plt.show()
-
-So we have 'z' which is an array of size 50, and values ranging from 0 to 255. I have reshaped 'z' to a column vector. It will be more useful when more than one features are present. Then I made data of np.float32 type.
-
-We get following image :
-
- .. image:: images/oc_1d_testdata.png
- :alt: Test Data
- :align: center
-
-Now we apply the KMeans function. Before that we need to specify the `criteria`. My criteria is such that, whenever 10 iterations of algorithm is ran, or an accuracy of ``epsilon = 1.0`` is reached, stop the algorithm and return the answer.
-::
-
- # Define criteria = ( type, max_iter = 10 , epsilon = 1.0 )
- criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 10, 1.0)
-
- # Set flags (Just to avoid line break in the code)
- flags = cv2.KMEANS_RANDOM_CENTERS
-
- # Apply KMeans
- compactness,labels,centers = cv2.kmeans(z,2,None,criteria,10,flags)
-
-This gives us the compactness, labels and centers. In this case, I got centers as 60 and 207. Labels will have the same size as that of test data where each data will be labelled as '0','1','2' etc. depending on their centroids. Now we split the data to different clusters depending on their labels.
-::
-
- A = z[labels==0]
- B = z[labels==1]
-
-Now we plot A in Red color and B in Blue color and their centroids in Yellow color.
-::
-
- # Now plot 'A' in red, 'B' in blue, 'centers' in yellow
- plt.hist(A,256,[0,256],color = 'r')
- plt.hist(B,256,[0,256],color = 'b')
- plt.hist(centers,32,[0,256],color = 'y')
- plt.show()
-
-Below is the output we got:
-
- .. image:: images/oc_1d_clustered.png
- :alt: Result of KMeans Clustering
- :align: center
-
-2. Data with Multiple Features
-===============================
-
-In previous example, we took only height for t-shirt problem. Here, we will take both height and weight, ie two features.
-
-Remember, in previous case, we made our data to a single column vector. Each feature is arranged in a column, while each row corresponds to an input test sample.
-
-For example, in this case, we set a test data of size 50x2, which are heights and weights of 50 people. First column corresponds to height of all the 50 people and second column corresponds to their weights. First row contains two elements where first one is the height of first person and second one his weight. Similarly remaining rows corresponds to heights and weights of other people. Check image below:
-
- .. image:: images/oc_feature_representation.jpg
- :alt: Feature Representation
- :align: center
-
-Now I am directly moving to the code:
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- X = np.random.randint(25,50,(25,2))
- Y = np.random.randint(60,85,(25,2))
- Z = np.vstack((X,Y))
-
- # convert to np.float32
- Z = np.float32(Z)
-
- # define criteria and apply kmeans()
- criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 10, 1.0)
- ret,label,center=cv2.kmeans(Z,2,None,criteria,10,cv2.KMEANS_RANDOM_CENTERS)
-
- # Now separate the data, Note the flatten()
- A = Z[label.ravel()==0]
- B = Z[label.ravel()==1]
-
- # Plot the data
- plt.scatter(A[:,0],A[:,1])
- plt.scatter(B[:,0],B[:,1],c = 'r')
- plt.scatter(center[:,0],center[:,1],s = 80,c = 'y', marker = 's')
- plt.xlabel('Height'),plt.ylabel('Weight')
- plt.show()
-
-Below is the output we get:
-
- .. image:: images/oc_2d_clustered.jpg
- :alt: Result of KMeans Clustering
- :align: center
-
-3. Color Quantization
-=======================
-
-Color Quantization is the process of reducing number of colors in an image. One reason to do so is to reduce the memory. Sometimes, some devices may have limitation such that it can produce only limited number of colors. In those cases also, color quantization is performed. Here we use k-means clustering for color quantization.
-
-There is nothing new to be explained here. There are 3 features, say, R,G,B. So we need to reshape the image to an array of Mx3 size (M is number of pixels in image). And after the clustering, we apply centroid values (it is also R,G,B) to all pixels, such that resulting image will have specified number of colors. And again we need to reshape it back to the shape of original image. Below is the code:
-::
-
- import numpy as np
- import cv2
-
- img = cv2.imread('home.jpg')
- Z = img.reshape((-1,3))
-
- # convert to np.float32
- Z = np.float32(Z)
-
- # define criteria, number of clusters(K) and apply kmeans()
- criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 10, 1.0)
- K = 8
- ret,label,center=cv2.kmeans(Z,K,None,criteria,10,cv2.KMEANS_RANDOM_CENTERS)
-
- # Now convert back into uint8, and make original image
- center = np.uint8(center)
- res = center[label.flatten()]
- res2 = res.reshape((img.shape))
-
- cv2.imshow('res2',res2)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-See the result below for K=8:
-
- .. image:: images/oc_color_quantization.jpg
- :alt: Color Quantization
- :align: center
-
-Additional Resources
-=======================
-
-Exercises
-=============
+++ /dev/null
-.. _KMeans_Clustering_Understanding:
-
-Understanding K-Means Clustering
-***********************************
-
-Goal
-=====
-
-In this chapter, we will understand the concepts of K-Means Clustering, how it works etc.
-
-Theory
-=======
-
-We will deal this with an example which is commonly used.
-
-T-shirt size problem
-------------------------
-
-Consider a company, which is going to release a new model of T-shirt to market. Obviously they will have to manufacture models in different sizes to satisfy people of all sizes. So the company make a data of people's height and weight, and plot them on to a graph, as below:
-
- .. image:: images/tshirt.jpg
- :alt: T-shirt Problem
- :align: center
-
-Company can't create t-shirts with all the sizes. Instead, they divide people to Small, Medium and Large, and manufacture only these 3 models which will fit into all the people. This grouping of people into three groups can be done by k-means clustering, and algorithm provides us best 3 sizes, which will satisfy all the people. And if it doesn't, company can divide people to more groups, may be five, and so on. Check image below :
-
- .. image:: images/tshirt_grouped.jpg
- :alt: People Grouped into Different Sizes
- :align: center
-
-How does it work ?
-------------------------------
-
-This algorithm is an iterative process. We will explain it step-by-step with the help of images.
-
-Consider a set of data as below ( You can consider it as t-shirt problem). We need to cluster this data into two groups.
-
- .. image:: images/testdata.jpg
- :alt: Test Data
- :align: center
-
-**Step : 1** - Algorithm randomly chooses two centroids, :math:`C1` and :math:`C2` (sometimes, any two data are taken as the centroids).
-
-**Step : 2** - It calculates the distance from each point to both centroids. If a test data is more closer to :math:`C1`, then that data is labelled with '0'. If it is closer to :math:`C2`, then labelled as '1' (If more centroids are there, labelled as '2','3' etc).
-
-In our case, we will color all '0' labelled with red, and '1' labelled with blue. So we get following image after above operations.
-
- .. image:: images/initial_labelling.jpg
- :alt: Initial Centroid Selection and Data Collection
- :align: center
-
-**Step : 3** - Next we calculate the average of all blue points and red points separately and that will be our new centroids. That is :math:`C1` and :math:`C2` shift to newly calculated centroids. (Remember, the images shown are not true values and not to true scale, it is just for demonstration only).
-
-And again, perform step 2 with new centroids and label data to '0' and '1'.
-
-So we get result as below :
-
- .. image:: images/update_centroid.jpg
- :alt: New Centroid Calculated and Data Re-laballed
- :align: center
-
-Now **Step - 2** and **Step - 3** are iterated until both centroids are converged to fixed points. *(Or it may be stopped depending on the criteria we provide, like maximum number of iterations, or a specific accuracy is reached etc.)* **These points are such that sum of distances between test data and their corresponding centroids are minimum**. Or simply, sum of distances between :math:`C1 \leftrightarrow Red\_Points` and :math:`C2 \leftrightarrow Blue\_Points` is minimum.
-
-.. math::
-
- minimize \;\bigg[J = \sum_{All\: Red_Points}distance(C1,Red\_Point) + \sum_{All\: Blue\_Points}distance(C2,Blue\_Point)\bigg]
-
-Final result almost looks like below :
-
- .. image:: images/final_clusters.jpg
- :alt: Final Result
- :align: center
-
-So this is just an intuitive understanding of K-Means Clustering. For more details and mathematical explanation, please read any standard machine learning textbooks or check links in additional resources. It is just a top layer of K-Means clustering. There are a lot of modifications to this algorithm like, how to choose the initial centroids, how to speed up the iteration process etc.
-
-Additional Resources
-=====================
-#. `Machine Learning Course <https://www.coursera.org/course/ml>`_, Video lectures by Prof. Andrew Ng (Some of the images are taken from this)
-
-Exercises
-===========
+++ /dev/null
-.. _KNN:
-
-K-Nearest Neighbour
-**********************
-
-* :ref:`KNN_Understanding`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |KNN_1| Get a basic understanding of what kNN is
- =========== ===================================================================
-
- .. |KNN_1| image:: images/knn_icon1.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`KNN_OpenCV`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |KNN_2| Now let's use kNN in OpenCV for digit recognition OCR
- =========== ===================================================================
-
- .. |KNN_2| image:: images/knn_icon2.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- py_knn_understanding/py_knn_understanding
- py_knn_opencv/py_knn_opencv
+++ /dev/null
-.. _KNN_OpenCV:
-
-OCR of Hand-written Data using kNN
-***********************************************
-
-Goal
-=======
-
-In this chapter
- * We will use our knowledge on kNN to build a basic OCR application.
- * We will try with Digits and Alphabets data available that comes with OpenCV.
-
-
-OCR of Hand-written Digits
-============================
-
-Our goal is to build an application which can read the handwritten digits. For this we need some train_data and test_data. OpenCV comes with an image `digits.png` (in the folder ``opencv/samples/python2/data/``) which has 5000 handwritten digits (500 for each digit). Each digit is a 20x20 image. So our first step is to split this image into 5000 different digits. For each digit, we flatten it into a single row with 400 pixels. That is our feature set, ie intensity values of all pixels. It is the simplest feature set we can create. We use first 250 samples of each digit as train_data, and next 250 samples as test_data. So let's prepare them first.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('digits.png')
- gray = cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)
-
- # Now we split the image to 5000 cells, each 20x20 size
- cells = [np.hsplit(row,100) for row in np.vsplit(gray,50)]
-
- # Make it into a Numpy array. It size will be (50,100,20,20)
- x = np.array(cells)
-
- # Now we prepare train_data and test_data.
- train = x[:,:50].reshape(-1,400).astype(np.float32) # Size = (2500,400)
- test = x[:,50:100].reshape(-1,400).astype(np.float32) # Size = (2500,400)
-
- # Create labels for train and test data
- k = np.arange(10)
- train_labels = np.repeat(k,250)[:,np.newaxis]
- test_labels = train_labels.copy()
-
- # Initiate kNN, train the data, then test it with test data for k=1
- knn = cv2.KNearest()
- knn.train(train,train_labels)
- ret,result,neighbours,dist = knn.find_nearest(test,k=5)
-
- # Now we check the accuracy of classification
- # For that, compare the result with test_labels and check which are wrong
- matches = result==test_labels
- correct = np.count_nonzero(matches)
- accuracy = correct*100.0/result.size
- print accuracy
-
-
-So our basic OCR app is ready. This particular example gave me an accuracy of 91%. One option improve accuracy is to add more data for training, especially the wrong ones. So instead of finding this training data everytime I start application, I better save it, so that next time, I directly read this data from a file and start classification. You can do it with the help of some Numpy functions like np.savetxt, np.savez, np.load etc. Please check their docs for more details.
-::
-
- # save the data
- np.savez('knn_data.npz',train=train, train_labels=train_labels)
-
- # Now load the data
- with np.load('knn_data.npz') as data:
- print data.files
- train = data['train']
- train_labels = data['train_labels']
-
-In my system, it takes around 4.4 MB of memory. Since we are using intensity values (uint8 data) as features, it would be better to convert the data to np.uint8 first and then save it. It takes only 1.1 MB in this case. Then while loading, you can convert back into float32.
-
-OCR of English Alphabets
-===========================
-
-Next we will do the same for English alphabets, but there is a slight change in data and feature set. Here, instead of images, OpenCV comes with a data file, ``letter-recognition.data`` in ``opencv/samples/cpp/`` folder. If you open it, you will see 20000 lines which may, on first sight, look like garbage. Actually, in each row, first column is an alphabet which is our label. Next 16 numbers following it are its different features. These features are obtained from `UCI Machine Learning Repository <http://archive.ics.uci.edu/ml/>`_. You can find the details of these features in `this page <http://archive.ics.uci.edu/ml/datasets/Letter+Recognition>`_.
-
-There are 20000 samples available, so we take first 10000 data as training samples and remaining 10000 as test samples. We should change the alphabets to ascii characters because we can't work with alphabets directly.
-::
-
- import cv2
- import numpy as np
- import matplotlib.pyplot as plt
-
- # Load the data, converters convert the letter to a number
- data= np.loadtxt('letter-recognition.data', dtype= 'float32', delimiter = ',',
- converters= {0: lambda ch: ord(ch)-ord('A')})
-
- # split the data to two, 10000 each for train and test
- train, test = np.vsplit(data,2)
-
- # split trainData and testData to features and responses
- responses, trainData = np.hsplit(train,[1])
- labels, testData = np.hsplit(test,[1])
-
- # Initiate the kNN, classify, measure accuracy.
- knn = cv2.KNearest()
- knn.train(trainData, responses)
- ret, result, neighbours, dist = knn.find_nearest(testData, k=5)
-
- correct = np.count_nonzero(result == labels)
- accuracy = correct*100.0/10000
- print accuracy
-
-It gives me an accuracy of 93.22%. Again, if you want to increase accuracy, you can iteratively add error data in each level.
-
-Additional Resources
-=======================
-
-Exercises
-=============
+++ /dev/null
-.. _KNN_Understanding:
-
-Understanding k-Nearest Neighbour
-***********************************
-
-Goal
-=====
-
-In this chapter, we will understand the concepts of k-Nearest Neighbour (kNN) algorithm.
-
-Theory
-=======
-
-kNN is one of the simplest of classification algorithms available for supervised learning. The idea is to search for closest match of the test data in feature space. We will look into it with below image.
-
- .. image:: images/knn_theory.png
- :alt: Understanding kNN
- :align: center
-
-In the image, there are two families, `Blue Squares and Red Triangles`. We call each family as **Class**. Their houses are shown in their town map which we call `feature space`. *(You can consider a feature space as a space where all datas are projected. For example, consider a 2D coordinate space. Each data has two features, x and y coordinates. You can represent this data in your 2D coordinate space, right? Now imagine if there are three features, you need 3D space. Now consider N features, where you need N-dimensional space, right? This N-dimensional space is its feature space. In our image, you can consider it as a 2D case with two features)*.
-
-Now a new member comes into the town and creates a new home, which is shown as green circle. He should be added to one of these Blue/Red families. We call that process, **Classification**. What we do? Since we are dealing with kNN, let us apply this algorithm.
-
-One method is to check who is his nearest neighbour. From the image, it is clear it is the Red Triangle family. So he is also added into Red Triangle. This method is called simply **Nearest Neighbour**, because classification depends only on the nearest neighbour.
-
-But there is a problem with that. Red Triangle may be the nearest. But what if there are lot of Blue Squares near to him? Then Blue Squares have more strength in that locality than Red Triangle. So just checking nearest one is not sufficient. Instead we check some `k` nearest families. Then whoever is majority in them, the new guy belongs to that family. In our image, let's take `k=3`, ie 3 nearest families. He has two Red and one Blue (there are two Blues equidistant, but since k=3, we take only one of them), so again he should be added to Red family. But what if we take `k=7`? Then he has 5 Blue families and 2 Red families. Great!! Now he should be added to Blue family. So it all changes with value of k. More funny thing is, what if `k = 4`? He has 2 Red and 2 Blue neighbours. It is a tie !!! So better take k as an odd number. So this method is called **k-Nearest Neighbour** since classification depends on k nearest neighbours.
-
-Again, in kNN, it is true we are considering k neighbours, but we are giving equal importance to all, right? Is it justice? For example, take the case of `k=4`. We told it is a tie. But see, the 2 Red families are more closer to him than the other 2 Blue families. So he is more eligible to be added to Red. So how do we mathematically explain that? We give some weights to each family depending on their distance to the new-comer. For those who are near to him get higher weights while those are far away get lower weights. Then we add total weights of each family separately. Whoever gets highest total weights, new-comer goes to that family. This is called **modified kNN**.
-
-So what are some important things you see here?
-
- * You need to have information about all the houses in town, right? Because, we have to check the distance from new-comer to all the existing houses to find the nearest neighbour. If there are plenty of houses and families, it takes lots of memory, and more time for calculation also.
- * There is almost zero time for any kind of training or preparation.
-
-Now let's see it in OpenCV.
-
-kNN in OpenCV
-===============
-
-We will do a simple example here, with two families (classes), just like above. Then in the next chapter, we will do an even better example.
-
-So here, we label the Red family as **Class-0** (so denoted by 0) and Blue family as **Class-1** (denoted by 1). We create 25 families or 25 training data, and label them either Class-0 or Class-1. We do all these with the help of Random Number Generator in Numpy.
-
-Then we plot it with the help of Matplotlib. Red families are shown as Red Triangles and Blue families are shown as Blue Squares.
-::
-
- import cv2
- import numpy as np
- import matplotlib.pyplot as plt
-
- # Feature set containing (x,y) values of 25 known/training data
- trainData = np.random.randint(0,100,(25,2)).astype(np.float32)
-
- # Labels each one either Red or Blue with numbers 0 and 1
- responses = np.random.randint(0,2,(25,1)).astype(np.float32)
-
- # Take Red families and plot them
- red = trainData[responses.ravel()==0]
- plt.scatter(red[:,0],red[:,1],80,'r','^')
-
- # Take Blue families and plot them
- blue = trainData[responses.ravel()==1]
- plt.scatter(blue[:,0],blue[:,1],80,'b','s')
-
- plt.show()
-
-You will get something similar to our first image. Since you are using random number generator, you will be getting different data each time you run the code.
-
-Next initiate the kNN algorithm and pass the `trainData` and `responses` to train the kNN (It constructs a search tree).
-
-Then we will bring one new-comer and classify him to a family with the help of kNN in OpenCV. Before going to kNN, we need to know something on our test data (data of new comers). Our data should be a floating point array with size :math:`number \; of \; testdata \times number \; of \; features`. Then we find the nearest neighbours of new-comer. We can specify how many neighbours we want. It returns:
-
- 1. The label given to new-comer depending upon the kNN theory we saw earlier. If you want Nearest Neighbour algorithm, just specify `k=1` where k is the number of neighbours.
- 2. The labels of k-Nearest Neighbours.
- 3. Corresponding distances from new-comer to each nearest neighbour.
-
-So let's see how it works. New comer is marked in green color.
-::
-
- newcomer = np.random.randint(0,100,(1,2)).astype(np.float32)
- plt.scatter(newcomer[:,0],newcomer[:,1],80,'g','o')
-
- knn = cv2.KNearest()
- knn.train(trainData,responses)
- ret, results, neighbours ,dist = knn.find_nearest(newcomer, 3)
-
- print "result: ", results,"\n"
- print "neighbours: ", neighbours,"\n"
- print "distance: ", dist
-
- plt.show()
-
-I got the result as follows:
-::
-
- result: [[ 1.]]
- neighbours: [[ 1. 1. 1.]]
- distance: [[ 53. 58. 61.]]
-
-It says our new-comer got 3 neighbours, all from Blue family. Therefore, he is labelled as Blue family. It is obvious from plot below:
-
- .. image:: images/knn_simple.png
- :alt: kNN Demo
- :align: center
-
-If you have large number of data, you can just pass it as array. Corresponding results are also obtained as arrays.
-::
-
- # 10 new comers
- newcomers = np.random.randint(0,100,(10,2)).astype(np.float32)
- ret, results,neighbours,dist = knn.find_nearest(newcomer, 3)
- # The results also will contain 10 labels.
-
-
-Additional Resources
-======================
-
-#. `NPTEL notes on Pattern Recognition, Chapter 11 <http://www.nptel.iitm.ac.in/courses/106108057/12>`_
-
-Exercises
-===========
+++ /dev/null
-.. _SVM_Understanding:
-
-Understanding SVM
-********************
-
-Goal
-======
-
-In this chapter
- * We will see an intuitive understanding of SVM
-
-
-Theory
-==========
-
-Linearly Separable Data
----------------------------
-
-Consider the image below which has two types of data, red and blue. In kNN, for a test data, we used to measure its distance to all the training samples and take the one with minimum distance. It takes plenty of time to measure all the distances and plenty of memory to store all the training-samples. But considering the data given in image, should we need that much?
-
- .. image:: images/svm_basics1.png
- :alt: Test Data
- :align: center
-
-Consider another idea. We find a line, :math:`f(x)=ax_1+bx_2+c` which divides both the data to two regions. When we get a new test_data :math:`X`, just substitute it in :math:`f(x)`. If :math:`f(X) > 0`, it belongs to blue group, else it belongs to red group. We can call this line as **Decision Boundary**. It is very simple and memory-efficient. Such data which can be divided into two with a straight line (or hyperplanes in higher dimensions) is called **Linear Separable**.
-
-So in above image, you can see plenty of such lines are possible. Which one we will take? Very intuitively we can say that the line should be passing as far as possible from all the points. Why? Because there can be noise in the incoming data. This data should not affect the classification accuracy. So taking a farthest line will provide more immunity against noise. So what SVM does is to find a straight line (or hyperplane) with largest minimum distance to the training samples. See the bold line in below image passing through the center.
-
- .. image:: images/svm_basics2.png
- :alt: Decision Boundary
- :align: center
-
-So to find this Decision Boundary, you need training data. Do you need all? NO. Just the ones which are close to the opposite group are sufficient. In our image, they are the one blue filled circle and two red filled squares. We can call them **Support Vectors** and the lines passing through them are called **Support Planes**. They are adequate for finding our decision boundary. We need not worry about all the data. It helps in data reduction.
-
-What happened is, first two hyperplanes are found which best represents the data. For eg, blue data is represented by :math:`w^Tx+b_0 > 1` while red data is represented by :math:`w^Tx+b_0 < -1` where :math:`w` is **weight vector** ( :math:`w=[w_1, w_2,..., w_n]`) and :math:`x` is the feature vector (:math:`x = [x_1,x_2,..., x_n]`). :math:`b_0` is the **bias**. Weight vector decides the orientation of decision boundary while bias point decides its location. Now decision boundary is defined to be midway between these hyperplanes, so expressed as :math:`w^Tx+b_0 = 0`. The minimum distance from support vector to the decision boundary is given by, :math:`distance_{support \, vectors}=\frac{1}{||w||}`. Margin is twice this distance, and we need to maximize this margin. i.e. we need to minimize a new function :math:`L(w, b_0)` with some constraints which can expressed below:
-
-.. math::
-
- \min_{w, b_0} L(w, b_0) = \frac{1}{2}||w||^2 \; \text{subject to} \; t_i(w^Tx+b_0) \geq 1 \; \forall i
-
-where :math:`t_i` is the label of each class, :math:`t_i \in [-1,1]`.
-
-
-
-Non-Linearly Separable Data
------------------------------
-
-Consider some data which can't be divided into two with a straight line. For example, consider an one-dimensional data where 'X' is at -3 & +3 and 'O' is at -1 & +1. Clearly it is not linearly separable. But there are methods to solve these kinds of problems. If we can map this data set with a function, :math:`f(x) = x^2`, we get 'X' at 9 and 'O' at 1 which are linear separable.
-
-Otherwise we can convert this one-dimensional to two-dimensional data. We can use :math:`f(x)=(x,x^2)` function to map this data. Then 'X' becomes (-3,9) and (3,9) while 'O' becomes (-1,1) and (1,1). This is also linear separable. In short, chance is more for a non-linear separable data in lower-dimensional space to become linear separable in higher-dimensional space.
-
-In general, it is possible to map points in a d-dimensional space to some D-dimensional space :math:`(D>d)` to check the possibility of linear separability. There is an idea which helps to compute the dot product in the high-dimensional (kernel) space by performing computations in the low-dimensional input (feature) space. We can illustrate with following example.
-
-Consider two points in two-dimensional space, :math:`p=(p_1,p_2)` and :math:`q=(q_1,q_2)`. Let :math:`\phi` be a mapping function which maps a two-dimensional point to three-dimensional space as follows:
-
-.. math::
-
- \phi (p) = (p_{1}^2,p_{2}^2,\sqrt{2} p_1 p_2)
- \phi (q) = (q_{1}^2,q_{2}^2,\sqrt{2} q_1 q_2)
-
-Let us define a kernel function :math:`K(p,q)` which does a dot product between two points, shown below:
-
-.. math::
-
- K(p,q) = \phi(p).\phi(q) &= \phi(p)^T \phi(q) \\
- &= (p_{1}^2,p_{2}^2,\sqrt{2} p_1 p_2).(q_{1}^2,q_{2}^2,\sqrt{2} q_1 q_2) \\
- &= p_1 q_1 + p_2 q_2 + 2 p_1 q_1 p_2 q_2 \\
- &= (p_1 q_1 + p_2 q_2)^2 \\
- \phi(p).\phi(q) &= (p.q)^2
-
-It means, a dot product in three-dimensional space can be achieved using squared dot product in two-dimensional space. This can be applied to higher dimensional space. So we can calculate higher dimensional features from lower dimensions itself. Once we map them, we get a higher dimensional space.
-
-In addition to all these concepts, there comes the problem of misclassification. So just finding decision boundary with maximum margin is not sufficient. We need to consider the problem of misclassification errors also. Sometimes, it may be possible to find a decision boundary with less margin, but with reduced misclassification. Anyway we need to modify our model such that it should find decision boundary with maximum margin, but with less misclassification. The minimization criteria is modified as:
-
-.. math::
-
- min \; ||w||^2 + C(distance \; of \; misclassified \; samples \; to \; their \; correct \; regions)
-
-Below image shows this concept. For each sample of the training data a new parameter :math:`\xi_i` is defined. It is the distance from its corresponding training sample to their correct decision region. For those who are not misclassified, they fall on their corresponding support planes, so their distance is zero.
-
- .. image:: images/svm_basics3.png
- :alt: Misclassification
- :align: center
-
-So the new optimization problem is :
-
-.. math::
-
- \min_{w, b_{0}} L(w,b_0) = ||w||^{2} + C \sum_{i} {\xi_{i}} \text{ subject to } y_{i}(w^{T} x_{i} + b_{0}) \geq 1 - \xi_{i} \text{ and } \xi_{i} \geq 0 \text{ } \forall i
-
-How should the parameter C be chosen? It is obvious that the answer to this question depends on how the training data is distributed. Although there is no general answer, it is useful to take into account these rules:
-
- * Large values of C give solutions with less misclassification errors but a smaller margin. Consider that in this case it is expensive to make misclassification errors. Since the aim of the optimization is to minimize the argument, few misclassifications errors are allowed.
- * Small values of C give solutions with bigger margin and more classification errors. In this case the minimization does not consider that much the term of the sum so it focuses more on finding a hyperplane with big margin.
-
-Additional Resources
-======================
-
-#. `NPTEL notes on Statistical Pattern Recognition, Chapters 25-29 <http://www.nptel.iitm.ac.in/courses/106108057/26>`_.
-
-
-Exercises
-===========
+++ /dev/null
-.. _SVM:
-
-Support Vector Machines (SVM)
-********************************
-
-* :ref:`SVM_Understanding`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |SVM_1| Get a basic understanding of what SVM is
- =========== ===================================================================
-
- .. |SVM_1| image:: images/svm_icon1.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`svm_opencv`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |SVM_2| Let's use SVM functionalities in OpenCV
- =========== ===================================================================
-
- .. |SVM_2| image:: images/svm_icon2.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- py_svm_basics/py_svm_basics
- py_svm_opencv/py_svm_opencv
+++ /dev/null
-.. _svm_opencv:
-
-
-OCR of Hand-written Data using SVM
-***********************************************
-
-Goal
-=========
-
-In this chapter
-
- * We will revisit the hand-written data OCR, but, with SVM instead of kNN.
-
-
-OCR of Hand-written Digits
-============================
-
-In kNN, we directly used pixel intensity as the feature vector. This time we will use `Histogram of Oriented Gradients <http://en.wikipedia.org/wiki/Histogram_of_oriented_gradients>`_ (HOG) as feature vectors.
-
-Here, before finding the HOG, we deskew the image using its second order moments. So we first define a function **deskew()** which takes a digit image and deskew it. Below is the deskew() function:
-::
-
- def deskew(img):
- m = cv2.moments(img)
- if abs(m['mu02']) < 1e-2:
- return img.copy()
- skew = m['mu11']/m['mu02']
- M = np.float32([[1, skew, -0.5*SZ*skew], [0, 1, 0]])
- img = cv2.warpAffine(img,M,(SZ, SZ),flags=affine_flags)
- return img
-
-Below image shows above deskew function applied to an image of zero. Left image is the original image and right image is the deskewed image.
-
- .. image:: images/deskew.jpg
- :alt: Deskew
- :align: center
-
-
-Next we have to find the HOG Descriptor of each cell. For that, we find Sobel derivatives of each cell in X and Y direction. Then find their magnitude and direction of gradient at each pixel. This gradient is quantized to 16 integer values. Divide this image to four sub-squares. For each sub-square, calculate the histogram of direction (16 bins) weighted with their magnitude. So each sub-square gives you a vector containing 16 values. Four such vectors (of four sub-squares) together gives us a feature vector containing 64 values. This is the feature vector we use to train our data.
-::
-
- def hog(img):
- gx = cv2.Sobel(img, cv2.CV_32F, 1, 0)
- gy = cv2.Sobel(img, cv2.CV_32F, 0, 1)
- mag, ang = cv2.cartToPolar(gx, gy)
-
- # quantizing binvalues in (0...16)
- bins = np.int32(bin_n*ang/(2*np.pi))
-
- # Divide to 4 sub-squares
- bin_cells = bins[:10,:10], bins[10:,:10], bins[:10,10:], bins[10:,10:]
- mag_cells = mag[:10,:10], mag[10:,:10], mag[:10,10:], mag[10:,10:]
- hists = [np.bincount(b.ravel(), m.ravel(), bin_n) for b, m in zip(bin_cells, mag_cells)]
- hist = np.hstack(hists)
- return hist
-
-
-Finally, as in the previous case, we start by splitting our big dataset into individual cells. For every digit, 250 cells are reserved for training data and remaining 250 data is reserved for testing. Full code is given below:
-::
-
- import cv2
- import numpy as np
-
- SZ=20
- bin_n = 16 # Number of bins
-
- svm_params = dict( kernel_type = cv2.SVM_LINEAR,
- svm_type = cv2.SVM_C_SVC,
- C=2.67, gamma=5.383 )
-
- affine_flags = cv2.WARP_INVERSE_MAP|cv2.INTER_LINEAR
-
- def deskew(img):
- m = cv2.moments(img)
- if abs(m['mu02']) < 1e-2:
- return img.copy()
- skew = m['mu11']/m['mu02']
- M = np.float32([[1, skew, -0.5*SZ*skew], [0, 1, 0]])
- img = cv2.warpAffine(img,M,(SZ, SZ),flags=affine_flags)
- return img
-
- def hog(img):
- gx = cv2.Sobel(img, cv2.CV_32F, 1, 0)
- gy = cv2.Sobel(img, cv2.CV_32F, 0, 1)
- mag, ang = cv2.cartToPolar(gx, gy)
- bins = np.int32(bin_n*ang/(2*np.pi)) # quantizing binvalues in (0...16)
- bin_cells = bins[:10,:10], bins[10:,:10], bins[:10,10:], bins[10:,10:]
- mag_cells = mag[:10,:10], mag[10:,:10], mag[:10,10:], mag[10:,10:]
- hists = [np.bincount(b.ravel(), m.ravel(), bin_n) for b, m in zip(bin_cells, mag_cells)]
- hist = np.hstack(hists) # hist is a 64 bit vector
- return hist
-
- img = cv2.imread('digits.png',0)
-
- cells = [np.hsplit(row,100) for row in np.vsplit(img,50)]
-
- # First half is trainData, remaining is testData
- train_cells = [ i[:50] for i in cells ]
- test_cells = [ i[50:] for i in cells]
-
- ###### Now training ########################
-
- deskewed = [map(deskew,row) for row in train_cells]
- hogdata = [map(hog,row) for row in deskewed]
- trainData = np.float32(hogdata).reshape(-1,64)
- responses = np.float32(np.repeat(np.arange(10),250)[:,np.newaxis])
-
- svm = cv2.SVM()
- svm.train(trainData,responses, params=svm_params)
- svm.save('svm_data.dat')
-
- ###### Now testing ########################
-
- deskewed = [map(deskew,row) for row in test_cells]
- hogdata = [map(hog,row) for row in deskewed]
- testData = np.float32(hogdata).reshape(-1,bin_n*4)
- result = svm.predict_all(testData)
-
- ####### Check Accuracy ########################
- mask = result==responses
- correct = np.count_nonzero(mask)
- print correct*100.0/result.size
-
-This particular technique gave me nearly 94% accuracy. You can try different values for various parameters of SVM to check if higher accuracy is possible. Or you can read technical papers on this area and try to implement them.
-
-
-Additional Resources
-=====================
-
-1. `Histograms of Oriented Gradients Video <www.youtube.com/watch?v=0Zib1YEE4LU>`_
-
-Exercises
-==============
-1. OpenCV samples contain ``digits.py`` which applies a slight improvement of the above method to get improved result. It also contains the reference. Check it and understand it.
+++ /dev/null
-.. _PY_Table-Of-Content-ML:
-
-Machine Learning
-********************
-
-* :ref:`KNN`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |ML_KNN| Learn to use kNN for classification
- Plus learn about handwritten digit recognition using kNN
- =========== ===================================================================
-
- .. |ML_KNN| image:: images/knnicon.png
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`SVM`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |ML_SVM| Understand concepts of SVM
- =========== ===================================================================
-
- .. |ML_SVM| image:: images/svmicon.png
- :height: 90pt
- :width: 90pt
-
-* :ref:`KMeans_Clustering`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ===================================================================
- |ML_KM| Learn to use K-Means Clustering to group data to a number of clusters.
- Plus learn to do color quantization using K-Means Clustering
- =========== ===================================================================
-
- .. |ML_KM| image:: images/kmeansicon.jpg
- :height: 90pt
- :width: 90pt
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_knn/py_knn_index
- ../py_svm/py_svm_index
- ../py_kmeans/py_kmeans_index
+++ /dev/null
-.. _face_detection:
-
-
-Face Detection using Haar Cascades
-***************************************
-
-Goal
-========
-
-In this session,
-
- * We will see the basics of face detection using Haar Feature-based Cascade Classifiers
- * We will extend the same for eye detection etc.
-
-
-Basics
-=========
-
-Object Detection using Haar feature-based cascade classifiers is an effective object detection method proposed by Paul Viola and Michael Jones in their paper, "Rapid Object Detection using a Boosted Cascade of Simple Features" in 2001. It is a machine learning based approach where a cascade function is trained from a lot of positive and negative images. It is then used to detect objects in other images.
-
-Here we will work with face detection. Initially, the algorithm needs a lot of positive images (images of faces) and negative images (images without faces) to train the classifier. Then we need to extract features from it. For this, haar features shown in below image are used. They are just like our convolutional kernel. Each feature is a single value obtained by subtracting sum of pixels under white rectangle from sum of pixels under black rectangle.
-
- .. image:: images/haar_features.jpg
- :alt: Haar Features
- :align: center
-
-
-Now all possible sizes and locations of each kernel is used to calculate plenty of features. (Just imagine how much computation it needs? Even a 24x24 window results over 160000 features). For each feature calculation, we need to find sum of pixels under white and black rectangles. To solve this, they introduced the integral images. It simplifies calculation of sum of pixels, how large may be the number of pixels, to an operation involving just four pixels. Nice, isn't it? It makes things super-fast.
-
-But among all these features we calculated, most of them are irrelevant. For example, consider the image below. Top row shows two good features. The first feature selected seems to focus on the property that the region of the eyes is often darker than the region of the nose and cheeks. The second feature selected relies on the property that the eyes are darker than the bridge of the nose. But the same windows applying on cheeks or any other place is irrelevant. So how do we select the best features out of 160000+ features? It is achieved by **Adaboost**.
-
- .. image:: images/haar.png
- :alt: Face Detection
- :align: center
-
-For this, we apply each and every feature on all the training images. For each feature, it finds the best threshold which will classify the faces to positive and negative. But obviously, there will be errors or misclassifications. We select the features with minimum error rate, which means they are the features that best classifies the face and non-face images. (The process is not as simple as this. Each image is given an equal weight in the beginning. After each classification, weights of misclassified images are increased. Then again same process is done. New error rates are calculated. Also new weights. The process is continued until required accuracy or error rate is achieved or required number of features are found).
-
-Final classifier is a weighted sum of these weak classifiers. It is called weak because it alone can't classify the image, but together with others forms a strong classifier. The paper says even 200 features provide detection with 95% accuracy. Their final setup had around 6000 features. (Imagine a reduction from 160000+ features to 6000 features. That is a big gain).
-
-So now you take an image. Take each 24x24 window. Apply 6000 features to it. Check if it is face or not. Wow.. Wow.. Isn't it a little inefficient and time consuming? Yes, it is. Authors have a good solution for that.
-
-In an image, most of the image region is non-face region. So it is a better idea to have a simple method to check if a window is not a face region. If it is not, discard it in a single shot. Don't process it again. Instead focus on region where there can be a face. This way, we can find more time to check a possible face region.
-
-For this they introduced the concept of **Cascade of Classifiers**. Instead of applying all the 6000 features on a window, group the features into different stages of classifiers and apply one-by-one. (Normally first few stages will contain very less number of features). If a window fails the first stage, discard it. We don't consider remaining features on it. If it passes, apply the second stage of features and continue the process. The window which passes all stages is a face region. How is the plan !!!
-
-Authors' detector had 6000+ features with 38 stages with 1, 10, 25, 25 and 50 features in first five stages. (Two features in the above image is actually obtained as the best two features from Adaboost). According to authors, on an average, 10 features out of 6000+ are evaluated per sub-window.
-
-So this is a simple intuitive explanation of how Viola-Jones face detection works. Read paper for more details or check out the references in Additional Resources section.
-
-
-Haar-cascade Detection in OpenCV
-===================================
-
-OpenCV comes with a trainer as well as detector. If you want to train your own classifier for any object like car, planes etc. you can use OpenCV to create one. Its full details are given here: `Cascade Classifier Training. <http://docs.opencv.org/doc/user_guide/ug_traincascade.html>`_
-
-Here we will deal with detection. OpenCV already contains many pre-trained classifiers for face, eyes, smile etc. Those XML files are stored in ``opencv/data/haarcascades/`` folder. Let's create face and eye detector with OpenCV.
-
-First we need to load the required XML classifiers. Then load our input image (or video) in grayscale mode.
-::
-
- import numpy as np
- import cv2
-
- face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml')
- eye_cascade = cv2.CascadeClassifier('haarcascade_eye.xml')
-
- img = cv2.imread('sachin.jpg')
- gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
-
-
-Now we find the faces in the image. If faces are found, it returns the positions of detected faces as Rect(x,y,w,h). Once we get these locations, we can create a ROI for the face and apply eye detection on this ROI (since eyes are always on the face !!! ).
-::
-
- faces = face_cascade.detectMultiScale(gray, 1.3, 5)
- for (x,y,w,h) in faces:
- cv2.rectangle(img,(x,y),(x+w,y+h),(255,0,0),2)
- roi_gray = gray[y:y+h, x:x+w]
- roi_color = img[y:y+h, x:x+w]
- eyes = eye_cascade.detectMultiScale(roi_gray)
- for (ex,ey,ew,eh) in eyes:
- cv2.rectangle(roi_color,(ex,ey),(ex+ew,ey+eh),(0,255,0),2)
-
- cv2.imshow('img',img)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-
-Result looks like below:
-
- .. image:: images/face.jpg
- :alt: Face Detection
- :align: center
-
-
-Additional Resources
-=======================
-
-#. Video Lecture on `Face Detection and Tracking <http://www.youtube.com/watch?v=WfdYYNamHZ8>`_
-
-#. An interesting interview regarding Face Detection by `Adam Harvey <http://www.makematics.com/research/viola-jones/>`_
-
-
-Exercises
-===========
+++ /dev/null
-.. _PY_Table-Of-Content-Objdetection:
-
-
-Object Detection
---------------------------------
-
-
-
-* :ref:`face_detection`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |objdet_1| Face detection using haar-cascades
-
- =========== ======================================================
-
- .. |objdet_1| image:: images/face_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_face_detection/py_face_detection
+++ /dev/null
-.. _inpainting:
-
-
-Image Inpainting
-**********************
-
-Goal
-======
-
-In this chapter,
- * We will learn how to remove small noises, strokes etc in old photographs by a method called inpainting
- * We will see inpainting functionalities in OpenCV.
-
-
-Basics
-===========
-
-Most of you will have some old degraded photos at your home with some black spots, some strokes etc on it. Have you ever thought of restoring it back? We can't simply erase them in a paint tool because it is will simply replace black structures with white structures which is of no use. In these cases, a technique called image inpainting is used. The basic idea is simple: Replace those bad marks with its neighbouring pixels so that it looks like the neigbourhood. Consider the image shown below (taken from `Wikipedia <http://en.wikipedia.org/wiki/Inpainting>`_):
-
- .. image:: images/inpaint_basics.jpg
- :alt: Inpainting example
- :align: center
-
-Several algorithms were designed for this purpose and OpenCV provides two of them. Both can be accessed by the same function, **cv2.inpaint()**
-
-First algorithm is based on the paper **"An Image Inpainting Technique Based on the Fast Marching Method"** by Alexandru Telea in 2004. It is based on Fast Marching Method. Consider a region in the image to be inpainted. Algorithm starts from the boundary of this region and goes inside the region gradually filling everything in the boundary first. It takes a small neighbourhood around the pixel on the neigbourhood to be inpainted. This pixel is replaced by normalized weighted sum of all the known pixels in the neigbourhood. Selection of the weights is an important matter. More weightage is given to those pixels lying near to the point, near to the normal of the boundary and those lying on the boundary contours. Once a pixel is inpainted, it moves to next nearest pixel using Fast Marching Method. FMM ensures those pixels near the known pixels are inpainted first, so that it just works like a manual heuristic operation. This algorithm is enabled by using the flag, ``cv2.INPAINT_TELEA``.
-
-Second algorithm is based on the paper **"Navier-Stokes, Fluid Dynamics, and Image and Video Inpainting"** by Bertalmio, Marcelo, Andrea L. Bertozzi, and Guillermo Sapiro in 2001. This algorithm is based on fluid dynamics and utilizes partial differential equations. Basic principle is heurisitic. It first travels along the edges from known regions to unknown regions (because edges are meant to be continuous). It continues isophotes (lines joining points with same intensity, just like contours joins points with same elevation) while matching gradient vectors at the boundary of the inpainting region. For this, some methods from fluid dynamics are used. Once they are obtained, color is filled to reduce minimum variance in that area. This algorithm is enabled by using the flag, ``cv2.INPAINT_NS``.
-
-
-Code
-===========
-
-We need to create a mask of same size as that of input image, where non-zero pixels corresponds to the area which is to be inpainted. Everything else is simple. My image is degraded with some black strokes (I added manually). I created a corresponding strokes with Paint tool.
-::
-
- import numpy as np
- import cv2
-
- img = cv2.imread('messi_2.jpg')
- mask = cv2.imread('mask2.png',0)
-
- dst = cv2.inpaint(img,mask,3,cv2.INPAINT_TELEA)
-
- cv2.imshow('dst',dst)
- cv2.waitKey(0)
- cv2.destroyAllWindows()
-
-
-See the result below. First image shows degraded input. Second image is the mask. Third image is the result of first algorithm and last image is the result of second algorithm.
-
- .. image:: images/inpaint_result.jpg
- :alt: Inpainting result
- :align: center
-
-
-Additional Resources
-=========================
-
-#. Bertalmio, Marcelo, Andrea L. Bertozzi, and Guillermo Sapiro. "Navier-stokes, fluid dynamics, and image and video inpainting." In Computer Vision and Pattern Recognition, 2001. CVPR 2001. Proceedings of the 2001 IEEE Computer Society Conference on, vol. 1, pp. I-355. IEEE, 2001.
-
-#. Telea, Alexandru. "An image inpainting technique based on the fast marching method." Journal of graphics tools 9.1 (2004): 23-34.
-
-
-Exercises
-================
-
-#. OpenCV comes with an interactive sample on inpainting, ``samples/python2/inpaint.py``, try it.
-
-#. A few months ago, I watched a video on `Content-Aware Fill <http://www.youtube.com/watch?v=ZtoUiplKa2A>`_, an advanced inpainting technique used in Adobe Photoshop. On further search, I was able to find that same technique is already there in GIMP with different name, "Resynthesizer" (You need to install separate plugin). I am sure you will enjoy the technique.
+++ /dev/null
-.. _non_local_means:
-
-
-Image Denoising
-************************
-
-Goal
-=========
-
-In this chapter,
-
- * You will learn about Non-local Means Denoising algorithm to remove noise in the image.
- * You will see different functions like **cv2.fastNlMeansDenoising()**, **cv2.fastNlMeansDenoisingColored()** etc.
-
-
-Theory
-=========
-
-In earlier chapters, we have seen many image smoothing techniques like Gaussian Blurring, Median Blurring etc and they were good to some extent in removing small quantities of noise. In those techniques, we took a small neighbourhood around a pixel and did some operations like gaussian weighted average, median of the values etc to replace the central element. In short, noise removal at a pixel was local to its neighbourhood.
-
-There is a property of noise. Noise is generally considered to be a random variable with zero mean. Consider a noisy pixel, :math:`p = p_0 + n` where :math:`p_0` is the true value of pixel and :math:`n` is the noise in that pixel. You can take large number of same pixels (say :math:`N`) from different images and computes their average. Ideally, you should get :math:`p = p_0` since mean of noise is zero.
-
-You can verify it yourself by a simple setup. Hold a static camera to a certain location for a couple of seconds. This will give you plenty of frames, or a lot of images of the same scene. Then write a piece of code to find the average of all the frames in the video (This should be too simple for you now ). Compare the final result and first frame. You can see reduction in noise. Unfortunately this simple method is not robust to camera and scene motions. Also often there is only one noisy image available.
-
-So idea is simple, we need a set of similar images to average out the noise. Consider a small window (say 5x5 window) in the image. Chance is large that the same patch may be somewhere else in the image. Sometimes in a small neigbourhood around it. What about using these similar patches together and find their average? For that particular window, that is fine. See an example image below:
-
- .. image:: images/nlm_patch.jpg
- :alt: Similar patches
- :align: center
-
-The blue patches in the image looks the similar. Green patches looks similar. So we take a pixel, take small window around it, search for similar windows in the image, average all the windows and replace the pixel with the result we got. This method is Non-Local Means Denoising. It takes more time compared to blurring techniques we saw earlier, but its result is very good. More details and online demo can be found at first link in additional resources.
-
-For color images, image is converted to CIELAB colorspace and then it separately denoise L and AB components.
-
-
-Image Denoising in OpenCV
-===================================
-
-OpenCV provides four variations of this technique.
-
-#. **cv2.fastNlMeansDenoising()** - works with a single grayscale images
-#. **cv2.fastNlMeansDenoisingColored()** - works with a color image.
-#. **cv2.fastNlMeansDenoisingMulti()** - works with image sequence captured in short period of time (grayscale images)
-#. **cv2.fastNlMeansDenoisingColoredMulti()** - same as above, but for color images.
-
-Common arguments are:
- * h : parameter deciding filter strength. Higher h value removes noise better, but removes details of image also. (10 is ok)
- * hForColorComponents : same as h, but for color images only. (normally same as h)
- * templateWindowSize : should be odd. (recommended 7)
- * searchWindowSize : should be odd. (recommended 21)
-
-Please visit first link in additional resources for more details on these parameters.
-
-We will demonstrate 2 and 3 here. Rest is left for you.
-
-
-1. cv2.fastNlMeansDenoisingColored()
-------------------------------------------
-
-As mentioned above it is used to remove noise from color images. (Noise is expected to be gaussian). See the example below:
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- img = cv2.imread('die.png')
-
- dst = cv2.fastNlMeansDenoisingColored(img,None,10,10,7,21)
-
- plt.subplot(121),plt.imshow(img)
- plt.subplot(122),plt.imshow(dst)
- plt.show()
-
-
-Below is a zoomed version of result. My input image has a gaussian noise of :math:`\sigma = 25`. See the result:
-
- .. image:: images/nlm_result1.jpg
- :alt: Result of denoising
- :align: center
-
-
-2. cv2.fastNlMeansDenoisingMulti()
-------------------------------------------
-Now we will apply the same method to a video. The first argument is the list of noisy frames. Second argument `imgToDenoiseIndex` specifies which frame we need to denoise, for that we pass the index of frame in our input list. Third is the `temporalWindowSize` which specifies the number of nearby frames to be used for denoising. It should be odd. In that case, a total of `temporalWindowSize` frames are used where central frame is the frame to be denoised. For example, you passed a list of 5 frames as input. Let `imgToDenoiseIndex = 2` and `temporalWindowSize = 3`. Then frame-1, frame-2 and frame-3 are used to denoise frame-2. Let's see an example.
-::
-
- import numpy as np
- import cv2
- from matplotlib import pyplot as plt
-
- cap = cv2.VideoCapture('vtest.avi')
-
- # create a list of first 5 frames
- img = [cap.read()[1] for i in xrange(5)]
-
- # convert all to grayscale
- gray = [cv2.cvtColor(i, cv2.COLOR_BGR2GRAY) for i in img]
-
- # convert all to float64
- gray = [np.float64(i) for i in gray]
-
- # create a noise of variance 25
- noise = np.random.randn(*gray[1].shape)*10
-
- # Add this noise to images
- noisy = [i+noise for i in gray]
-
- # Convert back to uint8
- noisy = [np.uint8(np.clip(i,0,255)) for i in noisy]
-
- # Denoise 3rd frame considering all the 5 frames
- dst = cv2.fastNlMeansDenoisingMulti(noisy, 2, 5, None, 4, 7, 35)
-
- plt.subplot(131),plt.imshow(gray[2],'gray')
- plt.subplot(132),plt.imshow(noisy[2],'gray')
- plt.subplot(133),plt.imshow(dst,'gray')
- plt.show()
-
-
-Below image shows a zoomed version of the result we got:
-
- .. image:: images/nlm_multi.jpg
- :alt: Denoising a frame
- :align: center
-
-
-It takes considerable amount of time for computation. In the result, first image is the original frame, second is the noisy one, third is the denoised image.
-
-
-Additional Resources
-========================
-
-#. http://www.ipol.im/pub/art/2011/bcm_nlm/ (It has the details, online demo etc. Highly recommended to visit. Our test image is generated from this link)
-
-#. `Online course at coursera <https://www.coursera.org/course/images>`_ (First image taken from here)
-
-Exercises
-============
+++ /dev/null
-.. _PY_Table-Of-Content-Photo:
-
-
-Computational Photography
---------------------------------
-
-Here you will learn different OpenCV functionalities related to Computational Photography like image denoising etc.
-
-
-* :ref:`non_local_means`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |photo_1| See a good technique to remove noises in images called Non-Local Means Denoising
-
- =========== ======================================================
-
- .. |photo_1| image:: images/nlm_icon.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`inpainting`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |photo_2| Do you have a old degraded photo with many black spots and strokes on it? Take it. Let's try to restore them with a technique called image inpainting.
-
- =========== ======================================================
-
- .. |photo_2| image:: images/inpainticon.jpg
- :height: 90pt
- :width: 90pt
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_non_local_means/py_non_local_means
- ../py_inpainting/py_inpainting
+++ /dev/null
-.. _Intro:
-
-
-Introduction to OpenCV-Python Tutorials
-*******************************************
-
-OpenCV
-===============
-
-OpenCV was started at Intel in 1999 by **Gary Bradsky**, and the first release came out in 2000. **Vadim Pisarevsky** joined Gary Bradsky to manage Intel's Russian software OpenCV team. In 2005, OpenCV was used on Stanley, the vehicle that won the 2005 DARPA Grand Challenge. Later, its active development continued under the support of Willow Garage with Gary Bradsky and Vadim Pisarevsky leading the project. OpenCV now supports a multitude of algorithms related to Computer Vision and Machine Learning and is expanding day by day.
-
-OpenCV supports a wide variety of programming languages such as C++, Python, Java, etc., and is available on different platforms including Windows, Linux, OS X, Android, and iOS. Interfaces for high-speed GPU operations based on CUDA and OpenCL are also under active development.
-
-OpenCV-Python is the Python API for OpenCV, combining the best qualities of the OpenCV C++ API and the Python language.
-
-
-OpenCV-Python
-===============
-
-OpenCV-Python is a library of Python bindings designed to solve computer vision problems.
-
-Python is a general purpose programming language started by **Guido van Rossum** that became very popular very quickly, mainly because of its simplicity and code readability. It enables the programmer to express ideas in fewer lines of code without reducing readability.
-
-Compared to languages like C/C++, Python is slower. That said, Python can be easily extended with C/C++, which allows us to write computationally intensive code in C/C++ and create Python wrappers that can be used as Python modules. This gives us two advantages: first, the code is as fast as the original C/C++ code (since it is the actual C++ code working in background) and second, it easier to code in Python than C/C++. OpenCV-Python is a Python wrapper for the original OpenCV C++ implementation.
-
-OpenCV-Python makes use of **Numpy**, which is a highly optimized library for numerical operations with a MATLAB-style syntax. All the OpenCV array structures are converted to and from Numpy arrays. This also makes it easier to integrate with other libraries that use Numpy such as SciPy and Matplotlib.
-
-
-OpenCV-Python Tutorials
-=============================
-
-OpenCV introduces a new set of tutorials which will guide you through various functions available in OpenCV-Python. **This guide is mainly focused on OpenCV 3.x version** (although most of the tutorials will also work with OpenCV 2.x).
-
-Prior knowledge of Python and Numpy is recommended as they won't be covered in this guide. **Proficiency with Numpy is a must in order to write optimized code using OpenCV-Python.**
-
-This tutorial was originally started by *Abid Rahman K.* as part of the Google Summer of Code 2013 program under the guidance of *Alexander Mordvintsev*.
-
-
-OpenCV Needs You !!!
-==========================
-
-Since OpenCV is an open source initiative, all are welcome to make contributions to the library, documentation, and tutorials. If you find any mistake in this tutorial (from a small spelling mistake to an egregious error in code or concept), feel free to correct it by cloning OpenCV in `GitHub <https://github.com/Itseez/opencv>`_ and submitting a pull request. OpenCV developers will check your pull request, give you important feedback and (once it passes the approval of the reviewer) it will be merged into OpenCV. You will then become an open source contributor :-)
-
-As new modules are added to OpenCV-Python, this tutorial will have to be expanded. If you are familiar with a particular algorithm and can write up a tutorial including basic theory of the algorithm and code showing example usage, please do so.
-
-Remember, we **together** can make this project a great success !!!
-
-
-Contributors
-=================
-
-Below is the list of contributors who submitted tutorials to OpenCV-Python.
-
-1. Alexander Mordvintsev (GSoC-2013 mentor)
-2. Abid Rahman K. (GSoC-2013 intern)
-
-
-Additional Resources
-=======================
-
-1. A Quick guide to Python - `A Byte of Python <http://swaroopch.com/notes/python/>`_
-2. `Basic Numpy Tutorials <http://wiki.scipy.org/Tentative_NumPy_Tutorial>`_
-3. `Numpy Examples List <http://wiki.scipy.org/Numpy_Example_List>`_
-4. `OpenCV Documentation <http://docs.opencv.org/>`_
-5. `OpenCV Forum <http://answers.opencv.org/questions/>`_
+++ /dev/null
-.. _Install-OpenCV-Python-in-Fedora:
-
-Install OpenCV-Python in Fedora
-*********************************
-
-Goals
-======
-
-In this tutorial
- * We will learn to setup OpenCV-Python in your Fedora system. Below steps are tested for Fedora 18 (64-bit) and Fedora 19 (32-bit).
-
-Introduction
-==================
-
-OpenCV-Python can be installed in Fedora in two ways, 1) Install from pre-built binaries available in fedora repositories, 2) Compile from the source. In this section, we will see both.
-
-Another important thing is the additional libraries required. OpenCV-Python requires only **Numpy** (in addition to other dependencies, which we will see later). But in this tutorials, we also use **Matplotlib** for some easy and nice plotting purposes (which I feel much better compared to OpenCV). Matplotlib is optional, but highly recommended. Similarly we will also see **IPython**, an Interactive Python Terminal, which is also highly recommended.
-
-
-Installing OpenCV-Python from Pre-built Binaries
-===================================================
-
-Install all packages with following command in terminal as root.
-
- .. code-block:: bash
-
- $ yum install numpy opencv*
-
-Open Python IDLE (or IPython) and type following codes in Python terminal.
-
- .. code-block:: python
-
- >>> import cv2
- >>> print cv2.__version__
-
-If the results are printed out without any errors, congratulations !!! You have installed OpenCV-Python successfully.
-
-It is quite easy. But there is a problem with this. Yum repositories may not contain the latest version of OpenCV always. For example, at the time of writing this tutorial, yum repository contains 2.4.5 while latest OpenCV version is 2.4.6. With respect to Python API, latest version will always contain much better support. Also, there may be chance of problems with camera support, video playback etc depending upon the drivers, ffmpeg, gstreamer packages present etc.
-
-So my personnel preference is next method, i.e. compiling from source. Also at some point of time, if you want to contribute to OpenCV, you will need this.
-
-
-Installing OpenCV from source
-===============================
-
-Compiling from source may seem a little complicated at first, but once you succeeded in it, there is nothing complicated.
-
-First we will install some dependencies. Some are compulsory, some are optional. Optional dependencies, you can leave if you don't want.
-
-
-Compulsory Dependencies
----------------------------
-
-
-We need **CMake** to configure the installation, **GCC** for compilation, **Python-devel** and **Numpy** for creating Python extensions etc.
-
- .. code-block:: bash
-
- yum install cmake
- yum install python-devel numpy
- yum install gcc gcc-c++
-
-
-Next we need **GTK** support for GUI features, Camera support (libdc1394, libv4l), Media Support (ffmpeg, gstreamer) etc.
-
- .. code-block:: bash
-
- yum install gtk2-devel
- yum install libdc1394-devel
- yum install libv4l-devel
- yum install ffmpeg-devel
- yum install gstreamer-plugins-base-devel
-
-
-Optional Dependencies
---------------------------
-
-Above dependencies are sufficient to install OpenCV in your fedora machine. But depending upon your requirements, you may need some extra dependencies. A list of such optional dependencies are given below. You can either leave it or install it, your call :)
-
-OpenCV comes with supporting files for image formats like PNG, JPEG, JPEG2000, TIFF, WebP etc. But it may be a little old. If you want to get latest libraries, you can install development files for these formats.
-
- .. code-block:: bash
-
- yum install libpng-devel
- yum install libjpeg-turbo-devel
- yum install jasper-devel
- yum install openexr-devel
- yum install libtiff-devel
- yum install libwebp-devel
-
-
-Several OpenCV functions are parallelized with **Intel's Threading Building Blocks** (TBB). But if you want to enable it, you need to install TBB first. ( Also while configuring installation with CMake, don't forget to pass ``-D WITH_TBB=ON``. More details below.)
-
- .. code-block:: bash
-
- yum install tbb-devel
-
-OpenCV uses another library **Eigen** for optimized mathematical operations. So if you have Eigen installed in your system, you can exploit it. ( Also while configuring installation with CMake, don't forget to pass ``-D WITH_EIGEN=ON``. More details below.)
-
- .. code-block:: bash
-
- yum install eigen3-devel
-
-If you want to build **documentation** ( *Yes, you can create offline version of OpenCV's complete official documentation in your system in HTML with full search facility so that you need not access internet always if any question, and it is quite FAST!!!* ), you need to install **Sphinx** (a documentation generation tool) and **pdflatex** (if you want to create a PDF version of it). ( Also while configuring installation with CMake, don't forget to pass ``-D BUILD_DOCS=ON``. More details below.)
-
- .. code-block:: bash
-
- yum install python-sphinx
- yum install texlive
-
-
-Downloading OpenCV
------------------------
-
-Next we have to download OpenCV. You can download the latest release of OpenCV from `sourceforge site <http://sourceforge.net/projects/opencvlibrary/>`_. Then extract the folder.
-
-Or you can download latest source from OpenCV's github repo. (If you want to contribute to OpenCV, choose this. It always keeps your OpenCV up-to-date). For that, you need to install **Git** first.
-
- .. code-block:: bash
-
- yum install git
- git clone https://github.com/Itseez/opencv.git
-
-It will create a folder ``OpenCV`` in home directory (or the directory you specify). The cloning may take some time depending upon your internet connection.
-
-Now open a terminal window and navigate to the downloaded OpenCV folder. Create a new ``build`` folder and navigate to it.
-
- .. code-block:: bash
-
- mkdir build
- cd build
-
-
-Configuring and Installing
-----------------------------
-
-Now we have installed all the required dependencies, let's install OpenCV. Installation has to be configured with CMake. It specifies which modules are to be installed, installation path, which additional libraries to be used, whether documentation and examples to be compiled etc. Below command is normally used for configuration (executed from ``build`` folder).
-
- .. code-block:: bash
-
- cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local ..
-
-It specifies that build type is "Release Mode" and installation path is ``/usr/local``. Observe the ``-D`` before each option and ``..`` at the end. In short, this is the format:
-
- .. code-block:: bash
-
- cmake [-D <flag>] [-D <flag>] ..
-
-You can specify as many flags you want, but each flag should be preceded by ``-D``.
-
-So in this tutorial, we are installing OpenCV with TBB and Eigen support. We also build the documentation, but we exclude Performance tests and building samples. We also disable GPU related modules (since we use OpenCV-Python, we don't need GPU related modules. It saves us some time).
-
-*(All the below commands can be done in a single cmake statement, but it is split here for better understanding.)*
-
-* Enable TBB and Eigen support:
-
- .. code-block:: bash
-
- cmake -D WITH_TBB=ON -D WITH_EIGEN=ON ..
-
-* Enable documentation and disable tests and samples
-
- .. code-block:: bash
-
- cmake -D BUILD_DOCS=ON -D BUILD_TESTS=OFF -D BUILD_PERF_TESTS=OFF -D BUILD_EXAMPLES=OFF ..
-
-* Disable all GPU related modules.
-
- .. code-block:: bash
-
- cmake -D WITH_OPENCL=OFF -D WITH_CUDA=OFF -D BUILD_opencv_gpu=OFF -D BUILD_opencv_gpuarithm=OFF -D BUILD_opencv_gpubgsegm=OFF -D BUILD_opencv_gpucodec=OFF -D BUILD_opencv_gpufeatures2d=OFF -D BUILD_opencv_gpufilters=OFF -D BUILD_opencv_gpuimgproc=OFF -D BUILD_opencv_gpulegacy=OFF -D BUILD_opencv_gpuoptflow=OFF -D BUILD_opencv_gpustereo=OFF -D BUILD_opencv_gpuwarping=OFF ..
-
-* Set installation path and build type
-
- .. code-block:: bash
-
- cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local ..
-
-
-Each time you enter cmake statement, it prints out the resulting configuration setup. In the final setup you got, make sure that following fields are filled (below is the some important parts of configuration I got). These fields should be filled appropriately in your system also. Otherwise some problem has happened. So check if you have correctly performed above steps.
-
- .. code-block:: bash
-
- -- GUI:
- -- GTK+ 2.x: YES (ver 2.24.19)
- -- GThread : YES (ver 2.36.3)
-
- -- Video I/O:
- -- DC1394 2.x: YES (ver 2.2.0)
- -- FFMPEG: YES
- -- codec: YES (ver 54.92.100)
- -- format: YES (ver 54.63.104)
- -- util: YES (ver 52.18.100)
- -- swscale: YES (ver 2.2.100)
- -- gentoo-style: YES
- -- GStreamer:
- -- base: YES (ver 0.10.36)
- -- video: YES (ver 0.10.36)
- -- app: YES (ver 0.10.36)
- -- riff: YES (ver 0.10.36)
- -- pbutils: YES (ver 0.10.36)
-
- -- V4L/V4L2: Using libv4l (ver 1.0.0)
-
- -- Other third-party libraries:
- -- Use Eigen: YES (ver 3.1.4)
- -- Use TBB: YES (ver 4.0 interface 6004)
-
- -- Python:
- -- Interpreter: /usr/bin/python2 (ver 2.7.5)
- -- Libraries: /lib/libpython2.7.so (ver 2.7.5)
- -- numpy: /usr/lib/python2.7/site-packages/numpy/core/include (ver 1.7.1)
- -- packages path: lib/python2.7/site-packages
-
- -- Documentation:
- -- Build Documentation: YES
- -- Sphinx: /usr/bin/sphinx-build (ver 1.1.3)
- -- PdfLaTeX compiler: /usr/bin/pdflatex
- --
- -- Tests and samples:
- -- Tests: NO
- -- Performance tests: NO
- -- C/C++ Examples: NO
-
-
-Many other flags and settings are there. It is left for you for further exploration.
-
-Now you build the files using ``make`` command and install it using ``make install`` command. ``make install`` should be executed as root.
-
- .. code-block:: bash
-
- make
- su
- make install
-
-Installation is over. All files are installed in ``/usr/local/`` folder. But to use it, your Python should be able to find OpenCV module. You have two options for that.
-
-1. **Move the module to any folder in Python Path** : Python path can be found out by entering ``import sys;print sys.path`` in Python terminal. It will print out many locations. Move ``/usr/local/lib/python2.7/site-packages/cv2.so`` to any of this folder. For example,
-
- .. code-block:: bash
-
- su mv /usr/local/lib/python2.7/site-packages/cv2.so /usr/lib/python2.7/site-packages
-
-But you will have to do this every time you install OpenCV.
-
-2. **Add ``/usr/local/lib/python2.7/site-packages`` to the PYTHON_PATH**: It is to be done only once. Just open ``~/.bashrc`` and add following line to it, then log out and come back.
-
- .. code-block:: bash
-
- export PYTHONPATH=$PYTHONPATH:/usr/local/lib/python2.7/site-packages
-
-Thus OpenCV installation is finished. Open a terminal and try ``import cv2``.
-
-To build the documentation, just enter following commands:
-
- .. code-block:: bash
-
- make docs
- make html_docs
-
-Then open ``opencv/build/doc/_html/index.html`` and bookmark it in the browser.
-
-
-Additional Resources
-========================
-
-Exercises
-===============
-
-1. Compile OpenCV from source in your Fedora machine.
+++ /dev/null
-.. _Install-OpenCV-Python-in-Windows:
-
-Install OpenCV-Python in Windows
-*********************************
-
-Goals
-======
-
-In this tutorial
- * We will learn to setup OpenCV-Python in your Windows system.
-
-*Below steps are tested in a Windows 7-64 bit machine with Visual Studio 2010 and Visual Studio 2012. The screenshots shows VS2012.*
-
-Installing OpenCV from prebuilt binaries
-=========================================
-
-1. Below Python packages are to be downloaded and installed to their default locations.
-
- 1.1. `Python-2.7.x <http://python.org/ftp/python/2.7.5/python-2.7.5.msi>`_.
-
- 1.2. `Numpy <http://sourceforge.net/projects/numpy/files/NumPy/1.7.1/numpy-1.7.1-win32-superpack-python2.7.exe/download>`_.
-
- 1.3. `Matplotlib <https://downloads.sourceforge.net/project/matplotlib/matplotlib/matplotlib-1.3.0/matplotlib-1.3.0.win32-py2.7.exe>`_ (*Matplotlib is optional, but recommended since we use it a lot in our tutorials*).
-
-2. Install all packages into their default locations. Python will be installed to **C:/Python27/**.
-
-3. After installation, open Python IDLE. Enter ``import numpy`` and make sure Numpy is working fine.
-
-4. Download latest OpenCV release from `sourceforge site <http://sourceforge.net/projects/opencvlibrary/files/opencv-win/2.4.6/OpenCV-2.4.6.0.exe/download>`_ and double-click to extract it.
-
-7. Goto **opencv/build/python/2.7** folder.
-
-8. Copy **cv2.pyd** to **C:/Python27/lib/site-packages**.
-
-9. Open Python IDLE and type following codes in Python terminal.
-
- >>> import cv2
- >>> print cv2.__version__
-
-If the results are printed out without any errors, congratulations !!! You have installed OpenCV-Python successfully.
-
-
-Building OpenCV from source
-===============================
-1. Download and install Visual Studio and CMake.
-
- 1.1. `Visual Studio 2012 <http://go.microsoft.com/?linkid=9816768>`_
-
- 1.2. `CMake <http://www.cmake.org/files/v2.8/cmake-2.8.11.2-win32-x86.exe>`_
-
-2. Download and install necessary Python packages to their default locations
-
- 2.1. `Python 2.7.x <http://python.org/ftp/python/2.7.5/python-2.7.5.msi>`_
-
- 2.2. `Numpy <http://sourceforge.net/projects/numpy/files/NumPy/1.7.1/numpy-1.7.1-win32-superpack-python2.7.exe/download>`_
-
- 2.3. `Matplotlib <https://downloads.sourceforge.net/project/matplotlib/matplotlib/matplotlib-1.3.0/matplotlib-1.3.0.win32-py2.7.exe>`_ (*Matplotlib is optional, but recommended since we use it a lot in our tutorials.*)
-
-.. note:: In this case, we are using 32-bit binaries of Python packages. But if you want to use OpenCV for x64, 64-bit binaries of Python packages are to be installed. Problem is that, there is no official 64-bit binaries of Numpy. You have to build it on your own. For that, you have to use the same compiler used to build Python. When you start Python IDLE, it shows the compiler details. You can get more `information here <http://stackoverflow.com/q/2676763/1134940>`_. So your system must have the same Visual Studio version and build Numpy from source.
-
-.. note:: Another method to have 64-bit Python packages is to use ready-made Python distributions from third-parties like `Anaconda <http://www.continuum.io/downloads>`_, `Enthought <https://www.enthought.com/downloads/>`_ etc. It will be bigger in size, but will have everything you need. Everything in a single shell. You can also download 32-bit versions also.
-
-3. Make sure Python and Numpy are working fine.
-
-4. Download OpenCV source. It can be from `Sourceforge <http://sourceforge.net/projects/opencvlibrary/>`_ (for official release version) or from `Github <https://github.com/Itseez/opencv>`_ (for latest source).
-
-5. Extract it to a folder, ``opencv`` and create a new folder ``build`` in it.
-
-6. Open CMake-gui (*Start > All Programs > CMake-gui*)
-
-7. Fill the fields as follows (see the image below):
-
- 7.1. Click on **Browse Source...** and locate the ``opencv`` folder.
-
- 7.2. Click on **Browse Build...** and locate the ``build`` folder we created.
-
- 7.3. Click on **Configure**.
-
- .. image:: images/Capture1.jpg
- :alt: capture1
- :align: center
-
-
- 7.4. It will open a new window to select the compiler. Choose appropriate compiler (here, Visual Studio 11) and click **Finish**.
-
- .. image:: images/Capture2.png
- :alt: capture2
- :align: center
-
-
- 7.5. Wait until analysis is finished.
-
-8. You will see all the fields are marked in red. Click on the **WITH** field to expand it. It decides what extra features you need. So mark appropriate fields. See the below image:
-
- .. image:: images/Capture3.png
- :alt: capture3
- :align: center
-
-
-9. Now click on **BUILD** field to expand it. First few fields configure the build method. See the below image:
-
- .. image:: images/Capture5.png
- :alt: capture5
- :align: center
-
-
-10. Remaining fields specify what modules are to be built. Since GPU modules are not yet supported by OpenCV-Python, you can completely avoid it to save time (But if you work with them, keep it there). See the image below:
-
- .. image:: images/Capture6.png
- :alt: capture6
- :align: center
-
-
-11. Now click on **ENABLE** field to expand it. Make sure **ENABLE_SOLUTION_FOLDERS** is unchecked (Solution folders are not supported by Visual Studio Express edition). See the image below:
-
- .. image:: images/Capture7.png
- :alt: capture7
- :align: center
-
-
-12. Also make sure that in the **PYTHON** field, everything is filled. (Ignore PYTHON_DEBUG_LIBRARY). See image below:
-
- .. image:: images/Capture80.png
- :alt: capture80
- :align: center
-
-
-13. Finally click the **Generate** button.
-
-14. Now go to our **opencv/build** folder. There you will find **OpenCV.sln** file. Open it with Visual Studio.
-
-15. Check build mode as **Release** instead of **Debug**.
-
-16. In the solution explorer, right-click on the **Solution** (or **ALL_BUILD**) and build it. It will take some time to finish.
-
-17. Again, right-click on **INSTALL** and build it. Now OpenCV-Python will be installed.
-
- .. image:: images/Capture8.png
- :alt: capture8
- :align: center
-
-
-18. Open Python IDLE and enter ``import cv2``. If no error, it is installed correctly.
-
-.. note:: We have installed with no other support like TBB, Eigen, Qt, Documentation etc. It would be difficult to explain it here. A more detailed video will be added soon or you can just hack around.
-
-
-Additional Resources
-==========================
-
-
-Exercises
-============
-
-1. If you have a windows machine, compile the OpenCV from source. Do all kinds of hacks. If you meet any problem, visit OpenCV forum and explain your problem.
+++ /dev/null
-.. _PY_Table-Of-Content-Setup:
-
-Introduction to OpenCV
------------------------------------------------------------
-
-* :ref:`Intro`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |Intro_1| Getting Started with OpenCV-Python
-
- =========== ======================================================
-
- .. |Intro_1| image:: images/opencv_logo.jpg
- :height: 90pt
- :width: 90pt
-
-
-
-* :ref:`Install-OpenCV-Python-in-Windows`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |Install_1| Set Up OpenCV-Python in Windows
-
- =========== ======================================================
-
- .. |Install_1| image:: images/windows_logo.jpg
- :height: 90pt
- :width: 90pt
-
-* :ref:`Install-OpenCV-Python-in-Fedora`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |Install_2| Set Up OpenCV-Python in Fedora
-
- =========== ======================================================
-
- .. |Install_2| image:: images/fedora_logo.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_intro/py_intro
- ../py_setup_in_windows/py_setup_in_windows
- ../py_setup_in_fedora/py_setup_in_fedora
+++ /dev/null
-#######################
-OpenCV-Python Tutorials
-#######################
-
-* :ref:`PY_Table-Of-Content-Setup`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Introduct| Learn how to setup OpenCV-Python on your computer!
-
- =========== =======================================================
-
- .. |Introduct| image:: images/intro.png
- :height: 80pt
- :width: 80pt
- :alt: Introduction Icon
-
-* :ref:`PY_Table-Of-Content-Gui`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Gui| Here you will learn how to display and save images and videos, control mouse events and create trackbar.
- =========== =======================================================
-
- .. |Gui| image:: images/gui.jpg
- :height: 80pt
- :width: 80pt
- :alt: gui Icon
-
-* :ref:`PY_Table-Of-Content-Core`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Core| In this section you will learn basic operations on image like pixel editing, geometric transformations, code optimization, some mathematical tools etc.
-
- =========== =======================================================
-
- .. |Core| image:: images/core.jpg
- :height: 80pt
- :width: 80pt
- :alt: core Icon
-
-
-* :ref:`PY_Table-Of-Content-ImgProc`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |ImgProc| In this section you will learn different image processing functions inside OpenCV.
-
- =========== =======================================================
-
- .. |ImgProc| image:: images/imgproc.jpg
- :height: 80pt
- :width: 80pt
- :alt: imgproc Icon
-
-* :ref:`PY_Table-Of-Content-Feature2D`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Feature2D| In this section you will learn about feature detectors and descriptors
-
- =========== =======================================================
-
- .. |Feature2D| image:: images/featureicon.jpg
- :height: 80pt
- :width: 80pt
- :alt: imgproc Icon
-
-
-* :ref:`PY_Table-Of-Content-Video`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Video| In this section you will learn different techniques to work with videos like object tracking etc.
-
- =========== =======================================================
-
- .. |Video| image:: images/videoicon.jpg
- :height: 80pt
- :width: 80pt
- :alt: imgproc Icon
-
-
-* :ref:`PY_Table-Of-Content-Calib`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Calib| In this section we will learn about camera calibration, stereo imaging etc.
-
- =========== =======================================================
-
- .. |Calib| image:: images/calib3d_icon.jpg
- :height: 80pt
- :width: 80pt
- :alt: Calib Icon
-
-
-
-* :ref:`PY_Table-Of-Content-ML`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |ML| In this section you will learn different image processing functions inside OpenCV.
-
- =========== =======================================================
-
- .. |ML| image:: images/MachineLearnings.jpg
- :height: 80pt
- :width: 80pt
- :alt: ML Icon
-
-
-* :ref:`PY_Table-Of-Content-Photo`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Photo| In this section you will learn different computational photography techniques like image denoising etc.
-
- =========== =======================================================
-
- .. |Photo| image:: images/photoicon.jpg
- :height: 80pt
- :width: 80pt
- :alt: ML Icon
-
-
-* :ref:`PY_Table-Of-Content-Objdetection`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Objde| In this section you will object detection techniques like face detection etc.
-
- =========== =======================================================
-
- .. |Objde| image:: images/obj_icon.jpg
- :height: 80pt
- :width: 80pt
- :alt: OD Icon
-
-
-* :ref:`PY_Table-Of-Content-Bindings`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =====================================================================
- |PyBin| In this section, we will see how OpenCV-Python bindings are generated
-
- =========== =====================================================================
-
- .. |PyBin| image:: images/obj_icon.jpg
- :height: 80pt
- :width: 80pt
- :alt: OD Icon
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :maxdepth: 2
- :hidden:
-
- py_setup/py_table_of_contents_setup/py_table_of_contents_setup
- py_gui/py_table_of_contents_gui/py_table_of_contents_gui
- py_core/py_table_of_contents_core/py_table_of_contents_core
- py_imgproc/py_table_of_contents_imgproc/py_table_of_contents_imgproc
- py_feature2d/py_table_of_contents_feature2d/py_table_of_contents_feature2d
- py_video/py_table_of_contents_video/py_table_of_contents_video
- py_calib3d/py_table_of_contents_calib3d/py_table_of_contents_calib3d
- py_ml/py_table_of_contents_ml/py_table_of_contents_ml
- py_photo/py_table_of_contents_photo/py_table_of_contents_photo
- py_objdetect/py_table_of_contents_objdetect/py_table_of_contents_objdetect
- py_bindings/py_table_of_contents_bindings/py_table_of_contents_bindings
+++ /dev/null
-.. _py_background_subtraction:
-
-
-Background Subtraction
-****************************
-
-Goal
-=======
-
-In this chapter,
-
- * We will familiarize with the background subtraction methods available in OpenCV.
-
-Basics
-=============
-
-Background subtraction is a major preprocessing steps in many vision based applications. For example, consider the cases like visitor counter where a static camera takes the number of visitors entering or leaving the room, or a traffic camera extracting information about the vehicles etc. In all these cases, first you need to extract the person or vehicles alone. Technically, you need to extract the moving foreground from static background.
-
-If you have an image of background alone, like image of the room without visitors, image of the road without vehicles etc, it is an easy job. Just subtract the new image from the background. You get the foreground objects alone. But in most of the cases, you may not have such an image, so we need to extract the background from whatever images we have. It become more complicated when there is shadow of the vehicles. Since shadow is also moving, simple subtraction will mark that also as foreground. It complicates things.
-
-Several algorithms were introduced for this purpose. OpenCV has implemented three such algorithms which is very easy to use. We will see them one-by-one.
-
-
-BackgroundSubtractorMOG
------------------------------------
-
-It is a Gaussian Mixture-based Background/Foreground Segmentation Algorithm. It was introduced in the paper "An improved adaptive background mixture model for real-time tracking with shadow detection" by P. KadewTraKuPong and R. Bowden in 2001. It uses a method to model each background pixel by a mixture of K Gaussian distributions (K = 3 to 5). The weights of the mixture represent the time proportions that those colours stay in the scene. The probable background colours are the ones which stay longer and more static.
-
-While coding, we need to create a background object using the function, **cv2.createBackgroundSubtractorMOG()**. It has some optional parameters like length of history, number of gaussian mixtures, threshold etc. It is all set to some default values. Then inside the video loop, use ``backgroundsubtractor.apply()`` method to get the foreground mask.
-
-See a simple example below:
-::
-
- import numpy as np
- import cv2
-
- cap = cv2.VideoCapture('vtest.avi')
-
- fgbg = cv2.createBackgroundSubtractorMOG()
-
- while(1):
- ret, frame = cap.read()
-
- fgmask = fgbg.apply(frame)
-
- cv2.imshow('frame',fgmask)
- k = cv2.waitKey(30) & 0xff
- if k == 27:
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-
-( All the results are shown at the end for comparison).
-
-
-BackgroundSubtractorMOG2
-------------------------------------
-
-It is also a Gaussian Mixture-based Background/Foreground Segmentation Algorithm. It is based on two papers by Z.Zivkovic, "Improved adaptive Gausian mixture model for background subtraction" in 2004 and "Efficient Adaptive Density Estimation per Image Pixel for the Task of Background Subtraction" in 2006. One important feature of this algorithm is that it selects the appropriate number of gaussian distribution for each pixel. (Remember, in last case, we took a K gaussian distributions throughout the algorithm). It provides better adaptibility to varying scenes due illumination changes etc.
-
-As in previous case, we have to create a background subtractor object. Here, you have an option of selecting whether shadow to be detected or not. If ``detectShadows = True`` (which is so by default), it detects and marks shadows, but decreases the speed. Shadows will be marked in gray color.
-::
-
- import numpy as np
- import cv2
-
- cap = cv2.VideoCapture('vtest.avi')
-
- fgbg = cv2.createBackgroundSubtractorMOG2()
-
- while(1):
- ret, frame = cap.read()
-
- fgmask = fgbg.apply(frame)
-
- cv2.imshow('frame',fgmask)
- k = cv2.waitKey(30) & 0xff
- if k == 27:
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-(Results given at the end)
-
-
-BackgroundSubtractorGMG
------------------------------------
-
-This algorithm combines statistical background image estimation and per-pixel Bayesian segmentation. It was introduced by Andrew B. Godbehere, Akihiro Matsukawa, Ken Goldberg in their paper "Visual Tracking of Human Visitors under Variable-Lighting Conditions for a Responsive Audio Art Installation" in 2012. As per the paper, the system ran a successful interactive audio art installation called “Are We There Yet?” from March 31 - July 31 2011 at the Contemporary Jewish Museum in San Francisco, California.
-
-It uses first few (120 by default) frames for background modelling. It employs probabilistic foreground segmentation algorithm that identifies possible foreground objects using Bayesian inference. The estimates are adaptive; newer observations are more heavily weighted than old observations to accommodate variable illumination. Several morphological filtering operations like closing and opening are done to remove unwanted noise. You will get a black window during first few frames.
-
-It would be better to apply morphological opening to the result to remove the noises.
-::
-
- import numpy as np
- import cv2
-
- cap = cv2.VideoCapture('vtest.avi')
-
- kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE,(3,3))
- fgbg = cv2.createBackgroundSubtractorGMG()
-
- while(1):
- ret, frame = cap.read()
-
- fgmask = fgbg.apply(frame)
- fgmask = cv2.morphologyEx(fgmask, cv2.MORPH_OPEN, kernel)
-
- cv2.imshow('frame',fgmask)
- k = cv2.waitKey(30) & 0xff
- if k == 27:
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-
-Results
-===========
-
-
-**Original Frame**
-
-Below image shows the 200th frame of a video
-
- .. image:: images/resframe.jpg
- :alt: Original frame
- :align: center
-
-**Result of BackgroundSubtractorMOG**
-
- .. image:: images/resmog.jpg
- :alt: Result of BackgroundSubtractorMOG
- :align: center
-
-**Result of BackgroundSubtractorMOG2**
-
-Gray color region shows shadow region.
-
- .. image:: images/resmog2.jpg
- :alt: Result of BackgroundSubtractorMOG2
- :align: center
-
-**Result of BackgroundSubtractorGMG**
-
-Noise is removed with morphological opening.
-
- .. image:: images/resgmg.jpg
- :alt: Result of BackgroundSubtractorGMG
- :align: center
-
-
-Additional Resources
-=============================
-
-
-Exercises
-=================
+++ /dev/null
-.. _Lucas_Kanade:
-
-
-Optical Flow
-*********************************************
-
-Goal
-=======
-
-In this chapter,
- * We will understand the concepts of optical flow and its estimation using Lucas-Kanade method.
- * We will use functions like **cv2.calcOpticalFlowPyrLK()** to track feature points in a video.
-
-
-Optical Flow
-================
-
-Optical flow is the pattern of apparent motion of image objects between two consecutive frames caused by the movemement of object or camera. It is 2D vector field where each vector is a displacement vector showing the movement of points from first frame to second. Consider the image below (Image Courtesy: `Wikipedia article on Optical Flow <http://en.wikipedia.org/wiki/Optical_flow>`_).
-
-
- .. image:: images/optical_flow_basic1.jpg
- :alt: Optical Flow
- :align: center
-
-It shows a ball moving in 5 consecutive frames. The arrow shows its displacement vector. Optical flow has many applications in areas like :
-
- * Structure from Motion
- * Video Compression
- * Video Stabilization ...
-
-Optical flow works on several assumptions:
-
-1. The pixel intensities of an object do not change between consecutive frames.
-2. Neighbouring pixels have similar motion.
-
-Consider a pixel :math:`I(x,y,t)` in first frame (Check a new dimension, time, is added here. Earlier we were working with images only, so no need of time). It moves by distance :math:`(dx,dy)` in next frame taken after :math:`dt` time. So since those pixels are the same and intensity does not change, we can say,
-
-.. math::
-
- I(x,y,t) = I(x+dx, y+dy, t+dt)
-
-Then take taylor series approximation of right-hand side, remove common terms and divide by :math:`dt` to get the following equation:
-
-.. math::
-
- f_x u + f_y v + f_t = 0 \;
-
-where:
-
-.. math::
-
- f_x = \frac{\partial f}{\partial x} \; ; \; f_y = \frac{\partial f}{\partial x}
-
- u = \frac{dx}{dt} \; ; \; v = \frac{dy}{dt}
-
-
-Above equation is called Optical Flow equation. In it, we can find :math:`f_x` and :math:`f_y`, they are image gradients. Similarly :math:`f_t` is the gradient along time. But :math:`(u,v)` is unknown. We cannot solve this one equation with two unknown variables. So several methods are provided to solve this problem and one of them is Lucas-Kanade.
-
-Lucas-Kanade method
--------------------------
-
-We have seen an assumption before, that all the neighbouring pixels will have similar motion. Lucas-Kanade method takes a 3x3 patch around the point. So all the 9 points have the same motion. We can find :math:`(f_x, f_y, f_t)` for these 9 points. So now our problem becomes solving 9 equations with two unknown variables which is over-determined. A better solution is obtained with least square fit method. Below is the final solution which is two equation-two unknown problem and solve to get the solution.
-
-.. math::
-
- \begin{bmatrix} u \\ v \end{bmatrix} =
- \begin{bmatrix}
- \sum_{i}{f_{x_i}}^2 & \sum_{i}{f_{x_i} f_{y_i} } \\
- \sum_{i}{f_{x_i} f_{y_i}} & \sum_{i}{f_{y_i}}^2
- \end{bmatrix}^{-1}
- \begin{bmatrix}
- - \sum_{i}{f_{x_i} f_{t_i}} \\
- - \sum_{i}{f_{y_i} f_{t_i}}
- \end{bmatrix}
-
-
-( Check similarity of inverse matrix with Harris corner detector. It denotes that corners are better points to be tracked.)
-
-So from user point of view, idea is simple, we give some points to track, we receive the optical flow vectors of those points. But again there are some problems. Until now, we were dealing with small motions. So it fails when there is large motion. So again we go for pyramids. When we go up in the pyramid, small motions are removed and large motions becomes small motions. So applying Lucas-Kanade there, we get optical flow along with the scale.
-
-
-Lucas-Kanade Optical Flow in OpenCV
-=======================================
-
-OpenCV provides all these in a single function, **cv2.calcOpticalFlowPyrLK()**. Here, we create a simple application which tracks some points in a video. To decide the points, we use **cv2.goodFeaturesToTrack()**. We take the first frame, detect some Shi-Tomasi corner points in it, then we iteratively track those points using Lucas-Kanade optical flow. For the function **cv2.calcOpticalFlowPyrLK()** we pass the previous frame, previous points and next frame. It returns next points along with some status numbers which has a value of 1 if next point is found, else zero. We iteratively pass these next points as previous points in next step. See the code below:
-::
-
- import numpy as np
- import cv2
-
- cap = cv2.VideoCapture('slow.flv')
-
- # params for ShiTomasi corner detection
- feature_params = dict( maxCorners = 100,
- qualityLevel = 0.3,
- minDistance = 7,
- blockSize = 7 )
-
- # Parameters for lucas kanade optical flow
- lk_params = dict( winSize = (15,15),
- maxLevel = 2,
- criteria = (cv2.TERM_CRITERIA_EPS | cv2.TERM_CRITERIA_COUNT, 10, 0.03))
-
- # Create some random colors
- color = np.random.randint(0,255,(100,3))
-
- # Take first frame and find corners in it
- ret, old_frame = cap.read()
- old_gray = cv2.cvtColor(old_frame, cv2.COLOR_BGR2GRAY)
- p0 = cv2.goodFeaturesToTrack(old_gray, mask = None, **feature_params)
-
- # Create a mask image for drawing purposes
- mask = np.zeros_like(old_frame)
-
- while(1):
- ret,frame = cap.read()
- frame_gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
-
- # calculate optical flow
- p1, st, err = cv2.calcOpticalFlowPyrLK(old_gray, frame_gray, p0, None, **lk_params)
-
- # Select good points
- good_new = p1[st==1]
- good_old = p0[st==1]
-
- # draw the tracks
- for i,(new,old) in enumerate(zip(good_new,good_old)):
- a,b = new.ravel()
- c,d = old.ravel()
- mask = cv2.line(mask, (a,b),(c,d), color[i].tolist(), 2)
- frame = cv2.circle(frame,(a,b),5,color[i].tolist(),-1)
- img = cv2.add(frame,mask)
-
- cv2.imshow('frame',img)
- k = cv2.waitKey(30) & 0xff
- if k == 27:
- break
-
- # Now update the previous frame and previous points
- old_gray = frame_gray.copy()
- p0 = good_new.reshape(-1,1,2)
-
- cv2.destroyAllWindows()
- cap.release()
-
-
-(This code doesn't check how correct are the next keypoints. So even if any feature point disappears in image, there is a chance that optical flow finds the next point which may look close to it. So actually for a robust tracking, corner points should be detected in particular intervals. OpenCV samples comes up with such a sample which finds the feature points at every 5 frames. It also run a backward-check of the optical flow points got to select only good ones. Check ``samples/python2/lk_track.py``).
-
-See the results we got:
-
- .. image:: images/opticalflow_lk.jpg
- :alt: Lucas-Kanade method for optical flow
- :align: center
-
-
-Dense Optical Flow in OpenCV
-==============================
-
-Lucas-Kanade method computes optical flow for a sparse feature set (in our example, corners detected using Shi-Tomasi algorithm). OpenCV provides another algorithm to find the dense optical flow. It computes the optical flow for all the points in the frame. It is based on Gunner Farneback's algorithm which is explained in "Two-Frame Motion Estimation Based on Polynomial Expansion" by Gunner Farneback in 2003.
-
-Below sample shows how to find the dense optical flow using above algorithm. We get a 2-channel array with optical flow vectors, :math:`(u,v)`. We find their magnitude and direction. We color code the result for better visualization. Direction corresponds to Hue value of the image. Magnitude corresponds to Value plane. See the code below:
-::
-
- import cv2
- import numpy as np
- cap = cv2.VideoCapture("vtest.avi")
-
- ret, frame1 = cap.read()
- prvs = cv2.cvtColor(frame1,cv2.COLOR_BGR2GRAY)
- hsv = np.zeros_like(frame1)
- hsv[...,1] = 255
-
- while(1):
- ret, frame2 = cap.read()
- next = cv2.cvtColor(frame2,cv2.COLOR_BGR2GRAY)
-
- flow = cv2.calcOpticalFlowFarneback(prvs,next, None, 0.5, 3, 15, 3, 5, 1.2, 0)
-
- mag, ang = cv2.cartToPolar(flow[...,0], flow[...,1])
- hsv[...,0] = ang*180/np.pi/2
- hsv[...,2] = cv2.normalize(mag,None,0,255,cv2.NORM_MINMAX)
- rgb = cv2.cvtColor(hsv,cv2.COLOR_HSV2BGR)
-
- cv2.imshow('frame2',rgb)
- k = cv2.waitKey(30) & 0xff
- if k == 27:
- break
- elif k == ord('s'):
- cv2.imwrite('opticalfb.png',frame2)
- cv2.imwrite('opticalhsv.png',rgb)
- prvs = next
-
- cap.release()
- cv2.destroyAllWindows()
-
-See the result below:
-
- .. image:: images/opticalfb.jpg
- :alt: Dense Optical Flow
- :align: center
-
-OpenCV comes with a more advanced sample on dense optical flow, please see ``samples/python2/opt_flow.py``.
-
-Additional Resources
-========================
-
-
-Exercises
-===========
-
-#. Check the code in ``samples/python2/lk_track.py``. Try to understand the code.
-#. Check the code in ``samples/python2/opt_flow.py``. Try to understand the code.
+++ /dev/null
-.. _meanshift:
-
-
-Meanshift and Camshift
-****************************
-
-
-Goal
-========
-
-In this chapter,
-
- * We will learn about Meanshift and Camshift algorithms to find and track objects in videos.
-
-
-Meanshift
-============
-
-The intuition behind the meanshift is simple. Consider you have a set of points. (It can be a pixel distribution like histogram backprojection). You are given a small window (maybe a circle) and you have to move that window to the area of maximum pixel density (or maximum number of points). It is illustrated in the simple image given below:
-
- .. image:: images/meanshift_basics.jpg
- :alt: Intuition behind meanshift
- :align: center
-
-
-The initial window is shown in blue circle with the name "C1". Its original center is marked in blue rectangle, named "C1_o". But if you find the centroid of the points inside that window, you will get the point "C1_r" (marked in small blue circle) which is the real centroid of window. Surely they don't match. So move your window such that circle of the new window matches with previous centroid. Again find the new centroid. Most probably, it won't match. So move it again, and continue the iterations such that center of window and its centroid falls on the same location (or with a small desired error). So finally what you obtain is a window with maximum pixel distribution. It is marked with green circle, named "C2". As you can see in image, it has maximum number of points. The whole process is demonstrated on a static image below:
-
- .. image:: images/meanshift_face.gif
- :alt: Meanshift on static image
- :align: center
-
-So we normally pass the histogram backprojected image and initial target location. When the object moves, obviously the movement is reflected in histogram backprojected image. As a result, meanshift algorithm moves our window to the new location with maximum density.
-
-
-Meanshift in OpenCV
----------------------
-
-To use meanshift in OpenCV, first we need to setup the target, find its histogram so that we can backproject the target on each frame for calculation of meanshift. We also need to provide initial location of window. For histogram, only Hue is considered here. Also, to avoid false values due to low light, low light values are discarded using **cv2.inRange()** function.
-::
-
- import numpy as np
- import cv2
-
- cap = cv2.VideoCapture('slow.flv')
-
- # take first frame of the video
- ret,frame = cap.read()
-
- # setup initial location of window
- r,h,c,w = 250,90,400,125 # simply hardcoded the values
- track_window = (c,r,w,h)
-
- # set up the ROI for tracking
- roi = frame[r:r+h, c:c+w]
- hsv_roi = cv2.cvtColor(roi, cv2.COLOR_BGR2HSV)
- mask = cv2.inRange(hsv_roi, np.array((0., 60.,32.)), np.array((180.,255.,255.)))
- roi_hist = cv2.calcHist([hsv_roi],[0],mask,[180],[0,180])
- cv2.normalize(roi_hist,roi_hist,0,255,cv2.NORM_MINMAX)
-
- # Setup the termination criteria, either 10 iteration or move by atleast 1 pt
- term_crit = ( cv2.TERM_CRITERIA_EPS | cv2.TERM_CRITERIA_COUNT, 10, 1 )
-
- while(1):
- ret ,frame = cap.read()
-
- if ret == True:
- hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)
- dst = cv2.calcBackProject([hsv],[0],roi_hist,[0,180],1)
-
- # apply meanshift to get the new location
- ret, track_window = cv2.meanShift(dst, track_window, term_crit)
-
- # Draw it on image
- x,y,w,h = track_window
- img2 = cv2.rectangle(frame, (x,y), (x+w,y+h), 255,2)
- cv2.imshow('img2',img2)
-
- k = cv2.waitKey(60) & 0xff
- if k == 27:
- break
- else:
- cv2.imwrite(chr(k)+".jpg",img2)
-
- else:
- break
-
- cv2.destroyAllWindows()
- cap.release()
-
-
-Three frames in a video I used is given below:
-
- .. image:: images/meanshift_result.jpg
- :alt: Meanshift result
- :align: center
-
-
-Camshift
-============
-
-Did you closely watch the last result? There is a problem. Our window always has the same size when car is farther away and it is very close to camera. That is not good. We need to adapt the window size with size and rotation of the target. Once again, the solution came from "OpenCV Labs" and it is called CAMshift (Continuously Adaptive Meanshift) published by Gary Bradsky in his paper "Computer Vision Face Tracking for Use in a Perceptual User Interface" in 1988.
-
-It applies meanshift first. Once meanshift converges, it updates the size of the window as, :math:`s = 2 \times \sqrt{\frac{M_{00}}{256}}`. It also calculates the orientation of best fitting ellipse to it. Again it applies the meanshift with new scaled search window and previous window location. The process is continued until required accuracy is met.
-
- .. image:: images/camshift_face.gif
- :alt: Meanshift on static image
- :align: center
-
-
-Camshift in OpenCV
----------------------
-
-It is almost same as meanshift, but it returns a rotated rectangle (that is our result) and box parameters (used to be passed as search window in next iteration). See the code below:
-::
-
- import numpy as np
- import cv2
-
- cap = cv2.VideoCapture('slow.flv')
-
- # take first frame of the video
- ret,frame = cap.read()
-
- # setup initial location of window
- r,h,c,w = 250,90,400,125 # simply hardcoded the values
- track_window = (c,r,w,h)
-
- # set up the ROI for tracking
- roi = frame[r:r+h, c:c+w]
- hsv_roi = cv2.cvtColor(roi, cv2.COLOR_BGR2HSV)
- mask = cv2.inRange(hsv_roi, np.array((0., 60.,32.)), np.array((180.,255.,255.)))
- roi_hist = cv2.calcHist([hsv_roi],[0],mask,[180],[0,180])
- cv2.normalize(roi_hist,roi_hist,0,255,cv2.NORM_MINMAX)
-
- # Setup the termination criteria, either 10 iteration or move by atleast 1 pt
- term_crit = ( cv2.TERM_CRITERIA_EPS | cv2.TERM_CRITERIA_COUNT, 10, 1 )
-
- while(1):
- ret ,frame = cap.read()
-
- if ret == True:
- hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)
- dst = cv2.calcBackProject([hsv],[0],roi_hist,[0,180],1)
-
- # apply meanshift to get the new location
- ret, track_window = cv2.CamShift(dst, track_window, term_crit)
-
- # Draw it on image
- pts = cv2.boxPoints(ret)
- pts = np.int0(pts)
- img2 = cv2.polylines(frame,[pts],True, 255,2)
- cv2.imshow('img2',img2)
-
- k = cv2.waitKey(60) & 0xff
- if k == 27:
- break
- else:
- cv2.imwrite(chr(k)+".jpg",img2)
-
- else:
- break
-
- cv2.destroyAllWindows()
- cap.release()
-
-Three frames of the result is shown below:
-
- .. image:: images/camshift_result.jpg
- :alt: Camshift result
- :align: center
-
-
-Additional Resources
-=============================
-
-#. French Wikipedia page on `Camshift <http://fr.wikipedia.org/wiki/Camshift>`_. (The two animations are taken from here)
-
-#. Bradski, G.R., "Real time face and object tracking as a component of a perceptual user interface," Applications of Computer Vision, 1998. WACV '98. Proceedings., Fourth IEEE Workshop on , vol., no., pp.214,219, 19-21 Oct 1998
-
-
-Exercises
-===============
-
-#. OpenCV comes with a Python sample on interactive demo of camshift. Use it, hack it, understand it.
+++ /dev/null
-.. _PY_Table-Of-Content-Video:
-
-Video Analysis
-------------------------------------------
-
-* :ref:`meanshift`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |vdo_1| We have already seen an example of color-based tracking. It is simpler. This time, we see significantly better algorithms like "Meanshift", and its upgraded version, "Camshift" to find and track them.
-
- =========== ======================================================
-
- .. |vdo_1| image:: images/camshift.jpg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`Lucas_Kanade`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |vdo_2| Now let's discuss an important concept, "Optical Flow", which is related to videos and has many applications.
- =========== ======================================================
-
- .. |vdo_2| image:: images/opticalflow.jpeg
- :height: 90pt
- :width: 90pt
-
-
-* :ref:`py_background_subtraction`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |vdo_b| In several applications, we need to extract foreground for further operations like object tracking. Background Subtraction is a well-known method in those cases.
- =========== ======================================================
-
- .. |vdo_b| image:: images/background.jpg
- :height: 90pt
- :width: 90pt
-
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../py_meanshift/py_meanshift
- ../py_lucas_kanade/py_lucas_kanade
- ../py_bg_subtraction/py_bg_subtraction
+++ /dev/null
-#!/usr/bin/env python
-
-import os, sys, re
-
-finput=open(sys.argv[1], "rt")
-
-# read the whole file content to s
-s = "".join(finput.readlines())
-finput.close()
-
-# normalize line endings
-s = re.sub(r"\r\n", "\n", s)
-
-# remove trailing whitespaces
-s = re.sub(r"[ \t]+\n", "\n", s)
-
-# compress multiple empty lines
-for i in range(5):
- s = re.sub(r"\n\n\n", "\n\n", s)
-
-# remove empty line before ".." that terminates a code block
-s = re.sub(r"\n\n\.\.\n", "\n..\n", s)
-
-# move :: starting a code block to the end of previous line
-s = re.sub(r"\n\n::\n", " ::\n", s)
-
-# remove extra line breaks before/after _ or ,
-s = re.sub(r"\n[ \t]*([_,])\n", r"\1", s)
-
-# remove extra line breaks after `
-s = re.sub(r"`\n", "` ", s)
-
-# remove extra line breaks before `
-s = re.sub(r"\n[ \t]*`", " `", s)
-
-# remove links to wiki
-s = re.sub(r"\n[ \t]*`id=\d[^`]+`__\n", "", s)
-
-# remove trailing whitespaces one more time
-s = re.sub(r"[ \t]+\n", "\n", s)
-
-foutput=open(sys.argv[2], "wt")
-foutput.write(s)
-foutput.close()
+++ /dev/null
-.. _cameraCalibrationOpenCV:
-
-Camera calibration With OpenCV
-******************************
-
-Cameras have been around for a long-long time. However, with the introduction of the cheap *pinhole* cameras in the late 20th century, they became a common occurrence in our everyday life. Unfortunately, this cheapness comes with its price: significant distortion. Luckily, these are constants and with a calibration and some remapping we can correct this. Furthermore, with calibration you may also determine the relation between the camera's natural units (pixels) and the real world units (for example millimeters).
-
-Theory
-======
-
-For the distortion OpenCV takes into account the radial and tangential factors. For the radial factor one uses the following formula:
-
-.. math::
-
- x_{corrected} = x( 1 + k_1 r^2 + k_2 r^4 + k_3 r^6) \\
- y_{corrected} = y( 1 + k_1 r^2 + k_2 r^4 + k_3 r^6)
-
-So for an old pixel point at :math:`(x,y)` coordinates in the input image, its position on the corrected output image will be :math:`(x_{corrected} y_{corrected})`. The presence of the radial distortion manifests in form of the "barrel" or "fish-eye" effect.
-
-Tangential distortion occurs because the image taking lenses are not perfectly parallel to the imaging plane. It can be corrected via the formulas:
-
-.. math::
-
- x_{corrected} = x + [ 2p_1xy + p_2(r^2+2x^2)] \\
- y_{corrected} = y + [ p_1(r^2+ 2y^2)+ 2p_2xy]
-
-So we have five distortion parameters which in OpenCV are presented as one row matrix with 5 columns:
-
-.. math::
-
- Distortion_{coefficients}=(k_1 \hspace{10pt} k_2 \hspace{10pt} p_1 \hspace{10pt} p_2 \hspace{10pt} k_3)
-
-Now for the unit conversion we use the following formula:
-
-.. math::
-
- \left [ \begin{matrix} x \\ y \\ w \end{matrix} \right ] = \left [ \begin{matrix} f_x & 0 & c_x \\ 0 & f_y & c_y \\ 0 & 0 & 1 \end{matrix} \right ] \left [ \begin{matrix} X \\ Y \\ Z \end{matrix} \right ]
-
-Here the presence of :math:`w` is explained by the use of homography coordinate system (and :math:`w=Z`). The unknown parameters are :math:`f_x` and :math:`f_y` (camera focal lengths) and :math:`(c_x, c_y)` which are the optical centers expressed in pixels coordinates. If for both axes a common focal length is used with a given :math:`a` aspect ratio (usually 1), then :math:`f_y=f_x*a` and in the upper formula we will have a single focal length :math:`f`. The matrix containing these four parameters is referred to as the *camera matrix*. While the distortion coefficients are the same regardless of the camera resolutions used, these should be scaled along with the current resolution from the calibrated resolution.
-
-The process of determining these two matrices is the calibration. Calculation of these parameters is done through basic geometrical equations. The equations used depend on the chosen calibrating objects. Currently OpenCV supports three types of objects for calibration:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + Classical black-white chessboard
- + Symmetrical circle pattern
- + Asymmetrical circle pattern
-
-Basically, you need to take snapshots of these patterns with your camera and let OpenCV find them. Each found pattern results in a new equation. To solve the equation you need at least a predetermined number of pattern snapshots to form a well-posed equation system. This number is higher for the chessboard pattern and less for the circle ones. For example, in theory the chessboard pattern requires at least two snapshots. However, in practice we have a good amount of noise present in our input images, so for good results you will probably need at least 10 good snapshots of the input pattern in different positions.
-
-Goal
-====
-
-The sample application will:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + Determine the distortion matrix
- + Determine the camera matrix
- + Take input from Camera, Video and Image file list
- + Read configuration from XML/YAML file
- + Save the results into XML/YAML file
- + Calculate re-projection error
-
-Source code
-===========
-
-You may also find the source code in the :file:`samples/cpp/tutorial_code/calib3d/camera_calibration/` folder of the OpenCV source library or :download:`download it from here <../../../../samples/cpp/tutorial_code/calib3d/camera_calibration/camera_calibration.cpp>`. The program has a single argument: the name of its configuration file. If none is given then it will try to open the one named "default.xml". :download:`Here's a sample configuration file <../../../../samples/cpp/tutorial_code/calib3d/camera_calibration/in_VID5.xml>` in XML format. In the configuration file you may choose to use camera as an input, a video file or an image list. If you opt for the last one, you will need to create a configuration file where you enumerate the images to use. Here's :download:`an example of this <../../../../samples/cpp/tutorial_code/calib3d/camera_calibration/VID5.xml>`. The important part to remember is that the images need to be specified using the absolute path or the relative one from your application's working directory. You may find all this in the samples directory mentioned above.
-
-The application starts up with reading the settings from the configuration file. Although, this is an important part of it, it has nothing to do with the subject of this tutorial: *camera calibration*. Therefore, I've chosen not to post the code for that part here. Technical background on how to do this you can find in the :ref:`fileInputOutputXMLYAML` tutorial.
-
-Explanation
-===========
-
-1. **Read the settings.**
-
- .. code-block:: cpp
-
- Settings s;
- const string inputSettingsFile = argc > 1 ? argv[1] : "default.xml";
- FileStorage fs(inputSettingsFile, FileStorage::READ); // Read the settings
- if (!fs.isOpened())
- {
- cout << "Could not open the configuration file: \"" << inputSettingsFile << "\"" << endl;
- return -1;
- }
- fs["Settings"] >> s;
- fs.release(); // close Settings file
-
- if (!s.goodInput)
- {
- cout << "Invalid input detected. Application stopping. " << endl;
- return -1;
- }
-
- For this I've used simple OpenCV class input operation. After reading the file I've an additional post-processing function that checks validity of the input. Only if all inputs are good then *goodInput* variable will be true.
-
-#. **Get next input, if it fails or we have enough of them - calibrate**. After this we have a big loop where we do the following operations: get the next image from the image list, camera or video file. If this fails or we have enough images then we run the calibration process. In case of image we step out of the loop and otherwise the remaining frames will be undistorted (if the option is set) via changing from *DETECTION* mode to the *CALIBRATED* one.
-
- .. code-block:: cpp
-
- for(int i = 0;;++i)
- {
- Mat view;
- bool blinkOutput = false;
-
- view = s.nextImage();
-
- //----- If no more image, or got enough, then stop calibration and show result -------------
- if( mode == CAPTURING && imagePoints.size() >= (unsigned)s.nrFrames )
- {
- if( runCalibrationAndSave(s, imageSize, cameraMatrix, distCoeffs, imagePoints))
- mode = CALIBRATED;
- else
- mode = DETECTION;
- }
- if(view.empty()) // If no more images then run calibration, save and stop loop.
- {
- if( imagePoints.size() > 0 )
- runCalibrationAndSave(s, imageSize, cameraMatrix, distCoeffs, imagePoints);
- break;
- imageSize = view.size(); // Format input image.
- if( s.flipVertical ) flip( view, view, 0 );
- }
-
- For some cameras we may need to flip the input image. Here we do this too.
-
-#. **Find the pattern in the current input**. The formation of the equations I mentioned above aims to finding major patterns in the input: in case of the chessboard this are corners of the squares and for the circles, well, the circles themselves. The position of these will form the result which will be written into the *pointBuf* vector.
-
- .. code-block:: cpp
-
- vector<Point2f> pointBuf;
-
- bool found;
- switch( s.calibrationPattern ) // Find feature points on the input format
- {
- case Settings::CHESSBOARD:
- found = findChessboardCorners( view, s.boardSize, pointBuf,
- CALIB_CB_ADAPTIVE_THRESH | CALIB_CB_FAST_CHECK | CALIB_CB_NORMALIZE_IMAGE);
- break;
- case Settings::CIRCLES_GRID:
- found = findCirclesGrid( view, s.boardSize, pointBuf );
- break;
- case Settings::ASYMMETRIC_CIRCLES_GRID:
- found = findCirclesGrid( view, s.boardSize, pointBuf, CALIB_CB_ASYMMETRIC_GRID );
- break;
- }
-
- Depending on the type of the input pattern you use either the :calib3d:`findChessboardCorners <findchessboardcorners>` or the :calib3d:`findCirclesGrid <findcirclesgrid>` function. For both of them you pass the current image and the size of the board and you'll get the positions of the patterns. Furthermore, they return a boolean variable which states if the pattern was found in the input (we only need to take into account those images where this is true!).
-
- Then again in case of cameras we only take camera images when an input delay time is passed. This is done in order to allow user moving the chessboard around and getting different images. Similar images result in similar equations, and similar equations at the calibration step will form an ill-posed problem, so the calibration will fail. For square images the positions of the corners are only approximate. We may improve this by calling the :feature2d:`cornerSubPix <cornersubpix>` function. It will produce better calibration result. After this we add a valid inputs result to the *imagePoints* vector to collect all of the equations into a single container. Finally, for visualization feedback purposes we will draw the found points on the input image using :calib3d:`findChessboardCorners <drawchessboardcorners>` function.
-
- .. code-block:: cpp
-
- if ( found) // If done with success,
- {
- // improve the found corners' coordinate accuracy for chessboard
- if( s.calibrationPattern == Settings::CHESSBOARD)
- {
- Mat viewGray;
- cvtColor(view, viewGray, COLOR_BGR2GRAY);
- cornerSubPix( viewGray, pointBuf, Size(11,11),
- Size(-1,-1), TermCriteria( TermCriteria::EPS+TermCriteria::MAX_ITER, 30, 0.1 ));
- }
-
- if( mode == CAPTURING && // For camera only take new samples after delay time
- (!s.inputCapture.isOpened() || clock() - prevTimestamp > s.delay*1e-3*CLOCKS_PER_SEC) )
- {
- imagePoints.push_back(pointBuf);
- prevTimestamp = clock();
- blinkOutput = s.inputCapture.isOpened();
- }
-
- // Draw the corners.
- drawChessboardCorners( view, s.boardSize, Mat(pointBuf), found );
- }
-
-#. **Show state and result to the user, plus command line control of the application**. This part shows text output on the image.
-
- .. code-block:: cpp
-
- //----------------------------- Output Text ------------------------------------------------
- string msg = (mode == CAPTURING) ? "100/100" :
- mode == CALIBRATED ? "Calibrated" : "Press 'g' to start";
- int baseLine = 0;
- Size textSize = getTextSize(msg, 1, 1, 1, &baseLine);
- Point textOrigin(view.cols - 2*textSize.width - 10, view.rows - 2*baseLine - 10);
-
- if( mode == CAPTURING )
- {
- if(s.showUndistorsed)
- msg = format( "%d/%d Undist", (int)imagePoints.size(), s.nrFrames );
- else
- msg = format( "%d/%d", (int)imagePoints.size(), s.nrFrames );
- }
-
- putText( view, msg, textOrigin, 1, 1, mode == CALIBRATED ? GREEN : RED);
-
- if( blinkOutput )
- bitwise_not(view, view);
-
- If we ran calibration and got camera's matrix with the distortion coefficients we may want to correct the image using :imgproc_geometric:`undistort <undistort>` function:
-
- .. code-block:: cpp
-
- //------------------------- Video capture output undistorted ------------------------------
- if( mode == CALIBRATED && s.showUndistorsed )
- {
- Mat temp = view.clone();
- undistort(temp, view, cameraMatrix, distCoeffs);
- }
- //------------------------------ Show image and check for input commands -------------------
- imshow("Image View", view);
-
- Then we wait for an input key and if this is *u* we toggle the distortion removal, if it is *g* we start again the detection process, and finally for the *ESC* key we quit the application:
-
- .. code-block:: cpp
-
- char key = waitKey(s.inputCapture.isOpened() ? 50 : s.delay);
- if( key == ESC_KEY )
- break;
-
- if( key == 'u' && mode == CALIBRATED )
- s.showUndistorsed = !s.showUndistorsed;
-
- if( s.inputCapture.isOpened() && key == 'g' )
- {
- mode = CAPTURING;
- imagePoints.clear();
- }
-
-#. **Show the distortion removal for the images too**. When you work with an image list it is not possible to remove the distortion inside the loop. Therefore, you must do this after the loop. Taking advantage of this now I'll expand the :imgproc_geometric:`undistort <undistort>` function, which is in fact first calls :imgproc_geometric:`initUndistortRectifyMap <initundistortrectifymap>` to find transformation matrices and then performs transformation using :imgproc_geometric:`remap <remap>` function. Because, after successful calibration map calculation needs to be done only once, by using this expanded form you may speed up your application:
-
- .. code-block:: cpp
-
- if( s.inputType == Settings::IMAGE_LIST && s.showUndistorsed )
- {
- Mat view, rview, map1, map2;
- initUndistortRectifyMap(cameraMatrix, distCoeffs, Mat(),
- getOptimalNewCameraMatrix(cameraMatrix, distCoeffs, imageSize, 1, imageSize, 0),
- imageSize, CV_16SC2, map1, map2);
-
- for(int i = 0; i < (int)s.imageList.size(); i++ )
- {
- view = imread(s.imageList[i], 1);
- if(view.empty())
- continue;
- remap(view, rview, map1, map2, INTER_LINEAR);
- imshow("Image View", rview);
- char c = waitKey();
- if( c == ESC_KEY || c == 'q' || c == 'Q' )
- break;
- }
- }
-
-The calibration and save
-========================
-
-Because the calibration needs to be done only once per camera, it makes sense to save it after a successful calibration. This way later on you can just load these values into your program. Due to this we first make the calibration, and if it succeeds we save the result into an OpenCV style XML or YAML file, depending on the extension you give in the configuration file.
-
-Therefore in the first function we just split up these two processes. Because we want to save many of the calibration variables we'll create these variables here and pass on both of them to the calibration and saving function. Again, I'll not show the saving part as that has little in common with the calibration. Explore the source file in order to find out how and what:
-
-.. code-block:: cpp
-
-
- bool runCalibrationAndSave(Settings& s, Size imageSize, Mat& cameraMatrix, Mat& distCoeffs,vector<vector<Point2f> > imagePoints )
- {
- vector<Mat> rvecs, tvecs;
- vector<float> reprojErrs;
- double totalAvgErr = 0;
-
- bool ok = runCalibration(s,imageSize, cameraMatrix, distCoeffs, imagePoints, rvecs, tvecs,
- reprojErrs, totalAvgErr);
- cout << (ok ? "Calibration succeeded" : "Calibration failed")
- << ". avg re projection error = " << totalAvgErr ;
-
- if( ok ) // save only if the calibration was done with success
- saveCameraParams( s, imageSize, cameraMatrix, distCoeffs, rvecs ,tvecs, reprojErrs,
- imagePoints, totalAvgErr);
- return ok;
- }
-
-We do the calibration with the help of the :calib3d:`calibrateCamera <calibratecamera>` function. It has the following parameters:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + The object points. This is a vector of *Point3f* vector that for each input image describes how should the pattern look. If we have a planar pattern (like a chessboard) then we can simply set all Z coordinates to zero. This is a collection of the points where these important points are present. Because, we use a single pattern for all the input images we can calculate this just once and multiply it for all the other input views. We calculate the corner points with the *calcBoardCornerPositions* function as:
-
- .. code-block:: cpp
-
- void calcBoardCornerPositions(Size boardSize, float squareSize, vector<Point3f>& corners,
- Settings::Pattern patternType /*= Settings::CHESSBOARD*/)
- {
- corners.clear();
-
- switch(patternType)
- {
- case Settings::CHESSBOARD:
- case Settings::CIRCLES_GRID:
- for( int i = 0; i < boardSize.height; ++i )
- for( int j = 0; j < boardSize.width; ++j )
- corners.push_back(Point3f(float( j*squareSize ), float( i*squareSize ), 0));
- break;
-
- case Settings::ASYMMETRIC_CIRCLES_GRID:
- for( int i = 0; i < boardSize.height; i++ )
- for( int j = 0; j < boardSize.width; j++ )
- corners.push_back(Point3f(float((2*j + i % 2)*squareSize), float(i*squareSize), 0));
- break;
- }
- }
-
- And then multiply it as:
-
- .. code-block:: cpp
-
- vector<vector<Point3f> > objectPoints(1);
- calcBoardCornerPositions(s.boardSize, s.squareSize, objectPoints[0], s.calibrationPattern);
- objectPoints.resize(imagePoints.size(),objectPoints[0]);
-
- + The image points. This is a vector of *Point2f* vector which for each input image contains coordinates of the important points (corners for chessboard and centers of the circles for the circle pattern). We have already collected this from :calib3d:`findChessboardCorners <findchessboardcorners>` or :calib3d:`findCirclesGrid <findcirclesgrid>` function. We just need to pass it on.
-
- + The size of the image acquired from the camera, video file or the images.
-
- + The camera matrix. If we used the fixed aspect ratio option we need to set the :math:`f_x` to zero:
-
- .. code-block:: cpp
-
- cameraMatrix = Mat::eye(3, 3, CV_64F);
- if( s.flag & CALIB_FIX_ASPECT_RATIO )
- cameraMatrix.at<double>(0,0) = 1.0;
-
- + The distortion coefficient matrix. Initialize with zero.
-
- .. code-block:: cpp
-
- distCoeffs = Mat::zeros(8, 1, CV_64F);
-
- + For all the views the function will calculate rotation and translation vectors which transform the object points (given in the model coordinate space) to the image points (given in the world coordinate space). The 7-th and 8-th parameters are the output vector of matrices containing in the i-th position the rotation and translation vector for the i-th object point to the i-th image point.
-
- + The final argument is the flag. You need to specify here options like fix the aspect ratio for the focal length, assume zero tangential distortion or to fix the principal point.
-
- .. code-block:: cpp
-
- double rms = calibrateCamera(objectPoints, imagePoints, imageSize, cameraMatrix,
- distCoeffs, rvecs, tvecs, s.flag|CV_CALIB_FIX_K4|CV_CALIB_FIX_K5);
-
- + The function returns the average re-projection error. This number gives a good estimation of precision of the found parameters. This should be as close to zero as possible. Given the intrinsic, distortion, rotation and translation matrices we may calculate the error for one view by using the :calib3d:`projectPoints <projectpoints>` to first transform the object point to image point. Then we calculate the absolute norm between what we got with our transformation and the corner/circle finding algorithm. To find the average error we calculate the arithmetical mean of the errors calculated for all the calibration images.
-
- .. code-block:: cpp
-
- double computeReprojectionErrors( const vector<vector<Point3f> >& objectPoints,
- const vector<vector<Point2f> >& imagePoints,
- const vector<Mat>& rvecs, const vector<Mat>& tvecs,
- const Mat& cameraMatrix , const Mat& distCoeffs,
- vector<float>& perViewErrors)
- {
- vector<Point2f> imagePoints2;
- int i, totalPoints = 0;
- double totalErr = 0, err;
- perViewErrors.resize(objectPoints.size());
-
- for( i = 0; i < (int)objectPoints.size(); ++i )
- {
- projectPoints( Mat(objectPoints[i]), rvecs[i], tvecs[i], cameraMatrix, // project
- distCoeffs, imagePoints2);
- err = norm(Mat(imagePoints[i]), Mat(imagePoints2), NORM_L2); // difference
-
- int n = (int)objectPoints[i].size();
- perViewErrors[i] = (float) std::sqrt(err*err/n); // save for this view
- totalErr += err*err; // sum it up
- totalPoints += n;
- }
-
- return std::sqrt(totalErr/totalPoints); // calculate the arithmetical mean
- }
-
-Results
-=======
-
-Let there be :download:`this input chessboard pattern <../../../pattern.png>` which has a size of 9 X 6. I've used an AXIS IP camera to create a couple of snapshots of the board and saved it into VID5 directory. I've put this inside the :file:`images/CameraCalibration` folder of my working directory and created the following :file:`VID5.XML` file that describes which images to use:
-
-.. code-block:: xml
-
- <?xml version="1.0"?>
- <opencv_storage>
- <images>
- images/CameraCalibration/VID5/xx1.jpg
- images/CameraCalibration/VID5/xx2.jpg
- images/CameraCalibration/VID5/xx3.jpg
- images/CameraCalibration/VID5/xx4.jpg
- images/CameraCalibration/VID5/xx5.jpg
- images/CameraCalibration/VID5/xx6.jpg
- images/CameraCalibration/VID5/xx7.jpg
- images/CameraCalibration/VID5/xx8.jpg
- </images>
- </opencv_storage>
-
-Then passed :file:`images/CameraCalibration/VID5/VID5.XML` as an input in the configuration file. Here's a chessboard pattern found during the runtime of the application:
-
-.. image:: images/fileListImage.jpg
- :alt: A found chessboard
- :align: center
-
-After applying the distortion removal we get:
-
-.. image:: images/fileListImageUnDist.jpg
- :alt: Distortion removal for File List
- :align: center
-
-The same works for :download:`this asymmetrical circle pattern <../../../acircles_pattern.png>` by setting the input width to 4 and height to 11. This time I've used a live camera feed by specifying its ID ("1") for the input. Here's, how a detected pattern should look:
-
-.. image:: images/asymetricalPattern.jpg
- :alt: Asymmetrical circle detection
- :align: center
-
-In both cases in the specified output XML/YAML file you'll find the camera and distortion coefficients matrices:
-
-.. code-block:: cpp
-
- <Camera_Matrix type_id="opencv-matrix">
- <rows>3</rows>
- <cols>3</cols>
- <dt>d</dt>
- <data>
- 6.5746697944293521e+002 0. 3.1950000000000000e+002 0.
- 6.5746697944293521e+002 2.3950000000000000e+002 0. 0. 1.</data></Camera_Matrix>
- <Distortion_Coefficients type_id="opencv-matrix">
- <rows>5</rows>
- <cols>1</cols>
- <dt>d</dt>
- <data>
- -4.1802327176423804e-001 5.0715244063187526e-001 0. 0.
- -5.7843597214487474e-001</data></Distortion_Coefficients>
-
-Add these values as constants to your program, call the :imgproc_geometric:`initUndistortRectifyMap <initundistortrectifymap>` and the :imgproc_geometric:`remap <remap>` function to remove distortion and enjoy distortion free inputs for cheap and low quality cameras.
-
-You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=ViPN810E0SU>`_.
-
-.. raw:: html
-
- <div align="center">
- <iframe title=" Camera calibration With OpenCV - Chessboard or asymmetrical circle pattern." width="560" height="349" src="http://www.youtube.com/embed/ViPN810E0SU?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _CameraCalibrationSquareChessBoardTutorial:
-
-Camera calibration with square chessboard
-*****************************************
-
-.. highlight:: cpp
-
-The goal of this tutorial is to learn how to calibrate a camera given a set of chessboard images.
-
-*Test data*: use images in your data/chess folder.
-
-#.
- Compile opencv with samples by setting ``BUILD_EXAMPLES`` to ``ON`` in cmake configuration.
-
-#.
- Go to ``bin`` folder and use ``imagelist_creator`` to create an ``XML/YAML`` list of your images.
-
-#.
- Then, run ``calibration`` sample to get camera parameters. Use square size equal to 3cm.
-
-Pose estimation
-===============
-
-Now, let us write a code that detects a chessboard in a new image and finds its distance from the camera. You can apply the same method to any object with known 3D geometry that you can detect in an image.
-
-*Test data*: use chess_test*.jpg images from your data folder.
-
-#.
- Create an empty console project. Load a test image: ::
-
- Mat img = imread(argv[1], IMREAD_GRAYSCALE);
-
-#.
- Detect a chessboard in this image using findChessboard function. ::
-
- bool found = findChessboardCorners( img, boardSize, ptvec, CALIB_CB_ADAPTIVE_THRESH );
-
-#.
- Now, write a function that generates a ``vector<Point3f>`` array of 3d coordinates of a chessboard in any coordinate system. For simplicity, let us choose a system such that one of the chessboard corners is in the origin and the board is in the plane *z = 0*.
-
-#.
- Read camera parameters from XML/YAML file: ::
-
- FileStorage fs(filename, FileStorage::READ);
- Mat intrinsics, distortion;
- fs["camera_matrix"] >> intrinsics;
- fs["distortion_coefficients"] >> distortion;
-
-#.
- Now we are ready to find chessboard pose by running ``solvePnP``: ::
-
- vector<Point3f> boardPoints;
- // fill the array
- ...
-
- solvePnP(Mat(boardPoints), Mat(foundBoardCorners), cameraMatrix,
- distCoeffs, rvec, tvec, false);
-
-#.
- Calculate reprojection error like it is done in ``calibration`` sample (see ``opencv/samples/cpp/calibration.cpp``, function ``computeReprojectionErrors``).
-
-Question: how to calculate the distance from the camera origin to any of the corners?
+++ /dev/null
-.. _realTimePoseEstimation:
-
-Real Time pose estimation of a textured object
-**********************************************
-
-Nowadays, augmented reality is one of the top research topic in computer vision and robotics fields. The most elemental problem in augmented reality is the estimation of the camera pose respect of an object in the case of computer vision area to do later some 3D rendering or in the case of robotics obtain an object pose in order to grasp it and do some manipulation. However, this is not a trivial problem to solve due to the fact that the most common issue in image processing is the computational cost of applying a lot of algorithms or mathematical operations for solving a problem which is basic and immediateley for humans.
-
-
-Goal
-====
-
-In this tutorial is explained how to build a real time application to estimate the camera pose in order to track a textured object with six degrees of freedom given a 2D image and its 3D textured model.
-
-The application will have the followings parts:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + Read 3D textured object model and object mesh.
- + Take input from Camera or Video.
- + Extract ORB features and descriptors from the scene.
- + Match scene descriptors with model descriptors using Flann matcher.
- + Pose estimation using PnP + Ransac.
- + Linear Kalman Filter for bad poses rejection.
-
-
-Theory
-======
-
-In computer vision estimate the camera pose from *n* 3D-to-2D point correspondences is a fundamental and well understood problem. The most general version of the problem requires estimating the six degrees of freedom of the pose and five calibration parameters: focal length, principal point, aspect ratio and skew. It could be established with a minimum of 6 correspondences, using the well known Direct Linear Transform (DLT) algorithm. There are, though, several simplifications to the problem which turn into an extensive list of different algorithms that improve the accuracy of the DLT.
-
-The most common simplification is to assume known calibration parameters which is the so-called Perspective-*n*-Point problem:
-
-.. image:: images/pnp.jpg
- :alt: Perspective-n-Point problem scheme
- :align: center
-
-**Problem Formulation:** Given a set of correspondences between 3D points :math:`p_i` expressed in a world reference frame, and their 2D projections :math:`u_i` onto the image, we seek to retrieve the pose (:math:`R` and :math:`t`) of the camera w.r.t. the world and the focal length :math:`f`.
-
-OpenCV provides four different approaches to solve the Perspective-*n*-Point problem which return :math:`R` and :math:`t`. Then, using the following formula it's possible to project 3D points into the image plane:
-
-.. math::
-
- s\ \left [ \begin{matrix} u \\ v \\ 1 \end{matrix} \right ] = \left [ \begin{matrix} f_x & 0 & c_x \\ 0 & f_y & c_y \\ 0 & 0 & 1 \end{matrix} \right ] \left [ \begin{matrix} r_{11} & r_{12} & r_{13} & t_1 \\ r_{21} & r_{22} & r_{23} & t_2 \\ r_{31} & r_{32} & r_{33} & t_3 \end{matrix} \right ] \left [ \begin{matrix} X \\ Y \\ Z\\ 1 \end{matrix} \right ]
-
-The complete documentation of how to manage with this equations is in :calib3d:`Camera Calibration and 3D Reconstruction <>`.
-
-Source code
-===========
-
-You can find the source code of this tutorial in the :file:`samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/` folder of the OpenCV source library.
-
-The tutorial consists of two main programs:
-
-1. **Model registration**
-
- This applicaton is exclusive to whom don't have a 3D textured model of the object to be detected. You can use this program to create your own textured 3D model. This program only works for planar objects, then if you want to model an object with complex shape you should use a sophisticated software to create it.
-
- The application needs an input image of the object to be registered and its 3D mesh. We have also to provide the intrinsic parameters of the camera with which the input image was taken. All the files need to be specified using the absolute path or the relative one from your application’s working directory. If none files are specified the program will try to open the provided default parameters.
-
- The application starts up extracting the ORB features and descriptors from the input image and then uses the mesh along with the `Möller–Trumbore intersection algorithm <http://http://en.wikipedia.org/wiki/M%C3%B6ller%E2%80%93Trumbore_intersection_algorithm/>`_ to compute the 3D coordinates of the found features. Finally, the 3D points and the descriptors are stored in different lists in a file with YAML format which each row is a different point. The technical background on how to store the files can be found in the :ref:`fileInputOutputXMLYAML` tutorial.
-
-.. image:: images/registration.png
- :alt: Model registration
- :align: center
-
-
-2. **Model detection**
-
- The aim of this application is estimate in real time the object pose given its 3D textured model.
-
- The application starts up loading the 3D textured model in YAML file format with the same structure explained in the model registration program. From the scene, the ORB features and descriptors are detected and extracted. Then, is used :flann_based_matcher:`FlannBasedMatcher<>` with :flann:`LshIndexParams <flann-index-t-index>` to do the matching between the scene descriptors and the model descriptors. Using the found matches along with :calib3d:`solvePnPRansac <solvepnpransac>` function the :math:`R` and :math:`t` of the camera are computed. Finally, a :video:`KalmanFilter<kalmanfilter>` is applied in order to reject bad poses.
-
- In the case that you compiled OpenCV with the samples, you can find it in :file:`opencv/build/bin/cpp-tutorial-pnp_detection`. Then you can run the application and change some parameters:
-
- .. code-block:: cpp
-
- This program shows how to detect an object given its 3D textured model. You can choose to use a recorded video or the webcam.
- Usage:
- ./cpp-tutorial-pnp_detection -help
- Keys:
- 'esc' - to quit.
- --------------------------------------------------------------------------
-
- Usage: cpp-tutorial-pnp_detection [params]
-
- -c, --confidence (value:0.95)
- RANSAC confidence
- -e, --error (value:2.0)
- RANSAC reprojection errror
- -f, --fast (value:true)
- use of robust fast match
- -h, --help (value:true)
- print this message
- --in, --inliers (value:30)
- minimum inliers for Kalman update
- --it, --iterations (value:500)
- RANSAC maximum iterations count
- -k, --keypoints (value:2000)
- number of keypoints to detect
- --mesh
- path to ply mesh
- --method, --pnp (value:0)
- PnP method: (0) ITERATIVE - (1) EPNP - (2) P3P - (3) DLS
- --model
- path to yml model
- -r, --ratio (value:0.7)
- threshold for ratio test
- -v, --video
- path to recorded video
-
- For example, you can run the application changing the pnp method:
-
- .. code-block:: cpp
-
- ./cpp-tutorial-pnp_detection --method=2
-
-
-Explanation
-===========
-
-Here is explained in detail the code for the real time application:
-
-1. **Read 3D textured object model and object mesh.**
-
- In order to load the textured model I implemented the *class* **Model** which has the function *load()* that opens a YAML file and take the stored 3D points with its corresponding descriptors. You can find an example of a 3D textured model in :file:`samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/Data/cookies_ORB.yml`.
-
- .. code-block:: cpp
-
- /* Load a YAML file using OpenCV */
- void Model::load(const std::string path)
- {
- cv::Mat points3d_mat;
-
- cv::FileStorage storage(path, cv::FileStorage::READ);
- storage["points_3d"] >> points3d_mat;
- storage["descriptors"] >> descriptors_;
-
- points3d_mat.copyTo(list_points3d_in_);
-
- storage.release();
-
- }
-
- In the main program the model is loaded as follows:
-
- .. code-block:: cpp
-
- Model model; // instantiate Model object
- model.load(yml_read_path); // load a 3D textured object model
-
- In order to read the model mesh I implemented a *class* **Mesh** which has a function *load()* that opens a :math:`*`.ply file and store the 3D points of the object and also the composed triangles. You can find an example of a model mesh in :file:`samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/Data/box.ply`.
-
- .. code-block:: cpp
-
- /* Load a CSV with *.ply format */
- void Mesh::load(const std::string path)
- {
-
- // Create the reader
- CsvReader csvReader(path);
-
- // Clear previous data
- list_vertex_.clear();
- list_triangles_.clear();
-
- // Read from .ply file
- csvReader.readPLY(list_vertex_, list_triangles_);
-
- // Update mesh attributes
- num_vertexs_ = list_vertex_.size();
- num_triangles_ = list_triangles_.size();
-
- }
-
- In the main program the mesh is loaded as follows:
-
- .. code-block:: cpp
-
- Mesh mesh; // instantiate Mesh object
- mesh.load(ply_read_path); // load an object mesh
-
- You can also load different model and mesh:
-
- .. code-block:: cpp
-
- ./cpp-tutorial-pnp_detection --mesh=/absolute_path_to_your_mesh.ply --model=/absolute_path_to_your_model.yml
-
-
-2. **Take input from Camera or Video**
-
- To detect is necessary capture video. It's done loading a recorded video by passing the absolute path where it is located in your machine. In order to test the application you can find a recorded video in :file:`samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/Data/box.mp4`.
-
- .. code-block:: cpp
-
- cv::VideoCapture cap; // instantiate VideoCapture
- cap.open(video_read_path); // open a recorded video
-
- if(!cap.isOpened()) // check if we succeeded
- {
- std::cout << "Could not open the camera device" << std::endl;
- return -1;
- }
-
- Then the algorithm is computed frame per frame:
-
- .. code-block:: cpp
-
- cv::Mat frame, frame_vis;
-
- while(cap.read(frame) && cv::waitKey(30) != 27) // capture frame until ESC is pressed
- {
-
- frame_vis = frame.clone(); // refresh visualisation frame
-
- // MAIN ALGORITHM
-
- }
-
- You can also load different recorded video:
-
- .. code-block:: cpp
-
- ./cpp-tutorial-pnp_detection --video=/absolute_path_to_your_video.mp4
-
-
-3. **Extract ORB features and descriptors from the scene**
-
- The next step is to detect the scene features and extract it descriptors. For this task I implemented a *class* **RobustMatcher** which has a function for keypoints detection and features extraction. You can find it in :file:`samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/src/RobusMatcher.cpp`. In your *RobusMatch* object you can use any of the 2D features detectors of OpenCV. In this case I used :feature_detection_and_description:`ORB<orb>` features because is based on :feature_detection_and_description:`FAST<fast>` to detect the keypoints and :descriptor_extractor:`BRIEF<briefdescriptorextractor>` to extract the descriptors which means that is fast and robust to rotations. You can find more detailed information about *ORB* in the documentation.
-
- The following code is how to instantiate and set the features detector and the descriptors extractor:
-
- .. code-block:: cpp
-
- RobustMatcher rmatcher; // instantiate RobustMatcher
-
- cv::FeatureDetector * detector = new cv::OrbFeatureDetector(numKeyPoints); // instatiate ORB feature detector
- cv::DescriptorExtractor * extractor = new cv::OrbDescriptorExtractor(); // instatiate ORB descriptor extractor
-
- rmatcher.setFeatureDetector(detector); // set feature detector
- rmatcher.setDescriptorExtractor(extractor); // set descriptor extractor
-
- The features and descriptors will be computed by the *RobustMatcher* inside the matching function.
-
-
-4. **Match scene descriptors with model descriptors using Flann matcher**
-
- It is the first step in our detection algorithm. The main idea is to match the scene descriptors with our model descriptors in order to know the 3D coordinates of the found features into the current scene.
-
- Firstly, we have to set which matcher we want to use. In this case is used :flann_based_matcher:`FlannBasedMatcher<>` matcher which in terms of computational cost is faster than the :brute_force_matcher:`BruteForceMatcher<bfmatcher>` matcher as we increase the trained collectction of features. Then, for FlannBased matcher the index created is *Multi-Probe LSH: Efficient Indexing for High-Dimensional Similarity Search* due to *ORB* descriptors are binary.
-
- You can tune the *LSH* and search parameters to improve the matching efficiency:
-
- .. code-block:: cpp
-
- cv::Ptr<cv::flann::IndexParams> indexParams = cv::makePtr<cv::flann::LshIndexParams>(6, 12, 1); // instantiate LSH index parameters
- cv::Ptr<cv::flann::SearchParams> searchParams = cv::makePtr<cv::flann::SearchParams>(50); // instantiate flann search parameters
-
- cv::DescriptorMatcher * matcher = new cv::FlannBasedMatcher(indexParams, searchParams); // instantiate FlannBased matcher
- rmatcher.setDescriptorMatcher(matcher); // set matcher
-
-
- Secondly, we have to call the matcher by using *robustMatch()* or *fastRobustMatch()* function. The difference of using this two functions is its computational cost. The first method is slower but more robust at filtering good matches because uses two ratio test and a symmetry test. In contrast, the second method is faster but less robust because only applies a single ratio test to the matches.
-
- The following code is to get the model 3D points and its descriptors and then call the matcher in the main program:
-
- .. code-block:: cpp
-
- // Get the MODEL INFO
-
- std::vector<cv::Point3f> list_points3d_model = model.get_points3d(); // list with model 3D coordinates
- cv::Mat descriptors_model = model.get_descriptors(); // list with descriptors of each 3D coordinate
-
- .. code-block:: cpp
-
- // -- Step 1: Robust matching between model descriptors and scene descriptors
-
- std::vector<cv::DMatch> good_matches; // to obtain the model 3D points in the scene
- std::vector<cv::KeyPoint> keypoints_scene; // to obtain the 2D points of the scene
-
- if(fast_match)
- {
- rmatcher.fastRobustMatch(frame, good_matches, keypoints_scene, descriptors_model);
- }
- else
- {
- rmatcher.robustMatch(frame, good_matches, keypoints_scene, descriptors_model);
- }
-
- The following code corresponds to the *robustMatch()* function which belongs to the *RobustMatcher* class. This function uses the given image to detect the keypoints and extract the descriptors, match using *two Nearest Neighbour* the extracted descriptors with the given model descriptors and vice versa. Then, a ratio test is applied to the two direction matches in order to remove these matches which its distance ratio between the first and second best match is larger than a given threshold. Finally, a symmetry test is applied in order the remove non symmetrical matches.
-
- .. code-block:: cpp
-
- void RobustMatcher::robustMatch( const cv::Mat& frame, std::vector<cv::DMatch>& good_matches,
- std::vector<cv::KeyPoint>& keypoints_frame,
- const std::vector<cv::KeyPoint>& keypoints_model, const cv::Mat& descriptors_model )
- {
-
- // 1a. Detection of the ORB features
- this->computeKeyPoints(frame, keypoints_frame);
-
- // 1b. Extraction of the ORB descriptors
- cv::Mat descriptors_frame;
- this->computeDescriptors(frame, keypoints_frame, descriptors_frame);
-
- // 2. Match the two image descriptors
- std::vector<std::vector<cv::DMatch> > matches12, matches21;
-
- // 2a. From image 1 to image 2
- matcher_->knnMatch(descriptors_frame, descriptors_model, matches12, 2); // return 2 nearest neighbours
-
- // 2b. From image 2 to image 1
- matcher_->knnMatch(descriptors_model, descriptors_frame, matches21, 2); // return 2 nearest neighbours
-
- // 3. Remove matches for which NN ratio is > than threshold
- // clean image 1 -> image 2 matches
- int removed1 = ratioTest(matches12);
- // clean image 2 -> image 1 matches
- int removed2 = ratioTest(matches21);
-
- // 4. Remove non-symmetrical matches
- symmetryTest(matches12, matches21, good_matches);
-
- }
-
- After the matches filtering we have to subtract the 2D and 3D correspondences from the found scene keypoints and our 3D model using the obtained *DMatches* vector. For more information about :basicstructures:`DMatch <dmatch>` check the documentation.
-
- .. code-block:: cpp
-
- // -- Step 2: Find out the 2D/3D correspondences
-
- std::vector<cv::Point3f> list_points3d_model_match; // container for the model 3D coordinates found in the scene
- std::vector<cv::Point2f> list_points2d_scene_match; // container for the model 2D coordinates found in the scene
-
- for(unsigned int match_index = 0; match_index < good_matches.size(); ++match_index)
- {
- cv::Point3f point3d_model = list_points3d_model[ good_matches[match_index].trainIdx ]; // 3D point from model
- cv::Point2f point2d_scene = keypoints_scene[ good_matches[match_index].queryIdx ].pt; // 2D point from the scene
- list_points3d_model_match.push_back(point3d_model); // add 3D point
- list_points2d_scene_match.push_back(point2d_scene); // add 2D point
- }
-
- You can also change the ratio test threshold, the number of keypoints to detect as well as use or not the robust matcher:
-
- .. code-block:: cpp
-
- ./cpp-tutorial-pnp_detection --ratio=0.8 --keypoints=1000 --fast=false
-
-
-5. **Pose estimation using PnP + Ransac**
-
- Once with the 2D and 3D correspondences we have to apply a PnP algorithm in order to estimate the camera pose. The reason why we have to use :calib3d:`solvePnPRansac <solvepnpransac>` instead of :calib3d:`solvePnP <solvepnp>` is due to the fact that after the matching not all the found correspondences are correct and, as like as not, there are false correspondences or also called *outliers*. The `Random Sample Consensus <http://en.wikipedia.org/wiki/RANSAC>`_ or *Ransac* is a non-deterministic iterative method which estimate parameters of a mathematical model from observed data producing an aproximate result as the number of iterations increase. After appyling *Ransac* all the *outliers* will be eliminated to then estimate the camera pose with a certain probability to obtain a good solution.
-
- For the camera pose estimation I have implemented a *class* **PnPProblem**. This *class* has 4 atributes: a given calibration matrix, the rotation matrix, the translation matrix and the rotation-translation matrix. The intrinsic calibration parameters of the camera which you are using to estimate the pose are necessary. In order to obtain the parameters you can check :ref:`CameraCalibrationSquareChessBoardTutorial` and :ref:`cameraCalibrationOpenCV` tutorials.
-
- The following code is how to declare the *PnPProblem class* in the main program:
-
- .. code-block:: cpp
-
- // Intrinsic camera parameters: UVC WEBCAM
-
- double f = 55; // focal length in mm
- double sx = 22.3, sy = 14.9; // sensor size
- double width = 640, height = 480; // image size
-
- double params_WEBCAM[] = { width*f/sx, // fx
- height*f/sy, // fy
- width/2, // cx
- height/2}; // cy
-
- PnPProblem pnp_detection(params_WEBCAM); // instantiate PnPProblem class
-
- The following code is how the *PnPProblem class* initialises its atributes:
-
- .. code-block:: cpp
-
- // Custom constructor given the intrinsic camera parameters
-
- PnPProblem::PnPProblem(const double params[])
- {
- _A_matrix = cv::Mat::zeros(3, 3, CV_64FC1); // intrinsic camera parameters
- _A_matrix.at<double>(0, 0) = params[0]; // [ fx 0 cx ]
- _A_matrix.at<double>(1, 1) = params[1]; // [ 0 fy cy ]
- _A_matrix.at<double>(0, 2) = params[2]; // [ 0 0 1 ]
- _A_matrix.at<double>(1, 2) = params[3];
- _A_matrix.at<double>(2, 2) = 1;
- _R_matrix = cv::Mat::zeros(3, 3, CV_64FC1); // rotation matrix
- _t_matrix = cv::Mat::zeros(3, 1, CV_64FC1); // translation matrix
- _P_matrix = cv::Mat::zeros(3, 4, CV_64FC1); // rotation-translation matrix
-
- }
-
- OpenCV provides four PnP methods: ITERATIVE, EPNP, P3P and DLS. Depending on the application type, the estimation method will be different. In the case that we want to make a real time application, the more suitable methods are EPNP and P3P due to that are faster than ITERATIVE and DLS at finding an optimal solution. However, EPNP and P3P are not especially robust in front of planar surfaces and sometimes the pose estimation seems to have a mirror effect. Therefore, in this this tutorial is used ITERATIVE method due to the object to be detected has planar surfaces.
-
- The OpenCV Ransac implementation wants you to provide three parameters: the maximum number of iterations until stop the algorithm, the maximum allowed distance between the observed and computed point projections to consider it an inlier and the confidence to obtain a good result. You can tune these paramaters in order to improve your algorithm performance. Increasing the number of iterations you will have a more accurate solution, but will take more time to find a solution. Increasing the reprojection error will reduce the computation time, but your solution will be unaccurate. Decreasing the confidence your arlgorithm will be faster, but the obtained solution will be unaccurate.
-
- The following parameters work for this application:
-
- .. code-block:: cpp
-
- // RANSAC parameters
-
- int iterationsCount = 500; // number of Ransac iterations.
- float reprojectionError = 2.0; // maximum allowed distance to consider it an inlier.
- float confidence = 0.95; // ransac successful confidence.
-
-
- The following code corresponds to the *estimatePoseRANSAC()* function which belongs to the *PnPProblem class*. This function estimates the rotation and translation matrix given a set of 2D/3D correspondences, the desired PnP method to use, the output inliers container and the Ransac parameters:
-
- .. code-block:: cpp
-
- // Estimate the pose given a list of 2D/3D correspondences with RANSAC and the method to use
-
- void PnPProblem::estimatePoseRANSAC( const std::vector<cv::Point3f> &list_points3d, // list with model 3D coordinates
- const std::vector<cv::Point2f> &list_points2d, // list with scene 2D coordinates
- int flags, cv::Mat &inliers, int iterationsCount, // PnP method; inliers container
- float reprojectionError, float confidence ) // Ransac parameters
- {
- cv::Mat distCoeffs = cv::Mat::zeros(4, 1, CV_64FC1); // vector of distortion coefficients
- cv::Mat rvec = cv::Mat::zeros(3, 1, CV_64FC1); // output rotation vector
- cv::Mat tvec = cv::Mat::zeros(3, 1, CV_64FC1); // output translation vector
-
- bool useExtrinsicGuess = false; // if true the function uses the provided rvec and tvec values as
- // initial approximations of the rotation and translation vectors
-
- cv::solvePnPRansac( list_points3d, list_points2d, _A_matrix, distCoeffs, rvec, tvec,
- useExtrinsicGuess, iterationsCount, reprojectionError, confidence,
- inliers, flags );
-
- Rodrigues(rvec,_R_matrix); // converts Rotation Vector to Matrix
- _t_matrix = tvec; // set translation matrix
-
- this->set_P_matrix(_R_matrix, _t_matrix); // set rotation-translation matrix
-
- }
-
- In the following code are the 3th and 4th steps of the main algorithm. The first, calling the above function and the second taking the output inliers vector from Ransac to get the 2D scene points for drawing purpose. As seen in the code we must be sure to apply Ransac if we have matches, in the other case, the function :calib3d:`solvePnPRansac <solvepnpransac>` crashes due to any OpenCV *bug*.
-
- .. code-block:: cpp
-
- if(good_matches.size() > 0) // None matches, then RANSAC crashes
- {
-
- // -- Step 3: Estimate the pose using RANSAC approach
- pnp_detection.estimatePoseRANSAC( list_points3d_model_match, list_points2d_scene_match,
- pnpMethod, inliers_idx, iterationsCount, reprojectionError, confidence );
-
-
- // -- Step 4: Catch the inliers keypoints to draw
- for(int inliers_index = 0; inliers_index < inliers_idx.rows; ++inliers_index)
- {
- int n = inliers_idx.at<int>(inliers_index); // i-inlier
- cv::Point2f point2d = list_points2d_scene_match[n]; // i-inlier point 2D
- list_points2d_inliers.push_back(point2d); // add i-inlier to list
- }
-
-
- Finally, once the camera pose has been estimated we can use the :math:`R` and :math:`t` in order to compute the 2D projection onto the image of a given 3D point expressed in a world reference frame using the showed formula on *Theory*.
-
- The following code corresponds to the *backproject3DPoint()* function which belongs to the *PnPProblem class*. The function backproject a given 3D point expressed in a world reference frame onto a 2D image:
-
- .. code-block:: cpp
-
- // Backproject a 3D point to 2D using the estimated pose parameters
-
- cv::Point2f PnPProblem::backproject3DPoint(const cv::Point3f &point3d)
- {
- // 3D point vector [x y z 1]'
- cv::Mat point3d_vec = cv::Mat(4, 1, CV_64FC1);
- point3d_vec.at<double>(0) = point3d.x;
- point3d_vec.at<double>(1) = point3d.y;
- point3d_vec.at<double>(2) = point3d.z;
- point3d_vec.at<double>(3) = 1;
-
- // 2D point vector [u v 1]'
- cv::Mat point2d_vec = cv::Mat(4, 1, CV_64FC1);
- point2d_vec = _A_matrix * _P_matrix * point3d_vec;
-
- // Normalization of [u v]'
- cv::Point2f point2d;
- point2d.x = point2d_vec.at<double>(0) / point2d_vec.at<double>(2);
- point2d.y = point2d_vec.at<double>(1) / point2d_vec.at<double>(2);
-
- return point2d;
- }
-
- The above function is used to compute all the 3D points of the object *Mesh* to show the pose of the object.
-
- You can also change RANSAC parameters and PnP method:
-
- .. code-block:: cpp
-
- ./cpp-tutorial-pnp_detection --error=0.25 --confidence=0.90 --iterations=250 --method=3
-
-
-6. **Linear Kalman Filter for bad poses rejection**
-
- Is it common in computer vision or robotics fields that after applying detection or tracking techniques, bad results are obtained due to some sensor errors. In order to avoid these bad detections in this tutorial is explained how to implement a Linear Kalman Filter. The Kalman Filter will be applied after detected a given number of inliers.
-
- You can find more information about what `Kalman Filter <http://en.wikipedia.org/wiki/Kalman_filter>`_ is. In this tutorial it's used the OpenCV implementation of the :video:`Kalman Filter <kalmanfilter>` based on `Linear Kalman Filter for position and orientation tracking <http://campar.in.tum.de/Chair/KalmanFilter>`_ to set the dynamics and measurement models.
-
- Firstly, we have to define our state vector which will have 18 states: the positional data (x,y,z) with its first and second derivatives (velocity and acceleration), then rotation is added in form of three euler angles (roll, pitch, jaw) together with their first and second derivatives (angular velocity and acceleration)
-
- .. math::
-
- X = (x,y,z,\dot x,\dot y,\dot z,\ddot x,\ddot y,\ddot z,\psi,\theta,\phi,\dot \psi,\dot \theta,\dot \phi,\ddot \psi,\ddot \theta,\ddot \phi)^T
-
- Secondly, we have to define the number of measuremnts which will be 6: from :math:`R` and :math:`t` we can extract :math:`(x,y,z)` and :math:`(\psi,\theta,\phi)`. In addition, we have to define the number of control actions to apply to the system which in this case will be *zero*. Finally, we have to define the differential time between measurements which in this case is :math:`1/T`, where *T* is the frame rate of the video.
-
- .. code-block:: cpp
-
- cv::KalmanFilter KF; // instantiate Kalman Filter
-
- int nStates = 18; // the number of states
- int nMeasurements = 6; // the number of measured states
- int nInputs = 0; // the number of action control
-
- double dt = 0.125; // time between measurements (1/FPS)
-
- initKalmanFilter(KF, nStates, nMeasurements, nInputs, dt); // init function
-
-
- The following code corresponds to the *Kalman Filter* initialisation. Firstly, is set the process noise, the measurement noise and the error covariance matrix. Secondly, are set the transition matrix which is the dynamic model and finally the measurement matrix, which is the measurement model.
-
- You can tune the process and measurement noise to improve the *Kalman Filter* performance. As the measurement noise is reduced the faster will converge doing the algorithm sensitive in front of bad measurements.
-
- .. code-block:: cpp
-
- void initKalmanFilter(cv::KalmanFilter &KF, int nStates, int nMeasurements, int nInputs, double dt)
- {
-
- KF.init(nStates, nMeasurements, nInputs, CV_64F); // init Kalman Filter
-
- cv::setIdentity(KF.processNoiseCov, cv::Scalar::all(1e-5)); // set process noise
- cv::setIdentity(KF.measurementNoiseCov, cv::Scalar::all(1e-4)); // set measurement noise
- cv::setIdentity(KF.errorCovPost, cv::Scalar::all(1)); // error covariance
-
-
- /* DYNAMIC MODEL */
-
- // [1 0 0 dt 0 0 dt2 0 0 0 0 0 0 0 0 0 0 0]
- // [0 1 0 0 dt 0 0 dt2 0 0 0 0 0 0 0 0 0 0]
- // [0 0 1 0 0 dt 0 0 dt2 0 0 0 0 0 0 0 0 0]
- // [0 0 0 1 0 0 dt 0 0 0 0 0 0 0 0 0 0 0]
- // [0 0 0 0 1 0 0 dt 0 0 0 0 0 0 0 0 0 0]
- // [0 0 0 0 0 1 0 0 dt 0 0 0 0 0 0 0 0 0]
- // [0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0]
- // [0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0]
- // [0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0]
- // [0 0 0 0 0 0 0 0 0 1 0 0 dt 0 0 dt2 0 0]
- // [0 0 0 0 0 0 0 0 0 0 1 0 0 dt 0 0 dt2 0]
- // [0 0 0 0 0 0 0 0 0 0 0 1 0 0 dt 0 0 dt2]
- // [0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 dt 0 0]
- // [0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 dt 0]
- // [0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 dt]
- // [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0]
- // [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0]
- // [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1]
-
- // position
- KF.transitionMatrix.at<double>(0,3) = dt;
- KF.transitionMatrix.at<double>(1,4) = dt;
- KF.transitionMatrix.at<double>(2,5) = dt;
- KF.transitionMatrix.at<double>(3,6) = dt;
- KF.transitionMatrix.at<double>(4,7) = dt;
- KF.transitionMatrix.at<double>(5,8) = dt;
- KF.transitionMatrix.at<double>(0,6) = 0.5*pow(dt,2);
- KF.transitionMatrix.at<double>(1,7) = 0.5*pow(dt,2);
- KF.transitionMatrix.at<double>(2,8) = 0.5*pow(dt,2);
-
- // orientation
- KF.transitionMatrix.at<double>(9,12) = dt;
- KF.transitionMatrix.at<double>(10,13) = dt;
- KF.transitionMatrix.at<double>(11,14) = dt;
- KF.transitionMatrix.at<double>(12,15) = dt;
- KF.transitionMatrix.at<double>(13,16) = dt;
- KF.transitionMatrix.at<double>(14,17) = dt;
- KF.transitionMatrix.at<double>(9,15) = 0.5*pow(dt,2);
- KF.transitionMatrix.at<double>(10,16) = 0.5*pow(dt,2);
- KF.transitionMatrix.at<double>(11,17) = 0.5*pow(dt,2);
-
-
- /* MEASUREMENT MODEL */
-
- // [1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
- // [0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
- // [0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
- // [0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0]
- // [0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0]
- // [0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0]
-
- KF.measurementMatrix.at<double>(0,0) = 1; // x
- KF.measurementMatrix.at<double>(1,1) = 1; // y
- KF.measurementMatrix.at<double>(2,2) = 1; // z
- KF.measurementMatrix.at<double>(3,9) = 1; // roll
- KF.measurementMatrix.at<double>(4,10) = 1; // pitch
- KF.measurementMatrix.at<double>(5,11) = 1; // yaw
-
- }
-
- In the following code is the 5th step of the main algorithm. When the obtained number of inliers after *Ransac* is over the threshold, the measurements matrix is filled and then the *Kalman Filter* is updated:
-
- .. code-block:: cpp
-
- // -- Step 5: Kalman Filter
-
- // GOOD MEASUREMENT
- if( inliers_idx.rows >= minInliersKalman )
- {
-
- // Get the measured translation
- cv::Mat translation_measured(3, 1, CV_64F);
- translation_measured = pnp_detection.get_t_matrix();
-
- // Get the measured rotation
- cv::Mat rotation_measured(3, 3, CV_64F);
- rotation_measured = pnp_detection.get_R_matrix();
-
- // fill the measurements vector
- fillMeasurements(measurements, translation_measured, rotation_measured);
-
- }
-
- // Instantiate estimated translation and rotation
- cv::Mat translation_estimated(3, 1, CV_64F);
- cv::Mat rotation_estimated(3, 3, CV_64F);
-
- // update the Kalman filter with good measurements
- updateKalmanFilter( KF, measurements,
- translation_estimated, rotation_estimated);
-
- The following code corresponds to the *fillMeasurements()* function which converts the measured `Rotation Matrix to Eulers angles <http://euclideanspace.com/maths/geometry/rotations/conversions/matrixToEuler/index.htm>`_ and fill the measurements matrix along with the measured translation vector:
-
- .. code-block:: cpp
-
- void fillMeasurements( cv::Mat &measurements,
- const cv::Mat &translation_measured, const cv::Mat &rotation_measured)
- {
- // Convert rotation matrix to euler angles
- cv::Mat measured_eulers(3, 1, CV_64F);
- measured_eulers = rot2euler(rotation_measured);
-
- // Set measurement to predict
- measurements.at<double>(0) = translation_measured.at<double>(0); // x
- measurements.at<double>(1) = translation_measured.at<double>(1); // y
- measurements.at<double>(2) = translation_measured.at<double>(2); // z
- measurements.at<double>(3) = measured_eulers.at<double>(0); // roll
- measurements.at<double>(4) = measured_eulers.at<double>(1); // pitch
- measurements.at<double>(5) = measured_eulers.at<double>(2); // yaw
- }
-
-
- The following code corresponds to the *updateKalmanFilter()* function which update the Kalman Filter and set the estimated Rotation Matrix and translation vector. The estimated Rotation Matrix comes from the estimated `Euler angles to Rotation Matrix <http://euclideanspace.com/maths/geometry/rotations/conversions/eulerToMatrix/index.htm>`_.
-
- .. code-block:: cpp
-
- void updateKalmanFilter( cv::KalmanFilter &KF, cv::Mat &measurement,
- cv::Mat &translation_estimated, cv::Mat &rotation_estimated )
- {
-
- // First predict, to update the internal statePre variable
- cv::Mat prediction = KF.predict();
-
- // The "correct" phase that is going to use the predicted value and our measurement
- cv::Mat estimated = KF.correct(measurement);
-
- // Estimated translation
- translation_estimated.at<double>(0) = estimated.at<double>(0);
- translation_estimated.at<double>(1) = estimated.at<double>(1);
- translation_estimated.at<double>(2) = estimated.at<double>(2);
-
- // Estimated euler angles
- cv::Mat eulers_estimated(3, 1, CV_64F);
- eulers_estimated.at<double>(0) = estimated.at<double>(9);
- eulers_estimated.at<double>(1) = estimated.at<double>(10);
- eulers_estimated.at<double>(2) = estimated.at<double>(11);
-
- // Convert estimated quaternion to rotation matrix
- rotation_estimated = euler2rot(eulers_estimated);
-
- }
-
- The 6th step is set the estimated rotation-translation matrix:
-
- .. code-block:: cpp
-
- // -- Step 6: Set estimated projection matrix
- pnp_detection_est.set_P_matrix(rotation_estimated, translation_estimated);
-
-
- The last and optional step is draw the found pose. To do it I implemented a function to draw all the mesh 3D points and an extra reference axis:
-
- .. code-block:: cpp
-
- // -- Step X: Draw pose
-
- drawObjectMesh(frame_vis, &mesh, &pnp_detection, green); // draw current pose
- drawObjectMesh(frame_vis, &mesh, &pnp_detection_est, yellow); // draw estimated pose
-
- double l = 5;
- std::vector<cv::Point2f> pose_points2d;
- pose_points2d.push_back(pnp_detection_est.backproject3DPoint(cv::Point3f(0,0,0))); // axis center
- pose_points2d.push_back(pnp_detection_est.backproject3DPoint(cv::Point3f(l,0,0))); // axis x
- pose_points2d.push_back(pnp_detection_est.backproject3DPoint(cv::Point3f(0,l,0))); // axis y
- pose_points2d.push_back(pnp_detection_est.backproject3DPoint(cv::Point3f(0,0,l))); // axis z
- draw3DCoordinateAxes(frame_vis, pose_points2d); // draw axes
-
- You can also modify the minimum inliers to update Kalman Filter:
-
- .. code-block:: cpp
-
- ./cpp-tutorial-pnp_detection --inliers=20
-
-
-Results
-=======
-
-The following videos are the results of pose estimation in real time using the explained detection algorithm using the following parameters:
-
- .. code-block:: cpp
-
- // Robust Matcher parameters
-
- int numKeyPoints = 2000; // number of detected keypoints
- float ratio = 0.70f; // ratio test
- bool fast_match = true; // fastRobustMatch() or robustMatch()
-
-
- // RANSAC parameters
-
- int iterationsCount = 500; // number of Ransac iterations.
- int reprojectionError = 2.0; // maximum allowed distance to consider it an inlier.
- float confidence = 0.95; // ransac successful confidence.
-
-
- // Kalman Filter parameters
-
- int minInliersKalman = 30; // Kalman threshold updating
-
-
-You can watch the real time pose estimation on the `YouTube here <http://www.youtube.com/user/opencvdev/videos>`_.
-
-.. raw:: html
-
- <div align="center">
- <iframe title="Pose estimation of textured object using OpenCV" width="560" height="349" src="http://www.youtube.com/embed/XNATklaJlSQ?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
- <div align="center">
- <iframe title="Pose estimation of textured object using OpenCV in cluttered background" width="560" height="349" src="http://www.youtube.com/embed/YLS9bWek78k?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _Table-Of-Content-Calib3D:
-
-*calib3d* module. Camera calibration and 3D reconstruction
------------------------------------------------------------
-
-Although we got most of our images in a 2D format they do come from a 3D world. Here you will learn how to find out from the 2D images information about the 3D world.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |CameraCalSqChess| **Title:** :ref:`CameraCalibrationSquareChessBoardTutorial`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_VictorE|
-
- You will use some chessboard images to calibrate your camera.
-
- ===================== ==============================================
-
- .. |CameraCalSqChess| image:: images/camera_calibration_square_chess.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |CameraCalibration| **Title:** :ref:`cameraCalibrationOpenCV`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- Camera calibration by using either the chessboard, circle or the asymmetrical circle pattern. Get the images either from a camera attached, a video file or from an image collection.
-
- ===================== ==============================================
-
- .. |CameraCalibration| image:: images/camera_calibration.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |PoseEstimation| **Title:** :ref:`realTimePoseEstimation`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* Edgar Riba
-
- Real time pose estimation of a textured object using ORB features, FlannBased matcher, PnP approach plus Ransac and Linear Kalman Filter to reject possible bad poses.
-
- ===================== ==============================================
-
- .. |PoseEstimation| image:: images/real_time_pose_estimation.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../camera_calibration_square_chess/camera_calibration_square_chess
- ../camera_calibration/camera_calibration
- ../real_time_pose/real_time_pose
+++ /dev/null
-.. _Adding_Images:
-
-Adding (blending) two images using OpenCV
-*******************************************
-
-Goal
-=====
-
-In this tutorial you will learn:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * what is *linear blending* and why it is useful;
- * how to add two images using :add_weighted:`addWeighted <>`
-
-Theory
-=======
-
-.. note::
-
- The explanation below belongs to the book `Computer Vision: Algorithms and Applications <http://szeliski.org/Book/>`_ by Richard Szeliski
-
-From our previous tutorial, we know already a bit of *Pixel operators*. An interesting dyadic (two-input) operator is the *linear blend operator*:
-
-.. math::
-
- g(x) = (1 - \alpha)f_{0}(x) + \alpha f_{1}(x)
-
-By varying :math:`\alpha` from :math:`0 \rightarrow 1` this operator can be used to perform a temporal *cross-disolve* between two images or videos, as seen in slide shows and film productions (cool, eh?)
-
-Code
-=====
-
-As usual, after the not-so-lengthy explanation, let's go to the code:
-
-.. code-block:: cpp
-
- #include <opencv2/opencv.hpp>
- #include <iostream>
-
- using namespace cv;
-
- int main( int argc, char** argv )
- {
- double alpha = 0.5; double beta; double input;
-
- Mat src1, src2, dst;
-
- /// Ask the user enter alpha
- std::cout<<" Simple Linear Blender "<<std::endl;
- std::cout<<"-----------------------"<<std::endl;
- std::cout<<"* Enter alpha [0-1]: ";
- std::cin>>input;
-
- /// We use the alpha provided by the user if it is between 0 and 1
- if( input >= 0.0 && input <= 1.0 )
- { alpha = input; }
-
- /// Read image ( same size, same type )
- src1 = imread("../../images/LinuxLogo.jpg");
- src2 = imread("../../images/WindowsLogo.jpg");
-
- if( !src1.data ) { printf("Error loading src1 \n"); return -1; }
- if( !src2.data ) { printf("Error loading src2 \n"); return -1; }
-
- /// Create Windows
- namedWindow("Linear Blend", 1);
-
- beta = ( 1.0 - alpha );
- addWeighted( src1, alpha, src2, beta, 0.0, dst);
-
- imshow( "Linear Blend", dst );
-
- waitKey(0);
- return 0;
- }
-
-Explanation
-============
-
-#. Since we are going to perform:
-
- .. math::
-
- g(x) = (1 - \alpha)f_{0}(x) + \alpha f_{1}(x)
-
- We need two source images (:math:`f_{0}(x)` and :math:`f_{1}(x)`). So, we load them in the usual way:
-
- .. code-block:: cpp
-
- src1 = imread("../../images/LinuxLogo.jpg");
- src2 = imread("../../images/WindowsLogo.jpg");
-
- .. warning::
-
- Since we are *adding* *src1* and *src2*, they both have to be of the same size (width and height) and type.
-
-#. Now we need to generate the :math:`g(x)` image. For this, the function :add_weighted:`addWeighted <>` comes quite handy:
-
- .. code-block:: cpp
-
- beta = ( 1.0 - alpha );
- addWeighted( src1, alpha, src2, beta, 0.0, dst);
-
- since :add_weighted:`addWeighted <>` produces:
-
- .. math::
-
- dst = \alpha \cdot src1 + \beta \cdot src2 + \gamma
-
- In this case, :math:`\gamma` is the argument :math:`0.0` in the code above.
-
-#. Create windows, show the images and wait for the user to end the program.
-
-Result
-=======
-
-.. image:: images/Adding_Images_Tutorial_Result_Big.jpg
- :alt: Blending Images Tutorial - Final Result
- :align: center
+++ /dev/null
-.. _Drawing_1:
-
-Basic Drawing
-****************
-
-Goals
-======
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use :point:`Point <>` to define 2D points in an image.
- * Use :scalar:`Scalar <>` and why it is useful
- * Draw a **line** by using the OpenCV function :line:`line <>`
- * Draw an **ellipse** by using the OpenCV function :ellipse:`ellipse <>`
- * Draw a **rectangle** by using the OpenCV function :rectangle:`rectangle <>`
- * Draw a **circle** by using the OpenCV function :circle:`circle <>`
- * Draw a **filled polygon** by using the OpenCV function :fill_poly:`fillPoly <>`
-
-OpenCV Theory
-===============
-
-For this tutorial, we will heavily use two structures: :point:`Point <>` and :scalar:`Scalar <>`:
-
-Point
--------
-
-.. container:: enumeratevisibleitemswithsquare
-
- It represents a 2D point, specified by its image coordinates :math:`x` and :math:`y`. We can define it as:
-
-.. code-block:: cpp
-
- Point pt;
- pt.x = 10;
- pt.y = 8;
-
-or
-
-.. code-block:: cpp
-
- Point pt = Point(10, 8);
-
-Scalar
--------
-* Represents a 4-element vector. The type Scalar is widely used in OpenCV for passing pixel values.
-* In this tutorial, we will use it extensively to represent RGB color values (3 parameters). It is not necessary to define the last argument if it is not going to be used.
-* Let's see an example, if we are asked for a color argument and we give:
-
- .. code-block:: cpp
-
- Scalar( a, b, c )
-
- We would be defining a RGB color such as: *Red = c*, *Green = b* and *Blue = a*
-
-
-Code
-=====
-* This code is in your OpenCV sample folder. Otherwise you can grab it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/core/Matrix/Drawing_1.cpp>`_
-
-Explanation
-=============
-
-#. Since we plan to draw two examples (an atom and a rook), we have to create 02 images and two windows to display them.
-
- .. code-block:: cpp
-
- /// Windows names
- char atom_window[] = "Drawing 1: Atom";
- char rook_window[] = "Drawing 2: Rook";
-
- /// Create black empty images
- Mat atom_image = Mat::zeros( w, w, CV_8UC3 );
- Mat rook_image = Mat::zeros( w, w, CV_8UC3 );
-
-#. We created functions to draw different geometric shapes. For instance, to draw the atom we used *MyEllipse* and *MyFilledCircle*:
-
- .. code-block:: cpp
-
- /// 1. Draw a simple atom:
-
- /// 1.a. Creating ellipses
- MyEllipse( atom_image, 90 );
- MyEllipse( atom_image, 0 );
- MyEllipse( atom_image, 45 );
- MyEllipse( atom_image, -45 );
-
- /// 1.b. Creating circles
- MyFilledCircle( atom_image, Point( w/2.0, w/2.0) );
-
-#. And to draw the rook we employed *MyLine*, *rectangle* and a *MyPolygon*:
-
- .. code-block:: cpp
-
- /// 2. Draw a rook
-
- /// 2.a. Create a convex polygon
- MyPolygon( rook_image );
-
- /// 2.b. Creating rectangles
- rectangle( rook_image,
- Point( 0, 7*w/8.0 ),
- Point( w, w),
- Scalar( 0, 255, 255 ),
- -1,
- 8 );
-
- /// 2.c. Create a few lines
- MyLine( rook_image, Point( 0, 15*w/16 ), Point( w, 15*w/16 ) );
- MyLine( rook_image, Point( w/4, 7*w/8 ), Point( w/4, w ) );
- MyLine( rook_image, Point( w/2, 7*w/8 ), Point( w/2, w ) );
- MyLine( rook_image, Point( 3*w/4, 7*w/8 ), Point( 3*w/4, w ) );
-
-#. Let's check what is inside each of these functions:
-
- * *MyLine*
-
- .. code-block:: cpp
-
- void MyLine( Mat img, Point start, Point end )
- {
- int thickness = 2;
- int lineType = 8;
- line( img, start, end,
- Scalar( 0, 0, 0 ),
- thickness,
- lineType );
- }
-
- As we can see, *MyLine* just call the function :line:`line <>`, which does the following:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Draw a line from Point **start** to Point **end**
- * The line is displayed in the image **img**
- * The line color is defined by **Scalar( 0, 0, 0)** which is the RGB value correspondent to **Black**
- * The line thickness is set to **thickness** (in this case 2)
- * The line is a 8-connected one (**lineType** = 8)
-
- * *MyEllipse*
-
- .. code-block:: cpp
-
- void MyEllipse( Mat img, double angle )
- {
- int thickness = 2;
- int lineType = 8;
-
- ellipse( img,
- Point( w/2.0, w/2.0 ),
- Size( w/4.0, w/16.0 ),
- angle,
- 0,
- 360,
- Scalar( 255, 0, 0 ),
- thickness,
- lineType );
- }
-
- From the code above, we can observe that the function :ellipse:`ellipse <>` draws an ellipse such that:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * The ellipse is displayed in the image **img**
- * The ellipse center is located in the point **(w/2.0, w/2.0)** and is enclosed in a box of size **(w/4.0, w/16.0)**
- * The ellipse is rotated **angle** degrees
- * The ellipse extends an arc between **0** and **360** degrees
- * The color of the figure will be **Scalar( 255, 255, 0)** which means blue in RGB value.
- * The ellipse's **thickness** is 2.
-
-
- * *MyFilledCircle*
-
- .. code-block:: cpp
-
- void MyFilledCircle( Mat img, Point center )
- {
- int thickness = -1;
- int lineType = 8;
-
- circle( img,
- center,
- w/32.0,
- Scalar( 0, 0, 255 ),
- thickness,
- lineType );
- }
-
- Similar to the ellipse function, we can observe that *circle* receives as arguments:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * The image where the circle will be displayed (**img**)
- * The center of the circle denoted as the Point **center**
- * The radius of the circle: **w/32.0**
- * The color of the circle: **Scalar(0, 0, 255)** which means *Red* in BGR
- * Since **thickness** = -1, the circle will be drawn filled.
-
- * *MyPolygon*
-
- .. code-block:: cpp
-
- void MyPolygon( Mat img )
- {
- int lineType = 8;
-
- /* Create some points */
- Point rook_points[1][20];
- rook_points[0][0] = Point( w/4.0, 7*w/8.0 );
- rook_points[0][1] = Point( 3*w/4.0, 7*w/8.0 );
- rook_points[0][2] = Point( 3*w/4.0, 13*w/16.0 );
- rook_points[0][3] = Point( 11*w/16.0, 13*w/16.0 );
- rook_points[0][4] = Point( 19*w/32.0, 3*w/8.0 );
- rook_points[0][5] = Point( 3*w/4.0, 3*w/8.0 );
- rook_points[0][6] = Point( 3*w/4.0, w/8.0 );
- rook_points[0][7] = Point( 26*w/40.0, w/8.0 );
- rook_points[0][8] = Point( 26*w/40.0, w/4.0 );
- rook_points[0][9] = Point( 22*w/40.0, w/4.0 );
- rook_points[0][10] = Point( 22*w/40.0, w/8.0 );
- rook_points[0][11] = Point( 18*w/40.0, w/8.0 );
- rook_points[0][12] = Point( 18*w/40.0, w/4.0 );
- rook_points[0][13] = Point( 14*w/40.0, w/4.0 );
- rook_points[0][14] = Point( 14*w/40.0, w/8.0 );
- rook_points[0][15] = Point( w/4.0, w/8.0 );
- rook_points[0][16] = Point( w/4.0, 3*w/8.0 );
- rook_points[0][17] = Point( 13*w/32.0, 3*w/8.0 );
- rook_points[0][18] = Point( 5*w/16.0, 13*w/16.0 );
- rook_points[0][19] = Point( w/4.0, 13*w/16.0) ;
-
- const Point* ppt[1] = { rook_points[0] };
- int npt[] = { 20 };
-
- fillPoly( img,
- ppt,
- npt,
- 1,
- Scalar( 255, 255, 255 ),
- lineType );
- }
-
- To draw a filled polygon we use the function :fill_poly:`fillPoly <>`. We note that:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * The polygon will be drawn on **img**
- * The vertices of the polygon are the set of points in **ppt**
- * The total number of vertices to be drawn are **npt**
- * The number of polygons to be drawn is only **1**
- * The color of the polygon is defined by **Scalar( 255, 255, 255)**, which is the BGR value for *white*
-
- * *rectangle*
-
- .. code-block:: cpp
-
- rectangle( rook_image,
- Point( 0, 7*w/8.0 ),
- Point( w, w),
- Scalar( 0, 255, 255 ),
- -1, 8 );
-
- Finally we have the :rectangle:`rectangle <>` function (we did not create a special function for this guy). We note that:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * The rectangle will be drawn on **rook_image**
- * Two opposite vertices of the rectangle are defined by ** Point( 0, 7*w/8.0 )** and **Point( w, w)**
- * The color of the rectangle is given by **Scalar(0, 255, 255)** which is the BGR value for *yellow*
- * Since the thickness value is given by **-1**, the rectangle will be filled.
-
-Result
-=======
-
-Compiling and running your program should give you a result like this:
-
-.. image:: images/Drawing_1_Tutorial_Result_0.png
- :alt: Drawing Tutorial 1 - Final Result
- :align: center
+++ /dev/null
-.. _Basic_Linear_Transform:
-
-Changing the contrast and brightness of an image!
-***************************************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + Access pixel values
- + Initialize a matrix with zeros
- + Learn what :saturate_cast:`saturate_cast <>` does and why it is useful
- + Get some cool info about pixel transformations
-
-Theory
-=======
-
-.. note::
-
- The explanation below belongs to the book `Computer Vision: Algorithms and Applications <http://szeliski.org/Book/>`_ by Richard Szeliski
-
-Image Processing
---------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * A general image processing operator is a function that takes one or more input images and produces an output image.
-
- * Image transforms can be seen as:
-
- + Point operators (pixel transforms)
- + Neighborhood (area-based) operators
-
-
-Pixel Transforms
------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * In this kind of image processing transform, each output pixel's value depends on only the corresponding input pixel value (plus, potentially, some globally collected information or parameters).
-
- * Examples of such operators include *brightness and contrast adjustments* as well as color correction and transformations.
-
-Brightness and contrast adjustments
-------------------------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Two commonly used point processes are *multiplication* and *addition* with a constant:
-
- .. math::
-
- g(x) = \alpha f(x) + \beta
-
- * The parameters :math:`\alpha > 0` and :math:`\beta` are often called the *gain* and *bias* parameters; sometimes these parameters are said to control *contrast* and *brightness* respectively.
-
- * You can think of :math:`f(x)` as the source image pixels and :math:`g(x)` as the output image pixels. Then, more conveniently we can write the expression as:
-
- .. math::
-
- g(i,j) = \alpha \cdot f(i,j) + \beta
-
- where :math:`i` and :math:`j` indicates that the pixel is located in the *i-th* row and *j-th* column.
-
-Code
-=====
-
-* The following code performs the operation :math:`g(i,j) = \alpha \cdot f(i,j) + \beta` :
-
-.. code-block:: cpp
-
- #include <opencv2/opencv.hpp>
- #include <iostream>
-
- using namespace cv;
-
- double alpha; /*< Simple contrast control */
- int beta; /*< Simple brightness control */
-
- int main( int argc, char** argv )
- {
- /// Read image given by user
- Mat image = imread( argv[1] );
- Mat new_image = Mat::zeros( image.size(), image.type() );
-
- /// Initialize values
- std::cout<<" Basic Linear Transforms "<<std::endl;
- std::cout<<"-------------------------"<<std::endl;
- std::cout<<"* Enter the alpha value [1.0-3.0]: ";std::cin>>alpha;
- std::cout<<"* Enter the beta value [0-100]: "; std::cin>>beta;
-
- /// Do the operation new_image(i,j) = alpha*image(i,j) + beta
- for( int y = 0; y < image.rows; y++ ) {
- for( int x = 0; x < image.cols; x++ ) {
- for( int c = 0; c < 3; c++ ) {
- new_image.at<Vec3b>(y,x)[c] =
- saturate_cast<uchar>( alpha*( image.at<Vec3b>(y,x)[c] ) + beta );
- }
- }
- }
-
- /// Create Windows
- namedWindow("Original Image", 1);
- namedWindow("New Image", 1);
-
- /// Show stuff
- imshow("Original Image", image);
- imshow("New Image", new_image);
-
- /// Wait until user press some key
- waitKey();
- return 0;
- }
-
-Explanation
-============
-
-#. We begin by creating parameters to save :math:`\alpha` and :math:`\beta` to be entered by the user:
-
- .. code-block:: cpp
-
- double alpha;
- int beta;
-
-
-#. We load an image using :imread:`imread <>` and save it in a Mat object:
-
- .. code-block:: cpp
-
- Mat image = imread( argv[1] );
-
-#. Now, since we will make some transformations to this image, we need a new Mat object to store it. Also, we want this to have the following features:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Initial pixel values equal to zero
- * Same size and type as the original image
-
- .. code-block:: cpp
-
- Mat new_image = Mat::zeros( image.size(), image.type() );
-
- We observe that :mat_zeros:`Mat::zeros <>` returns a Matlab-style zero initializer based on *image.size()* and *image.type()*
-
-#. Now, to perform the operation :math:`g(i,j) = \alpha \cdot f(i,j) + \beta` we will access to each pixel in image. Since we are operating with RGB images, we will have three values per pixel (R, G and B), so we will also access them separately. Here is the piece of code:
-
- .. code-block:: cpp
-
- for( int y = 0; y < image.rows; y++ ) {
- for( int x = 0; x < image.cols; x++ ) {
- for( int c = 0; c < 3; c++ ) {
- new_image.at<Vec3b>(y,x)[c] =
- saturate_cast<uchar>( alpha*( image.at<Vec3b>(y,x)[c] ) + beta );
- }
- }
- }
-
- Notice the following:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * To access each pixel in the images we are using this syntax: *image.at<Vec3b>(y,x)[c]* where *y* is the row, *x* is the column and *c* is R, G or B (0, 1 or 2).
-
- * Since the operation :math:`\alpha \cdot p(i,j) + \beta` can give values out of range or not integers (if :math:`\alpha` is float), we use :saturate_cast:`saturate_cast <>` to make sure the values are valid.
-
-
-#. Finally, we create windows and show the images, the usual way.
-
- .. code-block:: cpp
-
- namedWindow("Original Image", 1);
- namedWindow("New Image", 1);
-
- imshow("Original Image", image);
- imshow("New Image", new_image);
-
- waitKey(0);
-
-.. note::
-
- Instead of using the **for** loops to access each pixel, we could have simply used this command:
-
- .. code-block:: cpp
-
- image.convertTo(new_image, -1, alpha, beta);
-
- where :convert_to:`convertTo <>` would effectively perform *new_image = a*image + beta*. However, we wanted to show you how to access each pixel. In any case, both methods give the same result but convertTo is more optimized and works a lot faster.
-
-Result
-=======
-
-* Running our code and using :math:`\alpha = 2.2` and :math:`\beta = 50`
-
- .. code-block:: bash
-
- $ ./BasicLinearTransforms lena.jpg
- Basic Linear Transforms
- -------------------------
- * Enter the alpha value [1.0-3.0]: 2.2
- * Enter the beta value [0-100]: 50
-
-* We get this:
-
- .. image:: images/Basic_Linear_Transform_Tutorial_Result_big.jpg
- :alt: Basic Linear Transform - Final Result
- :align: center
+++ /dev/null
-.. _discretFourierTransform:
-
-Discrete Fourier Transform
-**************************
-
-Goal
-====
-
-We'll seek answers for the following questions:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + What is a Fourier transform and why use it?
- + How to do it in OpenCV?
- + Usage of functions such as: :imgprocfilter:`copyMakeBorder() <copymakeborder>`, :operationsonarrays:`merge() <merge>`, :operationsonarrays:`dft() <dft>`, :operationsonarrays:`getOptimalDFTSize() <getoptimaldftsize>`, :operationsonarrays:`log() <log>` and :operationsonarrays:`normalize() <normalize>` .
-
-Source code
-===========
-
-You can :download:`download this from here <../../../../samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp>` or find it in the :file:`samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp` of the OpenCV source code library.
-
-Here's a sample usage of :operationsonarrays:`dft() <dft>` :
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 1-4, 6, 20-21, 24-79
-
-Explanation
-===========
-
-The Fourier Transform will decompose an image into its sinus and cosines components. In other words, it will transform an image from its spatial domain to its frequency domain. The idea is that any function may be approximated exactly with the sum of infinite sinus and cosines functions. The Fourier Transform is a way how to do this. Mathematically a two dimensional images Fourier transform is:
-
-.. math::
-
- F(k,l) = \displaystyle\sum\limits_{i=0}^{N-1}\sum\limits_{j=0}^{N-1} f(i,j)e^{-i2\pi(\frac{ki}{N}+\frac{lj}{N})}
-
- e^{ix} = \cos{x} + i\sin {x}
-
-Here f is the image value in its spatial domain and F in its frequency domain. The result of the transformation is complex numbers. Displaying this is possible either via a *real* image and a *complex* image or via a *magnitude* and a *phase* image. However, throughout the image processing algorithms only the *magnitude* image is interesting as this contains all the information we need about the images geometric structure. Nevertheless, if you intend to make some modifications of the image in these forms and then you need to retransform it you'll need to preserve both of these.
-
-In this sample I'll show how to calculate and show the *magnitude* image of a Fourier Transform. In case of digital images are discrete. This means they may take up a value from a given domain value. For example in a basic gray scale image values usually are between zero and 255. Therefore the Fourier Transform too needs to be of a discrete type resulting in a Discrete Fourier Transform (*DFT*). You'll want to use this whenever you need to determine the structure of an image from a geometrical point of view. Here are the steps to follow (in case of a gray scale input image *I*):
-
-1. **Expand the image to an optimal size**. The performance of a DFT is dependent of the image size. It tends to be the fastest for image sizes that are multiple of the numbers two, three and five. Therefore, to achieve maximal performance it is generally a good idea to pad border values to the image to get a size with such traits. The :operationsonarrays:`getOptimalDFTSize() <getoptimaldftsize>` returns this optimal size and we can use the :imgprocfilter:`copyMakeBorder() <copymakeborder>` function to expand the borders of an image:
-
- .. code-block:: cpp
-
- Mat padded; //expand input image to optimal size
- int m = getOptimalDFTSize( I.rows );
- int n = getOptimalDFTSize( I.cols ); // on the border add zero pixels
- copyMakeBorder(I, padded, 0, m - I.rows, 0, n - I.cols, BORDER_CONSTANT, Scalar::all(0));
-
- The appended pixels are initialized with zero.
-
-2. **Make place for both the complex and the real values**. The result of a Fourier Transform is complex. This implies that for each image value the result is two image values (one per component). Moreover, the frequency domains range is much larger than its spatial counterpart. Therefore, we store these usually at least in a *float* format. Therefore we'll convert our input image to this type and expand it with another channel to hold the complex values:
-
- .. code-block:: cpp
-
- Mat planes[] = {Mat_<float>(padded), Mat::zeros(padded.size(), CV_32F)};
- Mat complexI;
- merge(planes, 2, complexI); // Add to the expanded another plane with zeros
-
-3. **Make the Discrete Fourier Transform**. It's possible an in-place calculation (same input as output):
-
- .. code-block:: cpp
-
- dft(complexI, complexI); // this way the result may fit in the source matrix
-
-4. **Transform the real and complex values to magnitude**. A complex number has a real (*Re*) and a complex (imaginary - *Im*) part. The results of a DFT are complex numbers. The magnitude of a DFT is:
-
- .. math::
-
- M = \sqrt[2]{ {Re(DFT(I))}^2 + {Im(DFT(I))}^2}
-
- Translated to OpenCV code:
-
- .. code-block:: cpp
-
- split(complexI, planes); // planes[0] = Re(DFT(I), planes[1] = Im(DFT(I))
- magnitude(planes[0], planes[1], planes[0]);// planes[0] = magnitude
- Mat magI = planes[0];
-
-5. **Switch to a logarithmic scale**. It turns out that the dynamic range of the Fourier coefficients is too large to be displayed on the screen. We have some small and some high changing values that we can't observe like this. Therefore the high values will all turn out as white points, while the small ones as black. To use the gray scale values to for visualization we can transform our linear scale to a logarithmic one:
-
- .. math::
-
- M_1 = \log{(1 + M)}
-
- Translated to OpenCV code:
-
- .. code-block:: cpp
-
- magI += Scalar::all(1); // switch to logarithmic scale
- log(magI, magI);
-
-6. **Crop and rearrange**. Remember, that at the first step, we expanded the image? Well, it's time to throw away the newly introduced values. For visualization purposes we may also rearrange the quadrants of the result, so that the origin (zero, zero) corresponds with the image center.
-
- .. code-block:: cpp
-
- magI = magI(Rect(0, 0, magI.cols & -2, magI.rows & -2));
- int cx = magI.cols/2;
- int cy = magI.rows/2;
-
- Mat q0(magI, Rect(0, 0, cx, cy)); // Top-Left - Create a ROI per quadrant
- Mat q1(magI, Rect(cx, 0, cx, cy)); // Top-Right
- Mat q2(magI, Rect(0, cy, cx, cy)); // Bottom-Left
- Mat q3(magI, Rect(cx, cy, cx, cy)); // Bottom-Right
-
- Mat tmp; // swap quadrants (Top-Left with Bottom-Right)
- q0.copyTo(tmp);
- q3.copyTo(q0);
- tmp.copyTo(q3);
-
- q1.copyTo(tmp); // swap quadrant (Top-Right with Bottom-Left)
- q2.copyTo(q1);
- tmp.copyTo(q2);
-
-7. **Normalize**. This is done again for visualization purposes. We now have the magnitudes, however this are still out of our image display range of zero to one. We normalize our values to this range using the :operationsonarrays:`normalize() <normalize>` function.
-
- .. code-block:: cpp
-
- normalize(magI, magI, 0, 1, NORM_MINMAX); // Transform the matrix with float values into a
- // viewable image form (float between values 0 and 1).
-
-Result
-======
-
-An application idea would be to determine the geometrical orientation present in the image. For example, let us find out if a text is horizontal or not? Looking at some text you'll notice that the text lines sort of form also horizontal lines and the letters form sort of vertical lines. These two main components of a text snippet may be also seen in case of the Fourier transform. Let us use :download:`this horizontal <../../../../samples/data/imageTextN.png>` and :download:`this rotated<../../../../samples/data/imageTextR.png>` image about a text.
-
-In case of the horizontal text:
-
-.. image:: images/result_normal.jpg
- :alt: In case of normal text
- :align: center
-
-In case of a rotated text:
-
-.. image:: images/result_rotated.jpg
- :alt: In case of rotated text
- :align: center
-
-You can see that the most influential components of the frequency domain (brightest dots on the magnitude image) follow the geometric rotation of objects on the image. From this we may calculate the offset and perform an image rotation to correct eventual miss alignments.
+++ /dev/null
-.. _fileInputOutputXMLYAML:
-
-File Input and Output using XML and YAML files
-**********************************************
-
-Goal
-====
-
-You'll find answers for the following questions:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + How to print and read text entries to a file and OpenCV using YAML or XML files?
- + How to do the same for OpenCV data structures?
- + How to do this for your data structures?
- + Usage of OpenCV data structures such as :xmlymlpers:`FileStorage <filestorage>`, :xmlymlpers:`FileNode <filenode>` or :xmlymlpers:`FileNodeIterator <filenodeiterator>`.
-
-Source code
-===========
-
-You can :download:`download this from here <../../../../samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp>` or find it in the :file:`samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp` of the OpenCV source code library.
-
-Here's a sample code of how to achieve all the stuff enumerated at the goal list.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 1-7, 21-154
-
-Explanation
-===========
-
-Here we talk only about XML and YAML file inputs. Your output (and its respective input) file may have only one of these extensions and the structure coming from this. They are two kinds of data structures you may serialize: *mappings* (like the STL map) and *element sequence* (like the STL vector). The difference between these is that in a map every element has a unique name through what you may access it. For sequences you need to go through them to query a specific item.
-
-1. **XML/YAML File Open and Close.** Before you write any content to such file you need to open it and at the end to close it. The XML/YAML data structure in OpenCV is :xmlymlpers:`FileStorage <filestorage>`. To specify that this structure to which file binds on your hard drive you can use either its constructor or the *open()* function of this:
-
- .. code-block:: cpp
-
- string filename = "I.xml";
- FileStorage fs(filename, FileStorage::WRITE);
- //...
- fs.open(filename, FileStorage::READ);
-
- Either one of this you use the second argument is a constant specifying the type of operations you'll be able to on them: WRITE, READ or APPEND. The extension specified in the file name also determinates the output format that will be used. The output may be even compressed if you specify an extension such as *.xml.gz*.
-
- The file automatically closes when the :xmlymlpers:`FileStorage <filestorage>` objects is destroyed. However, you may explicitly call for this by using the *release* function:
-
- .. code-block:: cpp
-
- fs.release(); // explicit close
-
-#. **Input and Output of text and numbers.** The data structure uses the same << output operator that the STL library. For outputting any type of data structure we need first to specify its name. We do this by just simply printing out the name of this. For basic types you may follow this with the print of the value :
-
- .. code-block:: cpp
-
- fs << "iterationNr" << 100;
-
- Reading in is a simple addressing (via the [] operator) and casting operation or a read via the >> operator :
-
- .. code-block:: cpp
-
- int itNr;
- fs["iterationNr"] >> itNr;
- itNr = (int) fs["iterationNr"];
-
-#. **Input/Output of OpenCV Data structures.** Well these behave exactly just as the basic C++ types:
-
- .. code-block:: cpp
-
- Mat R = Mat_<uchar >::eye (3, 3),
- T = Mat_<double>::zeros(3, 1);
-
- fs << "R" << R; // Write cv::Mat
- fs << "T" << T;
-
- fs["R"] >> R; // Read cv::Mat
- fs["T"] >> T;
-
-#. **Input/Output of vectors (arrays) and associative maps.** As I mentioned beforehand, we can output maps and sequences (array, vector) too. Again we first print the name of the variable and then we have to specify if our output is either a sequence or map.
-
- For sequence before the first element print the "[" character and after the last one the "]" character:
-
- .. code-block:: cpp
-
- fs << "strings" << "["; // text - string sequence
- fs << "image1.jpg" << "Awesomeness" << "baboon.jpg";
- fs << "]"; // close sequence
-
- For maps the drill is the same however now we use the "{" and "}" delimiter characters:
-
- .. code-block:: cpp
-
- fs << "Mapping"; // text - mapping
- fs << "{" << "One" << 1;
- fs << "Two" << 2 << "}";
-
- To read from these we use the :xmlymlpers:`FileNode <filenode>` and the :xmlymlpers:`FileNodeIterator <filenodeiterator>` data structures. The [] operator of the :xmlymlpers:`FileStorage <filestorage>` class returns a :xmlymlpers:`FileNode <filenode>` data type. If the node is sequential we can use the :xmlymlpers:`FileNodeIterator <filenodeiterator>` to iterate through the items:
-
- .. code-block:: cpp
-
- FileNode n = fs["strings"]; // Read string sequence - Get node
- if (n.type() != FileNode::SEQ)
- {
- cerr << "strings is not a sequence! FAIL" << endl;
- return 1;
- }
-
- FileNodeIterator it = n.begin(), it_end = n.end(); // Go through the node
- for (; it != it_end; ++it)
- cout << (string)*it << endl;
-
- For maps you can use the [] operator again to acces the given item (or the >> operator too):
-
- .. code-block:: cpp
-
- n = fs["Mapping"]; // Read mappings from a sequence
- cout << "Two " << (int)(n["Two"]) << "; ";
- cout << "One " << (int)(n["One"]) << endl << endl;
-
-#. **Read and write your own data structures.** Suppose you have a data structure such as:
-
- .. code-block:: cpp
-
- class MyData
- {
- public:
- MyData() : A(0), X(0), id() {}
- public: // Data Members
- int A;
- double X;
- string id;
- };
-
- It's possible to serialize this through the OpenCV I/O XML/YAML interface (just as in case of the OpenCV data structures) by adding a read and a write function inside and outside of your class. For the inside part:
-
- .. code-block:: cpp
-
- void write(FileStorage& fs) const //Write serialization for this class
- {
- fs << "{" << "A" << A << "X" << X << "id" << id << "}";
- }
-
- void read(const FileNode& node) //Read serialization for this class
- {
- A = (int)node["A"];
- X = (double)node["X"];
- id = (string)node["id"];
- }
-
- Then you need to add the following functions definitions outside the class:
-
- .. code-block:: cpp
-
- void write(FileStorage& fs, const std::string&, const MyData& x)
- {
- x.write(fs);
- }
-
- void read(const FileNode& node, MyData& x, const MyData& default_value = MyData())
- {
- if(node.empty())
- x = default_value;
- else
- x.read(node);
- }
-
- Here you can observe that in the read section we defined what happens if the user tries to read a non-existing node. In this case we just return the default initialization value, however a more verbose solution would be to return for instance a minus one value for an object ID.
-
- Once you added these four functions use the >> operator for write and the << operator for read:
-
- .. code-block:: cpp
-
- MyData m(1);
- fs << "MyData" << m; // your own data structures
- fs["MyData"] >> m; // Read your own structure_
-
- Or to try out reading a non-existing read:
-
- .. code-block:: cpp
-
- fs["NonExisting"] >> m; // Do not add a fs << "NonExisting" << m command for this to work
- cout << endl << "NonExisting = " << endl << m << endl;
-
-Result
-======
-
-Well mostly we just print out the defined numbers. On the screen of your console you could see:
-
-.. code-block:: bash
-
- Write Done.
-
- Reading:
- 100image1.jpg
- Awesomeness
- baboon.jpg
- Two 2; One 1
-
-
- R = [1, 0, 0;
- 0, 1, 0;
- 0, 0, 1]
- T = [0; 0; 0]
-
- MyData =
- { id = mydata1234, X = 3.14159, A = 97}
-
- Attempt to read NonExisting (should initialize the data structure with its default).
- NonExisting =
- { id = , X = 0, A = 0}
-
- Tip: Open up output.xml with a text editor to see the serialized data.
-
-Nevertheless, it's much more interesting what you may see in the output xml file:
-
-.. code-block:: xml
-
- <?xml version="1.0"?>
- <opencv_storage>
- <iterationNr>100</iterationNr>
- <strings>
- image1.jpg Awesomeness baboon.jpg</strings>
- <Mapping>
- <One>1</One>
- <Two>2</Two></Mapping>
- <R type_id="opencv-matrix">
- <rows>3</rows>
- <cols>3</cols>
- <dt>u</dt>
- <data>
- 1 0 0 0 1 0 0 0 1</data></R>
- <T type_id="opencv-matrix">
- <rows>3</rows>
- <cols>1</cols>
- <dt>d</dt>
- <data>
- 0. 0. 0.</data></T>
- <MyData>
- <A>97</A>
- <X>3.1415926535897931e+000</X>
- <id>mydata1234</id></MyData>
- </opencv_storage>
-
-Or the YAML file:
-
-.. code-block:: yaml
-
- %YAML:1.0
- iterationNr: 100
- strings:
- - "image1.jpg"
- - Awesomeness
- - "baboon.jpg"
- Mapping:
- One: 1
- Two: 2
- R: !!opencv-matrix
- rows: 3
- cols: 3
- dt: u
- data: [ 1, 0, 0, 0, 1, 0, 0, 0, 1 ]
- T: !!opencv-matrix
- rows: 3
- cols: 1
- dt: d
- data: [ 0., 0., 0. ]
- MyData:
- A: 97
- X: 3.1415926535897931e+000
- id: mydata1234
-
-You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=A4yqVnByMMM>`_ .
-
-.. raw:: html
-
- <div align="center">
- <iframe title="File Input and Output using XML and YAML files in OpenCV" width="560" height="349" src="http://www.youtube.com/embed/A4yqVnByMMM?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _howToScanImagesOpenCV:
-
-How to scan images, lookup tables and time measurement with OpenCV
-*******************************************************************
-
-Goal
-====
-
-We'll seek answers for the following questions:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + How to go through each and every pixel of an image?
- + How is OpenCV matrix values stored?
- + How to measure the performance of our algorithm?
- + What are lookup tables and why use them?
-
-Our test case
-=============
-
-Let us consider a simple color reduction method. By using the unsigned char C and C++ type for matrix item storing, a channel of pixel may have up to 256 different values. For a three channel image this can allow the formation of way too many colors (16 million to be exact). Working with so many color shades may give a heavy blow to our algorithm performance. However, sometimes it is enough to work with a lot less of them to get the same final result.
-
-In this cases it's common that we make a *color space reduction*. This means that we divide the color space current value with a new input value to end up with fewer colors. For instance every value between zero and nine takes the new value zero, every value between ten and nineteen the value ten and so on.
-
-When you divide an *uchar* (unsigned char - aka values between zero and 255) value with an *int* value the result will be also *char*. These values may only be char values. Therefore, any fraction will be rounded down. Taking advantage of this fact the upper operation in the *uchar* domain may be expressed as:
-
-.. math::
-
- I_{new} = (\frac{I_{old}}{10}) * 10
-
-A simple color space reduction algorithm would consist of just passing through every pixel of an image matrix and applying this formula. It's worth noting that we do a divide and a multiplication operation. These operations are bloody expensive for a system. If possible it's worth avoiding them by using cheaper operations such as a few subtractions, addition or in best case a simple assignment. Furthermore, note that we only have a limited number of input values for the upper operation. In case of the *uchar* system this is 256 to be exact.
-
-Therefore, for larger images it would be wise to calculate all possible values beforehand and during the assignment just make the assignment, by using a lookup table. Lookup tables are simple arrays (having one or more dimensions) that for a given input value variation holds the final output value. Its strength lies that we do not need to make the calculation, we just need to read the result.
-
-Our test case program (and the sample presented here) will do the following: read in a console line argument image (that may be either color or gray scale - console line argument too) and apply the reduction with the given console line argument integer value. In OpenCV, at the moment they are three major ways of going through an image pixel by pixel. To make things a little more interesting will make the scanning for each image using all of these methods, and print out how long it took.
-
-You can download the full source code :download:`here <../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp>` or look it up in the samples directory of OpenCV at the cpp tutorial code for the core section. Its basic usage is:
-
-.. code-block:: bash
-
- how_to_scan_images imageName.jpg intValueToReduce [G]
-
-The final argument is optional. If given the image will be loaded in gray scale format, otherwise the RGB color way is used. The first thing is to calculate the lookup table.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
- :language: cpp
- :tab-width: 4
- :lines: 49-61
-
-Here we first use the C++ *stringstream* class to convert the third command line argument from text to an integer format. Then we use a simple look and the upper formula to calculate the lookup table. No OpenCV specific stuff here.
-
-Another issue is how do we measure time? Well OpenCV offers two simple functions to achieve this :UtilitySystemFunctions:`getTickCount() <gettickcount>` and :UtilitySystemFunctions:`getTickFrequency() <gettickfrequency>`. The first returns the number of ticks of your systems CPU from a certain event (like since you booted your system). The second returns how many times your CPU emits a tick during a second. So to measure in seconds the number of time elapsed between two operations is easy as:
-
-.. code-block:: cpp
-
- double t = (double)getTickCount();
- // do something ...
- t = ((double)getTickCount() - t)/getTickFrequency();
- cout << "Times passed in seconds: " << t << endl;
-
-.. _How_Image_Stored_Memory:
-
-How the image matrix is stored in the memory?
-=============================================
-
-As you could already read in my :ref:`matTheBasicImageContainer` tutorial the size of the matrix depends of the color system used. More accurately, it depends from the number of channels used. In case of a gray scale image we have something like:
-
-.. math::
-
- \newcommand{\tabItG}[1] { \textcolor{black}{#1} \cellcolor[gray]{0.8}}
- \begin{tabular} {ccccc}
- ~ & \multicolumn{1}{c}{Column 0} & \multicolumn{1}{c}{Column 1} & \multicolumn{1}{c}{Column ...} & \multicolumn{1}{c}{Column m}\\
- Row 0 & \tabItG{0,0} & \tabItG{0,1} & \tabItG{...} & \tabItG{0, m} \\
- Row 1 & \tabItG{1,0} & \tabItG{1,1} & \tabItG{...} & \tabItG{1, m} \\
- Row ... & \tabItG{...,0} & \tabItG{...,1} & \tabItG{...} & \tabItG{..., m} \\
- Row n & \tabItG{n,0} & \tabItG{n,1} & \tabItG{n,...} & \tabItG{n, m} \\
- \end{tabular}
-
-For multichannel images the columns contain as many sub columns as the number of channels. For example in case of an RGB color system:
-
-.. math::
-
- \newcommand{\tabIt}[1] { \textcolor{yellow}{#1} \cellcolor{blue} & \textcolor{black}{#1} \cellcolor{green} & \textcolor{black}{#1} \cellcolor{red}}
- \begin{tabular} {ccccccccccccc}
- ~ & \multicolumn{3}{c}{Column 0} & \multicolumn{3}{c}{Column 1} & \multicolumn{3}{c}{Column ...} & \multicolumn{3}{c}{Column m}\\
- Row 0 & \tabIt{0,0} & \tabIt{0,1} & \tabIt{...} & \tabIt{0, m} \\
- Row 1 & \tabIt{1,0} & \tabIt{1,1} & \tabIt{...} & \tabIt{1, m} \\
- Row ... & \tabIt{...,0} & \tabIt{...,1} & \tabIt{...} & \tabIt{..., m} \\
- Row n & \tabIt{n,0} & \tabIt{n,1} & \tabIt{n,...} & \tabIt{n, m} \\
- \end{tabular}
-
-Note that the order of the channels is inverse: BGR instead of RGB. Because in many cases the memory is large enough to store the rows in a successive fashion the rows may follow one after another, creating a single long row. Because everything is in a single place following one after another this may help to speed up the scanning process. We can use the :basicstructures:`isContinuous() <mat-iscontinuous>` function to *ask* the matrix if this is the case. Continue on to the next section to find an example.
-
-The efficient way
-=================
-
-When it comes to performance you cannot beat the classic C style operator[] (pointer) access. Therefore, the most efficient method we can recommend for making the assignment is:
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
- :language: cpp
- :tab-width: 4
- :lines: 126-153
-
-Here we basically just acquire a pointer to the start of each row and go through it until it ends. In the special case that the matrix is stored in a continues manner we only need to request the pointer a single time and go all the way to the end. We need to look out for color images: we have three channels so we need to pass through three times more items in each row.
-
-There's another way of this. The *data* data member of a *Mat* object returns the pointer to the first row, first column. If this pointer is null you have no valid input in that object. Checking this is the simplest method to check if your image loading was a success. In case the storage is continues we can use this to go through the whole data pointer. In case of a gray scale image this would look like:
-
-.. code-block:: cpp
-
- uchar* p = I.data;
-
- for( unsigned int i =0; i < ncol*nrows; ++i)
- *p++ = table[*p];
-
-You would get the same result. However, this code is a lot harder to read later on. It gets even harder if you have some more advanced technique there. Moreover, in practice I've observed you'll get the same performance result (as most of the modern compilers will probably make this small optimization trick automatically for you).
-
-The iterator (safe) method
-==========================
-
-In case of the efficient way making sure that you pass through the right amount of *uchar* fields and to skip the gaps that may occur between the rows was your responsibility. The iterator method is considered a safer way as it takes over these tasks from the user. All you need to do is ask the begin and the end of the image matrix and then just increase the begin iterator until you reach the end. To acquire the value *pointed* by the iterator use the * operator (add it before it).
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
- :language: cpp
- :tab-width: 4
- :lines: 155-183
-
-In case of color images we have three uchar items per column. This may be considered a short vector of uchar items, that has been baptized in OpenCV with the *Vec3b* name. To access the n-th sub column we use simple operator[] access. It's important to remember that OpenCV iterators go through the columns and automatically skip to the next row. Therefore in case of color images if you use a simple *uchar* iterator you'll be able to access only the blue channel values.
-
-On-the-fly address calculation with reference returning
-=======================================================
-
-The final method isn't recommended for scanning. It was made to acquire or modify somehow random elements in the image. Its basic usage is to specify the row and column number of the item you want to access. During our earlier scanning methods you could already observe that is important through what type we are looking at the image. It's no different here as you need manually to specify what type to use at the automatic lookup. You can observe this in case of the gray scale images for the following source code (the usage of the + :basicstructures:`at() <mat-at>` function):
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
- :language: cpp
- :tab-width: 4
- :lines: 185-217
-
-The functions takes your input type and coordinates and calculates on the fly the address of the queried item. Then returns a reference to that. This may be a constant when you *get* the value and non-constant when you *set* the value. As a safety step in **debug mode only*** there is performed a check that your input coordinates are valid and does exist. If this isn't the case you'll get a nice output message of this on the standard error output stream. Compared to the efficient way in release mode the only difference in using this is that for every element of the image you'll get a new row pointer for what we use the C operator[] to acquire the column element.
-
-If you need to multiple lookups using this method for an image it may be troublesome and time consuming to enter the type and the at keyword for each of the accesses. To solve this problem OpenCV has a :basicstructures:`Mat_ <id3>` data type. It's the same as Mat with the extra need that at definition you need to specify the data type through what to look at the data matrix, however in return you can use the operator() for fast access of items. To make things even better this is easily convertible from and to the usual :basicstructures:`Mat <id3>` data type. A sample usage of this you can see in case of the color images of the upper function. Nevertheless, it's important to note that the same operation (with the same runtime speed) could have been done with the :basicstructures:`at() <mat-at>` function. It's just a less to write for the lazy programmer trick.
-
-The Core Function
-=================
-
-This is a bonus method of achieving lookup table modification in an image. Because in image processing it's quite common that you want to replace all of a given image value to some other value OpenCV has a function that makes the modification without the need from you to write the scanning of the image. We use the :operationsOnArrays:`LUT() <lut>` function of the core module. First we build a Mat type of the lookup table:
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
- :language: cpp
- :tab-width: 4
- :lines: 108-111
-
-Finally call the function (I is our input image and J the output one):
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
- :language: cpp
- :tab-width: 4
- :lines: 116
-
-Performance Difference
-======================
-
-For the best result compile the program and run it on your own speed. For showing off better the differences I've used a quite large (2560 X 1600) image. The performance presented here are for color images. For a more accurate value I've averaged the value I got from the call of the function for hundred times.
-
-============= ====================
-Efficient Way 79.4717 milliseconds
-
-Iterator 83.7201 milliseconds
-
-On-The-Fly RA 93.7878 milliseconds
-
-LUT function 32.5759 milliseconds
-============= ====================
-
-We can conclude a couple of things. If possible, use the already made functions of OpenCV (instead reinventing these). The fastest method turns out to be the LUT function. This is because the OpenCV library is multi-thread enabled via Intel Threaded Building Blocks. However, if you need to write a simple image scan prefer the pointer method. The iterator is a safer bet, however quite slower. Using the on-the-fly reference access method for full image scan is the most costly in debug mode. In the release mode it may beat the iterator approach or not, however it surely sacrifices for this the safety trait of iterators.
-
-Finally, you may watch a sample run of the program on the `video posted <https://www.youtube.com/watch?v=fB3AN5fjgwc>`_ on our YouTube channel.
-
-.. raw:: html
-
- <div align="center">
- <iframe title="How to scan images in OpenCV?" width="560" height="349" src="http://www.youtube.com/embed/fB3AN5fjgwc?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _howToUseIPPAconversion:
-
-Intel® IPP Asynchronous C/C++ library in OpenCV
-***********************************************
-
-Goal
-====
-
-.. _hppiSobel: http://software.intel.com/en-us/node/474701
-.. _hppiMatrix: http://software.intel.com/en-us/node/501660
-
-The tutorial demonstrates the `Intel® IPP Asynchronous C/C++ <http://software.intel.com/en-us/intel-ipp-preview>`_ library usage with OpenCV.
-The code example below illustrates implementation of the Sobel operation, accelerated with Intel® IPP Asynchronous C/C++ functions.
-In this code example, :ippa_convert:`hpp::getMat <>` and :ippa_convert:`hpp::getHpp <>` functions are used for data conversion between hppiMatrix_ and ``Mat`` matrices.
-
-Code
-====
-
-You may also find the source code in the :file:`samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp`
-file of the OpenCV source library or :download:`download it from here
-<../../../../samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp>`.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
-
-Explanation
-===========
-
-#. Create parameters for OpenCV:
-
- .. code-block:: cpp
-
- VideoCapture cap;
- Mat image, gray, result;
-
- and IPP Async:
-
- .. code-block:: cpp
-
- hppiMatrix* src,* dst;
- hppAccel accel = 0;
- hppAccelType accelType;
- hppStatus sts;
- hppiVirtualMatrix * virtMatrix;
-
-#. Load input image or video. How to open and read video stream you can see in the :ref:`videoInputPSNRMSSIM` tutorial.
-
- .. code-block:: cpp
-
- if( useCamera )
- {
- printf("used camera\n");
- cap.open(0);
- }
- else
- {
- printf("used image %s\n", file.c_str());
- cap.open(file.c_str());
- }
-
- if( !cap.isOpened() )
- {
- printf("can not open camera or video file\n");
- return -1;
- }
-
-#. Create accelerator instance using `hppCreateInstance <http://software.intel.com/en-us/node/501686>`_:
-
- .. code-block:: cpp
-
- accelType = sAccel == "cpu" ? HPP_ACCEL_TYPE_CPU:
- sAccel == "gpu" ? HPP_ACCEL_TYPE_GPU:
- HPP_ACCEL_TYPE_ANY;
-
- //Create accelerator instance
- sts = hppCreateInstance(accelType, 0, &accel);
- CHECK_STATUS(sts, "hppCreateInstance");
-
-#. Create an array of virtual matrices using `hppiCreateVirtualMatrices <http://software.intel.com/en-us/node/501700>`_ function.
-
- .. code-block:: cpp
-
- virtMatrix = hppiCreateVirtualMatrices(accel, 1);
-
-#. Prepare a matrix for input and output data:
-
- .. code-block:: cpp
-
- cap >> image;
- if(image.empty())
- break;
-
- cvtColor( image, gray, COLOR_BGR2GRAY );
-
- result.create( image.rows, image.cols, CV_8U);
-
-#. Convert ``Mat`` to hppiMatrix_ using :ippa_convert:`getHpp <>` and call hppiSobel_ function.
-
- .. code-block:: cpp
-
- //convert Mat to hppiMatrix
- src = getHpp(gray, accel);
- dst = getHpp(result, accel);
-
- sts = hppiSobel(accel,src, HPP_MASK_SIZE_3X3,HPP_NORM_L1,virtMatrix[0]);
- CHECK_STATUS(sts,"hppiSobel");
-
- sts = hppiConvert(accel, virtMatrix[0], 0, HPP_RND_MODE_NEAR, dst, HPP_DATA_TYPE_8U);
- CHECK_STATUS(sts,"hppiConvert");
-
- // Wait for tasks to complete
- sts = hppWait(accel, HPP_TIME_OUT_INFINITE);
- CHECK_STATUS(sts, "hppWait");
-
- We use `hppiConvert <http://software.intel.com/en-us/node/501746>`_ because hppiSobel_ returns destination
- matrix with ``HPP_DATA_TYPE_16S`` data type for source matrix with ``HPP_DATA_TYPE_8U`` type.
- You should check ``hppStatus`` after each call IPP Async function.
-
-#. Create windows and show the images, the usual way.
-
- .. code-block:: cpp
-
- imshow("image", image);
- imshow("rez", result);
-
- waitKey(15);
-
-#. Delete hpp matrices.
-
- .. code-block:: cpp
-
- sts = hppiFreeMatrix(src);
- CHECK_DEL_STATUS(sts,"hppiFreeMatrix");
-
- sts = hppiFreeMatrix(dst);
- CHECK_DEL_STATUS(sts,"hppiFreeMatrix");
-
-#. Delete virtual matrices and accelerator instance.
-
- .. code-block:: cpp
-
- if (virtMatrix)
- {
- sts = hppiDeleteVirtualMatrices(accel, virtMatrix);
- CHECK_DEL_STATUS(sts,"hppiDeleteVirtualMatrices");
- }
-
- if (accel)
- {
- sts = hppDeleteInstance(accel);
- CHECK_DEL_STATUS(sts, "hppDeleteInstance");
- }
-
-Result
-=======
-
-After compiling the code above we can execute it giving an image or video path and accelerator type as an argument.
-For this tutorial we use baboon.png image as input. The result is below.
-
- .. image:: images/How_To_Use_IPPA_Result.jpg
- :alt: Final Result
- :align: center
\ No newline at end of file
+++ /dev/null
-.. _InteroperabilityWithOpenCV1:
-
-Interoperability with OpenCV 1
-******************************
-
-Goal
-====
-
-For the OpenCV developer team it's important to constantly improve the library. We are constantly thinking about methods that will ease your work process, while still maintain the libraries flexibility. The new C++ interface is a development of us that serves this goal. Nevertheless, backward compatibility remains important. We do not want to break your code written for earlier version of the OpenCV library. Therefore, we made sure that we add some functions that deal with this. In the following you'll learn:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + What changed with the version 2 of OpenCV in the way you use the library compared to its first version
- + How to add some Gaussian noise to an image
- + What are lookup tables and why use them?
-
-General
-=======
-
-When making the switch you first need to learn some about the new data structure for images: :ref:`matTheBasicImageContainer`, this replaces the old *CvMat* and *IplImage* ones. Switching to the new functions is easier. You just need to remember a couple of new things.
-
-OpenCV 2 received reorganization. No longer are all the functions crammed into a single library. We have many modules, each of them containing data structures and functions relevant to certain tasks. This way you do not need to ship a large library if you use just a subset of OpenCV. This means that you should also include only those headers you will use. For example:
-
-.. code-block:: cpp
-
- #include <opencv2/core.hpp>
- #include <opencv2/imgproc.hpp>
- #include <opencv2/highgui.hpp>
-
-
-All the OpenCV related stuff is put into the *cv* namespace to avoid name conflicts with other libraries data structures and functions. Therefore, either you need to prepend the *cv::* keyword before everything that comes from OpenCV or after the includes, you just add a directive to use this:
-
-.. code-block:: cpp
-
- using namespace cv; // The new C++ interface API is inside this namespace. Import it.
-
-Because the functions are already in a namespace there is no need for them to contain the *cv* prefix in their name. As such all the new C++ compatible functions don't have this and they follow the camel case naming rule. This means the first letter is small (unless it's a name, like Canny) and the subsequent words start with a capital letter (like *copyMakeBorder*).
-
-Now, remember that you need to link to your application all the modules you use, and in case you are on Windows using the *DLL* system you will need to add, again, to the path all the binaries. For more in-depth information if you're on Windows read :ref:`Windows_Visual_Studio_How_To` and for Linux an example usage is explained in :ref:`Linux_Eclipse_Usage`.
-
-Now for converting the *Mat* object you can use either the *IplImage* or the *CvMat* operators. While in the C interface you used to work with pointers here it's no longer the case. In the C++ interface we have mostly *Mat* objects. These objects may be freely converted to both *IplImage* and *CvMat* with simple assignment. For example:
-
-.. code-block:: cpp
-
- Mat I;
- IplImage pI = I;
- CvMat mI = I;
-
-Now if you want pointers the conversion gets just a little more complicated. The compilers can no longer automatically determinate what you want and as you need to explicitly specify your goal. This is to call the *IplImage* and *CvMat* operators and then get their pointers. For getting the pointer we use the & sign:
-
-.. code-block:: cpp
-
- Mat I;
- IplImage* pI = &I.operator IplImage();
- CvMat* mI = &I.operator CvMat();
-
-One of the biggest complaints of the C interface is that it leaves all the memory management to you. You need to figure out when it is safe to release your unused objects and make sure you do so before the program finishes or you could have troublesome memory leeks. To work around this issue in OpenCV there is introduced a sort of smart pointer. This will automatically release the object when it's no longer in use. To use this declare the pointers as a specialization of the *Ptr* :
-
-.. code-block:: cpp
-
- Ptr<IplImage> piI = &I.operator IplImage();
-
-Converting from the C data structures to the *Mat* is done by passing these inside its constructor. For example:
-
-.. code-block:: cpp
-
- Mat K(piL), L;
- L = Mat(pI);
-
-A case study
-============
-
-Now that you have the basics done :download:`here's <../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp>` an example that mixes the usage of the C interface with the C++ one. You will also find it in the sample directory of the OpenCV source code library at the :file:`samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp` . To further help on seeing the difference the programs supports two modes: one mixed C and C++ and one pure C++. If you define the *DEMO_MIXED_API_USE* you'll end up using the first. The program separates the color planes, does some modifications on them and in the end merge them back together.
-
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 1-10, 23-26, 29-46
-
-Here you can observe that with the new structure we have no pointer problems, although it is possible to use the old functions and in the end just transform the result to a *Mat* object.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 48-53
-
-Because, we want to mess around with the images luma component we first convert from the default RGB to the YUV color space and then split the result up into separate planes. Here the program splits: in the first example it processes each plane using one of the three major image scanning algorithms in OpenCV (C [] operator, iterator, individual element access). In a second variant we add to the image some Gaussian noise and then mix together the channels according to some formula.
-
-The scanning version looks like:
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 57-77
-
-Here you can observe that we may go through all the pixels of an image in three fashions: an iterator, a C pointer and an individual element access style. You can read a more in-depth description of these in the :ref:`howToScanImagesOpenCV` tutorial. Converting from the old function names is easy. Just remove the cv prefix and use the new *Mat* data structure. Here's an example of this by using the weighted addition function:
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 81-113
-
-As you may observe the *planes* variable is of type *Mat*. However, converting from *Mat* to *IplImage* is easy and made automatically with a simple assignment operator.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 117-129
-
-The new *imshow* highgui function accepts both the *Mat* and *IplImage* data structures. Compile and run the program and if the first image below is your input you may get either the first or second as output:
-
-.. image:: images/outputInteropOpenCV1.jpg
- :alt: The output of the sample
- :align: center
-
-
-You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=qckm-zvo31w>`_ and you can :download:`download the source code from here <../../../../samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp>` or find it in the :file:`samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp` of the OpenCV source code library.
-
-.. raw:: html
-
- <div align="center">
- <iframe title="Interoperability with OpenCV 1" width="560" height="349" src="http://www.youtube.com/embed/qckm-zvo31w?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _maskOperationsFilter:
-
-Mask operations on matrices
-***************************
-
-Mask operations on matrices are quite simple. The idea is that we recalculate each pixels value in an image according to a mask matrix (also known as kernel). This mask holds values that will adjust how much influence neighboring pixels (and the current pixel) have on the new pixel value. From a mathematical point of view we make a weighted average, with our specified values.
-
-Our test case
-=============
-
-Let us consider the issue of an image contrast enhancement method. Basically we want to apply for every pixel of the image the following formula:
-
-.. math::
-
- I(i,j) = 5*I(i,j) - [ I(i-1,j) + I(i+1,j) + I(i,j-1) + I(i,j+1)]
-
- \iff I(i,j)*M, \text{where }
- M = \bordermatrix{ _i\backslash ^j & -1 & 0 & +1 \cr
- -1 & 0 & -1 & 0 \cr
- 0 & -1 & 5 & -1 \cr
- +1 & 0 & -1 & 0 \cr
- }
-
-The first notation is by using a formula, while the second is a compacted version of the first by using a mask. You use the mask by putting the center of the mask matrix (in the upper case noted by the zero-zero index) on the pixel you want to calculate and sum up the pixel values multiplied with the overlapped matrix values. It's the same thing, however in case of large matrices the latter notation is a lot easier to look over.
-
-Now let us see how we can make this happen by using the basic pixel access method or by using the :filtering:`filter2D <filter2d>` function.
-
-The Basic Method
-================
-
-Here's a function that will do this:
-
-.. code-block:: cpp
-
- void Sharpen(const Mat& myImage, Mat& Result)
- {
- CV_Assert(myImage.depth() == CV_8U); // accept only uchar images
-
- Result.create(myImage.size(), myImage.type());
- const int nChannels = myImage.channels();
-
- for(int j = 1; j < myImage.rows - 1; ++j)
- {
- const uchar* previous = myImage.ptr<uchar>(j - 1);
- const uchar* current = myImage.ptr<uchar>(j );
- const uchar* next = myImage.ptr<uchar>(j + 1);
-
- uchar* output = Result.ptr<uchar>(j);
-
- for(int i = nChannels; i < nChannels * (myImage.cols - 1); ++i)
- {
- *output++ = saturate_cast<uchar>(5 * current[i]
- -current[i - nChannels] - current[i + nChannels] - previous[i] - next[i]);
- }
- }
-
- Result.row(0).setTo(Scalar(0));
- Result.row(Result.rows - 1).setTo(Scalar(0));
- Result.col(0).setTo(Scalar(0));
- Result.col(Result.cols - 1).setTo(Scalar(0));
- }
-
-At first we make sure that the input images data is in unsigned char format. For this we use the :utilitysystemfunctions:`CV_Assert <cv-assert>` function that throws an error when the expression inside it is false.
-
-.. code-block:: cpp
-
- CV_Assert(myImage.depth() == CV_8U); // accept only uchar images
-
-We create an output image with the same size and the same type as our input. As you can see in the :ref:`How_Image_Stored_Memory` section, depending on the number of channels we may have one or more subcolumns. We will iterate through them via pointers so the total number of elements depends from this number.
-
-.. code-block:: cpp
-
- Result.create(myImage.size(), myImage.type());
- const int nChannels = myImage.channels();
-
-We'll use the plain C [] operator to access pixels. Because we need to access multiple rows at the same time we'll acquire the pointers for each of them (a previous, a current and a next line). We need another pointer to where we're going to save the calculation. Then simply access the right items with the [] operator. For moving the output pointer ahead we simply increase this (with one byte) after each operation:
-
-.. code-block:: cpp
-
- for(int j = 1; j < myImage.rows - 1; ++j)
- {
- const uchar* previous = myImage.ptr<uchar>(j - 1);
- const uchar* current = myImage.ptr<uchar>(j );
- const uchar* next = myImage.ptr<uchar>(j + 1);
-
- uchar* output = Result.ptr<uchar>(j);
-
- for(int i = nChannels; i < nChannels * (myImage.cols - 1); ++i)
- {
- *output++ = saturate_cast<uchar>(5 * current[i]
- -current[i - nChannels] - current[i + nChannels] - previous[i] - next[i]);
- }
- }
-
-On the borders of the image the upper notation results inexistent pixel locations (like minus one - minus one). In these points our formula is undefined. A simple solution is to not apply the kernel in these points and, for example, set the pixels on the borders to zeros:
-
-.. code-block:: cpp
-
- Result.row(0).setTo(Scalar(0)); // The top row
- Result.row(Result.rows - 1).setTo(Scalar(0)); // The bottom row
- Result.col(0).setTo(Scalar(0)); // The left column
- Result.col(Result.cols - 1).setTo(Scalar(0)); // The right column
-
-The filter2D function
-=====================
-
-Applying such filters are so common in image processing that in OpenCV there exist a function that will take care of applying the mask (also called a kernel in some places). For this you first need to define a *Mat* object that holds the mask:
-
-.. code-block:: cpp
-
- Mat kern = (Mat_<char>(3,3) << 0, -1, 0,
- -1, 5, -1,
- 0, -1, 0);
-
-Then call the :filtering:`filter2D <filter2d>` function specifying the input, the output image and the kernell to use:
-
-.. code-block:: cpp
-
- filter2D(I, K, I.depth(), kern);
-
-The function even has a fifth optional argument to specify the center of the kernel, and a sixth one for determining what to do in the regions where the operation is undefined (borders). Using this function has the advantage that it's shorter, less verbose and because there are some optimization techniques implemented it is usually faster than the *hand-coded method*. For example in my test while the second one took only 13 milliseconds the first took around 31 milliseconds. Quite some difference.
-
-For example:
-
-.. image:: images/resultMatMaskFilter2D.png
- :alt: A sample output of the program
- :align: center
-
-You can download this source code from :download:`here <../../../../samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp>` or look in the OpenCV source code libraries sample directory at :file:`samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp`.
-
-Check out an instance of running the program on our `YouTube channel <http://www.youtube.com/watch?v=7PF1tAU9se4>`_ .
-
-.. raw:: html
-
- <div align="center">
- <iframe width="560" height="349" src="https://www.youtube.com/embed/7PF1tAU9se4?hd=1" frameborder="0" allowfullscreen></iframe>
- </div>
+++ /dev/null
-.. _matTheBasicImageContainer:
-
-Mat - The Basic Image Container
-*******************************
-
-Goal
-====
-
-We have multiple ways to acquire digital images from the real world: digital cameras, scanners, computed tomography, and magnetic resonance imaging to name a few. In every case what we (humans) see are images. However, when transforming this to our digital devices what we record are numerical values for each of the points of the image.
-
-.. image:: images/MatBasicImageForComputer.jpg
- :alt: A matrix of the mirror of a car
- :align: center
-
-For example in the above image you can see that the mirror of the car is nothing more than a matrix containing all the intensity values of the pixel points. How we get and store the pixels values may vary according to our needs, but in the end all images inside a computer world may be reduced to numerical matrices and other information describing the matrix itself. *OpenCV* is a computer vision library whose main focus is to process and manipulate this information. Therefore, the first thing you need to be familiar with is how OpenCV stores and handles images.
-
-*Mat*
-=====
-
-OpenCV has been around since 2001. In those days the library was built around a *C* interface and to store the image in the memory they used a C structure called *IplImage*. This is the one you'll see in most of the older tutorials and educational materials. The problem with this is that it brings to the table all the minuses of the C language. The biggest issue is the manual memory management. It builds on the assumption that the user is responsible for taking care of memory allocation and deallocation. While this is not a problem with smaller programs, once your code base grows it will be more of a struggle to handle all this rather than focusing on solving your development goal.
-
-Luckily C++ came around and introduced the concept of classes making easier for the user through automatic memory management (more or less). The good news is that C++ is fully compatible with C so no compatibility issues can arise from making the change. Therefore, OpenCV 2.0 introduced a new C++ interface which offered a new way of doing things which means you do not need to fiddle with memory management, making your code concise (less to write, to achieve more). The main downside of the C++ interface is that many embedded development systems at the moment support only C. Therefore, unless you are targeting embedded platforms, there's no point to using the *old* methods (unless you're a masochist programmer and you're asking for trouble).
-
-The first thing you need to know about *Mat* is that you no longer need to manually allocate its memory and release it as soon as you do not need it. While doing this is still a possibility, most of the OpenCV functions will allocate its output data automatically. As a nice bonus if you pass on an already existing *Mat* object, which has already allocated the required space for the matrix, this will be reused. In other words we use at all times only as much memory as we need to perform the task.
-
-*Mat* is basically a class with two data parts: the matrix header (containing information such as the size of the matrix, the method used for storing, at which address is the matrix stored, and so on) and a pointer to the matrix containing the pixel values (taking any dimensionality depending on the method chosen for storing) . The matrix header size is constant, however the size of the matrix itself may vary from image to image and usually is larger by orders of magnitude.
-
-OpenCV is an image processing library. It contains a large collection of image processing functions. To solve a computational challenge, most of the time you will end up using multiple functions of the library. Because of this, passing images to functions is a common practice. We should not forget that we are talking about image processing algorithms, which tend to be quite computational heavy. The last thing we want to do is further decrease the speed of your program by making unnecessary copies of potentially *large* images.
-
-To tackle this issue OpenCV uses a reference counting system. The idea is that each *Mat* object has its own header, however the matrix may be shared between two instance of them by having their matrix pointers point to the same address. Moreover, the copy operators **will only copy the headers** and the pointer to the large matrix, not the data itself.
-
-.. code-block:: cpp
- :linenos:
-
- Mat A, C; // creates just the header parts
- A = imread(argv[1], IMREAD_COLOR); // here we'll know the method used (allocate matrix)
-
- Mat B(A); // Use the copy constructor
-
- C = A; // Assignment operator
-
-All the above objects, in the end, point to the same single data matrix. Their headers are different, however, and making a modification using any of them will affect all the other ones as well. In practice the different objects just provide different access method to the same underlying data. Nevertheless, their header parts are different. The real interesting part is that you can create headers which refer to only a subsection of the full data. For example, to create a region of interest (*ROI*) in an image you just create a new header with the new boundaries:
-
-.. code-block:: cpp
- :linenos:
-
- Mat D (A, Rect(10, 10, 100, 100) ); // using a rectangle
- Mat E = A(Range::all(), Range(1,3)); // using row and column boundaries
-
-Now you may ask if the matrix itself may belong to multiple *Mat* objects who takes responsibility for cleaning it up when it's no longer needed. The short answer is: the last object that used it. This is handled by using a reference counting mechanism. Whenever somebody copies a header of a *Mat* object, a counter is increased for the matrix. Whenever a header is cleaned this counter is decreased. When the counter reaches zero the matrix too is freed. Sometimes you will want to copy the matrix itself too, so OpenCV provides the :basicstructures:`clone() <mat-clone>` and :basicstructures:`copyTo() <mat-copyto>` functions.
-
-.. code-block:: cpp
- :linenos:
-
- Mat F = A.clone();
- Mat G;
- A.copyTo(G);
-
-Now modifying *F* or *G* will not affect the matrix pointed by the *Mat* header. What you need to remember from all this is that:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Output image allocation for OpenCV functions is automatic (unless specified otherwise).
- * You do not need to think about memory management with OpenCVs C++ interface.
- * The assignment operator and the copy constructor only copies the header.
- * The underlying matrix of an image may be copied using the :basicstructures:`clone()<mat-clone>` and :basicstructures:`copyTo() <mat-copyto>` functions.
-
-*Storing* methods
-=================
-
-This is about how you store the pixel values. You can select the color space and the data type used. The color space refers to how we combine color components in order to code a given color. The simplest one is the gray scale where the colors at our disposal are black and white. The combination of these allows us to create many shades of gray.
-
-For *colorful* ways we have a lot more methods to choose from. Each of them breaks it down to three or four basic components and we can use the combination of these to create the others. The most popular one is RGB, mainly because this is also how our eye builds up colors. Its base colors are red, green and blue. To code the transparency of a color sometimes a fourth element: alpha (A) is added.
-
-There are, however, many other color systems each with their own advantages:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * RGB is the most common as our eyes use something similar, our display systems also compose colors using these.
- * The HSV and HLS decompose colors into their hue, saturation and value/luminance components, which is a more natural way for us to describe colors. You might, for example, dismiss the last component, making your algorithm less sensible to the light conditions of the input image.
- * YCrCb is used by the popular JPEG image format.
- * CIE L*a*b* is a perceptually uniform color space, which comes handy if you need to measure the *distance* of a given color to another color.
-
-Each of the building components has their own valid domains. This leads to the data type used. How we store a component defines the control we have over its domain. The smallest data type possible is *char*, which means one byte or 8 bits. This may be unsigned (so can store values from 0 to 255) or signed (values from -127 to +127). Although in case of three components this already gives 16 million possible colors to represent (like in case of RGB) we may acquire an even finer control by using the float (4 byte = 32 bit) or double (8 byte = 64 bit) data types for each component. Nevertheless, remember that increasing the size of a component also increases the size of the whole picture in the memory.
-
-Creating a *Mat* object explicitly
-==================================
-
-In the :ref:`Load_Save_Image` tutorial you have already learned how to write a matrix to an image file by using the :readwriteimage:`imwrite() <imwrite>` function. However, for debugging purposes it's much more convenient to see the actual values. You can do this using the << operator of *Mat*. Be aware that this only works for two dimensional matrices.
-
-Although *Mat* works really well as an image container, it is also a general matrix class. Therefore, it is possible to create and manipulate multidimensional matrices. You can create a Mat object in multiple ways:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + :basicstructures:`Mat() <mat-mat>` Constructor
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 27-28
-
- .. image:: images/MatBasicContainerOut1.png
- :alt: Demo image of the matrix output
- :align: center
-
- For two dimensional and multichannel images we first define their size: row and column count wise.
-
- Then we need to specify the data type to use for storing the elements and the number of channels per matrix point. To do this we have multiple definitions constructed according to the following convention:
-
- .. code-block:: cpp
-
- CV_[The number of bits per item][Signed or Unsigned][Type Prefix]C[The channel number]
-
- For instance, *CV_8UC3* means we use unsigned char types that are 8 bit long and each pixel has three of these to form the three channels. This are predefined for up to four channel numbers. The :basicstructures:`Scalar <scalar>` is four element short vector. Specify this and you can initialize all matrix points with a custom value. If you need more you can create the type with the upper macro, setting the channel number in parenthesis as you can see below.
-
- + Use C/C++ arrays and initialize via constructor
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 35-36
-
- The upper example shows how to create a matrix with more than two dimensions. Specify its dimension, then pass a pointer containing the size for each dimension and the rest remains the same.
-
-
- + Create a header for an already existing IplImage pointer:
-
- .. code-block:: cpp
-
- IplImage* img = cvLoadImage("greatwave.png", 1);
- Mat mtx(img); // convert IplImage* -> Mat
-
- + :basicstructures:`Create() <mat-create>` function:
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 31-32
-
- .. image:: images/MatBasicContainerOut2.png
- :alt: Demo image of the matrix output
- :align: center
-
- You cannot initialize the matrix values with this construction. It will only reallocate its matrix data memory if the new size will not fit into the old one.
-
- + MATLAB style initializer: :basicstructures:`zeros() <mat-zeros>`, :basicstructures:`ones() <mat-ones>`, :basicstructures:`eye() <mat-eye>`. Specify size and data type to use:
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 40-47
-
- .. image:: images/MatBasicContainerOut3.png
- :alt: Demo image of the matrix output
- :align: center
-
- + For small matrices you may use comma separated initializers:
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 50-51
-
- .. image:: images/MatBasicContainerOut6.png
- :alt: Demo image of the matrix output
- :align: center
-
- + Create a new header for an existing *Mat* object and :basicstructures:`clone() <mat-clone>` or :basicstructures:`copyTo() <mat-copyto>` it.
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 53-54
-
- .. image:: images/MatBasicContainerOut7.png
- :alt: Demo image of the matrix output
- :align: center
-
-.. note::
-
- You can fill out a matrix with random values using the :operationsOnArrays:`randu() <randu>` function. You need to give the lower and upper value for the random values:
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 57-58
-
-
-Output formatting
-=================
-
-In the above examples you could see the default formatting option. OpenCV, however, allows you to format your matrix output:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + Default
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 61
-
- .. image:: images/MatBasicContainerOut8.png
- :alt: Default Output
- :align: center
-
- + Python
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 62
-
- .. image:: images/MatBasicContainerOut16.png
- :alt: Default Output
- :align: center
-
- + Comma separated values (CSV)
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 64
-
- .. image:: images/MatBasicContainerOut10.png
- :alt: Default Output
- :align: center
-
- + Numpy
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 63
-
- .. image:: images/MatBasicContainerOut9.png
- :alt: Default Output
- :align: center
-
- + C
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 65
-
- .. image:: images/MatBasicContainerOut11.png
- :alt: Default Output
- :align: center
-
-Output of other common items
-============================
-
-OpenCV offers support for output of other common OpenCV data structures too via the << operator:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + 2D Point
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 67-68
-
- .. image:: images/MatBasicContainerOut12.png
- :alt: Default Output
- :align: center
-
-
- + 3D Point
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 70-71
-
- .. image:: images/MatBasicContainerOut13.png
- :alt: Default Output
- :align: center
-
- + std::vector via cv::Mat
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 74-77
-
- .. image:: images/MatBasicContainerOut14.png
- :alt: Default Output
- :align: center
-
- + std::vector of points
-
- .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
- :language: cpp
- :tab-width: 4
- :lines: 79-83
-
- .. image:: images/MatBasicContainerOut15.png
- :alt: Default Output
- :align: center
-
-Most of the samples here have been included in a small console application. You can download it from :download:`here <../../../../samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp>` or in the core section of the cpp samples.
-
-You can also find a quick video demonstration of this on `YouTube <https://www.youtube.com/watch?v=1tibU7vGWpk>`_.
-
-.. raw:: html
-
- <div align="center">
- <iframe title="Install OpenCV by using its source files - Part 1" width="560" height="349" src="http://www.youtube.com/embed/1tibU7vGWpk?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _Drawing_2:
-
-Random generator and text with OpenCV
-*************************************
-
-Goals
-======
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the *Random Number generator class* (:rng:`RNG <>`) and how to get a random number from a uniform distribution.
- * Display text on an OpenCV window by using the function :put_text:`putText <>`
-
-Code
-=====
-
-.. container:: enumeratevisibleitemswithsquare
-
- * In the previous tutorial (:ref:`Drawing_1`) we drew diverse geometric figures, giving as input parameters such as coordinates (in the form of :point:`Points <>`), color, thickness, etc. You might have noticed that we gave specific values for these arguments.
-
- * In this tutorial, we intend to use *random* values for the drawing parameters. Also, we intend to populate our image with a big number of geometric figures. Since we will be initializing them in a random fashion, this process will be automatic and made by using *loops* .
-
- * This code is in your OpenCV sample folder. Otherwise you can grab it from `here <http://code.opencv.org/projects/opencv/repository/revisions/master/raw/samples/cpp/tutorial_code/core/Matrix/Drawing_2.cpp>`_ .
-
-Explanation
-============
-
-#. Let's start by checking out the *main* function. We observe that first thing we do is creating a *Random Number Generator* object (RNG):
-
- .. code-block:: cpp
-
- RNG rng( 0xFFFFFFFF );
-
- RNG implements a random number generator. In this example, *rng* is a RNG element initialized with the value *0xFFFFFFFF*
-
-#. Then we create a matrix initialized to *zeros* (which means that it will appear as black), specifying its height, width and its type:
-
- .. code-block:: cpp
-
- /// Initialize a matrix filled with zeros
- Mat image = Mat::zeros( window_height, window_width, CV_8UC3 );
-
- /// Show it in a window during DELAY ms
- imshow( window_name, image );
-
-#. Then we proceed to draw crazy stuff. After taking a look at the code, you can see that it is mainly divided in 8 sections, defined as functions:
-
- .. code-block:: cpp
-
- /// Now, let's draw some lines
- c = Drawing_Random_Lines(image, window_name, rng);
- if( c != 0 ) return 0;
-
- /// Go on drawing, this time nice rectangles
- c = Drawing_Random_Rectangles(image, window_name, rng);
- if( c != 0 ) return 0;
-
- /// Draw some ellipses
- c = Drawing_Random_Ellipses( image, window_name, rng );
- if( c != 0 ) return 0;
-
- /// Now some polylines
- c = Drawing_Random_Polylines( image, window_name, rng );
- if( c != 0 ) return 0;
-
- /// Draw filled polygons
- c = Drawing_Random_Filled_Polygons( image, window_name, rng );
- if( c != 0 ) return 0;
-
- /// Draw circles
- c = Drawing_Random_Circles( image, window_name, rng );
- if( c != 0 ) return 0;
-
- /// Display text in random positions
- c = Displaying_Random_Text( image, window_name, rng );
- if( c != 0 ) return 0;
-
- /// Displaying the big end!
- c = Displaying_Big_End( image, window_name, rng );
-
- All of these functions follow the same pattern, so we will analyze only a couple of them, since the same explanation applies for all.
-
-#. Checking out the function **Drawing_Random_Lines**:
-
- .. code-block:: cpp
-
- int Drawing_Random_Lines( Mat image, char* window_name, RNG rng )
- {
- int lineType = 8;
- Point pt1, pt2;
-
- for( int i = 0; i < NUMBER; i++ )
- {
- pt1.x = rng.uniform( x_1, x_2 );
- pt1.y = rng.uniform( y_1, y_2 );
- pt2.x = rng.uniform( x_1, x_2 );
- pt2.y = rng.uniform( y_1, y_2 );
-
- line( image, pt1, pt2, randomColor(rng), rng.uniform(1, 10), 8 );
- imshow( window_name, image );
- if( waitKey( DELAY ) >= 0 )
- { return -1; }
- }
- return 0;
- }
-
- We can observe the following:
-
- * The *for* loop will repeat **NUMBER** times. Since the function :line:`line <>` is inside this loop, that means that **NUMBER** lines will be generated.
- * The line extremes are given by *pt1* and *pt2*. For *pt1* we can see that:
-
- .. code-block:: cpp
-
- pt1.x = rng.uniform( x_1, x_2 );
- pt1.y = rng.uniform( y_1, y_2 );
-
- * We know that **rng** is a *Random number generator* object. In the code above we are calling **rng.uniform(a,b)**. This generates a radombly uniformed distribution between the values **a** and **b** (inclusive in **a**, exclusive in **b**).
-
- * From the explanation above, we deduce that the extremes *pt1* and *pt2* will be random values, so the lines positions will be quite impredictable, giving a nice visual effect (check out the Result section below).
-
- * As another observation, we notice that in the :line:`line <>` arguments, for the *color* input we enter:
-
- .. code-block:: cpp
-
- randomColor(rng)
-
- Let's check the function implementation:
-
- .. code-block:: cpp
-
- static Scalar randomColor( RNG& rng )
- {
- int icolor = (unsigned) rng;
- return Scalar( icolor&255, (icolor>>8)&255, (icolor>>16)&255 );
- }
-
- As we can see, the return value is an *Scalar* with 3 randomly initialized values, which are used as the *R*, *G* and *B* parameters for the line color. Hence, the color of the lines will be random too!
-
-#. The explanation above applies for the other functions generating circles, ellipses, polygones, etc. The parameters such as *center* and *vertices* are also generated randomly.
-
-#. Before finishing, we also should take a look at the functions *Display_Random_Text* and *Displaying_Big_End*, since they both have a few interesting features:
-
-#. **Display_Random_Text:**
-
- .. code-block:: cpp
-
- int Displaying_Random_Text( Mat image, char* window_name, RNG rng )
- {
- int lineType = 8;
-
- for ( int i = 1; i < NUMBER; i++ )
- {
- Point org;
- org.x = rng.uniform(x_1, x_2);
- org.y = rng.uniform(y_1, y_2);
-
- putText( image, "Testing text rendering", org, rng.uniform(0,8),
- rng.uniform(0,100)*0.05+0.1, randomColor(rng), rng.uniform(1, 10), lineType);
-
- imshow( window_name, image );
- if( waitKey(DELAY) >= 0 )
- { return -1; }
- }
-
- return 0;
- }
-
- Everything looks familiar but the expression:
-
- .. code-block:: cpp
-
- putText( image, "Testing text rendering", org, rng.uniform(0,8),
- rng.uniform(0,100)*0.05+0.1, randomColor(rng), rng.uniform(1, 10), lineType);
-
-
- So, what does the function :put_text:`putText <>` do? In our example:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Draws the text **"Testing text rendering"** in **image**
- * The bottom-left corner of the text will be located in the Point **org**
- * The font type is a random integer value in the range: :math:`[0, 8>`.
- * The scale of the font is denoted by the expression **rng.uniform(0, 100)x0.05 + 0.1** (meaning its range is: :math:`[0.1, 5.1>`)
- * The text color is random (denoted by **randomColor(rng)**)
- * The text thickness ranges between 1 and 10, as specified by **rng.uniform(1,10)**
-
- As a result, we will get (analagously to the other drawing functions) **NUMBER** texts over our image, in random locations.
-
-#. **Displaying_Big_End**
-
- .. code-block:: cpp
-
- int Displaying_Big_End( Mat image, char* window_name, RNG rng )
- {
- Size textsize = getTextSize("OpenCV forever!", FONT_HERSHEY_COMPLEX, 3, 5, 0);
- Point org((window_width - textsize.width)/2, (window_height - textsize.height)/2);
- int lineType = 8;
-
- Mat image2;
-
- for( int i = 0; i < 255; i += 2 )
- {
- image2 = image - Scalar::all(i);
- putText( image2, "OpenCV forever!", org, FONT_HERSHEY_COMPLEX, 3,
- Scalar(i, i, 255), 5, lineType );
-
- imshow( window_name, image2 );
- if( waitKey(DELAY) >= 0 )
- { return -1; }
- }
-
- return 0;
- }
-
- Besides the function **getTextSize** (which gets the size of the argument text), the new operation we can observe is inside the *foor* loop:
-
- .. code-block:: cpp
-
- image2 = image - Scalar::all(i)
-
- So, **image2** is the substraction of **image** and **Scalar::all(i)**. In fact, what happens here is that every pixel of **image2** will be the result of substracting every pixel of **image** minus the value of **i** (remember that for each pixel we are considering three values such as R, G and B, so each of them will be affected)
-
- Also remember that the substraction operation *always* performs internally a **saturate** operation, which means that the result obtained will always be inside the allowed range (no negative and between 0 and 255 for our example).
-
-
-Result
-========
-
-As you just saw in the Code section, the program will sequentially execute diverse drawing functions, which will produce:
-
-#. First a random set of *NUMBER* lines will appear on screen such as it can be seen in this screenshot:
-
- .. image:: images/Drawing_2_Tutorial_Result_0.jpg
- :alt: Drawing Tutorial 2 - Final Result 0
- :align: center
-
-#. Then, a new set of figures, these time *rectangles* will follow.
-
-#. Now some ellipses will appear, each of them with random position, size, thickness and arc length:
-
- .. image:: images/Drawing_2_Tutorial_Result_2.jpg
- :alt: Drawing Tutorial 2 - Final Result 2
- :align: center
-
-#. Now, *polylines* with 03 segments will appear on screen, again in random configurations.
-
- .. image:: images/Drawing_2_Tutorial_Result_3.jpg
- :alt: Drawing Tutorial 2 - Final Result 3
- :align: center
-
-#. Filled polygons (in this example triangles) will follow.
-
-#. The last geometric figure to appear: circles!
-
- .. image:: images/Drawing_2_Tutorial_Result_5.jpg
- :alt: Drawing Tutorial 2 - Final Result 5
- :align: center
-
-#. Near the end, the text *"Testing Text Rendering"* will appear in a variety of fonts, sizes, colors and positions.
-
-#. And the big end (which by the way expresses a big truth too):
-
- .. image:: images/Drawing_2_Tutorial_Result_big.jpg
- :alt: Drawing Tutorial 2 - Final Result 7
- :align: center
+++ /dev/null
-.. _Table-Of-Content-Core:
-
-*core* module. The Core Functionality
------------------------------------------------------------
-
-Here you will learn the about the basic building blocks of the library. A must read and know for understanding how to manipulate the images on a pixel level.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |MatBasicIma| **Title:** :ref:`matTheBasicImageContainer`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- You will learn how to store images in the memory and how to print out their content to the console.
-
- =============== ======================================================
-
- .. |MatBasicIma| image:: images/matTheBasicImageStructure.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |HowScanImag| **Title:** :ref:`howToScanImagesOpenCV`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- You'll find out how to scan images (go through each of the image pixels) with OpenCV. Bonus: time measurement with OpenCV.
-
- =============== ======================================================
-
- .. |HowScanImag| image:: images/howToScanImages.jpg
- :height: 90pt
- :width: 90pt
-
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |HowFilterIm| **Title:** :ref:`maskOperationsFilter`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- You'll find out how to scan images with neighbor access and use the :filtering:`filter2D <filter2d>` function to apply kernel filters on images.
-
- =============== ======================================================
-
- .. |HowFilterIm| image:: images/matMaskFilter2DOp.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |Beginners_4| **Title:** :ref:`Adding_Images`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will learn how to blend two images!
-
- =============== ======================================================
-
- .. |Beginners_4| image:: images/Adding_Images_Tutorial_Result_0.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ====================================================
- |Bas_Lin_Tran| **Title:** :ref:`Basic_Linear_Transform`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will learn how to change our image appearance!
-
- =============== ====================================================
-
- .. |Bas_Lin_Tran| image:: images/Basic_Linear_Transform_Tutorial_Result_0.jpg
- :height: 90pt
- :width: 90pt
-
-
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |Beginners_6| **Title:** :ref:`Drawing_1`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will learn how to draw simple geometry with OpenCV!
-
- =============== ======================================================
-
- .. |Beginners_6| image:: images/Drawing_1_Tutorial_Result_0.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |Beginners_7| **Title:** :ref:`Drawing_2`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will draw some *fancy-looking* stuff using OpenCV!
-
- =============== ======================================================
-
- .. |Beginners_7| image:: images/Drawing_2_Tutorial_Result_7.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |DiscFourTr| **Title:** :ref:`discretFourierTransform`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- You will see how and why use the Discrete Fourier transformation with OpenCV.
-
- =============== ======================================================
-
- .. |DiscFourTr| image:: images/discrete_fourier_transform.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |FileIOXMLYAML| **Title:** :ref:`fileInputOutputXMLYAML`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- You will see how to use the :xmlymlpers:`FileStorage <filestorage>` data structure of OpenCV to write and read data to XML or YAML file format.
-
- =============== ======================================================
-
- .. |FileIOXMLYAML| image:: images/file_input_output_with_xml_yml.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |InterOOpenCV1| **Title:** :ref:`InteroperabilityWithOpenCV1`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- Did you used OpenCV before its 2.0 version? Do you wanna know what happened with your library with 2.0? Don't you know how to convert your old OpenCV programs to the new C++ interface? Look here to shed light on all this questions.
-
- =============== ======================================================
-
- .. |InterOOpenCV1| image:: images/interopOpenCV1.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |IPPIma| **Title:** :ref:`howToUseIPPAconversion`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_ElenaG|
-
- You will see how to use the IPP Async with OpenCV.
-
- =============== ======================================================
-
- .. |IPPIma| image:: images/How_To_Use_IPPA.jpg
- :height: 90pt
- :width: 90pt
- .. |Author_ElenaG| unicode:: Elena U+0020 Gvozdeva
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../mat_the_basic_image_container/mat_the_basic_image_container
- ../how_to_scan_images/how_to_scan_images
- ../mat-mask-operations/mat-mask-operations
- ../adding_images/adding_images
- ../basic_linear_transform/basic_linear_transform
- ../basic_geometric_drawing/basic_geometric_drawing
- ../random_generator_and_text/random_generator_and_text
- ../discrete_fourier_transform/discrete_fourier_transform
- ../file_input_output_with_xml_yml/file_input_output_with_xml_yml
- ../interoperability_with_OpenCV_1/interoperability_with_OpenCV_1
- ../how_to_use_ippa_conversion/how_to_use_ippa_conversion
+++ /dev/null
-
-.. note::
- Unfortunetly we have no tutorials into this section. And you can help us with that, since OpenCV is a community effort. If you have a tutorial suggestion or you have written a tutorial yourself (or coded a sample code) that you would like to see here, please contact follow these instructions: :how_to_contribute:`How to contribute <>`.
+++ /dev/null
-.. |Author_AnaH| unicode:: Ana U+0020 Huam U+00E1 n
-.. |Author_BernatG| unicode:: Bern U+00E1 t U+0020 G U+00E1 bor
-.. |Author_AndreyK| unicode:: Andrey U+0020 Kamaev
-.. |Author_LeonidBLB| unicode:: Leonid U+0020 Beynenson
-.. |Author_VsevolodG| unicode:: Vsevolod U+0020 Glumov
-.. |Author_VictorE| unicode:: Victor U+0020 Eruhimov
-.. |Author_ArtemM| unicode:: Artem U+0020 Myagkov
-.. |Author_FernandoI| unicode:: Fernando U+0020 Iglesias U+0020 Garc U+00ED a
-.. |Author_EduardF| unicode:: Eduard U+0020 Feicho
-.. |Author_AlexB| unicode:: Alexandre U+0020 Benoit
-.. |Author_EricCh| unicode:: Eric U+0020 Christiansen
-.. |Author_AndreyP| unicode:: Andrey U+0020 Pavlenko
-.. |Author_AlexS| unicode:: Alexander U+0020 Smorkalov
-.. |Author_MimmoC| unicode:: Mimmo U+0020 Cosenza
-.. |Author_BarisD| unicode:: Bar U+0131 U+015F U+0020 Evrim U+0020 Demir U+00F6 z
-.. |Author_DomenicoB| unicode:: Domenico U+0020 Daniele U+0020 Bloisi
-.. |Author_MarvinS| unicode:: Marvin U+0020 Smith
+++ /dev/null
-.. _akazeMatching:
-
-
-AKAZE local features matching
-******************************
-
-Introduction
-------------------
-
-In this tutorial we will learn how to use [AKAZE]_ local features to detect and match keypoints on two images.
-
-We will find keypoints on a pair of images with given homography matrix,
-match them and count the number of inliers (i. e. matches that fit in the given homography).
-
-You can find expanded version of this example here: https://github.com/pablofdezalc/test_kaze_akaze_opencv
-
-.. [AKAZE] Fast Explicit Diffusion for Accelerated Features in Nonlinear Scale Spaces. Pablo F. Alcantarilla, Jesús Nuevo and Adrien Bartoli. In British Machine Vision Conference (BMVC), Bristol, UK, September 2013.
-
-Data
-------------------
-We are going to use images 1 and 3 from *Graffity* sequence of Oxford dataset.
-
-.. image:: images/graf.png
- :height: 200pt
- :width: 320pt
- :alt: Graffity
- :align: center
-
-Homography is given by a 3 by 3 matrix:
-
-.. code-block:: none
-
- 7.6285898e-01 -2.9922929e-01 2.2567123e+02
- 3.3443473e-01 1.0143901e+00 -7.6999973e+01
- 3.4663091e-04 -1.4364524e-05 1.0000000e+00
-
-You can find the images (*graf1.png*, *graf3.png*) and homography (*H1to3p.xml*) in *opencv/samples/cpp*.
-
-Source Code
-===========
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/features2D/AKAZE_match.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
-
-Explanation
-===========
-
-#. **Load images and homography**
-
- .. code-block:: cpp
-
- Mat img1 = imread("graf1.png", IMREAD_GRAYSCALE);
- Mat img2 = imread("graf3.png", IMREAD_GRAYSCALE);
-
- Mat homography;
- FileStorage fs("H1to3p.xml", FileStorage::READ);
- fs.getFirstTopLevelNode() >> homography;
-
- We are loading grayscale images here. Homography is stored in the xml created with FileStorage.
-
-#. **Detect keypoints and compute descriptors using AKAZE**
-
- .. code-block:: cpp
-
- vector<KeyPoint> kpts1, kpts2;
- Mat desc1, desc2;
-
- AKAZE akaze;
- akaze(img1, noArray(), kpts1, desc1);
- akaze(img2, noArray(), kpts2, desc2);
-
- We create AKAZE object and use it's *operator()* functionality. Since we don't need the *mask* parameter, *noArray()* is used.
-
-#. **Use brute-force matcher to find 2-nn matches**
-
- .. code-block:: cpp
-
- BFMatcher matcher(NORM_HAMMING);
- vector< vector<DMatch> > nn_matches;
- matcher.knnMatch(desc1, desc2, nn_matches, 2);
-
- We use Hamming distance, because AKAZE uses binary descriptor by default.
-
-#. **Use 2-nn matches to find correct keypoint matches**
-
- .. code-block:: cpp
-
- for(size_t i = 0; i < nn_matches.size(); i++) {
- DMatch first = nn_matches[i][0];
- float dist1 = nn_matches[i][0].distance;
- float dist2 = nn_matches[i][1].distance;
-
- if(dist1 < nn_match_ratio * dist2) {
- matched1.push_back(kpts1[first.queryIdx]);
- matched2.push_back(kpts2[first.trainIdx]);
- }
- }
-
- If the closest match is *ratio* closer than the second closest one, then the match is correct.
-
-#. **Check if our matches fit in the homography model**
-
- .. code-block:: cpp
-
- for(int i = 0; i < matched1.size(); i++) {
- Mat col = Mat::ones(3, 1, CV_64F);
- col.at<double>(0) = matched1[i].pt.x;
- col.at<double>(1) = matched1[i].pt.y;
-
- col = homography * col;
- col /= col.at<double>(2);
- float dist = sqrt( pow(col.at<double>(0) - matched2[i].pt.x, 2) +
- pow(col.at<double>(1) - matched2[i].pt.y, 2));
-
- if(dist < inlier_threshold) {
- int new_i = inliers1.size();
- inliers1.push_back(matched1[i]);
- inliers2.push_back(matched2[i]);
- good_matches.push_back(DMatch(new_i, new_i, 0));
- }
- }
-
- If the distance from first keypoint's projection to the second keypoint is less than threshold, then it it fits in the homography.
-
- We create a new set of matches for the inliers, because it is required by the drawing function.
-
-#. **Output results**
-
- .. code-block:: cpp
-
- Mat res;
- drawMatches(img1, inliers1, img2, inliers2, good_matches, res);
- imwrite("res.png", res);
- ...
-
- Here we save the resulting image and print some statistics.
-
-Results
-=======
-
-Found matches
---------------
-
-.. image:: images/res.png
- :height: 200pt
- :width: 320pt
- :alt: Matches
- :align: center
-
-A-KAZE Matching Results
---------------------------
-
-.. code-block:: none
-
- Keypoints 1 2943
- Keypoints 2 3511
- Matches 447
- Inliers 308
- Inlier Ratio 0.689038
+++ /dev/null
-.. _akazeTracking:
-
-
-AKAZE and ORB planar tracking
-******************************
-
-Introduction
-------------------
-
-In this tutorial we will compare *AKAZE* and *ORB* local features
-using them to find matches between video frames and track object movements.
-
-The algorithm is as follows:
-
-* Detect and describe keypoints on the first frame, manually set object boundaries
-* For every next frame:
-
- #. Detect and describe keypoints
- #. Match them using bruteforce matcher
- #. Estimate homography transformation using RANSAC
- #. Filter inliers from all the matches
- #. Apply homography transformation to the bounding box to find the object
- #. Draw bounding box and inliers, compute inlier ratio as evaluation metric
-
-.. image:: images/frame.png
- :height: 480pt
- :width: 640pt
- :alt: Result frame example
- :align: center
-
-Data
-===========
-To do the tracking we need a video and object position on the first frame.
-
-You can download our example video and data from `here <https://docs.google.com/file/d/0B72G7D4snftJandBb0taLVJHMFk>`_.
-
-To run the code you have to specify input and output video path and object bounding box.
-
-.. code-block:: none
-
- ./planar_tracking blais.mp4 result.avi blais_bb.xml.gz
-
-Source Code
-===========
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/features2D/AKAZE_tracking/planar_tracking.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
-
-Explanation
-===========
-
-Tracker class
---------------
-
- This class implements algorithm described abobve
- using given feature detector and descriptor matcher.
-
-* **Setting up the first frame**
-
- .. code-block:: cpp
-
- void Tracker::setFirstFrame(const Mat frame, vector<Point2f> bb, string title, Stats& stats)
- {
- first_frame = frame.clone();
- (*detector)(first_frame, noArray(), first_kp, first_desc);
- stats.keypoints = (int)first_kp.size();
- drawBoundingBox(first_frame, bb);
- putText(first_frame, title, Point(0, 60), FONT_HERSHEY_PLAIN, 5, Scalar::all(0), 4);
- object_bb = bb;
- }
-
- We compute and store keypoints and descriptors from the first frame and prepare it for the output.
-
- We need to save number of detected keypoints to make sure both detectors locate roughly the same number of those.
-
-* **Processing frames**
-
- #. Locate keypoints and compute descriptors
-
- .. code-block:: cpp
-
- (*detector)(frame, noArray(), kp, desc);
-
- To find matches between frames we have to locate the keypoints first.
-
- In this tutorial detectors are set up to find about 1000 keypoints on each frame.
-
- #. Use 2-nn matcher to find correspondences
-
- .. code-block:: cpp
-
- matcher->knnMatch(first_desc, desc, matches, 2);
- for(unsigned i = 0; i < matches.size(); i++) {
- if(matches[i][0].distance < nn_match_ratio * matches[i][1].distance) {
- matched1.push_back(first_kp[matches[i][0].queryIdx]);
- matched2.push_back( kp[matches[i][0].trainIdx]);
- }
- }
-
- If the closest match is *nn_match_ratio* closer than the second closest one, then it's a match.
-
- 2. Use *RANSAC* to estimate homography transformation
-
- .. code-block:: cpp
-
- homography = findHomography(Points(matched1), Points(matched2),
- RANSAC, ransac_thresh, inlier_mask);
-
- If there are at least 4 matches we can use random sample consensus to estimate image transformation.
-
- 3. Save the inliers
-
- .. code-block:: cpp
-
- for(unsigned i = 0; i < matched1.size(); i++) {
- if(inlier_mask.at<uchar>(i)) {
- int new_i = static_cast<int>(inliers1.size());
- inliers1.push_back(matched1[i]);
- inliers2.push_back(matched2[i]);
- inlier_matches.push_back(DMatch(new_i, new_i, 0));
- }
- }
-
- Since *findHomography* computes the inliers we only have to save the chosen points and matches.
-
- 4. Project object bounding box
-
- .. code-block:: cpp
-
- perspectiveTransform(object_bb, new_bb, homography);
-
- If there is a reasonable number of inliers we can use estimated transformation to locate the object.
-
-Results
-=======
-You can watch the resulting `video on youtube <http://www.youtube.com/watch?v=LWY-w8AGGhE>`_.
-
-*AKAZE* statistics:
-
- .. code-block:: none
-
- Matches 626
- Inliers 410
- Inlier ratio 0.58
- Keypoints 1117
-
-*ORB* statistics:
-
- .. code-block:: none
-
- Matches 504
- Inliers 319
- Inlier ratio 0.56
- Keypoints 1112
+++ /dev/null
-.. _detectionOfPlanarObjects:
-
-Detection of planar objects
-***************************
-
-.. highlight:: cpp
-
-The goal of this tutorial is to learn how to use *features2d* and *calib3d* modules for detecting known planar objects in scenes.
-
-*Test data*: use images in your data folder, for instance, ``box.png`` and ``box_in_scene.png``.
-
-#.
- Create a new console project. Read two input images. ::
-
- Mat img1 = imread(argv[1], IMREAD_GRAYSCALE);
- Mat img2 = imread(argv[2], IMREAD_GRAYSCALE);
-
-#.
- Detect keypoints in both images and compute descriptors for each of the keypoints. ::
-
- // detecting keypoints
- Ptr<Feature2D> surf = SURF::create();
- vector<KeyPoint> keypoints1;
- Mat descriptors1;
- surf->detectAndCompute(img1, Mat(), keypoints1, descriptors1);
-
- ... // do the same for the second image
-
-#.
- Now, find the closest matches between descriptors from the first image to the second: ::
-
- // matching descriptors
- BruteForceMatcher<L2<float> > matcher;
- vector<DMatch> matches;
- matcher.match(descriptors1, descriptors2, matches);
-
-#.
- Visualize the results: ::
-
- // drawing the results
- namedWindow("matches", 1);
- Mat img_matches;
- drawMatches(img1, keypoints1, img2, keypoints2, matches, img_matches);
- imshow("matches", img_matches);
- waitKey(0);
-
-#.
- Find the homography transformation between two sets of points: ::
-
- vector<Point2f> points1, points2;
- // fill the arrays with the points
- ....
- Mat H = findHomography(Mat(points1), Mat(points2), RANSAC, ransacReprojThreshold);
-
-
-#.
- Create a set of inlier matches and draw them. Use perspectiveTransform function to map points with homography:
-
- Mat points1Projected;
- perspectiveTransform(Mat(points1), points1Projected, H);
-
-#.
- Use ``drawMatches`` for drawing inliers.
+++ /dev/null
-.. _feature_description:
-
-Feature Description
-*******************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the :descriptor_extractor:`DescriptorExtractor<>` interface in order to find the feature vector correspondent to the keypoints. Specifically:
-
- * Use :surf_descriptor_extractor:`SurfDescriptorExtractor<>` and its function :descriptor_extractor:`compute<>` to perform the required calculations.
- * Use a :brute_force_matcher:`BFMatcher<>` to match the features vector
- * Use the function :draw_matches:`drawMatches<>` to draw the detected matches.
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below.
-
-.. code-block:: cpp
-
- #include <stdio.h>
- #include <iostream>
- #include "opencv2/core.hpp"
- #include "opencv2/features2d.hpp"
- #include "opencv2/highgui.hpp"
- #include "opencv2/xfeatures2d.hpp"
-
- using namespace cv;
- using namespace cv::xfeatures2d;
-
- void readme();
-
- /* @function main */
- int main( int argc, char** argv )
- {
- if( argc != 3 )
- { return -1; }
-
- Mat img_1 = imread( argv[1], IMREAD_GRAYSCALE );
- Mat img_2 = imread( argv[2], IMREAD_GRAYSCALE );
-
- if( !img_1.data || !img_2.data )
- { return -1; }
-
- //-- Step 1: Detect the keypoints using SURF Detector, compute the descriptors
- int minHessian = 400;
-
- Ptr<SURF> detector = SURF::create();
- detector->setMinHessian(minHessian);
-
- std::vector<KeyPoint> keypoints_1, keypoints_2;
- Mat descriptors_1, descriptors_2;
-
- detector->detectAndCompute( img_1, keypoints_1, descriptors_1 );
- detector->detectAndCompute( img_2, keypoints_2, descriptors_2 );
-
- //-- Step 2: Matching descriptor vectors with a brute force matcher
- BFMatcher matcher(NORM_L2);
- std::vector< DMatch > matches;
- matcher.match( descriptors_1, descriptors_2, matches );
-
- //-- Draw matches
- Mat img_matches;
- drawMatches( img_1, keypoints_1, img_2, keypoints_2, matches, img_matches );
-
- //-- Show detected matches
- imshow("Matches", img_matches );
-
- waitKey(0);
-
- return 0;
- }
-
- /* @function readme */
- void readme()
- { std::cout << " Usage: ./SURF_descriptor <img1> <img2>" << std::endl; }
-
-Explanation
-============
-
-Result
-======
-
-#. Here is the result after applying the BruteForce matcher between the two original images:
-
- .. image:: images/Feature_Description_BruteForce_Result.jpg
- :align: center
- :height: 200pt
+++ /dev/null
-.. _feature_detection:
-
-Feature Detection
-******************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the :feature_detector:`FeatureDetector<>` interface in order to find interest points. Specifically:
-
- * Use the :surf_feature_detector:`SurfFeatureDetector<>` and its function :feature_detector_detect:`detect<>` to perform the detection process
- * Use the function :draw_keypoints:`drawKeypoints<>` to draw the detected keypoints
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below.
-
-.. code-block:: cpp
-
- #include <stdio.h>
- #include <iostream>
- #include "opencv2/core.hpp"
- #include "opencv2/features2d.hpp"
- #include "opencv2/xfeatures2d.hpp"
- #include "opencv2/highgui.hpp"
-
- using namespace cv;
- using namespace cv::xfeatures2d;
-
- void readme();
-
- /* @function main */
- int main( int argc, char** argv )
- {
- if( argc != 3 )
- { readme(); return -1; }
-
- Mat img_1 = imread( argv[1], IMREAD_GRAYSCALE );
- Mat img_2 = imread( argv[2], IMREAD_GRAYSCALE );
-
- if( !img_1.data || !img_2.data )
- { std::cout<< " --(!) Error reading images " << std::endl; return -1; }
-
- //-- Step 1: Detect the keypoints using SURF Detector
- int minHessian = 400;
-
- Ptr<SURF> detector = SURF::create( minHessian );
-
- std::vector<KeyPoint> keypoints_1, keypoints_2;
-
- detector->detect( img_1, keypoints_1 );
- detector->detect( img_2, keypoints_2 );
-
- //-- Draw keypoints
- Mat img_keypoints_1; Mat img_keypoints_2;
-
- drawKeypoints( img_1, keypoints_1, img_keypoints_1, Scalar::all(-1), DrawMatchesFlags::DEFAULT );
- drawKeypoints( img_2, keypoints_2, img_keypoints_2, Scalar::all(-1), DrawMatchesFlags::DEFAULT );
-
- //-- Show detected (drawn) keypoints
- imshow("Keypoints 1", img_keypoints_1 );
- imshow("Keypoints 2", img_keypoints_2 );
-
- waitKey(0);
-
- return 0;
- }
-
- /* @function readme */
- void readme()
- { std::cout << " Usage: ./SURF_detector <img1> <img2>" << std::endl; }
-
-Explanation
-============
-
-Result
-======
-
-#. Here is the result of the feature detection applied to the first image:
-
- .. image:: images/Feature_Detection_Result_a.jpg
- :align: center
- :height: 125pt
-
-#. And here is the result for the second image:
-
- .. image:: images/Feature_Detection_Result_b.jpg
- :align: center
- :height: 200pt
+++ /dev/null
-.. _feature_flann_matcher:
-
-Feature Matching with FLANN
-****************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the :flann_based_matcher:`FlannBasedMatcher<>` interface in order to perform a quick and efficient matching by using the :flann:`FLANN<>` ( *Fast Approximate Nearest Neighbor Search Library* )
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below.
-
-.. code-block:: cpp
-
- /*
- * @file SURF_FlannMatcher
- * @brief SURF detector + descriptor + FLANN Matcher
- * @author A. Huaman
- */
-
- #include <stdio.h>
- #include <iostream>
- #include <stdio.h>
- #include <iostream>
- #include "opencv2/core.hpp"
- #include "opencv2/features2d.hpp"
- #include "opencv2/imgcodecs.hpp"
- #include "opencv2/highgui.hpp"
- #include "opencv2/xfeatures2d.hpp"
-
- using namespace std;
- using namespace cv;
- using namespace cv::xfeatures2d;
-
- void readme();
-
- /*
- * @function main
- * @brief Main function
- */
- int main( int argc, char** argv )
- {
- if( argc != 3 )
- { readme(); return -1; }
-
- Mat img_1 = imread( argv[1], IMREAD_GRAYSCALE );
- Mat img_2 = imread( argv[2], IMREAD_GRAYSCALE );
-
- if( !img_1.data || !img_2.data )
- { std::cout<< " --(!) Error reading images " << std::endl; return -1; }
-
- //-- Step 1: Detect the keypoints using SURF Detector
- int minHessian = 400;
-
- SurfFeatureDetector detector( minHessian );
-
- std::vector<KeyPoint> keypoints_1, keypoints_2;
-
- detector.detect( img_1, keypoints_1 );
- detector.detect( img_2, keypoints_2 );
-
- //-- Step 2: Calculate descriptors (feature vectors)
- SurfDescriptorExtractor extractor;
-
- Mat descriptors_1, descriptors_2;
-
- extractor.compute( img_1, keypoints_1, descriptors_1 );
- extractor.compute( img_2, keypoints_2, descriptors_2 );
-
- //-- Step 3: Matching descriptor vectors using FLANN matcher
- FlannBasedMatcher matcher;
- std::vector< DMatch > matches;
- matcher.match( descriptors_1, descriptors_2, matches );
-
- double max_dist = 0; double min_dist = 100;
-
- //-- Quick calculation of max and min distances between keypoints
- for( int i = 0; i < descriptors_1.rows; i++ )
- { double dist = matches[i].distance;
- if( dist < min_dist ) min_dist = dist;
- if( dist > max_dist ) max_dist = dist;
- }
-
- printf("-- Max dist : %f \n", max_dist );
- printf("-- Min dist : %f \n", min_dist );
-
- //-- Draw only "good" matches (i.e. whose distance is less than 2*min_dist,
- //-- or a small arbitary value ( 0.02 ) in the event that min_dist is very
- //-- small)
- //-- PS.- radiusMatch can also be used here.
- std::vector< DMatch > good_matches;
-
- for( int i = 0; i < descriptors_1.rows; i++ )
- { if( matches[i].distance <= max(2*min_dist, 0.02) )
- { good_matches.push_back( matches[i]); }
- }
-
- //-- Draw only "good" matches
- Mat img_matches;
- drawMatches( img_1, keypoints_1, img_2, keypoints_2,
- good_matches, img_matches, Scalar::all(-1), Scalar::all(-1),
- vector<char>(), DrawMatchesFlags::NOT_DRAW_SINGLE_POINTS );
-
- //-- Show detected matches
- imshow( "Good Matches", img_matches );
-
- for( int i = 0; i < (int)good_matches.size(); i++ )
- { printf( "-- Good Match [%d] Keypoint 1: %d -- Keypoint 2: %d \n", i, good_matches[i].queryIdx, good_matches[i].trainIdx ); }
-
- waitKey(0);
-
- return 0;
- }
-
- /*
- * @function readme
- */
- void readme()
- { std::cout << " Usage: ./SURF_FlannMatcher <img1> <img2>" << std::endl; }
-
-
-Explanation
-============
-
-Result
-======
-
-#. Here is the result of the feature detection applied to the first image:
-
- .. image:: images/Featur_FlannMatcher_Result.jpg
- :align: center
- :height: 250pt
-
-#. Additionally, we get as console output the keypoints filtered:
-
- .. image:: images/Feature_FlannMatcher_Keypoints_Result.jpg
- :align: center
- :height: 250pt
+++ /dev/null
-.. _feature_homography:
-
-Features2D + Homography to find a known object
-**********************************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the function :find_homography:`findHomography<>` to find the transform between matched keypoints.
- * Use the function :perspective_transform:`perspectiveTransform<>` to map the points.
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below.
-
-.. code-block:: cpp
-
- #include <stdio.h>
- #include <iostream>
- #include "opencv2/core.hpp"
- #include "opencv2/features2d.hpp"
- #include "opencv2/highgui.hpp"
- #include "opencv2/calib3d.hpp"
- #include "opencv2/xfeatures2d.hpp"
-
- using namespace cv;
- using namespace cv::xfeatures2d;
-
- void readme();
-
- /* @function main */
- int main( int argc, char** argv )
- {
- if( argc != 3 )
- { readme(); return -1; }
-
- Mat img_object = imread( argv[1], IMREAD_GRAYSCALE );
- Mat img_scene = imread( argv[2], IMREAD_GRAYSCALE );
-
- if( !img_object.data || !img_scene.data )
- { std::cout<< " --(!) Error reading images " << std::endl; return -1; }
-
- //-- Step 1: Detect the keypoints using SURF Detector
- int minHessian = 400;
-
- SurfFeatureDetector detector( minHessian );
-
- std::vector<KeyPoint> keypoints_object, keypoints_scene;
-
- detector.detect( img_object, keypoints_object );
- detector.detect( img_scene, keypoints_scene );
-
- //-- Step 2: Calculate descriptors (feature vectors)
- SurfDescriptorExtractor extractor;
-
- Mat descriptors_object, descriptors_scene;
-
- extractor.compute( img_object, keypoints_object, descriptors_object );
- extractor.compute( img_scene, keypoints_scene, descriptors_scene );
-
- //-- Step 3: Matching descriptor vectors using FLANN matcher
- FlannBasedMatcher matcher;
- std::vector< DMatch > matches;
- matcher.match( descriptors_object, descriptors_scene, matches );
-
- double max_dist = 0; double min_dist = 100;
-
- //-- Quick calculation of max and min distances between keypoints
- for( int i = 0; i < descriptors_object.rows; i++ )
- { double dist = matches[i].distance;
- if( dist < min_dist ) min_dist = dist;
- if( dist > max_dist ) max_dist = dist;
- }
-
- printf("-- Max dist : %f \n", max_dist );
- printf("-- Min dist : %f \n", min_dist );
-
- //-- Draw only "good" matches (i.e. whose distance is less than 3*min_dist )
- std::vector< DMatch > good_matches;
-
- for( int i = 0; i < descriptors_object.rows; i++ )
- { if( matches[i].distance < 3*min_dist )
- { good_matches.push_back( matches[i]); }
- }
-
- Mat img_matches;
- drawMatches( img_object, keypoints_object, img_scene, keypoints_scene,
- good_matches, img_matches, Scalar::all(-1), Scalar::all(-1),
- vector<char>(), DrawMatchesFlags::NOT_DRAW_SINGLE_POINTS );
-
- //-- Localize the object
- std::vector<Point2f> obj;
- std::vector<Point2f> scene;
-
- for( int i = 0; i < good_matches.size(); i++ )
- {
- //-- Get the keypoints from the good matches
- obj.push_back( keypoints_object[ good_matches[i].queryIdx ].pt );
- scene.push_back( keypoints_scene[ good_matches[i].trainIdx ].pt );
- }
-
- Mat H = findHomography( obj, scene, RANSAC );
-
- //-- Get the corners from the image_1 ( the object to be "detected" )
- std::vector<Point2f> obj_corners(4);
- obj_corners[0] = cvPoint(0,0); obj_corners[1] = cvPoint( img_object.cols, 0 );
- obj_corners[2] = cvPoint( img_object.cols, img_object.rows ); obj_corners[3] = cvPoint( 0, img_object.rows );
- std::vector<Point2f> scene_corners(4);
-
- perspectiveTransform( obj_corners, scene_corners, H);
-
- //-- Draw lines between the corners (the mapped object in the scene - image_2 )
- line( img_matches, scene_corners[0] + Point2f( img_object.cols, 0), scene_corners[1] + Point2f( img_object.cols, 0), Scalar(0, 255, 0), 4 );
- line( img_matches, scene_corners[1] + Point2f( img_object.cols, 0), scene_corners[2] + Point2f( img_object.cols, 0), Scalar( 0, 255, 0), 4 );
- line( img_matches, scene_corners[2] + Point2f( img_object.cols, 0), scene_corners[3] + Point2f( img_object.cols, 0), Scalar( 0, 255, 0), 4 );
- line( img_matches, scene_corners[3] + Point2f( img_object.cols, 0), scene_corners[0] + Point2f( img_object.cols, 0), Scalar( 0, 255, 0), 4 );
-
- //-- Show detected matches
- imshow( "Good Matches & Object detection", img_matches );
-
- waitKey(0);
- return 0;
- }
-
- /* @function readme */
- void readme()
- { std::cout << " Usage: ./SURF_descriptor <img1> <img2>" << std::endl; }
-
-Explanation
-============
-
-Result
-======
-
-
-#. And here is the result for the detected object (highlighted in green)
-
- .. image:: images/Feature_Homography_Result.jpg
- :align: center
- :height: 200pt
+++ /dev/null
-.. _Table-Of-Content-Feature2D:
-
-*feature2d* module. 2D Features framework
------------------------------------------------------------
-
-Learn about how to use the feature points detectors, descriptors and matching framework found inside OpenCV.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |Harris| **Title:** :ref:`harris_detector`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Why is it a good idea to track corners? We learn to use the Harris method to detect corners
-
- ===================== ==============================================
-
- .. |Harris| image:: images/trackingmotion/Harris_Detector_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |ShiTomasi| **Title:** :ref:`good_features_to_track`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we use an improved method to detect corners more accuratelyI
-
- ===================== ==============================================
-
- .. |ShiTomasi| image:: images/trackingmotion/Shi_Tomasi_Detector_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |GenericCorner| **Title:** :ref:`generic_corner_detector`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Here you will learn how to use OpenCV functions to make your personalized corner detector!
-
- ===================== ==============================================
-
- .. |GenericCorner| image:: images/trackingmotion/Generic_Corner_Detector_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |Subpixel| **Title:** :ref:`corner_subpixeles`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Is pixel resolution enough? Here we learn a simple method to improve our accuracy.
-
- ===================== ==============================================
-
- .. |Subpixel| image:: images/trackingmotion/Corner_Subpixeles_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |FeatureDetect| **Title:** :ref:`feature_detection`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- In this tutorial, you will use *features2d* to detect interest points.
-
- ===================== ==============================================
-
- .. |FeatureDetect| image:: images/Feature_Detection_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |FeatureDescript| **Title:** :ref:`feature_description`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- In this tutorial, you will use *features2d* to calculate feature vectors.
-
- ===================== ==============================================
-
- .. |FeatureDescript| image:: images/Feature_Description_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |FeatureFlann| **Title:** :ref:`feature_flann_matcher`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- In this tutorial, you will use the FLANN library to make a fast matching.
-
- ===================== ==============================================
-
- .. |FeatureFlann| image:: images/Feature_Flann_Matcher_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |FeatureHomo| **Title:** :ref:`feature_homography`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- In this tutorial, you will use *features2d* and *calib3d* to detect an object in a scene.
-
- ===================== ==============================================
-
- .. |FeatureHomo| image:: images/Feature_Homography_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |DetectPlanar| **Title:** :ref:`detectionOfPlanarObjects`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_VictorE|
-
- You will use *features2d* and *calib3d* modules for detecting known planar objects in scenes.
-
- ===================== ==============================================
-
- .. |DetectPlanar| image:: images/detection_of_planar_objects.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |AkazeMatch| **Title:** :ref:`akazeMatching`
-
- *Compatibility:* > OpenCV 3.0
-
- *Author:* Fedor Morozov
-
- Using *AKAZE* local features to find correspondence between two images.
-
- ===================== ==============================================
-
- .. |AkazeMatch| image:: images/AKAZE_Match_Tutorial_Cover.png
- :height: 90pt
- :width: 90pt
-
- ===================== ==============================================
- |AkazeTracking| **Title:** :ref:`akazeTracking`
-
- *Compatibility:* > OpenCV 3.0
-
- *Author:* Fedor Morozov
-
- Using *AKAZE* and *ORB* for planar object tracking.
-
- ===================== ==============================================
-
- .. |AkazeTracking| image:: images/AKAZE_Tracking_Tutorial_Cover.png
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../feature_description/feature_description
- ../trackingmotion/harris_detector/harris_detector
- ../feature_flann_matcher/feature_flann_matcher
- ../feature_homography/feature_homography
- ../trackingmotion/good_features_to_track/good_features_to_track.rst
- ../trackingmotion/generic_corner_detector/generic_corner_detector
- ../trackingmotion/corner_subpixeles/corner_subpixeles
- ../feature_detection/feature_detection
- ../feature_flann_matcher/feature_flann_matcher
- ../feature_homography/feature_homography
- ../detection_of_planar_objects/detection_of_planar_objects
- ../akaze_matching/akaze_matching
- ../akaze_tracking/akaze_tracking
+++ /dev/null
-.. _corner_subpixeles:
-
-Detecting corners location in subpixeles
-****************************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :corner_sub_pix:`cornerSubPix <>` to find more exact corner positions (more exact than integer pixels).
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/TrackingMotion/cornerSubPix_Demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
- #include <stdlib.h>
-
- using namespace cv;
- using namespace std;
-
- /// Global variables
- Mat src, src_gray;
-
- int maxCorners = 10;
- int maxTrackbar = 25;
-
- RNG rng(12345);
- char* source_window = "Image";
-
- /// Function header
- void goodFeaturesToTrack_Demo( int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load source image and convert it to gray
- src = imread( argv[1], 1 );
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
-
- /// Create Window
- namedWindow( source_window, WINDOW_AUTOSIZE );
-
- /// Create Trackbar to set the number of corners
- createTrackbar( "Max corners:", source_window, &maxCorners, maxTrackbar, goodFeaturesToTrack_Demo);
-
- imshow( source_window, src );
-
- goodFeaturesToTrack_Demo( 0, 0 );
-
- waitKey(0);
- return(0);
- }
-
- /*
- * @function goodFeaturesToTrack_Demo.cpp
- * @brief Apply Shi-Tomasi corner detector
- */
- void goodFeaturesToTrack_Demo( int, void* )
- {
- if( maxCorners < 1 ) { maxCorners = 1; }
-
- /// Parameters for Shi-Tomasi algorithm
- vector<Point2f> corners;
- double qualityLevel = 0.01;
- double minDistance = 10;
- int blockSize = 3;
- bool useHarrisDetector = false;
- double k = 0.04;
-
- /// Copy the source image
- Mat copy;
- copy = src.clone();
-
- /// Apply corner detection
- goodFeaturesToTrack( src_gray,
- corners,
- maxCorners,
- qualityLevel,
- minDistance,
- Mat(),
- blockSize,
- useHarrisDetector,
- k );
-
-
- /// Draw corners detected
- cout<<"** Number of corners detected: "<<corners.size()<<endl;
- int r = 4;
- for( int i = 0; i < corners.size(); i++ )
- { circle( copy, corners[i], r, Scalar(rng.uniform(0,255), rng.uniform(0,255),
- rng.uniform(0,255)), -1, 8, 0 ); }
-
- /// Show what you got
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, copy );
-
- /// Set the neeed parameters to find the refined corners
- Size winSize = Size( 5, 5 );
- Size zeroZone = Size( -1, -1 );
- TermCriteria criteria = TermCriteria( TermCriteria::EPS + TermCriteria::MAX_ITER, 40, 0.001 );
-
- /// Calculate the refined corner locations
- cornerSubPix( src_gray, corners, winSize, zeroZone, criteria );
-
- /// Write them down
- for( int i = 0; i < corners.size(); i++ )
- { cout<<" -- Refined Corner ["<<i<<"] ("<<corners[i].x<<","<<corners[i].y<<")"<<endl; }
- }
-
-
-Explanation
-============
-
-Result
-======
-
-.. image:: images/Corner_Subpixeles_Original_Image.jpg
- :align: center
-
-Here is the result:
-
-.. image:: images/Corner_Subpixeles_Result.jpg
- :align: center
+++ /dev/null
-.. _generic_corner_detector:
-
-Creating yor own corner detector
-********************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :corner_eigenvals_and_vecs:`cornerEigenValsAndVecs <>` to find the eigenvalues and eigenvectors to determine if a pixel is a corner.
- * Use the OpenCV function :corner_min_eigenval:`cornerMinEigenVal <>` to find the minimum eigenvalues for corner detection.
- * To implement our own version of the Harris detector as well as the Shi-Tomasi detector, by using the two functions above.
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/TrackingMotion/cornerDetector_Demo.cpp>`_
-
-.. literalinclude:: ../../../../../samples/cpp/tutorial_code/TrackingMotion/cornerDetector_Demo.cpp
- :language: cpp
-
-Explanation
-============
-
-Result
-======
-
-.. image:: images/My_Harris_corner_detector_Result.jpg
- :align: center
-
-
-.. image:: images/My_Shi_Tomasi_corner_detector_Result.jpg
- :align: center
+++ /dev/null
-.. _good_features_to_track:
-
-Shi-Tomasi corner detector
-**************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the function :good_features_to_track:`goodFeaturesToTrack <>` to detect corners using the Shi-Tomasi method.
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/TrackingMotion/goodFeaturesToTrack_Demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
- #include <stdlib.h>
-
- using namespace cv;
- using namespace std;
-
- /// Global variables
- Mat src, src_gray;
-
- int maxCorners = 23;
- int maxTrackbar = 100;
-
- RNG rng(12345);
- char* source_window = "Image";
-
- /// Function header
- void goodFeaturesToTrack_Demo( int, void* );
-
- /*
- * @function main
- */
- int main( int argc, char** argv )
- {
- /// Load source image and convert it to gray
- src = imread( argv[1], 1 );
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
-
- /// Create Window
- namedWindow( source_window, WINDOW_AUTOSIZE );
-
- /// Create Trackbar to set the number of corners
- createTrackbar( "Max corners:", source_window, &maxCorners, maxTrackbar, goodFeaturesToTrack_Demo );
-
- imshow( source_window, src );
-
- goodFeaturesToTrack_Demo( 0, 0 );
-
- waitKey(0);
- return(0);
- }
-
- /*
- * @function goodFeaturesToTrack_Demo.cpp
- * @brief Apply Shi-Tomasi corner detector
- */
- void goodFeaturesToTrack_Demo( int, void* )
- {
- if( maxCorners < 1 ) { maxCorners = 1; }
-
- /// Parameters for Shi-Tomasi algorithm
- vector<Point2f> corners;
- double qualityLevel = 0.01;
- double minDistance = 10;
- int blockSize = 3;
- bool useHarrisDetector = false;
- double k = 0.04;
-
- /// Copy the source image
- Mat copy;
- copy = src.clone();
-
- /// Apply corner detection
- goodFeaturesToTrack( src_gray,
- corners,
- maxCorners,
- qualityLevel,
- minDistance,
- Mat(),
- blockSize,
- useHarrisDetector,
- k );
-
-
- /// Draw corners detected
- cout<<"** Number of corners detected: "<<corners.size()<<endl;
- int r = 4;
- for( int i = 0; i < corners.size(); i++ )
- { circle( copy, corners[i], r, Scalar(rng.uniform(0,255), rng.uniform(0,255),
- rng.uniform(0,255)), -1, 8, 0 ); }
-
- /// Show what you got
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, copy );
- }
-
-Explanation
-============
-
-Result
-======
-
-.. image:: images/Feature_Detection_Result_a.jpg
- :align: center
+++ /dev/null
-.. _harris_detector:
-
-Harris corner detector
-**********************
-
-Goal
-=====
-
-In this tutorial you will learn:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * What features are and why they are important
- * Use the function :corner_harris:`cornerHarris <>` to detect corners using the Harris-Stephens method.
-
-Theory
-======
-
-What is a feature?
--------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * In computer vision, usually we need to find matching points between different frames of an environment. Why? If we know how two images relate to each other, we can use *both* images to extract information of them.
-
- * When we say **matching points** we are referring, in a general sense, to *characteristics* in the scene that we can recognize easily. We call these characteristics **features**.
-
- * **So, what characteristics should a feature have?**
-
- * It must be *uniquely recognizable*
-
-
-Types of Image Features
-------------------------
-
-To mention a few:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Edges
- * **Corners** (also known as interest points)
- * Blobs (also known as regions of interest )
-
-In this tutorial we will study the *corner* features, specifically.
-
-Why is a corner so special?
-----------------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Because, since it is the intersection of two edges, it represents a point in which the directions of these two edges *change*. Hence, the gradient of the image (in both directions) have a high variation, which can be used to detect it.
-
-
-How does it work?
------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Let's look for corners. Since corners represents a variation in the gradient in the image, we will look for this "variation".
-
- * Consider a grayscale image :math:`I`. We are going to sweep a window :math:`w(x,y)` (with displacements :math:`u` in the x direction and :math:`v` in the right direction) :math:`I` and will calculate the variation of intensity.
-
- .. math::
-
- E(u,v) = \sum _{x,y} w(x,y)[ I(x+u,y+v) - I(x,y)]^{2}
-
- where:
-
- * :math:`w(x,y)` is the window at position :math:`(x,y)`
- * :math:`I(x,y)` is the intensity at :math:`(x,y)`
- * :math:`I(x+u,y+v)` is the intensity at the moved window :math:`(x+u,y+v)`
-
- * Since we are looking for windows with corners, we are looking for windows with a large variation in intensity. Hence, we have to maximize the equation above, specifically the term:
-
- .. math::
-
- \sum _{x,y}[ I(x+u,y+v) - I(x,y)]^{2}
-
-
- * Using *Taylor expansion*:
-
- .. math::
-
- E(u,v) \approx \sum _{x,y}[ I(x,y) + u I_{x} + vI_{y} - I(x,y)]^{2}
-
-
- * Expanding the equation and cancelling properly:
-
- .. math::
-
- E(u,v) \approx \sum _{x,y} u^{2}I_{x}^{2} + 2uvI_{x}I_{y} + v^{2}I_{y}^{2}
-
- * Which can be expressed in a matrix form as:
-
- .. math::
-
- E(u,v) \approx \begin{bmatrix}
- u & v
- \end{bmatrix}
- \left (
- \displaystyle \sum_{x,y}
- w(x,y)
- \begin{bmatrix}
- I_x^{2} & I_{x}I_{y} \\
- I_xI_{y} & I_{y}^{2}
- \end{bmatrix}
- \right )
- \begin{bmatrix}
- u \\
- v
- \end{bmatrix}
-
- * Let's denote:
-
- .. math::
-
- M = \displaystyle \sum_{x,y}
- w(x,y)
- \begin{bmatrix}
- I_x^{2} & I_{x}I_{y} \\
- I_xI_{y} & I_{y}^{2}
- \end{bmatrix}
-
- * So, our equation now is:
-
- .. math::
-
- E(u,v) \approx \begin{bmatrix}
- u & v
- \end{bmatrix}
- M
- \begin{bmatrix}
- u \\
- v
- \end{bmatrix}
-
-
- * A score is calculated for each window, to determine if it can possibly contain a corner:
-
- .. math::
-
- R = det(M) - k(trace(M))^{2}
-
- where:
-
- * det(M) = :math:`\lambda_{1}\lambda_{2}`
- * trace(M) = :math:`\lambda_{1}+\lambda_{2}`
-
- a window with a score :math:`R` greater than a certain value is considered a "corner"
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/TrackingMotion/cornerHarris_Demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
- #include <stdlib.h>
-
- using namespace cv;
- using namespace std;
-
- /// Global variables
- Mat src, src_gray;
- int thresh = 200;
- int max_thresh = 255;
-
- char* source_window = "Source image";
- char* corners_window = "Corners detected";
-
- /// Function header
- void cornerHarris_demo( int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load source image and convert it to gray
- src = imread( argv[1], 1 );
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
-
- /// Create a window and a trackbar
- namedWindow( source_window, WINDOW_AUTOSIZE );
- createTrackbar( "Threshold: ", source_window, &thresh, max_thresh, cornerHarris_demo );
- imshow( source_window, src );
-
- cornerHarris_demo( 0, 0 );
-
- waitKey(0);
- return(0);
- }
-
- /* @function cornerHarris_demo */
- void cornerHarris_demo( int, void* )
- {
-
- Mat dst, dst_norm, dst_norm_scaled;
- dst = Mat::zeros( src.size(), CV_32FC1 );
-
- /// Detector parameters
- int blockSize = 2;
- int apertureSize = 3;
- double k = 0.04;
-
- /// Detecting corners
- cornerHarris( src_gray, dst, blockSize, apertureSize, k, BORDER_DEFAULT );
-
- /// Normalizing
- normalize( dst, dst_norm, 0, 255, NORM_MINMAX, CV_32FC1, Mat() );
- convertScaleAbs( dst_norm, dst_norm_scaled );
-
- /// Drawing a circle around corners
- for( int j = 0; j < dst_norm.rows ; j++ )
- { for( int i = 0; i < dst_norm.cols; i++ )
- {
- if( (int) dst_norm.at<float>(j,i) > thresh )
- {
- circle( dst_norm_scaled, Point( i, j ), 5, Scalar(0), 2, 8, 0 );
- }
- }
- }
- /// Showing the result
- namedWindow( corners_window, WINDOW_AUTOSIZE );
- imshow( corners_window, dst_norm_scaled );
- }
-
-
-Explanation
-============
-
-Result
-======
-
-The original image:
-
-.. image:: images/Harris_Detector_Original_Image.jpg
- :align: center
-
-The detected corners are surrounded by a small black circle
-
-.. image:: images/Harris_Detector_Result.jpg
- :align: center
+++ /dev/null
-.. _Table-Of-Content-General:
-
-General tutorials
------------------------------------------------------------
-
-These tutorials are the bottom of the iceberg as they link together multiple of the modules presented above in order to solve complex problems.
-
-.. include:: ../../definitions/noContent.rst
-
-.. raw:: latex
-
- \pagebreak
+++ /dev/null
-.. _gpuBasicsSimilarity:
-
-Similarity check (PNSR and SSIM) on the GPU
-*******************************************
-
-Goal
-====
-
-In the :ref:`videoInputPSNRMSSIM` tutorial I already presented the PSNR and SSIM methods for
-checking the similarity between the two images. And as you could see there performing these takes
-quite some time, especially in the case of the SSIM. However, if the performance numbers of an
-OpenCV implementation for the CPU do not satisfy you and you happen to have an NVidia CUDA GPU
-device in your system all is not lost. You may try to port or write your algorithm for the video
-card.
-
-This tutorial will give a good grasp on how to approach coding by using the GPU module of OpenCV. As
-a prerequisite you should already know how to handle the core, highgui and imgproc modules. So, our
-goals are:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + What's different compared to the CPU?
- + Create the GPU code for the PSNR and SSIM
- + Optimize the code for maximal performance
-
-The source code
-===============
-
-You may also find the source code and these video file in the
-:file:`samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity` folder of the
-OpenCV source library or :download:`download it from here
-<../../../../samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp>`. The
-full source code is quite long (due to the controlling of the application via the command line
-arguments and performance measurement). Therefore, to avoid cluttering up these sections with those
-you'll find here only the functions itself.
-
-The PSNR returns a float number, that if the two inputs are similar between 30 and 50 (higher is
-better).
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 165-210, 18-23, 210-235
-
-The SSIM returns the MSSIM of the images. This is too a float number between zero and one (higher is
-better), however we have one for each channel. Therefore, we return a *Scalar* OpenCV data
-structure:
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 235-355, 26-42, 357-
-
-How to do it? - The GPU
-=======================
-
-Now as you can see we have three types of functions for each operation. One for the CPU and two for
-the GPU. The reason I made two for the GPU is too illustrate that often simple porting your CPU to
-GPU will actually make it slower. If you want some performance gain you will need to remember a few
-rules, whose I'm going to detail later on.
-
-The development of the GPU module was made so that it resembles as much as possible its CPU
-counterpart. This is to make porting easy. The first thing you need to do before writing any code is
-to link the GPU module to your project, and include the header file for the module. All the
-functions and data structures of the GPU are in a *gpu* sub namespace of the *cv* namespace. You may
-add this to the default one via the *use namespace* keyword, or mark it everywhere explicitly via
-the cv:: to avoid confusion. I'll do the later.
-
-.. code-block:: cpp
-
- #include <opencv2/gpu.hpp> // GPU structures and methods
-
-GPU stands for **g**\ raphics **p**\ rocessing **u**\ nit. It was originally build to render
-graphical scenes. These scenes somehow build on a lot of data. Nevertheless, these aren't all
-dependent one from another in a sequential way and as it is possible a parallel processing of them.
-Due to this a GPU will contain multiple smaller processing units. These aren't the state of the art
-processors and on a one on one test with a CPU it will fall behind. However, its strength lies in
-its numbers. In the last years there has been an increasing trend to harvest these massive parallel
-powers of the GPU in non-graphical scene rendering too. This gave birth to the general-purpose
-computation on graphics processing units (GPGPU).
-
-The GPU has its own memory. When you read data from the hard drive with OpenCV into a *Mat* object
-that takes place in your systems memory. The CPU works somehow directly on this (via its cache),
-however the GPU cannot. He has too transferred the information he will use for calculations from the
-system memory to its own. This is done via an upload process and takes time. In the end the result
-will have to be downloaded back to your system memory for your CPU to see it and use it. Porting
-small functions to GPU is not recommended as the upload/download time will be larger than the amount
-you gain by a parallel execution.
-
-Mat objects are stored only in the system memory (or the CPU cache). For getting an OpenCV matrix
-to the GPU you'll need to use its GPU counterpart :gpudatastructure:`GpuMat <gpu-gpumat>`. It works
-similar to the Mat with a 2D only limitation and no reference returning for its functions (cannot
-mix GPU references with CPU ones). To upload a Mat object to the GPU you need to call the upload
-function after creating an instance of the class. To download you may use simple assignment to a
-Mat object or use the download function.
-
-.. code-block:: cpp
-
- Mat I1; // Main memory item - read image into with imread for example
- gpu::GpuMat gI; // GPU matrix - for now empty
- gI1.upload(I1); // Upload a data from the system memory to the GPU memory
-
- I1 = gI1; // Download, gI1.download(I1) will work too
-
-Once you have your data up in the GPU memory you may call GPU enabled functions of OpenCV. Most of
-the functions keep the same name just as on the CPU, with the difference that they only accept
-*GpuMat* inputs. A full list of these you will find in the documentation: `online here
-<http://docs.opencv.org/modules/gpu/doc/gpu.html>`_ or the OpenCV reference manual that comes with
-the source code.
-
-Another thing to keep in mind is that not for all channel numbers you can make efficient algorithms
-on the GPU. Generally, I found that the input images for the GPU images need to be either one or
-four channel ones and one of the char or float type for the item sizes. No double support on the
-GPU, sorry. Passing other types of objects for some functions will result in an exception thrown,
-and an error message on the error output. The documentation details in most of the places the types
-accepted for the inputs. If you have three channel images as an input you can do two things: either
-adds a new channel (and use char elements) or split up the image and call the function for each
-image. The first one isn't really recommended as you waste memory.
-
-For some functions, where the position of the elements (neighbor items) doesn't matter quick
-solution is to just reshape it into a single channel image. This is the case for the PSNR
-implementation where for the *absdiff* method the value of the neighbors is not important. However,
-for the *GaussianBlur* this isn't an option and such need to use the split method for the SSIM. With
-this knowledge you can already make a GPU viable code (like mine GPU one) and run it. You'll be
-surprised to see that it might turn out slower than your CPU implementation.
-
-Optimization
-============
-
-The reason for this is that you're throwing out on the window the price for memory allocation and
-data transfer. And on the GPU this is damn high. Another possibility for optimization is to
-introduce asynchronous OpenCV GPU calls too with the help of the
-:gpudatastructure:`gpu::Stream<gpu-stream>`.
-
-1. Memory allocation on the GPU is considerable. Therefore, if it’s possible allocate new memory as
- few times as possible. If you create a function what you intend to call multiple times it is a
- good idea to allocate any local parameters for the function only once, during the first call.
- To do this you create a data structure containing all the local variables you will use. For
- instance in case of the PSNR these are:
-
- .. code-block:: cpp
-
- struct BufferPSNR // Optimized GPU versions
- { // Data allocations are very expensive on GPU. Use a buffer to solve: allocate once reuse later.
- gpu::GpuMat gI1, gI2, gs, t1,t2;
-
- gpu::GpuMat buf;
- };
-
- Then create an instance of this in the main program:
-
- .. code-block:: cpp
-
- BufferPSNR bufferPSNR;
-
- And finally pass this to the function each time you call it:
-
- .. code-block:: cpp
-
- double getPSNR_GPU_optimized(const Mat& I1, const Mat& I2, BufferPSNR& b)
-
- Now you access these local parameters as: *b.gI1*, *b.buf* and so on. The GpuMat will only
- reallocate itself on a new call if the new matrix size is different from the previous one.
-
-#. Avoid unnecessary function data transfers. Any small data transfer will be significant one once
- you go to the GPU. Therefore, if possible make all calculations in-place (in other words do not
- create new memory objects - for reasons explained at the previous point). For example, although
- expressing arithmetical operations may be easier to express in one line formulas, it will be
- slower. In case of the SSIM at one point I need to calculate:
-
- .. code-block:: cpp
-
- b.t1 = 2 * b.mu1_mu2 + C1;
-
- Although the upper call will succeed observe that there is a hidden data transfer present. Before
- it makes the addition it needs to store somewhere the multiplication. Therefore, it will create a
- local matrix in the background, add to that the *C1* value and finally assign that to *t1*. To
- avoid this we use the gpu functions, instead of the arithmetic operators:
-
- .. code-block:: cpp
-
- gpu::multiply(b.mu1_mu2, 2, b.t1); //b.t1 = 2 * b.mu1_mu2 + C1;
- gpu::add(b.t1, C1, b.t1);
-
-#. Use asynchronous calls (the :gpudatastructure:`gpu::Stream <gpu-stream>`). By default whenever
- you call a gpu function it will wait for the call to finish and return with the result
- afterwards. However, it is possible to make asynchronous calls, meaning it will call for the
- operation execution, make the costly data allocations for the algorithm and return back right
- away. Now you can call another function if you wish to do so. For the MSSIM this is a small
- optimization point. In our default implementation we split up the image into channels and call
- then for each channel the gpu functions. A small degree of parallelization is possible with the
- stream. By using a stream we can make the data allocation, upload operations while the GPU is
- already executing a given method. For example we need to upload two images. We queue these one
- after another and call already the function that processes it. The functions will wait for the
- upload to finish, however while that happens makes the output buffer allocations for the function
- to be executed next.
-
- .. code-block:: cpp
-
- gpu::Stream stream;
-
- stream.enqueueConvert(b.gI1, b.t1, CV_32F); // Upload
-
- gpu::split(b.t1, b.vI1, stream); // Methods (pass the stream as final parameter).
- gpu::multiply(b.vI1[i], b.vI1[i], b.I1_2, stream); // I1^2
-
-Result and conclusion
-=====================
-
-On an Intel P8700 laptop CPU paired with a low end NVidia GT220M here are the performance numbers:
-
-.. code-block:: cpp
-
- Time of PSNR CPU (averaged for 10 runs): 41.4122 milliseconds. With result of: 19.2506
- Time of PSNR GPU (averaged for 10 runs): 158.977 milliseconds. With result of: 19.2506
- Initial call GPU optimized: 31.3418 milliseconds. With result of: 19.2506
- Time of PSNR GPU OPTIMIZED ( / 10 runs): 24.8171 milliseconds. With result of: 19.2506
-
- Time of MSSIM CPU (averaged for 10 runs): 484.343 milliseconds. With result of B0.890964 G0.903845 R0.936934
- Time of MSSIM GPU (averaged for 10 runs): 745.105 milliseconds. With result of B0.89922 G0.909051 R0.968223
- Time of MSSIM GPU Initial Call 357.746 milliseconds. With result of B0.890964 G0.903845 R0.936934
- Time of MSSIM GPU OPTIMIZED ( / 10 runs): 203.091 milliseconds. With result of B0.890964 G0.903845 R0.936934
-
-In both cases we managed a performance increase of almost 100% compared to the CPU implementation.
-It may be just the improvement needed for your application to work. You may observe a runtime
-instance of this on the `YouTube here <https://www.youtube.com/watch?v=3_ESXmFlnvY>`_.
-
-.. raw:: html
-
- <div align="center">
- <iframe title="Similarity check (PNSR and SSIM) on the GPU" width="560" height="349" src="http://www.youtube.com/embed/3_ESXmFlnvY?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _Table-Of-Content-GPU:
-
-*gpu* module. GPU-Accelerated Computer Vision
----------------------------------------------
-
-Squeeze out every little computation power from your system by using the power of your video card to run the OpenCV algorithms.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |hVideoWrite| *Title:* :ref:`gpuBasicsSimilarity`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- This will give a good grasp on how to approach coding on the GPU module, once you already know how to handle the other modules. As a test case it will port the similarity methods from the tutorial :ref:`videoInputPSNRMSSIM` to the GPU.
-
- =============== ======================================================
-
- .. |hVideoWrite| image:: images/gpu-basics-similarity.png
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../gpu-basics-similarity/gpu-basics-similarity
+++ /dev/null
-.. _Raster_IO_GDAL:
-
-
-Reading Geospatial Raster files with GDAL
-*****************************************
-
-Geospatial raster data is a heavily used product in Geographic Information
-Systems and Photogrammetry. Raster data typically can represent imagery
-and Digital Elevation Models (DEM). The standard library for loading
-GIS imagery is the Geographic Data Abstraction Library (GDAL). In this example, we
-will show techniques for loading GIS raster formats using native OpenCV functions.
-In addition, we will show some an example of how OpenCV can use this data for
-novel and interesting purposes.
-
-Goals
-=====
-
-The primary objectives for this tutorial:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + How to use OpenCV imread to load satellite imagery.
- + How to use OpenCV imread to load SRTM Digital Elevation Models
- + Given the corner coordinates of both the image and DEM, correllate the elevation data to the image to find elevations for each pixel.
- + Show a basic, easy-to-implement example of a terrain heat map.
- + Show a basic use of DEM data coupled with ortho-rectified imagery.
-
-To implement these goals, the following code takes a Digital Elevation Model as well as a GeoTiff image of San Francisco as input.
-The image and DEM data is processed and generates a terrain heat map of the image as well as labels areas of the city which would
-be affected should the water level of the bay rise 10, 50, and 100 meters.
-
-Code
-====
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/HighGUI/GDAL_IO/gdal-image.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
-
-
-How to Read Raster Data using GDAL
-======================================
-
-This demonstration uses the default OpenCV :ocv:func:`imread` function. The primary difference is that in order to force GDAL to load the
-image, you must use the appropriate flag.
-
-.. code-block:: cpp
-
- cv::Mat image = cv::imread( argv[1], cv::IMREAD_LOAD_GDAL );
-
-When loading digital elevation models, the actual numeric value of each pixel is essential
-and cannot be scaled or truncated. For example, with image data a pixel represented as a double with a value of 1 has
-an equal appearance to a pixel which is represented as an unsigned character with a value of 255.
-With terrain data, the pixel value represents the elevation in meters. In order to ensure that OpenCV preserves the native value,
-use the GDAL flag in imread with the ANYDEPTH flag.
-
-.. code-block:: cpp
-
- cv::Mat dem = cv::imread( argv[2], cv::IMREAD_LOAD_GDAL | cv::IMREAD_ANYDEPTH );
-
-
-If you know beforehand the type of DEM model you are loading, then it may be a safe bet to test the ``Mat::type()`` or ``Mat::depth()``
-using an assert or other mechanism. NASA or DOD specification documents can provide the input types for various
-elevation models. The major types, SRTM and DTED, are both signed shorts.
-
-Notes
-=====
-
-Lat/Lon (Geodetic) Coordinates should normally be avoided
----------------------------------------------------------
-
-The Geodetic Coordinate System is a spherical coordinate system, meaning that using them with Cartesian mathematics is technically incorrect. This
-demo uses them to increase the readability and is accurate enough to make the point. A better coordinate system would be Universal Transverse Mercator.
-
-Finding the corner coordinates
-------------------------------
-
-One easy method to find the corner coordinates of an image is to use the command-line tool ``gdalinfo``. For imagery which is ortho-rectified and contains
-the projection information, you can use the `USGS EarthExplorer <http://http://earthexplorer.usgs.gov>`_.
-
-.. code-block:: bash
-
- $> gdalinfo N37W123.hgt
-
- Driver: SRTMHGT/SRTMHGT File Format
- Files: N37W123.hgt
- Size is 3601, 3601
- Coordinate System is:
- GEOGCS["WGS 84",
- DATUM["WGS_1984",
-
- ... more output ...
-
- Corner Coordinates:
- Upper Left (-123.0001389, 38.0001389) (123d 0' 0.50"W, 38d 0' 0.50"N)
- Lower Left (-123.0001389, 36.9998611) (123d 0' 0.50"W, 36d59'59.50"N)
- Upper Right (-121.9998611, 38.0001389) (121d59'59.50"W, 38d 0' 0.50"N)
- Lower Right (-121.9998611, 36.9998611) (121d59'59.50"W, 36d59'59.50"N)
- Center (-122.5000000, 37.5000000) (122d30' 0.00"W, 37d30' 0.00"N)
-
- ... more output ...
-
-
-Results
-=======
-
-Below is the output of the program. Use the first image as the input. For the DEM model, download the SRTM file located at the USGS here. `http://dds.cr.usgs.gov/srtm/version2_1/SRTM1/Region_04/N37W123.hgt.zip <http://dds.cr.usgs.gov/srtm/version2_1/SRTM1/Region_04/N37W123.hgt.zip>`_
-
-.. image:: images/gdal_output.jpg
-
-.. image:: images/gdal_heat-map.jpg
-
-.. image:: images/gdal_flood-zone.jpg
+++ /dev/null
-.. _Table-Of-Content-HighGui:
-
-*highgui* module. High Level GUI and Media
-------------------------------------------
-
-This section contains valuable tutorials about how to read/save your image/video files and how to use the built-in graphical user interface of the library.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |Beginners_5| *Title:* :ref:`Adding_Trackbars`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will learn how to add a Trackbar to our applications
-
- =============== ======================================================
-
- .. |Beginners_5| image:: images/Adding_Trackbars_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |hVideoInput| *Title:* :ref:`videoInputPSNRMSSIM`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- You will learn how to read video streams, and how to calculate similarity values such as PSNR or SSIM.
-
- =============== ======================================================
-
- .. |hVideoInput| image:: images/video-input-psnr-ssim.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |hVideoWrite| *Title:* :ref:`videoWriteHighGui`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- Whenever you work with video feeds you may eventually want to save your image processing result in a form of a new video file. Here's how to do it.
-
- =============== ======================================================
-
- .. |hVideoWrite| image:: images/video-write.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |hGDAL_IO| *Title:* :ref:`Raster_IO_GDAL`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_MarvinS|
-
- Read common GIS Raster and DEM files to display and manipulate geographic data.
-
- =============== ======================================================
-
- .. |hGDAL_IO| image:: images/gdal-io.jpg
- :height: 90pt
- :width: 90pt
-
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../trackbar/trackbar
- ../video-input-psnr-ssim/video-input-psnr-ssim
- ../video-write/video-write
- ../raster-gdal/raster_io_gdal
+++ /dev/null
-.. _Adding_Trackbars:
-
-Adding a Trackbar to our applications!
-***************************************
-
-* In the previous tutorials (about *linear blending* and the *brightness and contrast adjustments*) you might have noted that we needed to give some **input** to our programs, such as :math:`\alpha` and :math:`beta`. We accomplished that by entering this data using the Terminal
-
-* Well, it is time to use some fancy GUI tools. OpenCV provides some GUI utilities (*highgui.h*) for you. An example of this is a **Trackbar**
-
- .. image:: images/Adding_Trackbars_Tutorial_Trackbar.png
- :alt: Trackbar example
- :align: center
-
-* In this tutorial we will just modify our two previous programs so that they get the input information from the trackbar.
-
-
-Goals
-======
-
-In this tutorial you will learn how to:
-
-* Add a Trackbar in an OpenCV window by using :create_trackbar:`createTrackbar <>`
-
-Code
-=====
-
-Let's modify the program made in the tutorial :ref:`Adding_Images`. We will let the user enter the :math:`\alpha` value by using the Trackbar.
-
-.. code-block:: cpp
-
- #include <opencv2/opencv.hpp>
- using namespace cv;
-
- /// Global Variables
- const int alpha_slider_max = 100;
- int alpha_slider;
- double alpha;
- double beta;
-
- /// Matrices to store images
- Mat src1;
- Mat src2;
- Mat dst;
-
- /*
- * @function on_trackbar
- * @brief Callback for trackbar
- */
- void on_trackbar( int, void* )
- {
- alpha = (double) alpha_slider/alpha_slider_max ;
- beta = ( 1.0 - alpha );
-
- addWeighted( src1, alpha, src2, beta, 0.0, dst);
-
- imshow( "Linear Blend", dst );
- }
-
- int main( int argc, char** argv )
- {
- /// Read image ( same size, same type )
- src1 = imread("../../images/LinuxLogo.jpg");
- src2 = imread("../../images/WindowsLogo.jpg");
-
- if( !src1.data ) { printf("Error loading src1 \n"); return -1; }
- if( !src2.data ) { printf("Error loading src2 \n"); return -1; }
-
- /// Initialize values
- alpha_slider = 0;
-
- /// Create Windows
- namedWindow("Linear Blend", 1);
-
- /// Create Trackbars
- char TrackbarName[50];
- sprintf( TrackbarName, "Alpha x %d", alpha_slider_max );
-
- createTrackbar( TrackbarName, "Linear Blend", &alpha_slider, alpha_slider_max, on_trackbar );
-
- /// Show some stuff
- on_trackbar( alpha_slider, 0 );
-
- /// Wait until user press some key
- waitKey(0);
- return 0;
- }
-
-
-Explanation
-============
-
-We only analyze the code that is related to Trackbar:
-
-#. First, we load 02 images, which are going to be blended.
-
- .. code-block:: cpp
-
- src1 = imread("../../images/LinuxLogo.jpg");
- src2 = imread("../../images/WindowsLogo.jpg");
-
-#. To create a trackbar, first we have to create the window in which it is going to be located. So:
-
- .. code-block:: cpp
-
- namedWindow("Linear Blend", 1);
-
-#. Now we can create the Trackbar:
-
- .. code-block:: cpp
-
- createTrackbar( TrackbarName, "Linear Blend", &alpha_slider, alpha_slider_max, on_trackbar );
-
- Note the following:
-
- * Our Trackbar has a label **TrackbarName**
- * The Trackbar is located in the window named **"Linear Blend"**
- * The Trackbar values will be in the range from :math:`0` to **alpha_slider_max** (the minimum limit is always **zero**).
- * The numerical value of Trackbar is stored in **alpha_slider**
- * Whenever the user moves the Trackbar, the callback function **on_trackbar** is called
-
-#. Finally, we have to define the callback function **on_trackbar**
-
- .. code-block:: cpp
-
- void on_trackbar( int, void* )
- {
- alpha = (double) alpha_slider/alpha_slider_max ;
- beta = ( 1.0 - alpha );
-
- addWeighted( src1, alpha, src2, beta, 0.0, dst);
-
- imshow( "Linear Blend", dst );
- }
-
- Note that:
-
- * We use the value of **alpha_slider** (integer) to get a double value for **alpha**.
- * **alpha_slider** is updated each time the trackbar is displaced by the user.
- * We define *src1*, *src2*, *dist*, *alpha*, *alpha_slider* and *beta* as global variables, so they can be used everywhere.
-
-Result
-=======
-
-* Our program produces the following output:
-
- .. image:: images/Adding_Trackbars_Tutorial_Result_0.jpg
- :alt: Adding Trackbars - Windows Linux
- :align: center
-
-* As a manner of practice, you can also add 02 trackbars for the program made in :ref:`Basic_Linear_Transform`. One trackbar to set :math:`\alpha` and another for :math:`\beta`. The output might look like:
-
- .. image:: images/Adding_Trackbars_Tutorial_Result_1.jpg
- :alt: Adding Trackbars - Lena
- :align: center
+++ /dev/null
-.. _videoInputPSNRMSSIM:
-
-Video Input with OpenCV and similarity measurement
-**************************************************
-
-Goal
-====
-
-Today it is common to have a digital video recording system at your disposal. Therefore, you will eventually come to the situation that you no longer process a batch of images, but video streams. These may be of two kinds: real-time image feed (in the case of a webcam) or prerecorded and hard disk drive stored files. Luckily OpenCV threats these two in the same manner, with the same C++ class. So here's what you'll learn in this tutorial:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + How to open and read video streams
- + Two ways for checking image similarity: PSNR and SSIM
-
-The source code
-===============
-
-As a test case where to show off these using OpenCV I've created a small program that reads in two video files and performs a similarity check between them. This is something you could use to check just how well a new video compressing algorithms works. Let there be a reference (original) video like :download:`this small Megamind clip <../../../../samples/cpp/tutorial_code/HighGUI/video-input-psnr-ssim/video/Megamind.avi>` and :download:`a compressed version of it <../../../../samples/cpp/tutorial_code/HighGUI/video-input-psnr-ssim/video/Megamind_bugy.avi>`. You may also find the source code and these video file in the :file:`samples/cpp/tutorial_code/HighGUI/video-input-psnr-ssim/` folder of the OpenCV source library.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/HighGUI/video-input-psnr-ssim/video-input-psnr-ssim.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 1-15, 29-31, 33-208
-
-How to read a video stream (online-camera or offline-file)?
-===========================================================
-
-Essentially, all the functionalities required for video manipulation is integrated in the :hgvideo:`VideoCapture <videocapture>` C++ class. This on itself builds on the FFmpeg open source library. This is a basic dependency of OpenCV so you shouldn't need to worry about this. A video is composed of a succession of images, we refer to these in the literature as frames. In case of a video file there is a *frame rate* specifying just how long is between two frames. While for the video cameras usually there is a limit of just how many frames they can digitalize per second, this property is less important as at any time the camera sees the current snapshot of the world.
-
-The first task you need to do is to assign to a :hgvideo:`VideoCapture <videocapture>` class its source. You can do this either via the :hgvideo:`constructor <videocapture-videocapture>` or its :hgvideo:`open <videocapture-open>` function. If this argument is an integer then you will bind the class to a camera, a device. The number passed here is the ID of the device, assigned by the operating system. If you have a single camera attached to your system its ID will probably be zero and further ones increasing from there. If the parameter passed to these is a string it will refer to a video file, and the string points to the location and name of the file. For example, to the upper source code a valid command line is:
-
-.. code-block:: bash
-
- video/Megamind.avi video/Megamind_bug.avi 35 10
-
-We do a similarity check. This requires a reference and a test case video file. The first two arguments refer to this. Here we use a relative address. This means that the application will look into its current working directory and open the video folder and try to find inside this the *Megamind.avi* and the *Megamind_bug.avi*.
-
-.. code-block:: cpp
-
- const string sourceReference = argv[1],sourceCompareWith = argv[2];
-
- VideoCapture captRefrnc(sourceReference);
- // or
- VideoCapture captUndTst;
- captUndTst.open(sourceCompareWith);
-
-To check if the binding of the class to a video source was successful or not use the :hgvideo:`isOpened <video-isopened>` function:
-
-.. code-block:: cpp
-
- if ( !captRefrnc.isOpened())
- {
- cout << "Could not open reference " << sourceReference << endl;
- return -1;
- }
-
-Closing the video is automatic when the objects destructor is called. However, if you want to close it before this you need to call its :hgvideo:`release <videocapture-release>` function. The frames of the video are just simple images. Therefore, we just need to extract them from the :hgvideo:`VideoCapture <videocapture>` object and put them inside a *Mat* one. The video streams are sequential. You may get the frames one after another by the :hgvideo:`read <videocapture-read>` or the overloaded >> operator:
-
-.. code-block:: cpp
-
- Mat frameReference, frameUnderTest;
- captRefrnc >> frameReference;
- captUndTst.open(frameUnderTest);
-
-The upper read operations will leave empty the *Mat* objects if no frame could be acquired (either cause the video stream was closed or you got to the end of the video file). We can check this with a simple if:
-
-.. code-block:: cpp
-
- if( frameReference.empty() || frameUnderTest.empty())
- {
- // exit the program
- }
-
-A read method is made of a frame grab and a decoding applied on that. You may call explicitly these two by using the :hgvideo:`grab <videocapture-grab>` and then the :hgvideo:`retrieve <videocapture-retrieve>` functions.
-
-Videos have many-many information attached to them besides the content of the frames. These are usually numbers, however in some case it may be short character sequences (4 bytes or less). Due to this to acquire these information there is a general function named :hgvideo:`get <videocapture-get>` that returns double values containing these properties. Use bitwise operations to decode the characters from a double type and conversions where valid values are only integers. Its single argument is the ID of the queried property. For example, here we get the size of the frames in the reference and test case video file; plus the number of frames inside the reference.
-
-.. code-block:: cpp
-
- Size refS = Size((int) captRefrnc.get(CAP_PROP_FRAME_WIDTH),
- (int) captRefrnc.get(CAP_PROP_FRAME_HEIGHT)),
-
- cout << "Reference frame resolution: Width=" << refS.width << " Height=" << refS.height
- << " of nr#: " << captRefrnc.get(CAP_PROP_FRAME_COUNT) << endl;
-
-When you are working with videos you may often want to control these values yourself. To do this there is a :hgvideo:`set <videocapture-set>` function. Its first argument remains the name of the property you want to change and there is a second of double type containing the value to be set. It will return true if it succeeds and false otherwise. Good examples for this is seeking in a video file to a given time or frame:
-
-.. code-block:: cpp
-
- captRefrnc.set(CAP_PROP_POS_MSEC, 1.2); // go to the 1.2 second in the video
- captRefrnc.set(CAP_PROP_POS_FRAMES, 10); // go to the 10th frame of the video
- // now a read operation would read the frame at the set position
-
-For properties you can read and change look into the documentation of the :hgvideo:`get <videocapture-get>` and :hgvideo:`set <videocapture-set>` functions.
-
-
-Image similarity - PSNR and SSIM
-================================
-
-We want to check just how imperceptible our video converting operation went, therefore we need a system to check frame by frame the similarity or differences. The most common algorithm used for this is the PSNR (aka **Peak signal-to-noise ratio**). The simplest definition of this starts out from the *mean squad error*. Let there be two images: I1 and I2; with a two dimensional size i and j, composed of c number of channels.
-
-.. math::
-
- MSE = \frac{1}{c*i*j} \sum{(I_1-I_2)^2}
-
-Then the PSNR is expressed as:
-
-.. math::
-
- PSNR = 10 \cdot \log_{10} \left( \frac{MAX_I^2}{MSE} \right)
-
-Here the :math:`MAX_I^2` is the maximum valid value for a pixel. In case of the simple single byte image per pixel per channel this is 255. When two images are the same the MSE will give zero, resulting in an invalid divide by zero operation in the PSNR formula. In this case the PSNR is undefined and as we'll need to handle this case separately. The transition to a logarithmic scale is made because the pixel values have a very wide dynamic range. All this translated to OpenCV and a C++ function looks like:
-
-.. code-block:: cpp
-
- double getPSNR(const Mat& I1, const Mat& I2)
- {
- Mat s1;
- absdiff(I1, I2, s1); // |I1 - I2|
- s1.convertTo(s1, CV_32F); // cannot make a square on 8 bits
- s1 = s1.mul(s1); // |I1 - I2|^2
-
- Scalar s = sum(s1); // sum elements per channel
-
- double sse = s.val[0] + s.val[1] + s.val[2]; // sum channels
-
- if( sse <= 1e-10) // for small values return zero
- return 0;
- else
- {
- double mse =sse /(double)(I1.channels() * I1.total());
- double psnr = 10.0*log10((255*255)/mse);
- return psnr;
- }
- }
-
-Typically result values are anywhere between 30 and 50 for video compression, where higher is better. If the images significantly differ you'll get much lower ones like 15 and so. This similarity check is easy and fast to calculate, however in practice it may turn out somewhat inconsistent with human eye perception. The **structural similarity** algorithm aims to correct this.
-
-Describing the methods goes well beyond the purpose of this tutorial. For that I invite you to read the article introducing it. Nevertheless, you can get a good image of it by looking at the OpenCV implementation below.
-
-.. seealso::
-
- SSIM is described more in-depth in the: "Z. Wang, A. C. Bovik, H. R. Sheikh and E. P. Simoncelli, "Image quality assessment: From error visibility to structural similarity," IEEE Transactions on Image Processing, vol. 13, no. 4, pp. 600-612, Apr. 2004." article.
-
-.. code-block:: cpp
-
- Scalar getMSSIM( const Mat& i1, const Mat& i2)
- {
- const double C1 = 6.5025, C2 = 58.5225;
- /***************************** INITS **********************************/
- int d = CV_32F;
-
- Mat I1, I2;
- i1.convertTo(I1, d); // cannot calculate on one byte large values
- i2.convertTo(I2, d);
-
- Mat I2_2 = I2.mul(I2); // I2^2
- Mat I1_2 = I1.mul(I1); // I1^2
- Mat I1_I2 = I1.mul(I2); // I1 * I2
-
- /***********************PRELIMINARY COMPUTING ******************************/
-
- Mat mu1, mu2; //
- GaussianBlur(I1, mu1, Size(11, 11), 1.5);
- GaussianBlur(I2, mu2, Size(11, 11), 1.5);
-
- Mat mu1_2 = mu1.mul(mu1);
- Mat mu2_2 = mu2.mul(mu2);
- Mat mu1_mu2 = mu1.mul(mu2);
-
- Mat sigma1_2, sigma2_2, sigma12;
-
- GaussianBlur(I1_2, sigma1_2, Size(11, 11), 1.5);
- sigma1_2 -= mu1_2;
-
- GaussianBlur(I2_2, sigma2_2, Size(11, 11), 1.5);
- sigma2_2 -= mu2_2;
-
- GaussianBlur(I1_I2, sigma12, Size(11, 11), 1.5);
- sigma12 -= mu1_mu2;
-
- ///////////////////////////////// FORMULA ////////////////////////////////
- Mat t1, t2, t3;
-
- t1 = 2 * mu1_mu2 + C1;
- t2 = 2 * sigma12 + C2;
- t3 = t1.mul(t2); // t3 = ((2*mu1_mu2 + C1).*(2*sigma12 + C2))
-
- t1 = mu1_2 + mu2_2 + C1;
- t2 = sigma1_2 + sigma2_2 + C2;
- t1 = t1.mul(t2); // t1 =((mu1_2 + mu2_2 + C1).*(sigma1_2 + sigma2_2 + C2))
-
- Mat ssim_map;
- divide(t3, t1, ssim_map); // ssim_map = t3./t1;
-
- Scalar mssim = mean( ssim_map ); // mssim = average of ssim map
- return mssim;
- }
-
-This will return a similarity index for each channel of the image. This value is between zero and one, where one corresponds to perfect fit. Unfortunately, the many Gaussian blurring is quite costly, so while the PSNR may work in a real time like environment (24 frame per second) this will take significantly more than to accomplish similar performance results.
-
-Therefore, the source code presented at the start of the tutorial will perform the PSNR measurement for each frame, and the SSIM only for the frames where the PSNR falls below an input value. For visualization purpose we show both images in an OpenCV window and print the PSNR and MSSIM values to the console. Expect to see something like:
-
-.. image:: images/outputVideoInput.png
- :alt: A sample output
- :align: center
-
-You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=iOcNljutOgg>`_.
-
-.. raw:: html
-
- <div align="center">
- <iframe title="Video Input with OpenCV (Plus PSNR and MSSIM)" width="560" height="349" src="http://www.youtube.com/embed/iOcNljutOgg?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _videoWriteHighGui:
-
-Creating a video with OpenCV
-****************************
-
-Goal
-====
-
-Whenever you work with video feeds you may eventually want to save your image processing result in a form of a new video file. For simple video outputs you can use the OpenCV built-in :hgvideo:`VideoWriter <videowriter-videowriter>` class, designed for this.
-
-.. container:: enumeratevisibleitemswithsquare
-
- + How to create a video file with OpenCV
- + What type of video files you can create with OpenCV
- + How to extract a given color channel from a video
-
-As a simple demonstration I'll just extract one of the RGB color channels of an input video file into a new video. You can control the flow of the application from its console line arguments:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + The first argument points to the video file to work on
- + The second argument may be one of the characters: R G B. This will specify which of the channels to extract.
- + The last argument is the character Y (Yes) or N (No). If this is no, the codec used for the input video file will be the same as for the output. Otherwise, a window will pop up and allow you to select yourself the codec to use.
-
-For example, a valid command line would look like:
-
-.. code-block:: bash
-
- video-write.exe video/Megamind.avi R Y
-
-The source code
-===============
-You may also find the source code and these video file in the :file:`samples/cpp/tutorial_code/highgui/video-write/` folder of the OpenCV source library or :download:`download it from here <../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp>`.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
-
-The structure of a video
-========================
-For start, you should have an idea of just how a video file looks. Every video file in itself is a container. The type of the container is expressed in the files extension (for example *avi*, *mov* or *mkv*). This contains multiple elements like: video feeds, audio feeds or other tracks (like for example subtitles). How these feeds are stored is determined by the codec used for each one of them. In case of the audio tracks commonly used codecs are *mp3* or *aac*. For the video files the list is somehow longer and includes names such as *XVID*, *DIVX*, *H264* or *LAGS* (*Lagarith Lossless Codec*). The full list of codecs you may use on a system depends on just what one you have installed.
-
-.. image:: images/videoFileStructure.png
- :alt: The Structure of the video
- :align: center
-
-As you can see things can get really complicated with videos. However, OpenCV is mainly a computer vision library, not a video stream, codec and write one. Therefore, the developers tried to keep this part as simple as possible. Due to this OpenCV for video containers supports only the *avi* extension, its first version. A direct limitation of this is that you cannot save a video file larger than 2 GB. Furthermore you can only create and expand a single video track inside the container. No audio or other track editing support here. Nevertheless, any video codec present on your system might work. If you encounter some of these limitations you will need to look into more specialized video writing libraries such as *FFMpeg* or codecs as *HuffYUV*, *CorePNG* and *LCL*. As an alternative, create the video track with OpenCV and expand it with sound tracks or convert it to other formats by using video manipulation programs such as *VirtualDub* or *AviSynth*.
-The *VideoWriter* class
-=======================
-The content written here builds on the assumption you already read the :ref:`videoInputPSNRMSSIM` tutorial and you know how to read video files.
-To create a video file you just need to create an instance of the :hgvideo:`VideoWriter <videowriter-videowriter>` class. You can specify its properties either via parameters in the constructor or later on via the :hgvideo:`open <videowriter-open>` function. Either way, the parameters are the same:
-1. The name of the output that contains the container type in its extension. At the moment only *avi* is supported. We construct this from the input file, add to this the name of the channel to use, and finish it off with the container extension.
-
- .. code-block:: cpp
-
- const string source = argv[1]; // the source file name
- string::size_type pAt = source.find_last_of('.'); // Find extension point
- const string NAME = source.substr(0, pAt) + argv[2][0] + ".avi"; // Form the new name with container
-
-#. The codec to use for the video track. Now all the video codecs have a unique short name of maximum four characters. Hence, the *XVID*, *DIVX* or *H264* names. This is called a four character code. You may also ask this from an input video by using its *get* function. Because the *get* function is a general function it always returns double values. A double value is stored on 64 bits. Four characters are four bytes, meaning 32 bits. These four characters are coded in the lower 32 bits of the *double*. A simple way to throw away the upper 32 bits would be to just convert this value to *int*:
-
- .. code-block:: cpp
-
- VideoCapture inputVideo(source); // Open input
- int ex = static_cast<int>(inputVideo.get(CAP_PROP_FOURCC)); // Get Codec Type- Int form
-
- OpenCV internally works with this integer type and expect this as its second parameter. Now to convert from the integer form to string we may use two methods: a bitwise operator and a union method. The first one extracting from an int the characters looks like (an "and" operation, some shifting and adding a 0 at the end to close the string):
-
- .. code-block:: cpp
-
- char EXT[] = {ex & 0XFF , (ex & 0XFF00) >> 8,(ex & 0XFF0000) >> 16,(ex & 0XFF000000) >> 24, 0};
-
- You can do the same thing with the *union* as:
-
- .. code-block:: cpp
-
- union { int v; char c[5];} uEx ;
- uEx.v = ex; // From Int to char via union
- uEx.c[4]='\0';
-
- The advantage of this is that the conversion is done automatically after assigning, while for the bitwise operator you need to do the operations whenever you change the codec type. In case you know the codecs four character code beforehand, you can use the *CV_FOURCC* macro to build the integer:
-
- .. code-block::cpp
-
- CV_FOURCC('P','I','M,'1') // this is an MPEG1 codec from the characters to integer
-
- If you pass for this argument minus one than a window will pop up at runtime that contains all the codec installed on your system and ask you to select the one to use:
-
- .. image:: images/videoCompressSelect.png
- :alt: Select the codec type to use
- :align: center
-
-#. The frame per second for the output video. Again, here I keep the input videos frame per second by using the *get* function.
-#. The size of the frames for the output video. Here too I keep the input videos frame size per second by using the *get* function.
-#. The final argument is an optional one. By default is true and says that the output will be a colorful one (so for write you will send three channel images). To create a gray scale video pass a false parameter here.
-
-Here it is, how I use it in the sample:
-
- .. code-block:: cpp
-
- VideoWriter outputVideo;
- Size S = Size((int) inputVideo.get(CAP_PROP_FRAME_WIDTH), //Acquire input size
- (int) inputVideo.get(CAP_PROP_FRAME_HEIGHT));
- outputVideo.open(NAME , ex, inputVideo.get(CAP_PROP_FPS),S, true);
-
-Afterwards, you use the :hgvideo:`isOpened() <videowriter-isopened>` function to find out if the open operation succeeded or not. The video file automatically closes when the *VideoWriter* object is destroyed. After you open the object with success you can send the frames of the video in a sequential order by using the :hgvideo:`write<videowriter-write>` function of the class. Alternatively, you can use its overloaded operator << :
-
-.. code-block:: cpp
-
- outputVideo.write(res); //or
- outputVideo << res;
-
-Extracting a color channel from an RGB image means to set to zero the RGB values of the other channels. You can either do this with image scanning operations or by using the split and merge operations. You first split the channels up into different images, set the other channels to zero images of the same size and type and finally merge them back:
-
-.. code-block:: cpp
-
- split(src, spl); // process - extract only the correct channel
- for( int i =0; i < 3; ++i)
- if (i != channel)
- spl[i] = Mat::zeros(S, spl[0].type());
- merge(spl, res);
-
-Put all this together and you'll get the upper source code, whose runtime result will show something around the idea:
-
-.. image:: images/resultOutputWideoWrite.png
- :alt: A sample output
- :align: center
-
-You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=jpBwHxsl1_0>`_.
-
-.. raw:: html
-
- <div align="center">
- <iframe title="Creating a video with OpenCV" width="560" height="349" src="http://www.youtube.com/embed/jpBwHxsl1_0?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _Morphology_1:
-
-Eroding and Dilating
-**********************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-* Apply two very common morphology operators: Dilation and Erosion. For this purpose, you will use the following OpenCV functions:
-
- * :erode:`erode <>`
- * :dilate:`dilate <>`
-
-Cool Theory
-============
-
-.. note::
- The explanation below belongs to the book **Learning OpenCV** by Bradski and Kaehler.
-
-Morphological Operations
---------------------------
-
-* In short: A set of operations that process images based on shapes. Morphological operations apply a *structuring element* to an input image and generate an output image.
-
-* The most basic morphological operations are two: Erosion and Dilation. They have a wide array of uses, i.e. :
-
- * Removing noise
-
- * Isolation of individual elements and joining disparate elements in an image.
-
- * Finding of intensity bumps or holes in an image
-
-* We will explain dilation and erosion briefly, using the following image as an example:
-
- .. image:: images/Morphology_1_Tutorial_Theory_Original_Image.png
- :alt: Original image
- :align: center
-
-Dilation
-~~~~~~~~
-
-* This operations consists of convoluting an image :math:`A` with some kernel (:math:`B`), which can have any shape or size, usually a square or circle.
-
-* The kernel :math:`B` has a defined *anchor point*, usually being the center of the kernel.
-
-* As the kernel :math:`B` is scanned over the image, we compute the maximal pixel value overlapped by :math:`B` and replace the image pixel in the anchor point position with that maximal value. As you can deduce, this maximizing operation causes bright regions within an image to "grow" (therefore the name *dilation*). Take as an example the image above. Applying dilation we can get:
-
- .. image:: images/Morphology_1_Tutorial_Theory_Dilation.png
- :alt: Dilation result - Theory example
- :align: center
-
-The background (bright) dilates around the black regions of the letter.
-
-Erosion
-~~~~~~~
-
-* This operation is the sister of dilation. What this does is to compute a local minimum over the area of the kernel.
-
-* As the kernel :math:`B` is scanned over the image, we compute the minimal pixel value overlapped by :math:`B` and replace the image pixel under the anchor point with that minimal value.
-
-* Analagously to the example for dilation, we can apply the erosion operator to the original image (shown above). You can see in the result below that the bright areas of the image (the background, apparently), get thinner, whereas the dark zones (the "writing") gets bigger.
-
- .. image:: images/Morphology_1_Tutorial_Theory_Erosion.png
- :alt: Erosion result - Theory example
- :align: center
-
-
-Code
-======
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgProc/Morphology_1.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
- #include "highgui.h"
- #include <stdlib.h>
- #include <stdio.h>
-
- using namespace cv;
-
- /// Global variables
- Mat src, erosion_dst, dilation_dst;
-
- int erosion_elem = 0;
- int erosion_size = 0;
- int dilation_elem = 0;
- int dilation_size = 0;
- int const max_elem = 2;
- int const max_kernel_size = 21;
-
- /* Function Headers */
- void Erosion( int, void* );
- void Dilation( int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load an image
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
- /// Create windows
- namedWindow( "Erosion Demo", WINDOW_AUTOSIZE );
- namedWindow( "Dilation Demo", WINDOW_AUTOSIZE );
- cvMoveWindow( "Dilation Demo", src.cols, 0 );
-
- /// Create Erosion Trackbar
- createTrackbar( "Element:\n 0: Rect \n 1: Cross \n 2: Ellipse", "Erosion Demo",
- &erosion_elem, max_elem,
- Erosion );
-
- createTrackbar( "Kernel size:\n 2n +1", "Erosion Demo",
- &erosion_size, max_kernel_size,
- Erosion );
-
- /// Create Dilation Trackbar
- createTrackbar( "Element:\n 0: Rect \n 1: Cross \n 2: Ellipse", "Dilation Demo",
- &dilation_elem, max_elem,
- Dilation );
-
- createTrackbar( "Kernel size:\n 2n +1", "Dilation Demo",
- &dilation_size, max_kernel_size,
- Dilation );
-
- /// Default start
- Erosion( 0, 0 );
- Dilation( 0, 0 );
-
- waitKey(0);
- return 0;
- }
-
- /* @function Erosion */
- void Erosion( int, void* )
- {
- int erosion_type;
- if( erosion_elem == 0 ){ erosion_type = MORPH_RECT; }
- else if( erosion_elem == 1 ){ erosion_type = MORPH_CROSS; }
- else if( erosion_elem == 2) { erosion_type = MORPH_ELLIPSE; }
-
- Mat element = getStructuringElement( erosion_type,
- Size( 2*erosion_size + 1, 2*erosion_size+1 ),
- Point( erosion_size, erosion_size ) );
-
- /// Apply the erosion operation
- erode( src, erosion_dst, element );
- imshow( "Erosion Demo", erosion_dst );
- }
-
- /* @function Dilation */
- void Dilation( int, void* )
- {
- int dilation_type;
- if( dilation_elem == 0 ){ dilation_type = MORPH_RECT; }
- else if( dilation_elem == 1 ){ dilation_type = MORPH_CROSS; }
- else if( dilation_elem == 2) { dilation_type = MORPH_ELLIPSE; }
-
- Mat element = getStructuringElement( dilation_type,
- Size( 2*dilation_size + 1, 2*dilation_size+1 ),
- Point( dilation_size, dilation_size ) );
- /// Apply the dilation operation
- dilate( src, dilation_dst, element );
- imshow( "Dilation Demo", dilation_dst );
- }
-
-
-Explanation
-=============
-
-#. Most of the stuff shown is known by you (if you have any doubt, please refer to the tutorials in previous sections). Let's check the general structure of the program:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Load an image (can be RGB or grayscale)
- * Create two windows (one for dilation output, the other for erosion)
- * Create a set of 02 Trackbars for each operation:
-
- * The first trackbar "Element" returns either **erosion_elem** or **dilation_elem**
- * The second trackbar "Kernel size" return **erosion_size** or **dilation_size** for the corresponding operation.
-
- * Every time we move any slider, the user's function **Erosion** or **Dilation** will be called and it will update the output image based on the current trackbar values.
-
- Let's analyze these two functions:
-
-#. **erosion:**
-
- .. code-block:: cpp
-
- /* @function Erosion */
- void Erosion( int, void* )
- {
- int erosion_type;
- if( erosion_elem == 0 ){ erosion_type = MORPH_RECT; }
- else if( erosion_elem == 1 ){ erosion_type = MORPH_CROSS; }
- else if( erosion_elem == 2) { erosion_type = MORPH_ELLIPSE; }
-
- Mat element = getStructuringElement( erosion_type,
- Size( 2*erosion_size + 1, 2*erosion_size+1 ),
- Point( erosion_size, erosion_size ) );
- /// Apply the erosion operation
- erode( src, erosion_dst, element );
- imshow( "Erosion Demo", erosion_dst );
- }
-
- * The function that performs the *erosion* operation is :erode:`erode <>`. As we can see, it receives three arguments:
-
- * *src*: The source image
- * *erosion_dst*: The output image
- * *element*: This is the kernel we will use to perform the operation. If we do not specify, the default is a simple :math:`3x3` matrix. Otherwise, we can specify its shape. For this, we need to use the function :get_structuring_element:`getStructuringElement <>`:
-
- .. code-block:: cpp
-
- Mat element = getStructuringElement( erosion_type,
- Size( 2*erosion_size + 1, 2*erosion_size+1 ),
- Point( erosion_size, erosion_size ) );
-
- We can choose any of three shapes for our kernel:
-
- .. container:: enumeratevisibleitemswithsquare
-
- + Rectangular box: MORPH_RECT
- + Cross: MORPH_CROSS
- + Ellipse: MORPH_ELLIPSE
-
- Then, we just have to specify the size of our kernel and the *anchor point*. If not specified, it is assumed to be in the center.
-
- * That is all. We are ready to perform the erosion of our image.
-
- .. note::
- Additionally, there is another parameter that allows you to perform multiple erosions (iterations) at once. We are not using it in this simple tutorial, though. You can check out the Reference for more details.
-
-
-#. **dilation:**
-
-The code is below. As you can see, it is completely similar to the snippet of code for **erosion**. Here we also have the option of defining our kernel, its anchor point and the size of the operator to be used.
-
-.. code-block:: cpp
-
- /* @function Dilation */
- void Dilation( int, void* )
- {
- int dilation_type;
- if( dilation_elem == 0 ){ dilation_type = MORPH_RECT; }
- else if( dilation_elem == 1 ){ dilation_type = MORPH_CROSS; }
- else if( dilation_elem == 2) { dilation_type = MORPH_ELLIPSE; }
-
- Mat element = getStructuringElement( dilation_type,
- Size( 2*dilation_size + 1, 2*dilation_size+1 ),
- Point( dilation_size, dilation_size ) );
- /// Apply the dilation operation
- dilate( src, dilation_dst, element );
- imshow( "Dilation Demo", dilation_dst );
- }
-
-
-
-Results
-========
-
-* Compile the code above and execute it with an image as argument. For instance, using this image:
-
- .. image:: images/Morphology_1_Tutorial_Original_Image.jpg
- :alt: Original image
- :align: center
-
- We get the results below. Varying the indices in the Trackbars give different output images, naturally. Try them out! You can even try to add a third Trackbar to control the number of iterations.
-
- .. image:: images/Morphology_1_Result.jpg
- :alt: Dilation and Erosion application
- :align: center
+++ /dev/null
-.. _Smoothing:
-
-Smoothing Images
-******************
-
-Goal
-=====
-
-In this tutorial you will learn how to apply diverse linear filters to smooth images using OpenCV functions such as:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * :blur:`blur <>`
- * :gaussian_blur:`GaussianBlur <>`
- * :median_blur:`medianBlur <>`
- * :bilateral_filter:`bilateralFilter <>`
-
-Theory
-======
-
-.. note::
- The explanation below belongs to the book `Computer Vision: Algorithms and Applications <http://szeliski.org/Book/>`_ by Richard Szeliski and to *LearningOpenCV*
-
-.. container:: enumeratevisibleitemswithsquare
-
- * *Smoothing*, also called *blurring*, is a simple and frequently used image processing operation.
-
- * There are many reasons for smoothing. In this tutorial we will focus on smoothing in order to reduce noise (other uses will be seen in the following tutorials).
-
- * To perform a smoothing operation we will apply a *filter* to our image. The most common type of filters are *linear*, in which an output pixel's value (i.e. :math:`g(i,j)`) is determined as a weighted sum of input pixel values (i.e. :math:`f(i+k,j+l)`) :
-
- .. math::
- g(i,j) = \sum_{k,l} f(i+k, j+l) h(k,l)
-
- :math:`h(k,l)` is called the *kernel*, which is nothing more than the coefficients of the filter.
-
-
- It helps to visualize a *filter* as a window of coefficients sliding across the image.
-
- * There are many kind of filters, here we will mention the most used:
-
-Normalized Box Filter
------------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * This filter is the simplest of all! Each output pixel is the *mean* of its kernel neighbors ( all of them contribute with equal weights)
-
- * The kernel is below:
-
- .. math::
-
- K = \dfrac{1}{K_{width} \cdot K_{height}} \begin{bmatrix}
- 1 & 1 & 1 & ... & 1 \\
- 1 & 1 & 1 & ... & 1 \\
- . & . & . & ... & 1 \\
- . & . & . & ... & 1 \\
- 1 & 1 & 1 & ... & 1
- \end{bmatrix}
-
-
-Gaussian Filter
----------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Probably the most useful filter (although not the fastest). Gaussian filtering is done by convolving each point in the input array with a *Gaussian kernel* and then summing them all to produce the output array.
-
- * Just to make the picture clearer, remember how a 1D Gaussian kernel look like?
-
- .. image:: images/Smoothing_Tutorial_theory_gaussian_0.jpg
- :align: center
-
- Assuming that an image is 1D, you can notice that the pixel located in the middle would have the biggest weight. The weight of its neighbors decreases as the spatial distance between them and the center pixel increases.
-
-.. note::
-
- Remember that a 2D Gaussian can be represented as :
-
- .. math::
-
- G_{0}(x, y) = A e^{ \dfrac{ -(x - \mu_{x})^{2} }{ 2\sigma^{2}_{x} } + \dfrac{ -(y - \mu_{y})^{2} }{ 2\sigma^{2}_{y} } }
-
- where :math:`\mu` is the mean (the peak) and :math:`\sigma` represents the variance (per each of the variables :math:`x` and :math:`y`)
-
-
-Median Filter
---------------
-
-The median filter run through each element of the signal (in this case the image) and replace each pixel with the **median** of its neighboring pixels (located in a square neighborhood around the evaluated pixel).
-
-
-Bilateral Filter
------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * So far, we have explained some filters which main goal is to *smooth* an input image. However, sometimes the filters do not only dissolve the noise, but also smooth away the *edges*. To avoid this (at certain extent at least), we can use a bilateral filter.
-
- * In an analogous way as the Gaussian filter, the bilateral filter also considers the neighboring pixels with weights assigned to each of them. These weights have two components, the first of which is the same weighting used by the Gaussian filter. The second component takes into account the difference in intensity between the neighboring pixels and the evaluated one.
-
- * For a more detailed explanation you can check `this link <http://homepages.inf.ed.ac.uk/rbf/CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html>`_
-
-
-Code
-======
-
-.. container:: enumeratevisibleitemswithsquare
-
- * **What does this program do?**
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Loads an image
- * Applies 4 different kinds of filters (explained in Theory) and show the filtered images sequentially
-
- * **Downloadable code**:
- Click `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgProc/Smoothing.cpp>`_
-
- * **Code at glance:**
-
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
-
- using namespace std;
- using namespace cv;
-
- /// Global Variables
- int DELAY_CAPTION = 1500;
- int DELAY_BLUR = 100;
- int MAX_KERNEL_LENGTH = 31;
-
- Mat src; Mat dst;
- char window_name[] = "Filter Demo 1";
-
- /// Function headers
- int display_caption( char* caption );
- int display_dst( int delay );
-
- /*
- * function main
- */
- int main( int argc, char** argv )
- {
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
- /// Load the source image
- src = imread( "../images/lena.jpg", 1 );
-
- if( display_caption( "Original Image" ) != 0 ) { return 0; }
-
- dst = src.clone();
- if( display_dst( DELAY_CAPTION ) != 0 ) { return 0; }
-
- /// Applying Homogeneous blur
- if( display_caption( "Homogeneous Blur" ) != 0 ) { return 0; }
-
- for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
- { blur( src, dst, Size( i, i ), Point(-1,-1) );
- if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
-
- /// Applying Gaussian blur
- if( display_caption( "Gaussian Blur" ) != 0 ) { return 0; }
-
- for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
- { GaussianBlur( src, dst, Size( i, i ), 0, 0 );
- if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
-
- /// Applying Median blur
- if( display_caption( "Median Blur" ) != 0 ) { return 0; }
-
- for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
- { medianBlur ( src, dst, i );
- if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
-
- /// Applying Bilateral Filter
- if( display_caption( "Bilateral Blur" ) != 0 ) { return 0; }
-
- for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
- { bilateralFilter ( src, dst, i, i*2, i/2 );
- if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
-
- /// Wait until user press a key
- display_caption( "End: Press a key!" );
-
- waitKey(0);
- return 0;
- }
-
- int display_caption( char* caption )
- {
- dst = Mat::zeros( src.size(), src.type() );
- putText( dst, caption,
- Point( src.cols/4, src.rows/2),
- FONT_HERSHEY_COMPLEX, 1, Scalar(255, 255, 255) );
-
- imshow( window_name, dst );
- int c = waitKey( DELAY_CAPTION );
- if( c >= 0 ) { return -1; }
- return 0;
- }
-
- int display_dst( int delay )
- {
- imshow( window_name, dst );
- int c = waitKey ( delay );
- if( c >= 0 ) { return -1; }
- return 0;
- }
-
-
-
-Explanation
-=============
-
-#. Let's check the OpenCV functions that involve only the smoothing procedure, since the rest is already known by now.
-
-#. **Normalized Block Filter:**
-
- OpenCV offers the function :blur:`blur <>` to perform smoothing with this filter.
-
- .. code-block:: cpp
-
- for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
- { blur( src, dst, Size( i, i ), Point(-1,-1) );
- if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
-
-
- We specify 4 arguments (more details, check the Reference):
-
- .. container:: enumeratevisibleitemswithsquare
-
- + *src*: Source image
-
- + *dst*: Destination image
-
- + *Size( w,h )*: Defines the size of the kernel to be used ( of width *w* pixels and height *h* pixels)
-
- + *Point(-1, -1)*: Indicates where the anchor point (the pixel evaluated) is located with respect to the neighborhood. If there is a negative value, then the center of the kernel is considered the anchor point.
-
-#. **Gaussian Filter:**
-
- It is performed by the function :gaussian_blur:`GaussianBlur <>` :
-
- .. code-block:: cpp
-
- for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
- { GaussianBlur( src, dst, Size( i, i ), 0, 0 );
- if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
-
- Here we use 4 arguments (more details, check the OpenCV reference):
-
- .. container:: enumeratevisibleitemswithsquare
-
- + *src*: Source image
-
- + *dst*: Destination image
-
- + *Size(w, h)*: The size of the kernel to be used (the neighbors to be considered). :math:`w` and :math:`h` have to be odd and positive numbers otherwise thi size will be calculated using the :math:`\sigma_{x}` and :math:`\sigma_{y}` arguments.
-
- + :math:`\sigma_{x}`: The standard deviation in x. Writing :math:`0` implies that :math:`\sigma_{x}` is calculated using kernel size.
-
- + :math:`\sigma_{y}`: The standard deviation in y. Writing :math:`0` implies that :math:`\sigma_{y}` is calculated using kernel size.
-
-
-#. **Median Filter:**
-
- This filter is provided by the :median_blur:`medianBlur <>` function:
-
- .. code-block:: cpp
-
- for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
- { medianBlur ( src, dst, i );
- if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
-
- We use three arguments:
-
- .. container:: enumeratevisibleitemswithsquare
-
- + *src*: Source image
-
- + *dst*: Destination image, must be the same type as *src*
-
- + *i*: Size of the kernel (only one because we use a square window). Must be odd.
-
-
-#. **Bilateral Filter**
-
- Provided by OpenCV function :bilateral_filter:`bilateralFilter <>`
-
- .. code-block:: cpp
-
- for ( int i = 1; i < MAX_KERNEL_LENGTH; i = i + 2 )
- { bilateralFilter ( src, dst, i, i*2, i/2 );
- if( display_dst( DELAY_BLUR ) != 0 ) { return 0; } }
-
- We use 5 arguments:
-
- .. container:: enumeratevisibleitemswithsquare
-
- + *src*: Source image
-
- + *dst*: Destination image
-
- + *d*: The diameter of each pixel neighborhood.
-
- + :math:`\sigma_{Color}`: Standard deviation in the color space.
-
- + :math:`\sigma_{Space}`: Standard deviation in the coordinate space (in pixel terms)
-
-
-Results
-========
-
-.. container:: enumeratevisibleitemswithsquare
-
- * The code opens an image (in this case *lena.jpg*) and display it under the effects of the 4 filters explained.
-
- * Here is a snapshot of the image smoothed using *medianBlur*:
-
- .. image:: images/Smoothing_Tutorial_Result_Median_Filter.jpg
- :alt: Smoothing with a median filter
- :align: center
+++ /dev/null
-.. _back_projection:
-
-Back Projection
-****************
-
-
-Goal
-====
-
-In this tutorial you will learn:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * What is Back Projection and why it is useful
-
- * How to use the OpenCV function :calc_back_project:`calcBackProject <>` to calculate Back Projection
-
- * How to mix different channels of an image by using the OpenCV function :mix_channels:`mixChannels <>`
-
-
-Theory
-======
-
-What is Back Projection?
----------------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Back Projection is a way of recording how well the pixels of a given image fit the distribution of pixels in a histogram model.
-
- * To make it simpler: For Back Projection, you calculate the histogram model of a feature and then use it to find this feature in an image.
-
- * Application example: If you have a histogram of flesh color (say, a Hue-Saturation histogram ), then you can use it to find flesh color areas in an image:
-
-
-How does it work?
-------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * We explain this by using the skin example:
-
- * Let's say you have gotten a skin histogram (Hue-Saturation) based on the image below. The histogram besides is going to be our *model histogram* (which we know represents a sample of skin tonality). You applied some mask to capture only the histogram of the skin area:
-
- ====== ======
- |T0| |T1|
- ====== ======
-
- .. |T0| image:: images/Back_Projection_Theory0.jpg
- :align: middle
-
- .. |T1| image:: images/Back_Projection_Theory1.jpg
- :align: middle
-
-
- * Now, let's imagine that you get another hand image (Test Image) like the one below: (with its respective histogram):
-
- ====== ======
- |T2| |T3|
- ====== ======
-
- .. |T2| image:: images/Back_Projection_Theory2.jpg
- :align: middle
-
- .. |T3| image:: images/Back_Projection_Theory3.jpg
- :align: middle
-
-
- * What we want to do is to use our *model histogram* (that we know represents a skin tonality) to detect skin areas in our Test Image. Here are the steps
-
- a. In each pixel of our Test Image (i.e. :math:`p(i,j)` ), collect the data and find the correspondent bin location for that pixel (i.e. :math:`( h_{i,j}, s_{i,j} )` ).
-
- b. Lookup the *model histogram* in the correspondent bin - :math:`( h_{i,j}, s_{i,j} )` - and read the bin value.
-
- c. Store this bin value in a new image (*BackProjection*). Also, you may consider to normalize the *model histogram* first, so the output for the Test Image can be visible for you.
-
- d. Applying the steps above, we get the following BackProjection image for our Test Image:
-
- .. image:: images/Back_Projection_Theory4.jpg
- :align: center
-
- e. In terms of statistics, the values stored in *BackProjection* represent the *probability* that a pixel in *Test Image* belongs to a skin area, based on the *model histogram* that we use. For instance in our Test image, the brighter areas are more probable to be skin area (as they actually are), whereas the darker areas have less probability (notice that these "dark" areas belong to surfaces that have some shadow on it, which in turns affects the detection).
-
-
-Code
-====
-
-.. container:: enumeratevisibleitemswithsquare
-
- * **What does this program do?**
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Loads an image
- * Convert the original to HSV format and separate only *Hue* channel to be used for the Histogram (using the OpenCV function :mix_channels:`mixChannels <>`)
- * Let the user to enter the number of bins to be used in the calculation of the histogram.
- * Calculate the histogram (and update it if the bins change) and the backprojection of the same image.
- * Display the backprojection and the histogram in windows.
-
- * **Downloadable code**:
-
- a. Click `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/Histograms_Matching/calcBackProject_Demo1.cpp>`_ for the basic version (explained in this tutorial).
- b. For stuff slightly fancier (using H-S histograms and floodFill to define a mask for the skin area) you can check the `improved demo <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/Histograms_Matching/calcBackProject_Demo2.cpp>`_
- c. ...or you can always check out the classical `camshiftdemo <https://github.com/Itseez/opencv/tree/master/samples/cpp/camshiftdemo.cpp>`_ in samples.
-
- * **Code at glance:**
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
-
- #include <iostream>
-
- using namespace cv;
- using namespace std;
-
- /// Global Variables
- Mat src; Mat hsv; Mat hue;
- int bins = 25;
-
- /// Function Headers
- void Hist_and_Backproj(int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Read the image
- src = imread( argv[1], 1 );
- /// Transform it to HSV
- cvtColor( src, hsv, COLOR_BGR2HSV );
-
- /// Use only the Hue value
- hue.create( hsv.size(), hsv.depth() );
- int ch[] = { 0, 0 };
- mixChannels( &hsv, 1, &hue, 1, ch, 1 );
-
- /// Create Trackbar to enter the number of bins
- char* window_image = "Source image";
- namedWindow( window_image, WINDOW_AUTOSIZE );
- createTrackbar("* Hue bins: ", window_image, &bins, 180, Hist_and_Backproj );
- Hist_and_Backproj(0, 0);
-
- /// Show the image
- imshow( window_image, src );
-
- /// Wait until user exits the program
- waitKey(0);
- return 0;
- }
-
-
- /*
- * @function Hist_and_Backproj
- * @brief Callback to Trackbar
- */
- void Hist_and_Backproj(int, void* )
- {
- MatND hist;
- int histSize = MAX( bins, 2 );
- float hue_range[] = { 0, 180 };
- const float* ranges = { hue_range };
-
- /// Get the Histogram and normalize it
- calcHist( &hue, 1, 0, Mat(), hist, 1, &histSize, &ranges, true, false );
- normalize( hist, hist, 0, 255, NORM_MINMAX, -1, Mat() );
-
- /// Get Backprojection
- MatND backproj;
- calcBackProject( &hue, 1, 0, hist, backproj, &ranges, 1, true );
-
- /// Draw the backproj
- imshow( "BackProj", backproj );
-
- /// Draw the histogram
- int w = 400; int h = 400;
- int bin_w = cvRound( (double) w / histSize );
- Mat histImg = Mat::zeros( w, h, CV_8UC3 );
-
- for( int i = 0; i < bins; i ++ )
- { rectangle( histImg, Point( i*bin_w, h ), Point( (i+1)*bin_w, h - cvRound( hist.at<float>(i)*h/255.0 ) ), Scalar( 0, 0, 255 ), -1 ); }
-
- imshow( "Histogram", histImg );
- }
-
-Explanation
-===========
-
-#. Declare the matrices to store our images and initialize the number of bins to be used by our histogram:
-
- .. code-block:: cpp
-
- Mat src; Mat hsv; Mat hue;
- int bins = 25;
-
-#. Read the input image and transform it to HSV format:
-
- .. code-block:: cpp
-
- src = imread( argv[1], 1 );
- cvtColor( src, hsv, COLOR_BGR2HSV );
-
-#. For this tutorial, we will use only the Hue value for our 1-D histogram (check out the fancier code in the links above if you want to use the more standard H-S histogram, which yields better results):
-
- .. code-block:: cpp
-
- hue.create( hsv.size(), hsv.depth() );
- int ch[] = { 0, 0 };
- mixChannels( &hsv, 1, &hue, 1, ch, 1 );
-
- as you see, we use the function :mix_channels:`mixChannels` to get only the channel 0 (Hue) from the hsv image. It gets the following parameters:
-
- .. container:: enumeratevisibleitemswithsquare
-
- + **&hsv:** The source array from which the channels will be copied
- + **1:** The number of source arrays
- + **&hue:** The destination array of the copied channels
- + **1:** The number of destination arrays
- + **ch[] = {0,0}:** The array of index pairs indicating how the channels are copied. In this case, the Hue(0) channel of &hsv is being copied to the 0 channel of &hue (1-channel)
- + **1:** Number of index pairs
-
-#. Create a Trackbar for the user to enter the bin values. Any change on the Trackbar means a call to the **Hist_and_Backproj** callback function.
-
- .. code-block:: cpp
-
- char* window_image = "Source image";
- namedWindow( window_image, WINDOW_AUTOSIZE );
- createTrackbar("* Hue bins: ", window_image, &bins, 180, Hist_and_Backproj );
- Hist_and_Backproj(0, 0);
-
-#. Show the image and wait for the user to exit the program:
-
- .. code-block:: cpp
-
- imshow( window_image, src );
-
- waitKey(0);
- return 0;
-
-#. **Hist_and_Backproj function:** Initialize the arguments needed for :calc_hist:`calcHist <>`. The number of bins comes from the Trackbar:
-
-
- .. code-block:: cpp
-
- void Hist_and_Backproj(int, void* )
- {
- MatND hist;
- int histSize = MAX( bins, 2 );
- float hue_range[] = { 0, 180 };
- const float* ranges = { hue_range };
-
-#. Calculate the Histogram and normalize it to the range :math:`[0,255]`
-
- .. code-block:: cpp
-
- calcHist( &hue, 1, 0, Mat(), hist, 1, &histSize, &ranges, true, false );
- normalize( hist, hist, 0, 255, NORM_MINMAX, -1, Mat() );
-
-#. Get the Backprojection of the same image by calling the function :calc_back_project:`calcBackProject <>`
-
- .. code-block:: cpp
-
- MatND backproj;
- calcBackProject( &hue, 1, 0, hist, backproj, &ranges, 1, true );
-
- all the arguments are known (the same as used to calculate the histogram), only we add the backproj matrix, which will store the backprojection of the source image (&hue)
-
-#. Display backproj:
-
- .. code-block:: cpp
-
- imshow( "BackProj", backproj );
-
-#. Draw the 1-D Hue histogram of the image:
-
- .. code-block:: cpp
-
- int w = 400; int h = 400;
- int bin_w = cvRound( (double) w / histSize );
- Mat histImg = Mat::zeros( w, h, CV_8UC3 );
-
- for( int i = 0; i < bins; i ++ )
- { rectangle( histImg, Point( i*bin_w, h ), Point( (i+1)*bin_w, h - cvRound( hist.at<float>(i)*h/255.0 ) ), Scalar( 0, 0, 255 ), -1 ); }
-
- imshow( "Histogram", histImg );
-
-
-
-Results
-=======
-
-#. Here are the output by using a sample image ( guess what? Another hand ). You can play with the bin values and you will observe how it affects the results:
-
- ====== ====== ======
- |R0| |R1| |R2|
- ====== ====== ======
-
- .. |R0| image:: images/Back_Projection1_Source_Image.jpg
- :align: middle
-
- .. |R1| image:: images/Back_Projection1_Histogram.jpg
- :align: middle
-
- .. |R2| image:: images/Back_Projection1_BackProj.jpg
- :align: middle
+++ /dev/null
-.. _histogram_calculation:
-
-Histogram Calculation
-*********************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :split:`split <>` to divide an image into its correspondent planes.
-
- * To calculate histograms of arrays of images by using the OpenCV function :calc_hist:`calcHist <>`
-
- * To normalize an array by using the function :normalize:`normalize <>`
-
-
-.. note::
- In the last tutorial (:ref:`histogram_equalization`) we talked about a particular kind of histogram called *Image histogram*. Now we will considerate it in its more general concept. Read on!
-
-
-What are histograms?
---------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Histograms are collected *counts* of data organized into a set of predefined *bins*
-
- * When we say *data* we are not restricting it to be intensity values (as we saw in the previous Tutorial). The data collected can be whatever feature you find useful to describe your image.
-
- * Let's see an example. Imagine that a Matrix contains information of an image (i.e. intensity in the range :math:`0-255`):
-
-
- .. image:: images/Histogram_Calculation_Theory_Hist0.jpg
- :align: center
-
- * What happens if we want to *count* this data in an organized way? Since we know that the *range* of information value for this case is 256 values, we can segment our range in subparts (called **bins**) like:
-
- .. math::
- \begin{array}{l}
- [0, 255] = { [0, 15] \cup [16, 31] \cup ....\cup [240,255] } \\
- range = { bin_{1} \cup bin_{2} \cup ....\cup bin_{n = 15} }
- \end{array}
-
- and we can keep count of the number of pixels that fall in the range of each :math:`bin_{i}`. Applying this to the example above we get the image below ( axis x represents the bins and axis y the number of pixels in each of them).
-
-
- .. image:: images/Histogram_Calculation_Theory_Hist1.jpg
- :align: center
-
- * This was just a simple example of how an histogram works and why it is useful. An histogram can keep count not only of color intensities, but of whatever image features that we want to measure (i.e. gradients, directions, etc).
-
- * Let's identify some parts of the histogram:
-
- a. **dims**: The number of parameters you want to collect data of. In our example, **dims = 1** because we are only counting the intensity values of each pixel (in a greyscale image).
- b. **bins**: It is the number of **subdivisions** in each dim. In our example, **bins = 16**
- c. **range**: The limits for the values to be measured. In this case: **range = [0,255]**
-
- * What if you want to count two features? In this case your resulting histogram would be a 3D plot (in which x and y would be :math:`bin_{x}` and :math:`bin_{y}` for each feature and z would be the number of counts for each combination of :math:`(bin_{x}, bin_{y})`. The same would apply for more features (of course it gets trickier).
-
-
-What OpenCV offers you
------------------------
-
-For simple purposes, OpenCV implements the function :calc_hist:`calcHist <>`, which calculates the histogram of a set of arrays (usually images or image planes). It can operate with up to 32 dimensions. We will see it in the code below!
-
-
-Code
-====
-
-.. container:: enumeratevisibleitemswithsquare
-
- * **What does this program do?**
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Loads an image
- * Splits the image into its R, G and B planes using the function :split:`split <>`
- * Calculate the Histogram of each 1-channel plane by calling the function :calc_hist:`calcHist <>`
- * Plot the three histograms in a window
-
- * **Downloadable code**:
- Click `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/Histograms_Matching/calcHist_Demo.cpp>`_
-
- * **Code at glance:**
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
-
- using namespace std;
- using namespace cv;
-
- /*
- * @function main
- */
- int main( int argc, char** argv )
- {
- Mat src, dst;
-
- /// Load image
- src = imread( argv[1], 1 );
-
- if( !src.data )
- { return -1; }
-
- /// Separate the image in 3 places ( B, G and R )
- vector<Mat> bgr_planes;
- split( src, bgr_planes );
-
- /// Establish the number of bins
- int histSize = 256;
-
- /// Set the ranges ( for B,G,R) )
- float range[] = { 0, 256 } ;
- const float* histRange = { range };
-
- bool uniform = true; bool accumulate = false;
-
- Mat b_hist, g_hist, r_hist;
-
- /// Compute the histograms:
- calcHist( &bgr_planes[0], 1, 0, Mat(), b_hist, 1, &histSize, &histRange, uniform, accumulate );
- calcHist( &bgr_planes[1], 1, 0, Mat(), g_hist, 1, &histSize, &histRange, uniform, accumulate );
- calcHist( &bgr_planes[2], 1, 0, Mat(), r_hist, 1, &histSize, &histRange, uniform, accumulate );
-
- // Draw the histograms for B, G and R
- int hist_w = 512; int hist_h = 400;
- int bin_w = cvRound( (double) hist_w/histSize );
-
- Mat histImage( hist_h, hist_w, CV_8UC3, Scalar( 0,0,0) );
-
- /// Normalize the result to [ 0, histImage.rows ]
- normalize(b_hist, b_hist, 0, histImage.rows, NORM_MINMAX, -1, Mat() );
- normalize(g_hist, g_hist, 0, histImage.rows, NORM_MINMAX, -1, Mat() );
- normalize(r_hist, r_hist, 0, histImage.rows, NORM_MINMAX, -1, Mat() );
-
- /// Draw for each channel
- for( int i = 1; i < histSize; i++ )
- {
- line( histImage, Point( bin_w*(i-1), hist_h - cvRound(b_hist.at<float>(i-1)) ) ,
- Point( bin_w*(i), hist_h - cvRound(b_hist.at<float>(i)) ),
- Scalar( 255, 0, 0), 2, 8, 0 );
- line( histImage, Point( bin_w*(i-1), hist_h - cvRound(g_hist.at<float>(i-1)) ) ,
- Point( bin_w*(i), hist_h - cvRound(g_hist.at<float>(i)) ),
- Scalar( 0, 255, 0), 2, 8, 0 );
- line( histImage, Point( bin_w*(i-1), hist_h - cvRound(r_hist.at<float>(i-1)) ) ,
- Point( bin_w*(i), hist_h - cvRound(r_hist.at<float>(i)) ),
- Scalar( 0, 0, 255), 2, 8, 0 );
- }
-
- /// Display
- namedWindow("calcHist Demo", WINDOW_AUTOSIZE );
- imshow("calcHist Demo", histImage );
-
- waitKey(0);
-
- return 0;
- }
-
-Explanation
-===========
-
-#. Create the necessary matrices:
-
- .. code-block:: cpp
-
- Mat src, dst;
-
-#. Load the source image
-
- .. code-block:: cpp
-
- src = imread( argv[1], 1 );
-
- if( !src.data )
- { return -1; }
-
-#. Separate the source image in its three R,G and B planes. For this we use the OpenCV function :split:`split <>`:
-
- .. code-block:: cpp
-
- vector<Mat> bgr_planes;
- split( src, bgr_planes );
-
- our input is the image to be divided (this case with three channels) and the output is a vector of Mat )
-
-#. Now we are ready to start configuring the **histograms** for each plane. Since we are working with the B, G and R planes, we know that our values will range in the interval :math:`[0,255]`
-
- a. Establish number of bins (5, 10...):
-
- .. code-block:: cpp
-
- int histSize = 256; //from 0 to 255
-
- b. Set the range of values (as we said, between 0 and 255 )
-
- .. code-block:: cpp
-
- /// Set the ranges ( for B,G,R) )
- float range[] = { 0, 256 } ; //the upper boundary is exclusive
- const float* histRange = { range };
-
- c. We want our bins to have the same size (uniform) and to clear the histograms in the beginning, so:
-
- .. code-block:: cpp
-
- bool uniform = true; bool accumulate = false;
-
- d. Finally, we create the Mat objects to save our histograms. Creating 3 (one for each plane):
-
- .. code-block:: cpp
-
- Mat b_hist, g_hist, r_hist;
-
- e. We proceed to calculate the histograms by using the OpenCV function :calc_hist:`calcHist <>`:
-
- .. code-block:: cpp
-
- /// Compute the histograms:
- calcHist( &bgr_planes[0], 1, 0, Mat(), b_hist, 1, &histSize, &histRange, uniform, accumulate );
- calcHist( &bgr_planes[1], 1, 0, Mat(), g_hist, 1, &histSize, &histRange, uniform, accumulate );
- calcHist( &bgr_planes[2], 1, 0, Mat(), r_hist, 1, &histSize, &histRange, uniform, accumulate );
-
- where the arguments are:
-
- .. container:: enumeratevisibleitemswithsquare
-
- + **&bgr_planes[0]:** The source array(s)
- + **1**: The number of source arrays (in this case we are using 1. We can enter here also a list of arrays )
- + **0**: The channel (*dim*) to be measured. In this case it is just the intensity (each array is single-channel) so we just write 0.
- + **Mat()**: A mask to be used on the source array ( zeros indicating pixels to be ignored ). If not defined it is not used
- + **b_hist**: The Mat object where the histogram will be stored
- + **1**: The histogram dimensionality.
- + **histSize:** The number of bins per each used dimension
- + **histRange:** The range of values to be measured per each dimension
- + **uniform** and **accumulate**: The bin sizes are the same and the histogram is cleared at the beginning.
-
-
-#. Create an image to display the histograms:
-
- .. code-block:: cpp
-
- // Draw the histograms for R, G and B
- int hist_w = 512; int hist_h = 400;
- int bin_w = cvRound( (double) hist_w/histSize );
-
- Mat histImage( hist_h, hist_w, CV_8UC3, Scalar( 0,0,0) );
-
-#. Notice that before drawing, we first :normalize:`normalize <>` the histogram so its values fall in the range indicated by the parameters entered:
-
- .. code-block:: cpp
-
- /// Normalize the result to [ 0, histImage.rows ]
- normalize(b_hist, b_hist, 0, histImage.rows, NORM_MINMAX, -1, Mat() );
- normalize(g_hist, g_hist, 0, histImage.rows, NORM_MINMAX, -1, Mat() );
- normalize(r_hist, r_hist, 0, histImage.rows, NORM_MINMAX, -1, Mat() );
-
- this function receives these arguments:
-
- .. container:: enumeratevisibleitemswithsquare
-
- + **b_hist:** Input array
- + **b_hist:** Output normalized array (can be the same)
- + **0** and**histImage.rows**: For this example, they are the lower and upper limits to normalize the values of **r_hist**
- + **NORM_MINMAX:** Argument that indicates the type of normalization (as described above, it adjusts the values between the two limits set before)
- + **-1:** Implies that the output normalized array will be the same type as the input
- + **Mat():** Optional mask
-
-#. Finally, observe that to access the bin (in this case in this 1D-Histogram):
-
- .. code-block:: cpp
-
- /// Draw for each channel
- for( int i = 1; i < histSize; i++ )
- {
- line( histImage, Point( bin_w*(i-1), hist_h - cvRound(b_hist.at<float>(i-1)) ) ,
- Point( bin_w*(i), hist_h - cvRound(b_hist.at<float>(i)) ),
- Scalar( 255, 0, 0), 2, 8, 0 );
- line( histImage, Point( bin_w*(i-1), hist_h - cvRound(g_hist.at<float>(i-1)) ) ,
- Point( bin_w*(i), hist_h - cvRound(g_hist.at<float>(i)) ),
- Scalar( 0, 255, 0), 2, 8, 0 );
- line( histImage, Point( bin_w*(i-1), hist_h - cvRound(r_hist.at<float>(i-1)) ) ,
- Point( bin_w*(i), hist_h - cvRound(r_hist.at<float>(i)) ),
- Scalar( 0, 0, 255), 2, 8, 0 );
- }
-
-
- we use the expression:
-
- .. code-block:: cpp
-
- b_hist.at<float>(i)
-
-
- where :math:`i` indicates the dimension. If it were a 2D-histogram we would use something like:
-
- .. code-block:: cpp
-
- b_hist.at<float>( i, j )
-
-
-#. Finally we display our histograms and wait for the user to exit:
-
- .. code-block:: cpp
-
- namedWindow("calcHist Demo", WINDOW_AUTOSIZE );
- imshow("calcHist Demo", histImage );
-
- waitKey(0);
-
- return 0;
-
-
-Result
-======
-
-#. Using as input argument an image like the shown below:
-
- .. image:: images/Histogram_Calculation_Original_Image.jpg
- :align: center
-
-#. Produces the following histogram:
-
- .. image:: images/Histogram_Calculation_Result.jpg
- :align: center
+++ /dev/null
-.. _histogram_comparison:
-
-Histogram Comparison
-********************
-
-Goal
-====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the function :compare_hist:`compareHist <>` to get a numerical parameter that express how well two histograms match with each other.
- * Use different metrics to compare histograms
-
-
-Theory
-======
-
-.. container:: enumeratevisibleitemswithsquare
-
- * To compare two histograms ( :math:`H_{1}` and :math:`H_{2}` ), first we have to choose a *metric* (:math:`d(H_{1}, H_{2})`) to express how well both histograms match.
-
- * OpenCV implements the function :compare_hist:`compareHist <>` to perform a comparison. It also offers 4 different metrics to compute the matching:
-
-
- a. **Correlation ( CV\_COMP\_CORREL )**
-
- .. math::
-
- d(H_1,H_2) = \frac{\sum_I (H_1(I) - \bar{H_1}) (H_2(I) - \bar{H_2})}{\sqrt{\sum_I(H_1(I) - \bar{H_1})^2 \sum_I(H_2(I) - \bar{H_2})^2}}
-
- where
-
- .. math::
-
- \bar{H_k} = \frac{1}{N} \sum _J H_k(J)
-
-
- and :math:`N` is the total number of histogram bins.
-
-
-
- b. **Chi-Square ( CV\_COMP\_CHISQR )**
-
- .. math::
-
- d(H_1,H_2) = \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)}
-
-
- c. **Intersection ( method=CV\_COMP\_INTERSECT )**
-
- .. math::
-
- d(H_1,H_2) = \sum _I \min (H_1(I), H_2(I))
-
-
- d. **Bhattacharyya distance ( CV\_COMP\_BHATTACHARYYA )**
-
- .. math::
-
- d(H_1,H_2) = \sqrt{1 - \frac{1}{\sqrt{\bar{H_1} \bar{H_2} N^2}} \sum_I \sqrt{H_1(I) \cdot H_2(I)}}
-
-
-
-Code
-====
-
-.. container:: enumeratevisibleitemswithsquare
-
- * **What does this program do?**
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Loads a *base image* and 2 *test images* to be compared with it.
- * Generate 1 image that is the lower half of the *base image*
- * Convert the images to HSV format
- * Calculate the H-S histogram for all the images and normalize them in order to compare them.
- * Compare the histogram of the *base image* with respect to the 2 test histograms, the histogram of the lower half base image and with the same base image histogram.
- * Display the numerical matching parameters obtained.
-
- * **Downloadable code**:
- Click `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/Histograms_Matching/compareHist_Demo.cpp>`_
-
- * **Code at glance:**
-
-.. literalinclude:: ../../../../../samples/cpp/tutorial_code/Histograms_Matching/compareHist_Demo.cpp
- :language: cpp
- :tab-width: 4
-
-
-
-Explanation
-===========
-
-#. Declare variables such as the matrices to store the base image and the two other images to compare ( RGB and HSV )
-
- .. code-block:: cpp
-
- Mat src_base, hsv_base;
- Mat src_test1, hsv_test1;
- Mat src_test2, hsv_test2;
- Mat hsv_half_down;
-
-#. Load the base image (src\_base) and the other two test images:
-
- .. code-block:: cpp
-
- if( argc < 4 )
- { printf("** Error. Usage: ./compareHist_Demo <image_settings0> <image_setting1> <image_settings2>\n");
- return -1;
- }
-
- src_base = imread( argv[1], 1 );
- src_test1 = imread( argv[2], 1 );
- src_test2 = imread( argv[3], 1 );
-
-#. Convert them to HSV format:
-
- .. code-block:: cpp
-
- cvtColor( src_base, hsv_base, COLOR_BGR2HSV );
- cvtColor( src_test1, hsv_test1, COLOR_BGR2HSV );
- cvtColor( src_test2, hsv_test2, COLOR_BGR2HSV );
-
-#. Also, create an image of half the base image (in HSV format):
-
- .. code-block:: cpp
-
- hsv_half_down = hsv_base( Range( hsv_base.rows/2, hsv_base.rows - 1 ), Range( 0, hsv_base.cols - 1 ) );
-
-#. Initialize the arguments to calculate the histograms (bins, ranges and channels H and S ).
-
- .. code-block:: cpp
-
- int h_bins = 50; int s_bins = 60;
- int histSize[] = { h_bins, s_bins };
-
- float h_ranges[] = { 0, 180 };
- float s_ranges[] = { 0, 256 };
-
- const float* ranges[] = { h_ranges, s_ranges };
-
- int channels[] = { 0, 1 };
-
-#. Create the MatND objects to store the histograms:
-
- .. code-block:: cpp
-
- MatND hist_base;
- MatND hist_half_down;
- MatND hist_test1;
- MatND hist_test2;
-
-#. Calculate the Histograms for the base image, the 2 test images and the half-down base image:
-
- .. code-block:: cpp
-
- calcHist( &hsv_base, 1, channels, Mat(), hist_base, 2, histSize, ranges, true, false );
- normalize( hist_base, hist_base, 0, 1, NORM_MINMAX, -1, Mat() );
-
- calcHist( &hsv_half_down, 1, channels, Mat(), hist_half_down, 2, histSize, ranges, true, false );
- normalize( hist_half_down, hist_half_down, 0, 1, NORM_MINMAX, -1, Mat() );
-
- calcHist( &hsv_test1, 1, channels, Mat(), hist_test1, 2, histSize, ranges, true, false );
- normalize( hist_test1, hist_test1, 0, 1, NORM_MINMAX, -1, Mat() );
-
- calcHist( &hsv_test2, 1, channels, Mat(), hist_test2, 2, histSize, ranges, true, false );
- normalize( hist_test2, hist_test2, 0, 1, NORM_MINMAX, -1, Mat() );
-
-
-#. Apply sequentially the 4 comparison methods between the histogram of the base image (hist\_base) and the other histograms:
-
- .. code-block:: cpp
-
- for( int i = 0; i < 4; i++ )
- { int compare_method = i;
- double base_base = compareHist( hist_base, hist_base, compare_method );
- double base_half = compareHist( hist_base, hist_half_down, compare_method );
- double base_test1 = compareHist( hist_base, hist_test1, compare_method );
- double base_test2 = compareHist( hist_base, hist_test2, compare_method );
-
- printf( " Method [%d] Perfect, Base-Half, Base-Test(1), Base-Test(2) : %f, %f, %f, %f \n", i, base_base, base_half , base_test1, base_test2 );
- }
-
-
-Results
-========
-
-#. We use as input the following images:
-
- ============ ============ ============
- |Base_0| |Test_1| |Test_2|
- ============ ============ ============
-
- .. |Base_0| image:: images/Histogram_Comparison_Source_0.jpg
- :align: middle
-
- .. |Test_1| image:: images/Histogram_Comparison_Source_1.jpg
- :align: middle
-
- .. |Test_2| image:: images/Histogram_Comparison_Source_2.jpg
- :align: middle
-
- where the first one is the base (to be compared to the others), the other 2 are the test images. We will also compare the first image with respect to itself and with respect of half the base image.
-
-#. We should expect a perfect match when we compare the base image histogram with itself. Also, compared with the histogram of half the base image, it should present a high match since both are from the same source. For the other two test images, we can observe that they have very different lighting conditions, so the matching should not be very good:
-
-#. Here the numeric results:
-
- =============== =============== =============== =============== ===============
- *Method* Base - Base Base - Half Base - Test 1 Base - Test 2
- =============== =============== =============== =============== ===============
- *Correlation* 1.000000 0.930766 0.182073 0.120447
- *Chi-square* 0.000000 4.940466 21.184536 49.273437
- *Intersection* 24.391548 14.959809 3.889029 5.775088
- *Bhattacharyya* 0.000000 0.222609 0.646576 0.801869
- =============== =============== =============== =============== ===============
-
-
- For the *Correlation* and *Intersection* methods, the higher the metric, the more accurate the match. As we can see, the match *base-base* is the highest of all as expected. Also we can observe that the match *base-half* is the second best match (as we predicted). For the other two metrics, the less the result, the better the match. We can observe that the matches between the test 1 and test 2 with respect to the base are worse, which again, was expected.
+++ /dev/null
-.. _histogram_equalization:
-
-Histogram Equalization
-**********************
-
-Goal
-====
-
-In this tutorial you will learn:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * What an image histogram is and why it is useful
-
- * To equalize histograms of images by using the OpenCV function:equalize_hist:`equalizeHist <>`
-
-
-
-Theory
-======
-
-What is an Image Histogram?
----------------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * It is a graphical representation of the intensity distribution of an image.
-
- * It quantifies the number of pixels for each intensity value considered.
-
-.. image:: images/Histogram_Equalization_Theory_0.jpg
- :align: center
-
-
-What is Histogram Equalization?
--------------------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * It is a method that improves the contrast in an image, in order to stretch out the intensity range.
-
- * To make it clearer, from the image above, you can see that the pixels seem clustered around the middle of the available range of intensities. What Histogram Equalization does is to *stretch out* this range. Take a look at the figure below: The green circles indicate the *underpopulated* intensities. After applying the equalization, we get an histogram like the figure in the center. The resulting image is shown in the picture at right.
-
-.. image:: images/Histogram_Equalization_Theory_1.jpg
- :align: center
-
-How does it work?
------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Equalization implies *mapping* one distribution (the given histogram) to another distribution (a wider and more uniform distribution of intensity values) so the intensity values are spreaded over the whole range.
-
- * To accomplish the equalization effect, the remapping should be the *cumulative distribution function (cdf)* (more details, refer to *Learning OpenCV*). For the histogram :math:`H(i)`, its *cumulative distribution* :math:`H^{'}(i)` is:
-
- .. math::
-
- H^{'}(i) = \sum_{0 \le j < i} H(j)
-
- To use this as a remapping function, we have to normalize :math:`H^{'}(i)` such that the maximum value is 255 ( or the maximum value for the intensity of the image ). From the example above, the cumulative function is:
-
- .. image:: images/Histogram_Equalization_Theory_2.jpg
- :align: center
-
- * Finally, we use a simple remapping procedure to obtain the intensity values of the equalized image:
-
- .. math::
-
- equalized( x, y ) = H^{'}( src(x,y) )
-
-Code
-====
-
-.. container:: enumeratevisibleitemswithsquare
-
- * **What does this program do?**
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Loads an image
- * Convert the original image to grayscale
- * Equalize the Histogram by using the OpenCV function :equalize_hist:`EqualizeHist <>`
- * Display the source and equalized images in a window.
-
- * **Downloadable code**:
- Click `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/Histograms_Matching/EqualizeHist_Demo.cpp>`_
-
- * **Code at glance:**
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
-
- using namespace cv;
- using namespace std;
-
- /* @function main */
- int main( int argc, char** argv )
- {
- Mat src, dst;
-
- char* source_window = "Source image";
- char* equalized_window = "Equalized Image";
-
- /// Load image
- src = imread( argv[1], 1 );
-
- if( !src.data )
- { cout<<"Usage: ./Histogram_Demo <path_to_image>"<<endl;
- return -1;}
-
- /// Convert to grayscale
- cvtColor( src, src, COLOR_BGR2GRAY );
-
- /// Apply Histogram Equalization
- equalizeHist( src, dst );
-
- /// Display results
- namedWindow( source_window, WINDOW_AUTOSIZE );
- namedWindow( equalized_window, WINDOW_AUTOSIZE );
-
- imshow( source_window, src );
- imshow( equalized_window, dst );
-
- /// Wait until user exits the program
- waitKey(0);
-
- return 0;
- }
-
-Explanation
-===========
-
-#. Declare the source and destination images as well as the windows names:
-
- .. code-block:: cpp
-
- Mat src, dst;
-
- char* source_window = "Source image";
- char* equalized_window = "Equalized Image";
-
-#. Load the source image:
-
- .. code-block:: cpp
-
- src = imread( argv[1], 1 );
-
- if( !src.data )
- { cout<<"Usage: ./Histogram_Demo <path_to_image>"<<endl;
- return -1;}
-
-#. Convert it to grayscale:
-
- .. code-block:: cpp
-
- cvtColor( src, src, COLOR_BGR2GRAY );
-
-#. Apply histogram equalization with the function :equalize_hist:`equalizeHist <>` :
-
- .. code-block:: cpp
-
- equalizeHist( src, dst );
-
- As it can be easily seen, the only arguments are the original image and the output (equalized) image.
-
-#. Display both images (original and equalized) :
-
- .. code-block:: cpp
-
- namedWindow( source_window, WINDOW_AUTOSIZE );
- namedWindow( equalized_window, WINDOW_AUTOSIZE );
-
- imshow( source_window, src );
- imshow( equalized_window, dst );
-
-#. Wait until user exists the program
-
- .. code-block:: cpp
-
- waitKey(0);
- return 0;
-
-
-Results
-=======
-
-#. To appreciate better the results of equalization, let's introduce an image with not much contrast, such as:
-
- .. image:: images/Histogram_Equalization_Original_Image.jpg
- :align: center
-
- which, by the way, has this histogram:
-
- .. image:: images/Histogram_Equalization_Original_Histogram.jpg
- :align: center
-
- notice that the pixels are clustered around the center of the histogram.
-
-#. After applying the equalization with our program, we get this result:
-
- .. image:: images/Histogram_Equalization_Equalized_Image.jpg
- :align: center
-
- this image has certainly more contrast. Check out its new histogram like this:
-
- .. image:: images/Histogram_Equalization_Equalized_Histogram.jpg
- :align: center
-
- Notice how the number of pixels is more distributed through the intensity range.
-
-
-.. note::
- Are you wondering how did we draw the Histogram figures shown above? Check out the following tutorial!
+++ /dev/null
-.. _template_matching:
-
-Template Matching
-*****************
-
-Goal
-====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :match_template:`matchTemplate <>` to search for matches between an image patch and an input image
- * Use the OpenCV function :min_max_loc:`minMaxLoc <>` to find the maximum and minimum values (as well as their positions) in a given array.
-
-Theory
-======
-
-What is template matching?
---------------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- Template matching is a technique for finding areas of an image that match (are similar) to a template image (patch).
-
-
-How does it work?
-------------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * We need two primary components:
-
- a. **Source image (I):** The image in which we expect to find a match to the template image
- b. **Template image (T):** The patch image which will be compared to the template image
-
- our goal is to detect the highest matching area:
-
- .. image:: images/Template_Matching_Template_Theory_Summary.jpg
- :align: center
-
- * To identify the matching area, we have to *compare* the template image against the source image by sliding it:
-
- .. image:: images/Template_Matching_Template_Theory_Sliding.jpg
- :align: center
-
- * By **sliding**, we mean moving the patch one pixel at a time (left to right, up to down). At each location, a metric is calculated so it represents how "good" or "bad" the match at that location is (or how similar the patch is to that particular area of the source image).
-
- * For each location of **T** over **I**, you *store* the metric in the *result matrix* **(R)**. Each location :math:`(x,y)` in **R** contains the match metric:
-
- .. image:: images/Template_Matching_Template_Theory_Result.jpg
- :align: center
-
- the image above is the result **R** of sliding the patch with a metric **TM_CCORR_NORMED**. The brightest locations indicate the highest matches. As you can see, the location marked by the red circle is probably the one with the highest value, so that location (the rectangle formed by that point as a corner and width and height equal to the patch image) is considered the match.
-
- * In practice, we use the function :min_max_loc:`minMaxLoc <>` to locate the highest value (or lower, depending of the type of matching method) in the *R* matrix.
-
-Which are the matching methods available in OpenCV?
-----------------------------------------------------
-
-Good question. OpenCV implements Template matching in the function :match_template:`matchTemplate <>`. The available methods are 6:
-
-a. **method=CV\_TM\_SQDIFF**
-
- .. math::
-
- R(x,y)= \sum _{x',y'} (T(x',y')-I(x+x',y+y'))^2
-
-
-b. **method=CV\_TM\_SQDIFF\_NORMED**
-
- .. math::
-
- R(x,y)= \frac{\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
-
-
-c. **method=CV\_TM\_CCORR**
-
- .. math::
-
- R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y'))
-
-
-d. **method=CV\_TM\_CCORR\_NORMED**
-
- .. math::
-
- R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y'))}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
-
-
-e. **method=CV\_TM\_CCOEFF**
-
- .. math::
-
- R(x,y)= \sum _{x',y'} (T'(x',y') \cdot I(x+x',y+y'))
-
- where
-
- .. math::
-
- \begin{array}{l} T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum _{x'',y''} T(x'',y'') \\ I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h) \cdot \sum _{x'',y''} I(x+x'',y+y'') \end{array}
-
-
-f. **method=CV\_TM\_CCOEFF\_NORMED**
-
- .. math::
-
- R(x,y)= \frac{ \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }{ \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2} }
-
-
-Code
-====
-
-
-.. container:: enumeratevisibleitemswithsquare
-
- * **What does this program do?**
-
- .. container:: enumeratevisibleitemswithsquare
-
- * Loads an input image and a image patch (*template*)
- * Perform a template matching procedure by using the OpenCV function :match_template:`matchTemplate <>` with any of the 6 matching methods described before. The user can choose the method by entering its selection in the Trackbar.
- * Normalize the output of the matching procedure
- * Localize the location with higher matching probability
- * Draw a rectangle around the area corresponding to the highest match
-
- * **Downloadable code**:
- Click `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/Histograms_Matching/MatchTemplate_Demo.cpp>`_
-
- * **Code at glance:**
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
-
- using namespace std;
- using namespace cv;
-
- /// Global Variables
- Mat img; Mat templ; Mat result;
- char* image_window = "Source Image";
- char* result_window = "Result window";
-
- int match_method;
- int max_Trackbar = 5;
-
- /// Function Headers
- void MatchingMethod( int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load image and template
- img = imread( argv[1], 1 );
- templ = imread( argv[2], 1 );
-
- /// Create windows
- namedWindow( image_window, WINDOW_AUTOSIZE );
- namedWindow( result_window, WINDOW_AUTOSIZE );
-
- /// Create Trackbar
- char* trackbar_label = "Method: \n 0: SQDIFF \n 1: SQDIFF NORMED \n 2: TM CCORR \n 3: TM CCORR NORMED \n 4: TM COEFF \n 5: TM COEFF NORMED";
- createTrackbar( trackbar_label, image_window, &match_method, max_Trackbar, MatchingMethod );
-
- MatchingMethod( 0, 0 );
-
- waitKey(0);
- return 0;
- }
-
- /*
- * @function MatchingMethod
- * @brief Trackbar callback
- */
- void MatchingMethod( int, void* )
- {
- /// Source image to display
- Mat img_display;
- img.copyTo( img_display );
-
- /// Create the result matrix
- int result_cols = img.cols - templ.cols + 1;
- int result_rows = img.rows - templ.rows + 1;
-
- result.create( result_cols, result_rows, CV_32FC1 );
-
- /// Do the Matching and Normalize
- matchTemplate( img, templ, result, match_method );
- normalize( result, result, 0, 1, NORM_MINMAX, -1, Mat() );
-
- /// Localizing the best match with minMaxLoc
- double minVal; double maxVal; Point minLoc; Point maxLoc;
- Point matchLoc;
-
- minMaxLoc( result, &minVal, &maxVal, &minLoc, &maxLoc, Mat() );
-
- /// For SQDIFF and SQDIFF_NORMED, the best matches are lower values. For all the other methods, the higher the better
- if( match_method == CV_TM_SQDIFF || match_method == CV_TM_SQDIFF_NORMED )
- { matchLoc = minLoc; }
- else
- { matchLoc = maxLoc; }
-
- /// Show me what you got
- rectangle( img_display, matchLoc, Point( matchLoc.x + templ.cols , matchLoc.y + templ.rows ), Scalar::all(0), 2, 8, 0 );
- rectangle( result, matchLoc, Point( matchLoc.x + templ.cols , matchLoc.y + templ.rows ), Scalar::all(0), 2, 8, 0 );
-
- imshow( image_window, img_display );
- imshow( result_window, result );
-
- return;
- }
-
-Explanation
-===========
-
-#. Declare some global variables, such as the image, template and result matrices, as well as the match method and the window names:
-
- .. code-block:: cpp
-
- Mat img; Mat templ; Mat result;
- char* image_window = "Source Image";
- char* result_window = "Result window";
-
- int match_method;
- int max_Trackbar = 5;
-
-
-#. Load the source image and template:
-
- .. code-block:: cpp
-
- img = imread( argv[1], 1 );
- templ = imread( argv[2], 1 );
-
-#. Create the windows to show the results:
-
- .. code-block:: cpp
-
- namedWindow( image_window, WINDOW_AUTOSIZE );
- namedWindow( result_window, WINDOW_AUTOSIZE );
-
-#. Create the Trackbar to enter the kind of matching method to be used. When a change is detected the callback function **MatchingMethod** is called.
-
- .. code-block:: cpp
-
- char* trackbar_label = "Method: \n 0: SQDIFF \n 1: SQDIFF NORMED \n 2: TM CCORR \n 3: TM CCORR NORMED \n 4: TM COEFF \n 5: TM COEFF NORMED";
- createTrackbar( trackbar_label, image_window, &match_method, max_Trackbar, MatchingMethod );
-
-#. Wait until user exits the program.
-
- .. code-block:: cpp
-
- waitKey(0);
- return 0;
-
-#. Let's check out the callback function. First, it makes a copy of the source image:
-
- .. code-block:: cpp
-
- Mat img_display;
- img.copyTo( img_display );
-
-
-#. Next, it creates the result matrix that will store the matching results for each template location. Observe in detail the size of the result matrix (which matches all possible locations for it)
-
- .. code-block:: cpp
-
- int result_cols = img.cols - templ.cols + 1;
- int result_rows = img.rows - templ.rows + 1;
-
- result.create( result_cols, result_rows, CV_32FC1 );
-
-#. Perform the template matching operation:
-
- .. code-block:: cpp
-
- matchTemplate( img, templ, result, match_method );
-
- the arguments are naturally the input image **I**, the template **T**, the result **R** and the match_method (given by the Trackbar)
-
-#. We normalize the results:
-
- .. code-block:: cpp
-
- normalize( result, result, 0, 1, NORM_MINMAX, -1, Mat() );
-
-#. We localize the minimum and maximum values in the result matrix **R** by using :min_max_loc:`minMaxLoc <>`.
-
- .. code-block:: cpp
-
- double minVal; double maxVal; Point minLoc; Point maxLoc;
- Point matchLoc;
-
- minMaxLoc( result, &minVal, &maxVal, &minLoc, &maxLoc, Mat() );
-
- the function calls as arguments:
-
- .. container:: enumeratevisibleitemswithsquare
-
- + **result:** The source array
- + **&minVal** and **&maxVal:** Variables to save the minimum and maximum values in **result**
- + **&minLoc** and **&maxLoc:** The Point locations of the minimum and maximum values in the array.
- + **Mat():** Optional mask
-
-
-#. For the first two methods ( TM\_SQDIFF and MT\_SQDIFF\_NORMED ) the best match are the lowest values. For all the others, higher values represent better matches. So, we save the corresponding value in the **matchLoc** variable:
-
- .. code-block:: cpp
-
- if( match_method == TM_SQDIFF || match_method == TM_SQDIFF_NORMED )
- { matchLoc = minLoc; }
- else
- { matchLoc = maxLoc; }
-
-#. Display the source image and the result matrix. Draw a rectangle around the highest possible matching area:
-
- .. code-block:: cpp
-
- rectangle( img_display, matchLoc, Point( matchLoc.x + templ.cols , matchLoc.y + templ.rows ), Scalar::all(0), 2, 8, 0 );
- rectangle( result, matchLoc, Point( matchLoc.x + templ.cols , matchLoc.y + templ.rows ), Scalar::all(0), 2, 8, 0 );
-
- imshow( image_window, img_display );
- imshow( result_window, result );
-
-
-Results
-=======
-
-#. Testing our program with an input image such as:
-
- .. image:: images/Template_Matching_Original_Image.jpg
- :align: center
-
- and a template image:
-
- .. image:: images/Template_Matching_Template_Image.jpg
- :align: center
-
-#. Generate the following result matrices (first row are the standard methods SQDIFF, CCORR and CCOEFF, second row are the same methods in its normalized version). In the first column, the darkest is the better match, for the other two columns, the brighter a location, the higher the match.
-
- ============ ============ ============
- |Result_0| |Result_2| |Result_4|
- ============ ============ ============
- |Result_1| |Result_3| |Result_5|
- ============ ============ ============
-
- .. |Result_0| image:: images/Template_Matching_Correl_Result_0.jpg
- :align: middle
-
- .. |Result_1| image:: images/Template_Matching_Correl_Result_1.jpg
- :align: middle
-
- .. |Result_2| image:: images/Template_Matching_Correl_Result_2.jpg
- :align: middle
-
- .. |Result_3| image:: images/Template_Matching_Correl_Result_3.jpg
- :align: middle
-
- .. |Result_4| image:: images/Template_Matching_Correl_Result_4.jpg
- :align: middle
-
- .. |Result_5| image:: images/Template_Matching_Correl_Result_5.jpg
- :align: middle
-
-#. The right match is shown below (black rectangle around the face of the guy at the right). Notice that CCORR and CCDEFF gave erroneous best matches, however their normalized version did it right, this may be due to the fact that we are only considering the "highest match" and not the other possible high matches.
-
- .. image:: images/Template_Matching_Image_Result.jpg
- :align: center
+++ /dev/null
-.. _canny_detector:
-
-Canny Edge Detector
-********************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :canny:`Canny <>` to implement the Canny Edge Detector.
-
-Theory
-=======
-
-#. The *Canny Edge detector* was developed by John F. Canny in 1986. Also known to many as the *optimal detector*, Canny algorithm aims to satisfy three main criteria:
-
- * **Low error rate:** Meaning a good detection of only existent edges.
- * **Good localization:** The distance between edge pixels detected and real edge pixels have to be minimized.
- * **Minimal response:** Only one detector response per edge.
-
-Steps
-------
-
-#. Filter out any noise. The Gaussian filter is used for this purpose. An example of a Gaussian kernel of :math:`size = 5` that might be used is shown below:
-
- .. math::
-
- K = \dfrac{1}{159}\begin{bmatrix}
- 2 & 4 & 5 & 4 & 2 \\
- 4 & 9 & 12 & 9 & 4 \\
- 5 & 12 & 15 & 12 & 5 \\
- 4 & 9 & 12 & 9 & 4 \\
- 2 & 4 & 5 & 4 & 2
- \end{bmatrix}
-
-
-#. Find the intensity gradient of the image. For this, we follow a procedure analogous to Sobel:
-
- a. Apply a pair of convolution masks (in :math:`x` and :math:`y` directions:
-
- .. math::
-
- G_{x} = \begin{bmatrix}
- -1 & 0 & +1 \\
- -2 & 0 & +2 \\
- -1 & 0 & +1
- \end{bmatrix}
-
- G_{y} = \begin{bmatrix}
- -1 & -2 & -1 \\
- 0 & 0 & 0 \\
- +1 & +2 & +1
- \end{bmatrix}
-
- b. Find the gradient strength and direction with:
-
- .. math::
- \begin{array}{l}
- G = \sqrt{ G_{x}^{2} + G_{y}^{2} } \\
- \theta = \arctan(\dfrac{ G_{y} }{ G_{x} })
- \end{array}
-
- The direction is rounded to one of four possible angles (namely 0, 45, 90 or 135)
-
-#. *Non-maximum* suppression is applied. This removes pixels that are not considered to be part of an edge. Hence, only thin lines (candidate edges) will remain.
-
-#. *Hysteresis*: The final step. Canny does use two thresholds (upper and lower):
-
- a. If a pixel gradient is higher than the *upper* threshold, the pixel is accepted as an edge
- b. If a pixel gradient value is below the *lower* threshold, then it is rejected.
- c. If the pixel gradient is between the two thresholds, then it will be accepted only if it is connected to a pixel that is above the *upper* threshold.
-
- Canny recommended a *upper*:*lower* ratio between 2:1 and 3:1.
-
-#. For more details, you can always consult your favorite Computer Vision book.
-
-Code
-=====
-
-#. **What does this program do?**
-
- * Asks the user to enter a numerical value to set the lower threshold for our *Canny Edge Detector* (by means of a Trackbar)
- * Applies the *Canny Detector* and generates a **mask** (bright lines representing the edges on a black background).
- * Applies the mask obtained on the original image and display it in a window.
-
-#. The tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgTrans/CannyDetector_Demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
- #include <stdlib.h>
- #include <stdio.h>
-
- using namespace cv;
-
- /// Global variables
-
- Mat src, src_gray;
- Mat dst, detected_edges;
-
- int edgeThresh = 1;
- int lowThreshold;
- int const max_lowThreshold = 100;
- int ratio = 3;
- int kernel_size = 3;
- char* window_name = "Edge Map";
-
- /*
- * @function CannyThreshold
- * @brief Trackbar callback - Canny thresholds input with a ratio 1:3
- */
- void CannyThreshold(int, void*)
- {
- /// Reduce noise with a kernel 3x3
- blur( src_gray, detected_edges, Size(3,3) );
-
- /// Canny detector
- Canny( detected_edges, detected_edges, lowThreshold, lowThreshold*ratio, kernel_size );
-
- /// Using Canny's output as a mask, we display our result
- dst = Scalar::all(0);
-
- src.copyTo( dst, detected_edges);
- imshow( window_name, dst );
- }
-
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load an image
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
- /// Create a matrix of the same type and size as src (for dst)
- dst.create( src.size(), src.type() );
-
- /// Convert the image to grayscale
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
-
- /// Create a window
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
- /// Create a Trackbar for user to enter threshold
- createTrackbar( "Min Threshold:", window_name, &lowThreshold, max_lowThreshold, CannyThreshold );
-
- /// Show the image
- CannyThreshold(0, 0);
-
- /// Wait until user exit program by pressing a key
- waitKey(0);
-
- return 0;
- }
-
-Explanation
-============
-
-#. Create some needed variables:
-
- .. code-block:: cpp
-
- Mat src, src_gray;
- Mat dst, detected_edges;
-
- int edgeThresh = 1;
- int lowThreshold;
- int const max_lowThreshold = 100;
- int ratio = 3;
- int kernel_size = 3;
- char* window_name = "Edge Map";
-
- Note the following:
-
- a. We establish a ratio of lower:upper threshold of 3:1 (with the variable *ratio*)
- b. We set the kernel size of :math:`3` (for the Sobel operations to be performed internally by the Canny function)
- c. We set a maximum value for the lower Threshold of :math:`100`.
-
-
-#. Loads the source image:
-
- .. code-block:: cpp
-
- /// Load an image
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
-#. Create a matrix of the same type and size of *src* (to be *dst*)
-
- .. code-block:: cpp
-
- dst.create( src.size(), src.type() );
-
-#. Convert the image to grayscale (using the function :cvt_color:`cvtColor <>`:
-
- .. code-block:: cpp
-
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
-
-#. Create a window to display the results
-
- .. code-block:: cpp
-
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
-#. Create a Trackbar for the user to enter the lower threshold for our Canny detector:
-
- .. code-block:: cpp
-
- createTrackbar( "Min Threshold:", window_name, &lowThreshold, max_lowThreshold, CannyThreshold );
-
- Observe the following:
-
- a. The variable to be controlled by the Trackbar is *lowThreshold* with a limit of *max_lowThreshold* (which we set to 100 previously)
- b. Each time the Trackbar registers an action, the callback function *CannyThreshold* will be invoked.
-
-#. Let's check the *CannyThreshold* function, step by step:
-
- a. First, we blur the image with a filter of kernel size 3:
-
- .. code-block:: cpp
-
- blur( src_gray, detected_edges, Size(3,3) );
-
- b. Second, we apply the OpenCV function :canny:`Canny <>`:
-
- .. code-block:: cpp
-
- Canny( detected_edges, detected_edges, lowThreshold, lowThreshold*ratio, kernel_size );
-
- where the arguments are:
-
- * *detected_edges*: Source image, grayscale
- * *detected_edges*: Output of the detector (can be the same as the input)
- * *lowThreshold*: The value entered by the user moving the Trackbar
- * *highThreshold*: Set in the program as three times the lower threshold (following Canny's recommendation)
- * *kernel_size*: We defined it to be 3 (the size of the Sobel kernel to be used internally)
-
-#. We fill a *dst* image with zeros (meaning the image is completely black).
-
- .. code-block:: cpp
-
- dst = Scalar::all(0);
-
-#. Finally, we will use the function :copy_to:`copyTo <>` to map only the areas of the image that are identified as edges (on a black background).
-
- .. code-block:: cpp
-
- src.copyTo( dst, detected_edges);
-
- :copy_to:`copyTo <>` copy the *src* image onto *dst*. However, it will only copy the pixels in the locations where they have non-zero values. Since the output of the Canny detector is the edge contours on a black background, the resulting *dst* will be black in all the area but the detected edges.
-
-#. We display our result:
-
- .. code-block:: cpp
-
- imshow( window_name, dst );
-
-Result
-=======
-
-* After compiling the code above, we can run it giving as argument the path to an image. For example, using as an input the following image:
-
- .. image:: images/Canny_Detector_Tutorial_Original_Image.jpg
- :alt: Original test image
- :width: 200pt
- :align: center
-
-* Moving the slider, trying different threshold, we obtain the following result:
-
- .. image:: images/Canny_Detector_Tutorial_Result.jpg
- :alt: Result after running Canny
- :width: 200pt
- :align: center
-
-* Notice how the image is superposed to the black background on the edge regions.
+++ /dev/null
-.. _copyMakeBorderTutorial:
-
-Adding borders to your images
-******************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :copy_make_border:`copyMakeBorder <>` to set the borders (extra padding to your image).
-
-Theory
-========
-
-.. note::
- The explanation below belongs to the book **Learning OpenCV** by Bradski and Kaehler.
-
-
-#. In our previous tutorial we learned to use convolution to operate on images. One problem that naturally arises is how to handle the boundaries. How can we convolve them if the evaluated points are at the edge of the image?
-
-#. What most of OpenCV functions do is to copy a given image onto another slightly larger image and then automatically pads the boundary (by any of the methods explained in the sample code just below). This way, the convolution can be performed over the needed pixels without problems (the extra padding is cut after the operation is done).
-
-#. In this tutorial, we will briefly explore two ways of defining the extra padding (border) for an image:
-
- a. **BORDER_CONSTANT**: Pad the image with a constant value (i.e. black or :math:`0`
-
- b. **BORDER_REPLICATE**: The row or column at the very edge of the original is replicated to the extra border.
-
- This will be seen more clearly in the Code section.
-
-
-
-Code
-======
-
-#. **What does this program do?**
-
- * Load an image
- * Let the user choose what kind of padding use in the input image. There are two options:
-
- #. *Constant value border*: Applies a padding of a constant value for the whole border. This value will be updated randomly each 0.5 seconds.
- #. *Replicated border*: The border will be replicated from the pixel values at the edges of the original image.
-
- The user chooses either option by pressing 'c' (constant) or 'r' (replicate)
- * The program finishes when the user presses 'ESC'
-
-#. The tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgTrans/copyMakeBorder_demo.cpp>`_
-
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
- #include <stdlib.h>
- #include <stdio.h>
-
- using namespace cv;
-
- /// Global Variables
- Mat src, dst;
- int top, bottom, left, right;
- int borderType;
- Scalar value;
- char* window_name = "copyMakeBorder Demo";
- RNG rng(12345);
-
- /* @function main */
- int main( int argc, char** argv )
- {
-
- int c;
-
- /// Load an image
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1;
- printf(" No data entered, please enter the path to an image file \n");
- }
-
- /// Brief how-to for this program
- printf( "\n \t copyMakeBorder Demo: \n" );
- printf( "\t -------------------- \n" );
- printf( " ** Press 'c' to set the border to a random constant value \n");
- printf( " ** Press 'r' to set the border to be replicated \n");
- printf( " ** Press 'ESC' to exit the program \n");
-
- /// Create window
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
- /// Initialize arguments for the filter
- top = (int) (0.05*src.rows); bottom = (int) (0.05*src.rows);
- left = (int) (0.05*src.cols); right = (int) (0.05*src.cols);
- dst = src;
-
- imshow( window_name, dst );
-
- while( true )
- {
- c = waitKey(500);
-
- if( (char)c == 27 )
- { break; }
- else if( (char)c == 'c' )
- { borderType = BORDER_CONSTANT; }
- else if( (char)c == 'r' )
- { borderType = BORDER_REPLICATE; }
-
- value = Scalar( rng.uniform(0, 255), rng.uniform(0, 255), rng.uniform(0, 255) );
- copyMakeBorder( src, dst, top, bottom, left, right, borderType, value );
-
- imshow( window_name, dst );
- }
-
- return 0;
- }
-
-
-Explanation
-=============
-
-#. First we declare the variables we are going to use:
-
- .. code-block:: cpp
-
- Mat src, dst;
- int top, bottom, left, right;
- int borderType;
- Scalar value;
- char* window_name = "copyMakeBorder Demo";
- RNG rng(12345);
-
- Especial attention deserves the variable *rng* which is a random number generator. We use it to generate the random border color, as we will see soon.
-
-#. As usual we load our source image *src*:
-
- .. code-block:: cpp
-
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1;
- printf(" No data entered, please enter the path to an image file \n");
- }
-
-#. After giving a short intro of how to use the program, we create a window:
-
- .. code-block:: cpp
-
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
-#. Now we initialize the argument that defines the size of the borders (*top*, *bottom*, *left* and *right*). We give them a value of 5% the size of *src*.
-
- .. code-block:: cpp
-
- top = (int) (0.05*src.rows); bottom = (int) (0.05*src.rows);
- left = (int) (0.05*src.cols); right = (int) (0.05*src.cols);
-
-#. The program begins a *while* loop. If the user presses 'c' or 'r', the *borderType* variable takes the value of *BORDER_CONSTANT* or *BORDER_REPLICATE* respectively:
-
- .. code-block:: cpp
-
- while( true )
- {
- c = waitKey(500);
-
- if( (char)c == 27 )
- { break; }
- else if( (char)c == 'c' )
- { borderType = BORDER_CONSTANT; }
- else if( (char)c == 'r' )
- { borderType = BORDER_REPLICATE; }
-
-#. In each iteration (after 0.5 seconds), the variable *value* is updated...
-
- .. code-block:: cpp
-
- value = Scalar( rng.uniform(0, 255), rng.uniform(0, 255), rng.uniform(0, 255) );
-
- with a random value generated by the **RNG** variable *rng*. This value is a number picked randomly in the range :math:`[0,255]`
-
-#. Finally, we call the function :copy_make_border:`copyMakeBorder <>` to apply the respective padding:
-
- .. code-block:: cpp
-
- copyMakeBorder( src, dst, top, bottom, left, right, borderType, value );
-
- The arguments are:
-
- a. *src*: Source image
- #. *dst*: Destination image
- #. *top*, *bottom*, *left*, *right*: Length in pixels of the borders at each side of the image. We define them as being 5% of the original size of the image.
- #. *borderType*: Define what type of border is applied. It can be constant or replicate for this example.
- #. *value*: If *borderType* is *BORDER_CONSTANT*, this is the value used to fill the border pixels.
-
-#. We display our output image in the image created previously
-
- .. code-block:: cpp
-
- imshow( window_name, dst );
-
-
-
-
-Results
-========
-
-#. After compiling the code above, you can execute it giving as argument the path of an image. The result should be:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * By default, it begins with the border set to BORDER_CONSTANT. Hence, a succession of random colored borders will be shown.
- * If you press 'r', the border will become a replica of the edge pixels.
- * If you press 'c', the random colored borders will appear again
- * If you press 'ESC' the program will exit.
-
- Below some screenshot showing how the border changes color and how the *BORDER_REPLICATE* option looks:
-
-
- .. image:: images/CopyMakeBorder_Tutorial_Results.jpg
- :alt: Final result after copyMakeBorder application
- :width: 750pt
- :align: center
+++ /dev/null
-.. _filter_2d:
-
-Making your own linear filters!
-********************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :filter2d:`filter2D <>` to create your own linear filters.
-
-Theory
-=======
-
-.. note::
- The explanation below belongs to the book **Learning OpenCV** by Bradski and Kaehler.
-
-
-Convolution
-------------
-In a very general sense, convolution is an operation between every part of an image and an operator (kernel).
-
-What is a kernel?
-------------------
-A kernel is essentially a fixed size array of numerical coefficeints along with an *anchor point* in that array, which is tipically located at the center.
-
-.. image:: images/filter_2d_tutorial_kernel_theory.png
- :alt: kernel example
- :align: center
-
-How does convolution with a kernel work?
------------------------------------------
-
-Assume you want to know the resulting value of a particular location in the image. The value of the convolution is calculated in the following way:
-
-#. Place the kernel anchor on top of a determined pixel, with the rest of the kernel overlaying the corresponding local pixels in the image.
-
-#. Multiply the kernel coefficients by the corresponding image pixel values and sum the result.
-
-#. Place the result to the location of the *anchor* in the input image.
-
-#. Repeat the process for all pixels by scanning the kernel over the entire image.
-
-Expressing the procedure above in the form of an equation we would have:
-
-.. math::
-
- H(x,y) = \sum_{i=0}^{M_{i} - 1} \sum_{j=0}^{M_{j}-1} I(x+i - a_{i}, y + j - a_{j})K(i,j)
-
-Fortunately, OpenCV provides you with the function :filter2d:`filter2D <>` so you do not have to code all these operations.
-
-Code
-======
-
-#. **What does this program do?**
-
- * Loads an image
- * Performs a *normalized box filter*. For instance, for a kernel of size :math:`size = 3`, the kernel would be:
-
- .. math::
-
- K = \dfrac{1}{3 \cdot 3} \begin{bmatrix}
- 1 & 1 & 1 \\
- 1 & 1 & 1 \\
- 1 & 1 & 1
- \end{bmatrix}
-
- The program will perform the filter operation with kernels of sizes 3, 5, 7, 9 and 11.
-
- * The filter output (with each kernel) will be shown during 500 milliseconds
-
-#. The tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgTrans/filter2D_demo.cpp>`_
-
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
- #include <stdlib.h>
- #include <stdio.h>
-
- using namespace cv;
-
- /* @function main */
- int main ( int argc, char** argv )
- {
- /// Declare variables
- Mat src, dst;
-
- Mat kernel;
- Point anchor;
- double delta;
- int ddepth;
- int kernel_size;
- char* window_name = "filter2D Demo";
-
- int c;
-
- /// Load an image
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
- /// Create window
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
- /// Initialize arguments for the filter
- anchor = Point( -1, -1 );
- delta = 0;
- ddepth = -1;
-
- /// Loop - Will filter the image with different kernel sizes each 0.5 seconds
- int ind = 0;
- while( true )
- {
- c = waitKey(500);
- /// Press 'ESC' to exit the program
- if( (char)c == 27 )
- { break; }
-
- /// Update kernel size for a normalized box filter
- kernel_size = 3 + 2*( ind%5 );
- kernel = Mat::ones( kernel_size, kernel_size, CV_32F )/ (float)(kernel_size*kernel_size);
-
- /// Apply filter
- filter2D(src, dst, ddepth , kernel, anchor, delta, BORDER_DEFAULT );
- imshow( window_name, dst );
- ind++;
- }
-
- return 0;
- }
-
-Explanation
-=============
-
-#. Load an image
-
- .. code-block:: cpp
-
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
-#. Create a window to display the result
-
- .. code-block:: cpp
-
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
-#. Initialize the arguments for the linear filter
-
- .. code-block:: cpp
-
- anchor = Point( -1, -1 );
- delta = 0;
- ddepth = -1;
-
-
-#. Perform an infinite loop updating the kernel size and applying our linear filter to the input image. Let's analyze that more in detail:
-
-#. First we define the kernel our filter is going to use. Here it is:
-
- .. code-block:: cpp
-
- kernel_size = 3 + 2*( ind%5 );
- kernel = Mat::ones( kernel_size, kernel_size, CV_32F )/ (float)(kernel_size*kernel_size);
-
- The first line is to update the *kernel_size* to odd values in the range: :math:`[3,11]`. The second line actually builds the kernel by setting its value to a matrix filled with :math:`1's` and normalizing it by dividing it between the number of elements.
-
-#. After setting the kernel, we can generate the filter by using the function :filter2d:`filter2D <>`:
-
- .. code-block:: cpp
-
- filter2D(src, dst, ddepth , kernel, anchor, delta, BORDER_DEFAULT );
-
- The arguments denote:
-
- a. *src*: Source image
- #. *dst*: Destination image
- #. *ddepth*: The depth of *dst*. A negative value (such as :math:`-1`) indicates that the depth is the same as the source.
- #. *kernel*: The kernel to be scanned through the image
- #. *anchor*: The position of the anchor relative to its kernel. The location *Point(-1, -1)* indicates the center by default.
- #. *delta*: A value to be added to each pixel during the convolution. By default it is :math:`0`
- #. *BORDER_DEFAULT*: We let this value by default (more details in the following tutorial)
-
-#. Our program will effectuate a *while* loop, each 500 ms the kernel size of our filter will be updated in the range indicated.
-
-Results
-========
-
-#. After compiling the code above, you can execute it giving as argument the path of an image. The result should be a window that shows an image blurred by a normalized filter. Each 0.5 seconds the kernel size should change, as can be seen in the series of snapshots below:
-
- .. image:: images/filter_2d_tutorial_result.jpg
- :alt: kernel example
- :align: center
+++ /dev/null
-.. _hough_circle:
-
-Hough Circle Transform
-***********************
-
-Goal
-=====
-In this tutorial you will learn how to:
-
-* Use the OpenCV function :hough_circles:`HoughCircles <>` to detect circles in an image.
-
-Theory
-=======
-
-Hough Circle Transform
-------------------------
-
-* The Hough Circle Transform works in a *roughly* analogous way to the Hough Line Transform explained in the previous tutorial.
-* In the line detection case, a line was defined by two parameters :math:`(r, \theta)`. In the circle case, we need three parameters to define a circle:
-
- .. math::
-
- C : ( x_{center}, y_{center}, r )
-
- where :math:`(x_{center}, y_{center})` define the center position (green point) and :math:`r` is the radius, which allows us to completely define a circle, as it can be seen below:
-
- .. image:: images/Hough_Circle_Tutorial_Theory_0.jpg
- :alt: Result of detecting circles with Hough Transform
- :align: center
-
-* For sake of efficiency, OpenCV implements a detection method slightly trickier than the standard Hough Transform: *The Hough gradient method*, which is made up of two main stages. The first stage involves edge detection and finding the possible circle centers and the second stage finds the best radius for each candidate center. For more details, please check the book *Learning OpenCV* or your favorite Computer Vision bibliography
-
-Code
-======
-
-#. **What does this program do?**
-
- * Loads an image and blur it to reduce the noise
- * Applies the *Hough Circle Transform* to the blurred image .
- * Display the detected circle in a window.
-
- .. |TutorialHoughCirclesSimpleDownload| replace:: here
- .. _TutorialHoughCirclesSimpleDownload: https://github.com/Itseez/opencv/tree/master/samples/cpp/houghcircles.cpp
- .. |TutorialHoughCirclesFancyDownload| replace:: here
- .. _TutorialHoughCirclesFancyDownload: https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgTrans/HoughCircle_Demo.cpp
-
-#. The sample code that we will explain can be downloaded from |TutorialHoughCirclesSimpleDownload|_. A slightly fancier version (which shows trackbars for changing the threshold values) can be found |TutorialHoughCirclesFancyDownload|_.
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
-
- using namespace cv;
-
- /* @function main */
- int main(int argc, char** argv)
- {
- Mat src, src_gray;
-
- /// Read the image
- src = imread( argv[1], 1 );
-
- if( !src.data )
- { return -1; }
-
- /// Convert it to gray
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
-
- /// Reduce the noise so we avoid false circle detection
- GaussianBlur( src_gray, src_gray, Size(9, 9), 2, 2 );
-
- vector<Vec3f> circles;
-
- /// Apply the Hough Transform to find the circles
- HoughCircles( src_gray, circles, HOUGH_GRADIENT, 1, src_gray.rows/8, 200, 100, 0, 0 );
-
- /// Draw the circles detected
- for( size_t i = 0; i < circles.size(); i++ )
- {
- Point center(cvRound(circles[i][0]), cvRound(circles[i][1]));
- int radius = cvRound(circles[i][2]);
- // circle center
- circle( src, center, 3, Scalar(0,255,0), -1, 8, 0 );
- // circle outline
- circle( src, center, radius, Scalar(0,0,255), 3, 8, 0 );
- }
-
- /// Show your results
- namedWindow( "Hough Circle Transform Demo", WINDOW_AUTOSIZE );
- imshow( "Hough Circle Transform Demo", src );
-
- waitKey(0);
- return 0;
- }
-
-
-Explanation
-============
-
-
-#. Load an image
-
- .. code-block:: cpp
-
- src = imread( argv[1], 1 );
-
- if( !src.data )
- { return -1; }
-
-#. Convert it to grayscale:
-
- .. code-block:: cpp
-
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
-
-#. Apply a Gaussian blur to reduce noise and avoid false circle detection:
-
- .. code-block:: cpp
-
- GaussianBlur( src_gray, src_gray, Size(9, 9), 2, 2 );
-
-#. Proceed to apply Hough Circle Transform:
-
- .. code-block:: cpp
-
- vector<Vec3f> circles;
-
- HoughCircles( src_gray, circles, HOUGH_GRADIENT, 1, src_gray.rows/8, 200, 100, 0, 0 );
-
- with the arguments:
-
- * *src_gray*: Input image (grayscale).
- * *circles*: A vector that stores sets of 3 values: :math:`x_{c}, y_{c}, r` for each detected circle.
- * *HOUGH_GRADIENT*: Define the detection method. Currently this is the only one available in OpenCV.
- * *dp = 1*: The inverse ratio of resolution.
- * *min_dist = src_gray.rows/8*: Minimum distance between detected centers.
- * *param_1 = 200*: Upper threshold for the internal Canny edge detector.
- * *param_2* = 100*: Threshold for center detection.
- * *min_radius = 0*: Minimum radio to be detected. If unknown, put zero as default.
- * *max_radius = 0*: Maximum radius to be detected. If unknown, put zero as default.
-
-#. Draw the detected circles:
-
- .. code-block:: cpp
-
- for( size_t i = 0; i < circles.size(); i++ )
- {
- Point center(cvRound(circles[i][0]), cvRound(circles[i][1]));
- int radius = cvRound(circles[i][2]);
- // circle center
- circle( src, center, 3, Scalar(0,255,0), -1, 8, 0 );
- // circle outline
- circle( src, center, radius, Scalar(0,0,255), 3, 8, 0 );
- }
-
- You can see that we will draw the circle(s) on red and the center(s) with a small green dot
-
-#. Display the detected circle(s):
-
- .. code-block:: cpp
-
- namedWindow( "Hough Circle Transform Demo", WINDOW_AUTOSIZE );
- imshow( "Hough Circle Transform Demo", src );
-
-#. Wait for the user to exit the program
-
- .. code-block:: cpp
-
- waitKey(0);
-
-
-Result
-=======
-
-The result of running the code above with a test image is shown below:
-
-.. image:: images/Hough_Circle_Tutorial_Result.jpg
- :alt: Result of detecting circles with Hough Transform
- :align: center
+++ /dev/null
-.. _hough_lines:
-
-Hough Line Transform
-*********************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-* Use the OpenCV functions :hough_lines:`HoughLines <>` and :hough_lines_p:`HoughLinesP <>` to detect lines in an image.
-
-Theory
-=======
-
-.. note::
- The explanation below belongs to the book **Learning OpenCV** by Bradski and Kaehler.
-
-Hough Line Transform
----------------------
-#. The Hough Line Transform is a transform used to detect straight lines.
-#. To apply the Transform, first an edge detection pre-processing is desirable.
-
-How does it work?
-^^^^^^^^^^^^^^^^^^
-
-#. As you know, a line in the image space can be expressed with two variables. For example:
-
- a. In the **Cartesian coordinate system:** Parameters: :math:`(m,b)`.
- b. In the **Polar coordinate system:** Parameters: :math:`(r,\theta)`
-
- .. image:: images/Hough_Lines_Tutorial_Theory_0.jpg
- :alt: Line variables
- :align: center
-
- For Hough Transforms, we will express lines in the *Polar system*. Hence, a line equation can be written as:
-
- .. math::
-
- y = \left ( -\dfrac{\cos \theta}{\sin \theta} \right ) x + \left ( \dfrac{r}{\sin \theta} \right )
-
- Arranging the terms: :math:`r = x \cos \theta + y \sin \theta`
-
-#. In general for each point :math:`(x_{0}, y_{0})`, we can define the family of lines that goes through that point as:
-
- .. math::
-
- r_{\theta} = x_{0} \cdot \cos \theta + y_{0} \cdot \sin \theta
-
- Meaning that each pair :math:`(r_{\theta},\theta)` represents each line that passes by :math:`(x_{0}, y_{0})`.
-
-#. If for a given :math:`(x_{0}, y_{0})` we plot the family of lines that goes through it, we get a sinusoid. For instance, for :math:`x_{0} = 8` and :math:`y_{0} = 6` we get the following plot (in a plane :math:`\theta` - :math:`r`):
-
- .. image:: images/Hough_Lines_Tutorial_Theory_1.jpg
- :alt: Polar plot of a the family of lines of a point
- :align: center
-
- We consider only points such that :math:`r > 0` and :math:`0< \theta < 2 \pi`.
-
-#. We can do the same operation above for all the points in an image. If the curves of two different points intersect in the plane :math:`\theta` - :math:`r`, that means that both points belong to a same line. For instance, following with the example above and drawing the plot for two more points: :math:`x_{1} = 9`, :math:`y_{1} = 4` and :math:`x_{2} = 12`, :math:`y_{2} = 3`, we get:
-
- .. image:: images/Hough_Lines_Tutorial_Theory_2.jpg
- :alt: Polar plot of the family of lines for three points
- :align: center
-
- The three plots intersect in one single point :math:`(0.925, 9.6)`, these coordinates are the parameters (:math:`\theta, r`) or the line in which :math:`(x_{0}, y_{0})`, :math:`(x_{1}, y_{1})` and :math:`(x_{2}, y_{2})` lay.
-
-#. What does all the stuff above mean? It means that in general, a line can be *detected* by finding the number of intersections between curves.The more curves intersecting means that the line represented by that intersection have more points. In general, we can define a *threshold* of the minimum number of intersections needed to *detect* a line.
-
-#. This is what the Hough Line Transform does. It keeps track of the intersection between curves of every point in the image. If the number of intersections is above some *threshold*, then it declares it as a line with the parameters :math:`(\theta, r_{\theta})` of the intersection point.
-
-Standard and Probabilistic Hough Line Transform
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-OpenCV implements two kind of Hough Line Transforms:
-
-a. **The Standard Hough Transform**
-
- * It consists in pretty much what we just explained in the previous section. It gives you as result a vector of couples :math:`(\theta, r_{\theta})`
-
- * In OpenCV it is implemented with the function :hough_lines:`HoughLines <>`
-
-b. **The Probabilistic Hough Line Transform**
-
- * A more efficient implementation of the Hough Line Transform. It gives as output the extremes of the detected lines :math:`(x_{0}, y_{0}, x_{1}, y_{1})`
-
- * In OpenCV it is implemented with the function :hough_lines_p:`HoughLinesP <>`
-
-Code
-======
-
-.. |TutorialHoughLinesSimpleDownload| replace:: here
-.. _TutorialHoughLinesSimpleDownload: https://github.com/Itseez/opencv/tree/master/samples/cpp/houghlines.cpp
-.. |TutorialHoughLinesFancyDownload| replace:: here
-.. _TutorialHoughLinesFancyDownload: https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgTrans/HoughLines_Demo.cpp
-
-
-#. **What does this program do?**
-
- * Loads an image
- * Applies either a *Standard Hough Line Transform* or a *Probabilistic Line Transform*.
- * Display the original image and the detected line in two windows.
-
-#. The sample code that we will explain can be downloaded from |TutorialHoughLinesSimpleDownload|_. A slightly fancier version (which shows both Hough standard and probabilistic with trackbars for changing the threshold values) can be found |TutorialHoughLinesFancyDownload|_.
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
-
- #include <iostream>
-
- using namespace cv;
- using namespace std;
-
- void help()
- {
- cout << "\nThis program demonstrates line finding with the Hough transform.\n"
- "Usage:\n"
- "./houghlines <image_name>, Default is pic1.jpg\n" << endl;
- }
-
- int main(int argc, char** argv)
- {
- const char* filename = argc >= 2 ? argv[1] : "pic1.jpg";
-
- Mat src = imread(filename, 0);
- if(src.empty())
- {
- help();
- cout << "can not open " << filename << endl;
- return -1;
- }
-
- Mat dst, cdst;
- Canny(src, dst, 50, 200, 3);
- cvtColor(dst, cdst, COLOR_GRAY2BGR);
-
- #if 0
- vector<Vec2f> lines;
- HoughLines(dst, lines, 1, CV_PI/180, 100, 0, 0 );
-
- for( size_t i = 0; i < lines.size(); i++ )
- {
- float rho = lines[i][0], theta = lines[i][1];
- Point pt1, pt2;
- double a = cos(theta), b = sin(theta);
- double x0 = a*rho, y0 = b*rho;
- pt1.x = cvRound(x0 + 1000*(-b));
- pt1.y = cvRound(y0 + 1000*(a));
- pt2.x = cvRound(x0 - 1000*(-b));
- pt2.y = cvRound(y0 - 1000*(a));
- line( cdst, pt1, pt2, Scalar(0,0,255), 3, LINE_AA);
- }
- #else
- vector<Vec4i> lines;
- HoughLinesP(dst, lines, 1, CV_PI/180, 50, 50, 10 );
- for( size_t i = 0; i < lines.size(); i++ )
- {
- Vec4i l = lines[i];
- line( cdst, Point(l[0], l[1]), Point(l[2], l[3]), Scalar(0,0,255), 3, CV_AA);
- }
- #endif
- imshow("source", src);
- imshow("detected lines", cdst);
-
- waitKey();
-
- return 0;
- }
-
-Explanation
-=============
-
-#. Load an image
-
- .. code-block:: cpp
-
- Mat src = imread(filename, 0);
- if(src.empty())
- {
- help();
- cout << "can not open " << filename << endl;
- return -1;
- }
-
-#. Detect the edges of the image by using a Canny detector
-
- .. code-block:: cpp
-
- Canny(src, dst, 50, 200, 3);
-
- Now we will apply the Hough Line Transform. We will explain how to use both OpenCV functions available for this purpose:
-
-#. **Standard Hough Line Transform**
-
- a. First, you apply the Transform:
-
- .. code-block:: cpp
-
- vector<Vec2f> lines;
- HoughLines(dst, lines, 1, CV_PI/180, 100, 0, 0 );
-
- with the following arguments:
-
- * *dst*: Output of the edge detector. It should be a grayscale image (although in fact it is a binary one)
- * *lines*: A vector that will store the parameters :math:`(r,\theta)` of the detected lines
- * *rho* : The resolution of the parameter :math:`r` in pixels. We use **1** pixel.
- * *theta*: The resolution of the parameter :math:`\theta` in radians. We use **1 degree** (CV_PI/180)
- * *threshold*: The minimum number of intersections to "*detect*" a line
- * *srn* and *stn*: Default parameters to zero. Check OpenCV reference for more info.
-
- b. And then you display the result by drawing the lines.
-
- .. code-block:: cpp
-
- for( size_t i = 0; i < lines.size(); i++ )
- {
- float rho = lines[i][0], theta = lines[i][1];
- Point pt1, pt2;
- double a = cos(theta), b = sin(theta);
- double x0 = a*rho, y0 = b*rho;
- pt1.x = cvRound(x0 + 1000*(-b));
- pt1.y = cvRound(y0 + 1000*(a));
- pt2.x = cvRound(x0 - 1000*(-b));
- pt2.y = cvRound(y0 - 1000*(a));
- line( cdst, pt1, pt2, Scalar(0,0,255), 3, LINE_AA);
- }
-
-#. **Probabilistic Hough Line Transform**
-
- a. First you apply the transform:
-
- .. code-block:: cpp
-
- vector<Vec4i> lines;
- HoughLinesP(dst, lines, 1, CV_PI/180, 50, 50, 10 );
-
- with the arguments:
-
- * *dst*: Output of the edge detector. It should be a grayscale image (although in fact it is a binary one)
- * *lines*: A vector that will store the parameters :math:`(x_{start}, y_{start}, x_{end}, y_{end})` of the detected lines
- * *rho* : The resolution of the parameter :math:`r` in pixels. We use **1** pixel.
- * *theta*: The resolution of the parameter :math:`\theta` in radians. We use **1 degree** (CV_PI/180)
- * *threshold*: The minimum number of intersections to "*detect*" a line
- * *minLinLength*: The minimum number of points that can form a line. Lines with less than this number of points are disregarded.
- * *maxLineGap*: The maximum gap between two points to be considered in the same line.
-
- b. And then you display the result by drawing the lines.
-
- .. code-block:: cpp
-
- for( size_t i = 0; i < lines.size(); i++ )
- {
- Vec4i l = lines[i];
- line( cdst, Point(l[0], l[1]), Point(l[2], l[3]), Scalar(0,0,255), 3, LINE_AA);
- }
-
-
-#. Display the original image and the detected lines:
-
- .. code-block:: cpp
-
- imshow("source", src);
- imshow("detected lines", cdst);
-
-#. Wait until the user exits the program
-
- .. code-block:: cpp
-
- waitKey();
-
-
-Result
-=======
-
-.. note::
-
- The results below are obtained using the slightly fancier version we mentioned in the *Code* section. It still implements the same stuff as above, only adding the Trackbar for the Threshold.
-
-Using an input image such as:
-
-.. image:: images/Hough_Lines_Tutorial_Original_Image.jpg
- :alt: Result of detecting lines with Hough Transform
- :align: center
-
-We get the following result by using the Probabilistic Hough Line Transform:
-
-.. image:: images/Hough_Lines_Tutorial_Result.jpg
- :alt: Result of detecting lines with Hough Transform
- :align: center
-
-You may observe that the number of lines detected vary while you change the *threshold*. The explanation is sort of evident: If you establish a higher threshold, fewer lines will be detected (since you will need more points to declare a line detected).
+++ /dev/null
-.. _laplace_operator:
-
-Laplace Operator
-*****************
-
-Goal
-=====
-
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :laplacian:`Laplacian <>` to implement a discrete analog of the *Laplacian operator*.
-
-
-Theory
-=======
-
-#. In the previous tutorial we learned how to use the *Sobel Operator*. It was based on the fact that in the edge area, the pixel intensity shows a "jump" or a high variation of intensity. Getting the first derivative of the intensity, we observed that an edge is characterized by a maximum, as it can be seen in the figure:
-
- .. image:: images/Laplace_Operator_Tutorial_Theory_Previous.jpg
- :alt: Previous theory
- :align: center
-
-#. And...what happens if we take the second derivative?
-
- .. image:: images/Laplace_Operator_Tutorial_Theory_ddIntensity.jpg
- :alt: Second derivative
- :align: center
-
- You can observe that the second derivative is zero! So, we can also use this criterion to attempt to detect edges in an image. However, note that zeros will not only appear in edges (they can actually appear in other meaningless locations); this can be solved by applying filtering where needed.
-
-
-Laplacian Operator
--------------------
-
-#. From the explanation above, we deduce that the second derivative can be used to *detect edges*. Since images are "*2D*", we would need to take the derivative in both dimensions. Here, the Laplacian operator comes handy.
-
-#. The *Laplacian operator* is defined by:
-
- .. math::
-
- Laplace(f) = \dfrac{\partial^{2} f}{\partial x^{2}} + \dfrac{\partial^{2} f}{\partial y^{2}}
-
-#. The Laplacian operator is implemented in OpenCV by the function :laplacian:`Laplacian <>`. In fact, since the Laplacian uses the gradient of images, it calls internally the *Sobel* operator to perform its computation.
-
-Code
-======
-
-#. **What does this program do?**
-
- * Loads an image
- * Remove noise by applying a Gaussian blur and then convert the original image to grayscale
- * Applies a Laplacian operator to the grayscale image and stores the output image
- * Display the result in a window
-
-#. The tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgTrans/Laplace_Demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
- #include <stdlib.h>
- #include <stdio.h>
-
- using namespace cv;
-
- /* @function main */
- int main( int argc, char** argv )
- {
- Mat src, src_gray, dst;
- int kernel_size = 3;
- int scale = 1;
- int delta = 0;
- int ddepth = CV_16S;
- char* window_name = "Laplace Demo";
-
- int c;
-
- /// Load an image
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
- /// Remove noise by blurring with a Gaussian filter
- GaussianBlur( src, src, Size(3,3), 0, 0, BORDER_DEFAULT );
-
- /// Convert the image to grayscale
- cvtColor( src, src_gray, COLOR_RGB2GRAY );
-
- /// Create window
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
- /// Apply Laplace function
- Mat abs_dst;
-
- Laplacian( src_gray, dst, ddepth, kernel_size, scale, delta, BORDER_DEFAULT );
- convertScaleAbs( dst, abs_dst );
-
- /// Show what you got
- imshow( window_name, abs_dst );
-
- waitKey(0);
-
- return 0;
- }
-
-
-Explanation
-============
-
-#. Create some needed variables:
-
- .. code-block:: cpp
-
- Mat src, src_gray, dst;
- int kernel_size = 3;
- int scale = 1;
- int delta = 0;
- int ddepth = CV_16S;
- char* window_name = "Laplace Demo";
-
-#. Loads the source image:
-
- .. code-block:: cpp
-
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
-#. Apply a Gaussian blur to reduce noise:
-
- .. code-block:: cpp
-
- GaussianBlur( src, src, Size(3,3), 0, 0, BORDER_DEFAULT );
-
-#. Convert the image to grayscale using :cvt_color:`cvtColor <>`
-
- .. code-block:: cpp
-
- cvtColor( src, src_gray, COLOR_RGB2GRAY );
-
-#. Apply the Laplacian operator to the grayscale image:
-
- .. code-block:: cpp
-
- Laplacian( src_gray, dst, ddepth, kernel_size, scale, delta, BORDER_DEFAULT );
-
- where the arguments are:
-
- * *src_gray*: The input image.
- * *dst*: Destination (output) image
- * *ddepth*: Depth of the destination image. Since our input is *CV_8U* we define *ddepth* = *CV_16S* to avoid overflow
- * *kernel_size*: The kernel size of the Sobel operator to be applied internally. We use 3 in this example.
- * *scale*, *delta* and *BORDER_DEFAULT*: We leave them as default values.
-
-#. Convert the output from the Laplacian operator to a *CV_8U* image:
-
- .. code-block:: cpp
-
- convertScaleAbs( dst, abs_dst );
-
-#. Display the result in a window:
-
- .. code-block:: cpp
-
- imshow( window_name, abs_dst );
-
-
-Results
-========
-
-#. After compiling the code above, we can run it giving as argument the path to an image. For example, using as an input:
-
- .. image:: images/Laplace_Operator_Tutorial_Original_Image.jpg
- :alt: Original test image
- :width: 250pt
- :align: center
-
-#. We obtain the following result. Notice how the trees and the silhouette of the cow are approximately well defined (except in areas in which the intensity are very similar, i.e. around the cow's head). Also, note that the roof of the house behind the trees (right side) is notoriously marked. This is due to the fact that the contrast is higher in that region.
-
- .. image:: images/Laplace_Operator_Tutorial_Result.jpg
- :alt: Original test image
- :width: 250pt
- :align: center
+++ /dev/null
-.. _remap:
-
-Remapping
-*********
-
-Goal
-====
-
-In this tutorial you will learn how to:
-
-a. Use the OpenCV function :remap:`remap <>` to implement simple remapping routines.
-
-Theory
-======
-
-What is remapping?
-------------------
-
-* It is the process of taking pixels from one place in the image and locating them in another position in a new image.
-
-* To accomplish the mapping process, it might be necessary to do some interpolation for non-integer pixel locations, since there will not always be a one-to-one-pixel correspondence between source and destination images.
-
-* We can express the remap for every pixel location :math:`(x,y)` as:
-
- .. math::
-
- g(x,y) = f ( h(x,y) )
-
- where :math:`g()` is the remapped image, :math:`f()` the source image and :math:`h(x,y)` is the mapping function that operates on :math:`(x,y)`.
-
-* Let's think in a quick example. Imagine that we have an image :math:`I` and, say, we want to do a remap such that:
-
- .. math::
-
- h(x,y) = (I.cols - x, y )
-
- What would happen? It is easily seen that the image would flip in the :math:`x` direction. For instance, consider the input image:
-
- .. image:: images/Remap_Tutorial_Theory_0.jpg
- :alt: Original test image
- :width: 120pt
- :align: center
-
- observe how the red circle changes positions with respect to x (considering :math:`x` the horizontal direction):
-
- .. image:: images/Remap_Tutorial_Theory_1.jpg
- :alt: Original test image
- :width: 120pt
- :align: center
-
-* In OpenCV, the function :remap:`remap <>` offers a simple remapping implementation.
-
-Code
-====
-
-#. **What does this program do?**
-
- * Loads an image
- * Each second, apply 1 of 4 different remapping processes to the image and display them indefinitely in a window.
- * Wait for the user to exit the program
-
-#. The tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgTrans/Remap_Demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
-
- using namespace cv;
-
- /// Global variables
- Mat src, dst;
- Mat map_x, map_y;
- char* remap_window = "Remap demo";
- int ind = 0;
-
- /// Function Headers
- void update_map( void );
-
- /*
- * @function main
- */
- int main( int argc, char** argv )
- {
- /// Load the image
- src = imread( argv[1], 1 );
-
- /// Create dst, map_x and map_y with the same size as src:
- dst.create( src.size(), src.type() );
- map_x.create( src.size(), CV_32FC1 );
- map_y.create( src.size(), CV_32FC1 );
-
- /// Create window
- namedWindow( remap_window, WINDOW_AUTOSIZE );
-
- /// Loop
- while( true )
- {
- /// Each 1 sec. Press ESC to exit the program
- int c = waitKey( 1000 );
-
- if( (char)c == 27 )
- { break; }
-
- /// Update map_x & map_y. Then apply remap
- update_map();
- remap( src, dst, map_x, map_y, INTER_LINEAR, BORDER_CONSTANT, Scalar(0,0, 0) );
-
- /// Display results
- imshow( remap_window, dst );
- }
- return 0;
- }
-
- /*
- * @function update_map
- * @brief Fill the map_x and map_y matrices with 4 types of mappings
- */
- void update_map( void )
- {
- ind = ind%4;
-
- for( int j = 0; j < src.rows; j++ )
- { for( int i = 0; i < src.cols; i++ )
- {
- switch( ind )
- {
- case 0:
- if( i > src.cols*0.25 && i < src.cols*0.75 && j > src.rows*0.25 && j < src.rows*0.75 )
- {
- map_x.at<float>(j,i) = 2*( i - src.cols*0.25 ) + 0.5 ;
- map_y.at<float>(j,i) = 2*( j - src.rows*0.25 ) + 0.5 ;
- }
- else
- { map_x.at<float>(j,i) = 0 ;
- map_y.at<float>(j,i) = 0 ;
- }
- break;
- case 1:
- map_x.at<float>(j,i) = i ;
- map_y.at<float>(j,i) = src.rows - j ;
- break;
- case 2:
- map_x.at<float>(j,i) = src.cols - i ;
- map_y.at<float>(j,i) = j ;
- break;
- case 3:
- map_x.at<float>(j,i) = src.cols - i ;
- map_y.at<float>(j,i) = src.rows - j ;
- break;
- } // end of switch
- }
- }
- ind++;
- }
-
-Explanation
-===========
-
-#. Create some variables we will use:
-
- .. code-block:: cpp
-
- Mat src, dst;
- Mat map_x, map_y;
- char* remap_window = "Remap demo";
- int ind = 0;
-
-#. Load an image:
-
- .. code-block:: cpp
-
- src = imread( argv[1], 1 );
-
-#. Create the destination image and the two mapping matrices (for x and y )
-
- .. code-block:: cpp
-
- dst.create( src.size(), src.type() );
- map_x.create( src.size(), CV_32FC1 );
- map_y.create( src.size(), CV_32FC1 );
-
-#. Create a window to display results
-
- .. code-block:: cpp
-
- namedWindow( remap_window, WINDOW_AUTOSIZE );
-
-#. Establish a loop. Each 1000 ms we update our mapping matrices (*mat_x* and *mat_y*) and apply them to our source image:
-
- .. code-block:: cpp
-
- while( true )
- {
- /// Each 1 sec. Press ESC to exit the program
- int c = waitKey( 1000 );
-
- if( (char)c == 27 )
- { break; }
-
- /// Update map_x & map_y. Then apply remap
- update_map();
- remap( src, dst, map_x, map_y, INTER_LINEAR, BORDER_CONSTANT, Scalar(0,0, 0) );
-
- /// Display results
- imshow( remap_window, dst );
- }
-
- The function that applies the remapping is :remap:`remap <>`. We give the following arguments:
-
- * **src**: Source image
- * **dst**: Destination image of same size as *src*
- * **map_x**: The mapping function in the x direction. It is equivalent to the first component of :math:`h(i,j)`
- * **map_y**: Same as above, but in y direction. Note that *map_y* and *map_x* are both of the same size as *src*
- * **INTER_LINEAR**: The type of interpolation to use for non-integer pixels. This is by default.
- * **BORDER_CONSTANT**: Default
-
- How do we update our mapping matrices *mat_x* and *mat_y*? Go on reading:
-
-#. **Updating the mapping matrices:** We are going to perform 4 different mappings:
-
- a. Reduce the picture to half its size and will display it in the middle:
-
- .. math::
-
- h(i,j) = ( 2*i - src.cols/2 + 0.5, 2*j - src.rows/2 + 0.5)
-
- for all pairs :math:`(i,j)` such that: :math:`\dfrac{src.cols}{4}<i<\dfrac{3 \cdot src.cols}{4}` and :math:`\dfrac{src.rows}{4}<j<\dfrac{3 \cdot src.rows}{4}`
-
- b. Turn the image upside down: :math:`h( i, j ) = (i, src.rows - j)`
-
- c. Reflect the image from left to right: :math:`h(i,j) = ( src.cols - i, j )`
-
- d. Combination of b and c: :math:`h(i,j) = ( src.cols - i, src.rows - j )`
-
- This is expressed in the following snippet. Here, *map_x* represents the first coordinate of *h(i,j)* and *map_y* the second coordinate.
-
- .. code-block:: cpp
-
- for( int j = 0; j < src.rows; j++ )
- { for( int i = 0; i < src.cols; i++ )
- {
- switch( ind )
- {
- case 0:
- if( i > src.cols*0.25 && i < src.cols*0.75 && j > src.rows*0.25 && j < src.rows*0.75 )
- {
- map_x.at<float>(j,i) = 2*( i - src.cols*0.25 ) + 0.5 ;
- map_y.at<float>(j,i) = 2*( j - src.rows*0.25 ) + 0.5 ;
- }
- else
- { map_x.at<float>(j,i) = 0 ;
- map_y.at<float>(j,i) = 0 ;
- }
- break;
- case 1:
- map_x.at<float>(j,i) = i ;
- map_y.at<float>(j,i) = src.rows - j ;
- break;
- case 2:
- map_x.at<float>(j,i) = src.cols - i ;
- map_y.at<float>(j,i) = j ;
- break;
- case 3:
- map_x.at<float>(j,i) = src.cols - i ;
- map_y.at<float>(j,i) = src.rows - j ;
- break;
- } // end of switch
- }
- }
- ind++;
- }
-
-
-Result
-======
-
-#. After compiling the code above, you can execute it giving as argument an image path. For instance, by using the following image:
-
- .. image:: images/Remap_Tutorial_Original_Image.jpg
- :alt: Original test image
- :width: 250pt
- :align: center
-
-#. This is the result of reducing it to half the size and centering it:
-
- .. image:: images/Remap_Tutorial_Result_0.jpg
- :alt: Result 0 for remapping
- :width: 250pt
- :align: center
-
-#. Turning it upside down:
-
- .. image:: images/Remap_Tutorial_Result_1.jpg
- :alt: Result 0 for remapping
- :width: 250pt
- :align: center
-
-#. Reflecting it in the x direction:
-
- .. image:: images/Remap_Tutorial_Result_2.jpg
- :alt: Result 0 for remapping
- :width: 250pt
- :align: center
-
-#. Reflecting it in both directions:
-
-.. image:: images/Remap_Tutorial_Result_3.jpg
- :alt: Result 0 for remapping
- :width: 250pt
- :align: center
+++ /dev/null
-.. _sobel_derivatives:
-
-Sobel Derivatives
-******************
-
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :sobel:`Sobel <>` to calculate the derivatives from an image.
- * Use the OpenCV function :scharr:`Scharr <>` to calculate a more accurate derivative for a kernel of size :math:`3 \cdot 3`
-
-Theory
-========
-
-.. note::
- The explanation below belongs to the book **Learning OpenCV** by Bradski and Kaehler.
-
-
-#. In the last two tutorials we have seen applicative examples of convolutions. One of the most important convolutions is the computation of derivatives in an image (or an approximation to them).
-
-#. Why may be important the calculus of the derivatives in an image? Let's imagine we want to detect the *edges* present in the image. For instance:
-
-
- .. image:: images/Sobel_Derivatives_Tutorial_Theory_0.jpg
- :alt: How intensity changes in an edge
- :align: center
-
- You can easily notice that in an *edge*, the pixel intensity *changes* in a notorious way. A good way to express *changes* is by using *derivatives*. A high change in gradient indicates a major change in the image.
-
-#. To be more graphical, let's assume we have a 1D-image. An edge is shown by the "jump" in intensity in the plot below:
-
- .. image:: images/Sobel_Derivatives_Tutorial_Theory_Intensity_Function.jpg
- :alt: Intensity Plot for an edge
- :align: center
-
-#. The edge "jump" can be seen more easily if we take the first derivative (actually, here appears as a maximum)
-
- .. image:: images/Sobel_Derivatives_Tutorial_Theory_dIntensity_Function.jpg
- :alt: First derivative of Intensity - Plot for an edge
- :align: center
-
-#. So, from the explanation above, we can deduce that a method to detect edges in an image can be performed by locating pixel locations where the gradient is higher than its neighbors (or to generalize, higher than a threshold).
-
-#. More detailed explanation, please refer to **Learning OpenCV** by Bradski and Kaehler
-
-Sobel Operator
----------------
-
-#. The Sobel Operator is a discrete differentiation operator. It computes an approximation of the gradient of an image intensity function.
-
-#. The Sobel Operator combines Gaussian smoothing and differentiation.
-
-Formulation
-^^^^^^^^^^^^
-Assuming that the image to be operated is :math:`I`:
-
-#. We calculate two derivatives:
-
- a. **Horizontal changes**: This is computed by convolving :math:`I` with a kernel :math:`G_{x}` with odd size. For example for a kernel size of 3, :math:`G_{x}` would be computed as:
-
- .. math::
-
- G_{x} = \begin{bmatrix}
- -1 & 0 & +1 \\
- -2 & 0 & +2 \\
- -1 & 0 & +1
- \end{bmatrix} * I
-
- b. **Vertical changes**: This is computed by convolving :math:`I` with a kernel :math:`G_{y}` with odd size. For example for a kernel size of 3, :math:`G_{y}` would be computed as:
-
- .. math::
-
- G_{y} = \begin{bmatrix}
- -1 & -2 & -1 \\
- 0 & 0 & 0 \\
- +1 & +2 & +1
- \end{bmatrix} * I
-
-#. At each point of the image we calculate an approximation of the *gradient* in that point by combining both results above:
-
- .. math::
-
- G = \sqrt{ G_{x}^{2} + G_{y}^{2} }
-
- Although sometimes the following simpler equation is used:
-
- .. math::
-
- G = |G_{x}| + |G_{y}|
-
-
-.. note::
-
- When the size of the kernel is :math:`3`, the Sobel kernel shown above may produce noticeable inaccuracies (after all, Sobel is only an approximation of the derivative). OpenCV addresses this inaccuracy for kernels of size 3 by using the :scharr:`Scharr <>` function. This is as fast but more accurate than the standar Sobel function. It implements the following kernels:
-
- .. math::
-
- G_{x} = \begin{bmatrix}
- -3 & 0 & +3 \\
- -10 & 0 & +10 \\
- -3 & 0 & +3
- \end{bmatrix}
-
- G_{y} = \begin{bmatrix}
- -3 & -10 & -3 \\
- 0 & 0 & 0 \\
- +3 & +10 & +3
- \end{bmatrix}
-
- You can check out more information of this function in the OpenCV reference (:scharr:`Scharr <>`). Also, in the sample code below, you will notice that above the code for :sobel:`Sobel <>` function there is also code for the :scharr:`Scharr <>` function commented. Uncommenting it (and obviously commenting the Sobel stuff) should give you an idea of how this function works.
-
-Code
-=====
-
-#. **What does this program do?**
-
- * Applies the *Sobel Operator* and generates as output an image with the detected *edges* bright on a darker background.
-
-#. The tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgTrans/Sobel_Demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
- #include <stdlib.h>
- #include <stdio.h>
-
- using namespace cv;
-
- /* @function main */
- int main( int argc, char** argv )
- {
-
- Mat src, src_gray;
- Mat grad;
- char* window_name = "Sobel Demo - Simple Edge Detector";
- int scale = 1;
- int delta = 0;
- int ddepth = CV_16S;
-
- int c;
-
- /// Load an image
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
- GaussianBlur( src, src, Size(3,3), 0, 0, BORDER_DEFAULT );
-
- /// Convert it to gray
- cvtColor( src, src_gray, COLOR_RGB2GRAY );
-
- /// Create window
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
- /// Generate grad_x and grad_y
- Mat grad_x, grad_y;
- Mat abs_grad_x, abs_grad_y;
-
- /// Gradient X
- //Scharr( src_gray, grad_x, ddepth, 1, 0, scale, delta, BORDER_DEFAULT );
- Sobel( src_gray, grad_x, ddepth, 1, 0, 3, scale, delta, BORDER_DEFAULT );
- convertScaleAbs( grad_x, abs_grad_x );
-
- /// Gradient Y
- //Scharr( src_gray, grad_y, ddepth, 0, 1, scale, delta, BORDER_DEFAULT );
- Sobel( src_gray, grad_y, ddepth, 0, 1, 3, scale, delta, BORDER_DEFAULT );
- convertScaleAbs( grad_y, abs_grad_y );
-
- /// Total Gradient (approximate)
- addWeighted( abs_grad_x, 0.5, abs_grad_y, 0.5, 0, grad );
-
- imshow( window_name, grad );
-
- waitKey(0);
-
- return 0;
- }
-
-
-Explanation
-=============
-
-#. First we declare the variables we are going to use:
-
- .. code-block:: cpp
-
- Mat src, src_gray;
- Mat grad;
- char* window_name = "Sobel Demo - Simple Edge Detector";
- int scale = 1;
- int delta = 0;
- int ddepth = CV_16S;
-
-#. As usual we load our source image *src*:
-
- .. code-block:: cpp
-
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
-#. First, we apply a :gaussian_blur:`GaussianBlur <>` to our image to reduce the noise ( kernel size = 3 )
-
- .. code-block:: cpp
-
- GaussianBlur( src, src, Size(3,3), 0, 0, BORDER_DEFAULT );
-
-#. Now we convert our filtered image to grayscale:
-
- .. code-block:: cpp
-
- cvtColor( src, src_gray, COLOR_RGB2GRAY );
-
-#. Second, we calculate the "*derivatives*" in *x* and *y* directions. For this, we use the function :sobel:`Sobel <>` as shown below:
-
- .. code-block:: cpp
-
- Mat grad_x, grad_y;
- Mat abs_grad_x, abs_grad_y;
-
- /// Gradient X
- Sobel( src_gray, grad_x, ddepth, 1, 0, 3, scale, delta, BORDER_DEFAULT );
- /// Gradient Y
- Sobel( src_gray, grad_y, ddepth, 0, 1, 3, scale, delta, BORDER_DEFAULT );
-
- The function takes the following arguments:
-
- * *src_gray*: In our example, the input image. Here it is *CV_8U*
- * *grad_x*/*grad_y*: The output image.
- * *ddepth*: The depth of the output image. We set it to *CV_16S* to avoid overflow.
- * *x_order*: The order of the derivative in **x** direction.
- * *y_order*: The order of the derivative in **y** direction.
- * *scale*, *delta* and *BORDER_DEFAULT*: We use default values.
-
- Notice that to calculate the gradient in *x* direction we use: :math:`x_{order}= 1` and :math:`y_{order} = 0`. We do analogously for the *y* direction.
-
-#. We convert our partial results back to *CV_8U*:
-
- .. code-block:: cpp
-
- convertScaleAbs( grad_x, abs_grad_x );
- convertScaleAbs( grad_y, abs_grad_y );
-
-
-#. Finally, we try to approximate the *gradient* by adding both directional gradients (note that this is not an exact calculation at all! but it is good for our purposes).
-
- .. code-block:: cpp
-
- addWeighted( abs_grad_x, 0.5, abs_grad_y, 0.5, 0, grad );
-
-#. Finally, we show our result:
-
- .. code-block:: cpp
-
- imshow( window_name, grad );
-
-
-
-Results
-========
-
-#. Here is the output of applying our basic detector to *lena.jpg*:
-
-
- .. image:: images/Sobel_Derivatives_Tutorial_Result.jpg
- :alt: Result of applying Sobel operator to lena.jpg
- :width: 300pt
- :align: center
+++ /dev/null
-.. _warp_affine:
-
-Affine Transformations
-**********************
-
-
-Goal
-====
-
-In this tutorial you will learn how to:
-
-a. Use the OpenCV function :warp_affine:`warpAffine <>` to implement simple remapping routines.
-b. Use the OpenCV function :get_rotation_matrix_2d:`getRotationMatrix2D <>` to obtain a :math:`2 \times 3` rotation matrix
-
-
-Theory
-======
-
-What is an Affine Transformation?
-----------------------------------
-
-#. It is any transformation that can be expressed in the form of a *matrix multiplication* (linear transformation) followed by a *vector addition* (translation).
-
-#. From the above, We can use an Affine Transformation to express:
-
- a. Rotations (linear transformation)
- b. Translations (vector addition)
- c. Scale operations (linear transformation)
-
- you can see that, in essence, an Affine Transformation represents a **relation** between two images.
-
-#. The usual way to represent an Affine Transform is by using a :math:`2 \times 3` matrix.
-
- .. math::
-
- A = \begin{bmatrix}
- a_{00} & a_{01} \\
- a_{10} & a_{11}
- \end{bmatrix}_{2 \times 2}
- B = \begin{bmatrix}
- b_{00} \\
- b_{10}
- \end{bmatrix}_{2 \times 1}
-
- M = \begin{bmatrix}
- A & B
- \end{bmatrix}
- =
- \begin{bmatrix}
- a_{00} & a_{01} & b_{00} \\
- a_{10} & a_{11} & b_{10}
- \end{bmatrix}_{2 \times 3}
-
- Considering that we want to transform a 2D vector :math:`X = \begin{bmatrix}x \\ y\end{bmatrix}` by using :math:`A` and :math:`B`, we can do it equivalently with:
-
-
- :math:`T = A \cdot \begin{bmatrix}x \\ y\end{bmatrix} + B` or :math:`T = M \cdot [x, y, 1]^{T}`
-
- .. math::
-
- T = \begin{bmatrix}
- a_{00}x + a_{01}y + b_{00} \\
- a_{10}x + a_{11}y + b_{10}
- \end{bmatrix}
-
-
-How do we get an Affine Transformation?
----------------------------------------
-
-1. Excellent question. We mentioned that an Affine Transformation is basically a **relation** between two images. The information about this relation can come, roughly, in two ways:
-
- a. We know both :math:`X` and `T` and we also know that they are related. Then our job is to find :math:`M`
-
- b. We know :math:`M` and :math:`X`. To obtain :math:`T` we only need to apply :math:`T = M \cdot X`. Our information for :math:`M` may be explicit (i.e. have the 2-by-3 matrix) or it can come as a geometric relation between points.
-
-2. Let's explain a little bit better (b). Since :math:`M` relates 02 images, we can analyze the simplest case in which it relates three points in both images. Look at the figure below:
-
- .. image:: images/Warp_Affine_Tutorial_Theory_0.jpg
- :alt: Theory of Warp Affine
- :width: 350pt
- :align: center
-
- the points 1, 2 and 3 (forming a triangle in image 1) are mapped into image 2, still forming a triangle, but now they have changed notoriously. If we find the Affine Transformation with these 3 points (you can choose them as you like), then we can apply this found relation to the whole pixels in the image.
-
-
-Code
-====
-
-#. **What does this program do?**
-
- * Loads an image
- * Applies an Affine Transform to the image. This Transform is obtained from the relation between three points. We use the function :warp_affine:`warpAffine <>` for that purpose.
- * Applies a Rotation to the image after being transformed. This rotation is with respect to the image center
- * Waits until the user exits the program
-
-#. The tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgTrans/Geometric_Transforms_Demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
-
- using namespace cv;
- using namespace std;
-
- /// Global variables
- char* source_window = "Source image";
- char* warp_window = "Warp";
- char* warp_rotate_window = "Warp + Rotate";
-
- /* @function main */
- int main( int argc, char** argv )
- {
- Point2f srcTri[3];
- Point2f dstTri[3];
-
- Mat rot_mat( 2, 3, CV_32FC1 );
- Mat warp_mat( 2, 3, CV_32FC1 );
- Mat src, warp_dst, warp_rotate_dst;
-
- /// Load the image
- src = imread( argv[1], 1 );
-
- /// Set the dst image the same type and size as src
- warp_dst = Mat::zeros( src.rows, src.cols, src.type() );
-
- /// Set your 3 points to calculate the Affine Transform
- srcTri[0] = Point2f( 0,0 );
- srcTri[1] = Point2f( src.cols - 1, 0 );
- srcTri[2] = Point2f( 0, src.rows - 1 );
-
- dstTri[0] = Point2f( src.cols*0.0, src.rows*0.33 );
- dstTri[1] = Point2f( src.cols*0.85, src.rows*0.25 );
- dstTri[2] = Point2f( src.cols*0.15, src.rows*0.7 );
-
- /// Get the Affine Transform
- warp_mat = getAffineTransform( srcTri, dstTri );
-
- /// Apply the Affine Transform just found to the src image
- warpAffine( src, warp_dst, warp_mat, warp_dst.size() );
-
- /* Rotating the image after Warp */
-
- /// Compute a rotation matrix with respect to the center of the image
- Point center = Point( warp_dst.cols/2, warp_dst.rows/2 );
- double angle = -50.0;
- double scale = 0.6;
-
- /// Get the rotation matrix with the specifications above
- rot_mat = getRotationMatrix2D( center, angle, scale );
-
- /// Rotate the warped image
- warpAffine( warp_dst, warp_rotate_dst, rot_mat, warp_dst.size() );
-
- /// Show what you got
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, src );
-
- namedWindow( warp_window, WINDOW_AUTOSIZE );
- imshow( warp_window, warp_dst );
-
- namedWindow( warp_rotate_window, WINDOW_AUTOSIZE );
- imshow( warp_rotate_window, warp_rotate_dst );
-
- /// Wait until user exits the program
- waitKey(0);
-
- return 0;
- }
-
-Explanation
-===========
-
-#. Declare some variables we will use, such as the matrices to store our results and 2 arrays of points to store the 2D points that define our Affine Transform.
-
- .. code-block:: cpp
-
- Point2f srcTri[3];
- Point2f dstTri[3];
-
- Mat rot_mat( 2, 3, CV_32FC1 );
- Mat warp_mat( 2, 3, CV_32FC1 );
- Mat src, warp_dst, warp_rotate_dst;
-
-#. Load an image:
-
- .. code-block:: cpp
-
- src = imread( argv[1], 1 );
-
-#. Initialize the destination image as having the same size and type as the source:
-
- .. code-block:: cpp
-
- warp_dst = Mat::zeros( src.rows, src.cols, src.type() );
-
-#. **Affine Transform:** As we explained lines above, we need two sets of 3 points to derive the affine transform relation. Take a look:
-
- .. code-block:: cpp
-
- srcTri[0] = Point2f( 0,0 );
- srcTri[1] = Point2f( src.cols - 1, 0 );
- srcTri[2] = Point2f( 0, src.rows - 1 );
-
- dstTri[0] = Point2f( src.cols*0.0, src.rows*0.33 );
- dstTri[1] = Point2f( src.cols*0.85, src.rows*0.25 );
- dstTri[2] = Point2f( src.cols*0.15, src.rows*0.7 );
-
- You may want to draw the points to make a better idea of how they change. Their locations are approximately the same as the ones depicted in the example figure (in the Theory section). You may note that the size and orientation of the triangle defined by the 3 points change.
-
-#. Armed with both sets of points, we calculate the Affine Transform by using OpenCV function :get_affine_transform:`getAffineTransform <>`:
-
- .. code-block:: cpp
-
- warp_mat = getAffineTransform( srcTri, dstTri );
-
-
- We get as an output a :math:`2 \times 3` matrix (in this case **warp_mat**)
-
-#. We apply the Affine Transform just found to the src image
-
- .. code-block:: cpp
-
- warpAffine( src, warp_dst, warp_mat, warp_dst.size() );
-
- with the following arguments:
-
- * **src**: Input image
- * **warp_dst**: Output image
- * **warp_mat**: Affine transform
- * **warp_dst.size()**: The desired size of the output image
-
- We just got our first transformed image! We will display it in one bit. Before that, we also want to rotate it...
-
-#. **Rotate:**
- To rotate an image, we need to know two things:
-
- a. The center with respect to which the image will rotate
- b. The angle to be rotated. In OpenCV a positive angle is counter-clockwise
- c. *Optional:* A scale factor
-
- We define these parameters with the following snippet:
-
- .. code-block:: cpp
-
- Point center = Point( warp_dst.cols/2, warp_dst.rows/2 );
- double angle = -50.0;
- double scale = 0.6;
-
-#. We generate the rotation matrix with the OpenCV function :get_rotation_matrix_2d:`getRotationMatrix2D <>`, which returns a :math:`2 \times 3` matrix (in this case *rot_mat*)
-
- .. code-block:: cpp
-
- rot_mat = getRotationMatrix2D( center, angle, scale );
-
-#. We now apply the found rotation to the output of our previous Transformation.
-
- .. code-block:: cpp
-
- warpAffine( warp_dst, warp_rotate_dst, rot_mat, warp_dst.size() );
-
-#. Finally, we display our results in two windows plus the original image for good measure:
-
- .. code-block:: cpp
-
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, src );
-
- namedWindow( warp_window, WINDOW_AUTOSIZE );
- imshow( warp_window, warp_dst );
-
- namedWindow( warp_rotate_window, WINDOW_AUTOSIZE );
- imshow( warp_rotate_window, warp_rotate_dst );
-
-
-#. We just have to wait until the user exits the program
-
- .. code-block:: cpp
-
- waitKey(0);
-
-
-
-Result
-======
-
-#. After compiling the code above, we can give it the path of an image as argument. For instance, for a picture like:
-
- .. image:: images/Warp_Affine_Tutorial_Original_Image.jpg
- :alt: Original image
- :width: 250pt
- :align: center
-
- after applying the first Affine Transform we obtain:
-
- .. image:: images/Warp_Affine_Tutorial_Result_Warp.jpg
- :alt: Original image
- :width: 250pt
- :align: center
-
- and finally, after applying a negative rotation (remember negative means clockwise) and a scale factor, we get:
-
- .. image:: images/Warp_Affine_Tutorial_Result_Warp_Rotate.jpg
- :alt: Original image
- :width: 250pt
- :align: center
+++ /dev/null
-.. _Morphology_2:
-
-More Morphology Transformations
-*********************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :morphology_ex:`morphologyEx <>` to apply Morphological Transformation such as:
-
- + Opening
- + Closing
- + Morphological Gradient
- + Top Hat
- + Black Hat
-
-Theory
-=======
-
-.. note::
- The explanation below belongs to the book **Learning OpenCV** by Bradski and Kaehler.
-
-In the previous tutorial we covered two basic Morphology operations:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Erosion
- * Dilation.
-
-Based on these two we can effectuate more sophisticated transformations to our images. Here we discuss briefly 05 operations offered by OpenCV:
-
-Opening
----------
-
-* It is obtained by the erosion of an image followed by a dilation.
-
- .. math::
-
- dst = open( src, element) = dilate( erode( src, element ) )
-
-* Useful for removing small objects (it is assumed that the objects are bright on a dark foreground)
-
-* For instance, check out the example below. The image at the left is the original and the image at the right is the result after applying the opening transformation. We can observe that the small spaces in the corners of the letter tend to dissapear.
-
- .. image:: images/Morphology_2_Tutorial_Theory_Opening.png
- :alt: Opening
- :align: center
-
-Closing
----------
-
-* It is obtained by the dilation of an image followed by an erosion.
-
- .. math::
-
- dst = close( src, element ) = erode( dilate( src, element ) )
-
-* Useful to remove small holes (dark regions).
-
- .. image:: images/Morphology_2_Tutorial_Theory_Closing.png
- :alt: Closing example
- :align: center
-
-
-Morphological Gradient
-------------------------
-
-* It is the difference between the dilation and the erosion of an image.
-
- .. math::
-
- dst = morph_{grad}( src, element ) = dilate( src, element ) - erode( src, element )
-
-* It is useful for finding the outline of an object as can be seen below:
-
- .. image:: images/Morphology_2_Tutorial_Theory_Gradient.png
- :alt: Gradient
- :align: center
-
-
-Top Hat
----------
-
-* It is the difference between an input image and its opening.
-
- .. math::
-
- dst = tophat( src, element ) = src - open( src, element )
-
- .. image:: images/Morphology_2_Tutorial_Theory_TopHat.png
- :alt: Top Hat
- :align: center
-
-Black Hat
-----------
-
-* It is the difference between the closing and its input image
-
- .. math::
-
- dst = blackhat( src, element ) = close( src, element ) - src
-
- .. image:: images/Morphology_2_Tutorial_Theory_BlackHat.png
- :alt: Black Hat
- :align: center
-
-Code
-======
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgProc/Morphology_2.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
- #include <stdlib.h>
- #include <stdio.h>
-
- using namespace cv;
-
- /// Global variables
- Mat src, dst;
-
- int morph_elem = 0;
- int morph_size = 0;
- int morph_operator = 0;
- int const max_operator = 4;
- int const max_elem = 2;
- int const max_kernel_size = 21;
-
- char* window_name = "Morphology Transformations Demo";
-
- /* Function Headers */
- void Morphology_Operations( int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load an image
- src = imread( argv[1] );
-
- if( !src.data )
- { return -1; }
-
- /// Create window
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
- /// Create Trackbar to select Morphology operation
- createTrackbar("Operator:\n 0: Opening - 1: Closing \n 2: Gradient - 3: Top Hat \n 4: Black Hat", window_name, &morph_operator, max_operator, Morphology_Operations );
-
- /// Create Trackbar to select kernel type
- createTrackbar( "Element:\n 0: Rect - 1: Cross - 2: Ellipse", window_name,
- &morph_elem, max_elem,
- Morphology_Operations );
-
- /// Create Trackbar to choose kernel size
- createTrackbar( "Kernel size:\n 2n +1", window_name,
- &morph_size, max_kernel_size,
- Morphology_Operations );
-
- /// Default start
- Morphology_Operations( 0, 0 );
-
- waitKey(0);
- return 0;
- }
-
- /*
- * @function Morphology_Operations
- */
- void Morphology_Operations( int, void* )
- {
- // Since MORPH_X : 2,3,4,5 and 6
- int operation = morph_operator + 2;
-
- Mat element = getStructuringElement( morph_elem, Size( 2*morph_size + 1, 2*morph_size+1 ), Point( morph_size, morph_size ) );
-
- /// Apply the specified morphology operation
- morphologyEx( src, dst, operation, element );
- imshow( window_name, dst );
- }
-
-
-Explanation
-=============
-
-#. Let's check the general structure of the program:
-
- * Load an image
-
- * Create a window to display results of the Morphological operations
-
- * Create 03 Trackbars for the user to enter parameters:
-
- * The first trackbar **"Operator"** returns the kind of morphology operation to use (**morph_operator**).
-
- .. code-block:: cpp
-
- createTrackbar("Operator:\n 0: Opening - 1: Closing \n 2: Gradient - 3: Top Hat \n 4: Black Hat",
- window_name, &morph_operator, max_operator,
- Morphology_Operations );
-
-
-
- * The second trackbar **"Element"** returns **morph_elem**, which indicates what kind of structure our kernel is:
-
- .. code-block:: cpp
-
- createTrackbar( "Element:\n 0: Rect - 1: Cross - 2: Ellipse", window_name,
- &morph_elem, max_elem,
- Morphology_Operations );
-
- * The final trackbar **"Kernel Size"** returns the size of the kernel to be used (**morph_size**)
-
- .. code-block:: cpp
-
- createTrackbar( "Kernel size:\n 2n +1", window_name,
- &morph_size, max_kernel_size,
- Morphology_Operations );
-
-
- * Every time we move any slider, the user's function **Morphology_Operations** will be called to effectuate a new morphology operation and it will update the output image based on the current trackbar values.
-
- .. code-block:: cpp
-
- /*
- * @function Morphology_Operations
- */
- void Morphology_Operations( int, void* )
- {
- // Since MORPH_X : 2,3,4,5 and 6
- int operation = morph_operator + 2;
-
- Mat element = getStructuringElement( morph_elem, Size( 2*morph_size + 1, 2*morph_size+1 ), Point( morph_size, morph_size ) );
-
- /// Apply the specified morphology operation
- morphologyEx( src, dst, operation, element );
- imshow( window_name, dst );
- }
-
-
- We can observe that the key function to perform the morphology transformations is :morphology_ex:`morphologyEx <>`. In this example we use four arguments (leaving the rest as defaults):
-
- * **src** : Source (input) image
- * **dst**: Output image
- * **operation**: The kind of morphology transformation to be performed. Note that we have 5 alternatives:
-
- + *Opening*: MORPH_OPEN : 2
- + *Closing*: MORPH_CLOSE: 3
- + *Gradient*: MORPH_GRADIENT: 4
- + *Top Hat*: MORPH_TOPHAT: 5
- + *Black Hat*: MORPH_BLACKHAT: 6
-
- As you can see the values range from <2-6>, that is why we add (+2) to the values entered by the Trackbar:
-
- .. code-block:: cpp
-
- int operation = morph_operator + 2;
-
- * **element**: The kernel to be used. We use the function :get_structuring_element:`getStructuringElement <>` to define our own structure.
-
-
-
-Results
-========
-
-* After compiling the code above we can execute it giving an image path as an argument. For this tutorial we use as input the image: **baboon.png**:
-
- .. image:: images/Morphology_2_Tutorial_Original_Image.jpg
- :alt: Morphology 2: Original image
- :align: center
-
-* And here are two snapshots of the display window. The first picture shows the output after using the operator **Opening** with a cross kernel. The second picture (right side, shows the result of using a **Blackhat** operator with an ellipse kernel.
-
- .. image:: images/Morphology_2_Tutorial_Result.jpg
- :alt: Morphology 2: Result sample
- :align: center
+++ /dev/null
-.. _Pyramids:
-
-Image Pyramids
-***************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV functions :pyr_up:`pyrUp <>` and :pyr_down:`pyrDown <>` to downsample or upsample a given image.
-
-Theory
-=======
-
-.. note::
- The explanation below belongs to the book **Learning OpenCV** by Bradski and Kaehler.
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Usually we need to convert an image to a size different than its original. For this, there are two possible options:
-
- #. *Upsize* the image (zoom in) or
- #. *Downsize* it (zoom out).
-
- * Although there is a *geometric transformation* function in OpenCV that -literally- resize an image (:resize:`resize <>`, which we will show in a future tutorial), in this section we analyze first the use of **Image Pyramids**, which are widely applied in a huge range of vision applications.
-
-
-Image Pyramid
---------------
-
-.. container:: enumeratevisibleitemswithsquare
-
- * An image pyramid is a collection of images - all arising from a single original image - that are successively downsampled until some desired stopping point is reached.
-
- * There are two common kinds of image pyramids:
-
- * **Gaussian pyramid:** Used to downsample images
-
- * **Laplacian pyramid:** Used to reconstruct an upsampled image from an image lower in the pyramid (with less resolution)
-
- * In this tutorial we'll use the *Gaussian pyramid*.
-
-Gaussian Pyramid
-^^^^^^^^^^^^^^^^^
-
-* Imagine the pyramid as a set of layers in which the higher the layer, the smaller the size.
-
- .. image:: images/Pyramids_Tutorial_Pyramid_Theory.png
- :alt: Pyramid figure
- :align: center
-
-* Every layer is numbered from bottom to top, so layer :math:`(i+1)` (denoted as :math:`G_{i+1}` is smaller than layer :math:`i` (:math:`G_{i}`).
-
-* To produce layer :math:`(i+1)` in the Gaussian pyramid, we do the following:
-
- * Convolve :math:`G_{i}` with a Gaussian kernel:
-
- .. math::
-
- \frac{1}{16} \begin{bmatrix} 1 & 4 & 6 & 4 & 1 \\ 4 & 16 & 24 & 16 & 4 \\ 6 & 24 & 36 & 24 & 6 \\ 4 & 16 & 24 & 16 & 4 \\ 1 & 4 & 6 & 4 & 1 \end{bmatrix}
-
- * Remove every even-numbered row and column.
-
-* You can easily notice that the resulting image will be exactly one-quarter the area of its predecessor. Iterating this process on the input image :math:`G_{0}` (original image) produces the entire pyramid.
-
-* The procedure above was useful to downsample an image. What if we want to make it bigger?:
-
- * First, upsize the image to twice the original in each dimension, wit the new even rows and columns filled with zeros (:math:`0`)
-
- * Perform a convolution with the same kernel shown above (multiplied by 4) to approximate the values of the "missing pixels"
-
-* These two procedures (downsampling and upsampling as explained above) are implemented by the OpenCV functions :pyr_up:`pyrUp <>` and :pyr_down:`pyrDown <>`, as we will see in an example with the code below:
-
-.. note::
- When we reduce the size of an image, we are actually *losing* information of the image.
-
-Code
-======
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgProc/Pyramids.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
- #include <math.h>
- #include <stdlib.h>
- #include <stdio.h>
-
- using namespace cv;
-
- /// Global variables
- Mat src, dst, tmp;
- char* window_name = "Pyramids Demo";
-
-
- /*
- * @function main
- */
- int main( int argc, char** argv )
- {
- /// General instructions
- printf( "\n Zoom In-Out demo \n " );
- printf( "------------------ \n" );
- printf( " * [u] -> Zoom in \n" );
- printf( " * [d] -> Zoom out \n" );
- printf( " * [ESC] -> Close program \n \n" );
-
- /// Test image - Make sure it s divisible by 2^{n}
- src = imread( "../images/chicky_512.jpg" );
- if( !src.data )
- { printf(" No data! -- Exiting the program \n");
- return -1; }
-
- tmp = src;
- dst = tmp;
-
- /// Create window
- namedWindow( window_name, WINDOW_AUTOSIZE );
- imshow( window_name, dst );
-
- /// Loop
- while( true )
- {
- int c;
- c = waitKey(10);
-
- if( (char)c == 27 )
- { break; }
- if( (char)c == 'u' )
- { pyrUp( tmp, dst, Size( tmp.cols*2, tmp.rows*2 ) );
- printf( "** Zoom In: Image x 2 \n" );
- }
- else if( (char)c == 'd' )
- { pyrDown( tmp, dst, Size( tmp.cols/2, tmp.rows/2 ) );
- printf( "** Zoom Out: Image / 2 \n" );
- }
-
- imshow( window_name, dst );
- tmp = dst;
- }
- return 0;
- }
-
-Explanation
-=============
-
-#. Let's check the general structure of the program:
-
- * Load an image (in this case it is defined in the program, the user does not have to enter it as an argument)
-
- .. code-block:: cpp
-
- /// Test image - Make sure it s divisible by 2^{n}
- src = imread( "../images/chicky_512.jpg" );
- if( !src.data )
- { printf(" No data! -- Exiting the program \n");
- return -1; }
-
- * Create a Mat object to store the result of the operations (*dst*) and one to save temporal results (*tmp*).
-
- .. code-block:: cpp
-
- Mat src, dst, tmp;
- /* ... */
- tmp = src;
- dst = tmp;
-
-
-
- * Create a window to display the result
-
- .. code-block:: cpp
-
- namedWindow( window_name, WINDOW_AUTOSIZE );
- imshow( window_name, dst );
-
- * Perform an infinite loop waiting for user input.
-
- .. code-block:: cpp
-
- while( true )
- {
- int c;
- c = waitKey(10);
-
- if( (char)c == 27 )
- { break; }
- if( (char)c == 'u' )
- { pyrUp( tmp, dst, Size( tmp.cols*2, tmp.rows*2 ) );
- printf( "** Zoom In: Image x 2 \n" );
- }
- else if( (char)c == 'd' )
- { pyrDown( tmp, dst, Size( tmp.cols/2, tmp.rows/2 ) );
- printf( "** Zoom Out: Image / 2 \n" );
- }
-
- imshow( window_name, dst );
- tmp = dst;
- }
-
-
- Our program exits if the user presses *ESC*. Besides, it has two options:
-
- * **Perform upsampling (after pressing 'u')**
-
- .. code-block:: cpp
-
- pyrUp( tmp, dst, Size( tmp.cols*2, tmp.rows*2 )
-
- We use the function :pyr_up:`pyrUp <>` with 03 arguments:
-
- * *tmp*: The current image, it is initialized with the *src* original image.
- * *dst*: The destination image (to be shown on screen, supposedly the double of the input image)
- * *Size( tmp.cols*2, tmp.rows*2 )* : The destination size. Since we are upsampling, :pyr_up:`pyrUp <>` expects a size double than the input image (in this case *tmp*).
-
- * **Perform downsampling (after pressing 'd')**
-
- .. code-block:: cpp
-
- pyrDown( tmp, dst, Size( tmp.cols/2, tmp.rows/2 )
-
- Similarly as with :pyr_up:`pyrUp <>`, we use the function :pyr_down:`pyrDown <>` with 03 arguments:
-
- * *tmp*: The current image, it is initialized with the *src* original image.
- * *dst*: The destination image (to be shown on screen, supposedly half the input image)
- * *Size( tmp.cols/2, tmp.rows/2 )* : The destination size. Since we are upsampling, :pyr_down:`pyrDown <>` expects half the size the input image (in this case *tmp*).
-
- * Notice that it is important that the input image can be divided by a factor of two (in both dimensions). Otherwise, an error will be shown.
-
- * Finally, we update the input image **tmp** with the current image displayed, so the subsequent operations are performed on it.
-
- .. code-block:: cpp
-
- tmp = dst;
-
-
-
-Results
-========
-
-* After compiling the code above we can test it. The program calls an image **chicky_512.jpg** that comes in the *tutorial_code/image* folder. Notice that this image is :math:`512 \times 512`, hence a downsample won't generate any error (:math:`512 = 2^{9}`). The original image is shown below:
-
- .. image:: images/Pyramids_Tutorial_Original_Image.jpg
- :alt: Pyramids: Original image
- :align: center
-
-* First we apply two successive :pyr_down:`pyrDown <>` operations by pressing 'd'. Our output is:
-
- .. image:: images/Pyramids_Tutorial_PyrDown_Result.jpg
- :alt: Pyramids: PyrDown Result
- :align: center
-
-* Note that we should have lost some resolution due to the fact that we are diminishing the size of the image. This is evident after we apply :pyr_up:`pyrUp <>` twice (by pressing 'u'). Our output is now:
-
- .. image:: images/Pyramids_Tutorial_PyrUp_Result.jpg
- :alt: Pyramids: PyrUp Result
- :align: center
+++ /dev/null
-.. _bounding_rects_circles:
-
-
-Creating Bounding boxes and circles for contours
-*************************************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :bounding_rect:`boundingRect <>`
- * Use the OpenCV function :min_enclosing_circle:`minEnclosingCircle <>`
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ShapeDescriptors/generalContours_demo1.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
- #include <stdlib.h>
-
- using namespace cv;
- using namespace std;
-
- Mat src; Mat src_gray;
- int thresh = 100;
- int max_thresh = 255;
- RNG rng(12345);
-
- /// Function header
- void thresh_callback(int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load source image and convert it to gray
- src = imread( argv[1], 1 );
-
- /// Convert image to gray and blur it
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
- blur( src_gray, src_gray, Size(3,3) );
-
- /// Create Window
- char* source_window = "Source";
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, src );
-
- createTrackbar( " Threshold:", "Source", &thresh, max_thresh, thresh_callback );
- thresh_callback( 0, 0 );
-
- waitKey(0);
- return(0);
- }
-
- /* @function thresh_callback */
- void thresh_callback(int, void* )
- {
- Mat threshold_output;
- vector<vector<Point> > contours;
- vector<Vec4i> hierarchy;
-
- /// Detect edges using Threshold
- threshold( src_gray, threshold_output, thresh, 255, THRESH_BINARY );
- /// Find contours
- findContours( threshold_output, contours, hierarchy, RETR_TREE, CHAIN_APPROX_SIMPLE, Point(0, 0) );
-
- /// Approximate contours to polygons + get bounding rects and circles
- vector<vector<Point> > contours_poly( contours.size() );
- vector<Rect> boundRect( contours.size() );
- vector<Point2f>center( contours.size() );
- vector<float>radius( contours.size() );
-
- for( int i = 0; i < contours.size(); i++ )
- { approxPolyDP( Mat(contours[i]), contours_poly[i], 3, true );
- boundRect[i] = boundingRect( Mat(contours_poly[i]) );
- minEnclosingCircle( (Mat)contours_poly[i], center[i], radius[i] );
- }
-
-
- /// Draw polygonal contour + bonding rects + circles
- Mat drawing = Mat::zeros( threshold_output.size(), CV_8UC3 );
- for( int i = 0; i< contours.size(); i++ )
- {
- Scalar color = Scalar( rng.uniform(0, 255), rng.uniform(0,255), rng.uniform(0,255) );
- drawContours( drawing, contours_poly, i, color, 1, 8, vector<Vec4i>(), 0, Point() );
- rectangle( drawing, boundRect[i].tl(), boundRect[i].br(), color, 2, 8, 0 );
- circle( drawing, center[i], (int)radius[i], color, 2, 8, 0 );
- }
-
- /// Show in a window
- namedWindow( "Contours", WINDOW_AUTOSIZE );
- imshow( "Contours", drawing );
- }
-
-Explanation
-============
-
-Result
-======
-
-#. Here it is:
-
- ========== ==========
- |BRC_0| |BRC_1|
- ========== ==========
-
- .. |BRC_0| image:: images/Bounding_Rects_Circles_Source_Image.jpg
- :align: middle
-
- .. |BRC_1| image:: images/Bounding_Rects_Circles_Result.jpg
- :align: middle
+++ /dev/null
-.. _bounding_rotated_ellipses:
-
-
-Creating Bounding rotated boxes and ellipses for contours
-**********************************************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :min_area_rect:`minAreaRect <>`
- * Use the OpenCV function :fit_ellipse:`fitEllipse <>`
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ShapeDescriptors/generalContours_demo2.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
- #include <stdlib.h>
-
- using namespace cv;
- using namespace std;
-
- Mat src; Mat src_gray;
- int thresh = 100;
- int max_thresh = 255;
- RNG rng(12345);
-
- /// Function header
- void thresh_callback(int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load source image and convert it to gray
- src = imread( argv[1], 1 );
-
- /// Convert image to gray and blur it
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
- blur( src_gray, src_gray, Size(3,3) );
-
- /// Create Window
- char* source_window = "Source";
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, src );
-
- createTrackbar( " Threshold:", "Source", &thresh, max_thresh, thresh_callback );
- thresh_callback( 0, 0 );
-
- waitKey(0);
- return(0);
- }
-
- /* @function thresh_callback */
- void thresh_callback(int, void* )
- {
- Mat threshold_output;
- vector<vector<Point> > contours;
- vector<Vec4i> hierarchy;
-
- /// Detect edges using Threshold
- threshold( src_gray, threshold_output, thresh, 255, THRESH_BINARY );
- /// Find contours
- findContours( threshold_output, contours, hierarchy, RETR_TREE, CHAIN_APPROX_SIMPLE, Point(0, 0) );
-
- /// Find the rotated rectangles and ellipses for each contour
- vector<RotatedRect> minRect( contours.size() );
- vector<RotatedRect> minEllipse( contours.size() );
-
- for( int i = 0; i < contours.size(); i++ )
- { minRect[i] = minAreaRect( Mat(contours[i]) );
- if( contours[i].size() > 5 )
- { minEllipse[i] = fitEllipse( Mat(contours[i]) ); }
- }
-
- /// Draw contours + rotated rects + ellipses
- Mat drawing = Mat::zeros( threshold_output.size(), CV_8UC3 );
- for( int i = 0; i< contours.size(); i++ )
- {
- Scalar color = Scalar( rng.uniform(0, 255), rng.uniform(0,255), rng.uniform(0,255) );
- // contour
- drawContours( drawing, contours, i, color, 1, 8, vector<Vec4i>(), 0, Point() );
- // ellipse
- ellipse( drawing, minEllipse[i], color, 2, 8 );
- // rotated rectangle
- Point2f rect_points[4]; minRect[i].points( rect_points );
- for( int j = 0; j < 4; j++ )
- line( drawing, rect_points[j], rect_points[(j+1)%4], color, 1, 8 );
- }
-
- /// Show in a window
- namedWindow( "Contours", WINDOW_AUTOSIZE );
- imshow( "Contours", drawing );
- }
-
-Explanation
-============
-
-Result
-======
-
-#. Here it is:
-
- ========== ==========
- |BRE_0| |BRE_1|
- ========== ==========
-
- .. |BRE_0| image:: images/Bounding_Rotated_Ellipses_Source_Image.jpg
- :align: middle
-
- .. |BRE_1| image:: images/Bounding_Rotated_Ellipses_Result.jpg
- :align: middle
+++ /dev/null
-.. _find_contours:
-
-Finding contours in your image
-******************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :find_contours:`findContours <>`
- * Use the OpenCV function :draw_contours:`drawContours <>`
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ShapeDescriptors/findContours_demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
- #include <stdlib.h>
-
- using namespace cv;
- using namespace std;
-
- Mat src; Mat src_gray;
- int thresh = 100;
- int max_thresh = 255;
- RNG rng(12345);
-
- /// Function header
- void thresh_callback(int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load source image and convert it to gray
- src = imread( argv[1], 1 );
-
- /// Convert image to gray and blur it
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
- blur( src_gray, src_gray, Size(3,3) );
-
- /// Create Window
- char* source_window = "Source";
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, src );
-
- createTrackbar( " Canny thresh:", "Source", &thresh, max_thresh, thresh_callback );
- thresh_callback( 0, 0 );
-
- waitKey(0);
- return(0);
- }
-
- /* @function thresh_callback */
- void thresh_callback(int, void* )
- {
- Mat canny_output;
- vector<vector<Point> > contours;
- vector<Vec4i> hierarchy;
-
- /// Detect edges using canny
- Canny( src_gray, canny_output, thresh, thresh*2, 3 );
- /// Find contours
- findContours( canny_output, contours, hierarchy, RETR_TREE, CHAIN_APPROX_SIMPLE, Point(0, 0) );
-
- /// Draw contours
- Mat drawing = Mat::zeros( canny_output.size(), CV_8UC3 );
- for( int i = 0; i< contours.size(); i++ )
- {
- Scalar color = Scalar( rng.uniform(0, 255), rng.uniform(0,255), rng.uniform(0,255) );
- drawContours( drawing, contours, i, color, 2, 8, hierarchy, 0, Point() );
- }
-
- /// Show in a window
- namedWindow( "Contours", WINDOW_AUTOSIZE );
- imshow( "Contours", drawing );
- }
-
-Explanation
-============
-
-Result
-======
-
-#. Here it is:
-
- ============= =============
- |contour_0| |contour_1|
- ============= =============
-
- .. |contour_0| image:: images/Find_Contours_Original_Image.jpg
- :align: middle
-
- .. |contour_1| image:: images/Find_Contours_Result.jpg
- :align: middle
+++ /dev/null
-.. _hull:
-
-Convex Hull
-***********
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :convex_hull:`convexHull <>`
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ShapeDescriptors/hull_demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
- #include <stdlib.h>
-
- using namespace cv;
- using namespace std;
-
- Mat src; Mat src_gray;
- int thresh = 100;
- int max_thresh = 255;
- RNG rng(12345);
-
- /// Function header
- void thresh_callback(int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load source image and convert it to gray
- src = imread( argv[1], 1 );
-
- /// Convert image to gray and blur it
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
- blur( src_gray, src_gray, Size(3,3) );
-
- /// Create Window
- char* source_window = "Source";
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, src );
-
- createTrackbar( " Threshold:", "Source", &thresh, max_thresh, thresh_callback );
- thresh_callback( 0, 0 );
-
- waitKey(0);
- return(0);
- }
-
- /* @function thresh_callback */
- void thresh_callback(int, void* )
- {
- Mat src_copy = src.clone();
- Mat threshold_output;
- vector<vector<Point> > contours;
- vector<Vec4i> hierarchy;
-
- /// Detect edges using Threshold
- threshold( src_gray, threshold_output, thresh, 255, THRESH_BINARY );
-
- /// Find contours
- findContours( threshold_output, contours, hierarchy, RETR_TREE, CHAIN_APPROX_SIMPLE, Point(0, 0) );
-
- /// Find the convex hull object for each contour
- vector<vector<Point> >hull( contours.size() );
- for( int i = 0; i < contours.size(); i++ )
- { convexHull( Mat(contours[i]), hull[i], false ); }
-
- /// Draw contours + hull results
- Mat drawing = Mat::zeros( threshold_output.size(), CV_8UC3 );
- for( int i = 0; i< contours.size(); i++ )
- {
- Scalar color = Scalar( rng.uniform(0, 255), rng.uniform(0,255), rng.uniform(0,255) );
- drawContours( drawing, contours, i, color, 1, 8, vector<Vec4i>(), 0, Point() );
- drawContours( drawing, hull, i, color, 1, 8, vector<Vec4i>(), 0, Point() );
- }
-
- /// Show in a window
- namedWindow( "Hull demo", WINDOW_AUTOSIZE );
- imshow( "Hull demo", drawing );
- }
-
-
-Explanation
-============
-
-Result
-======
-
-#. Here it is:
-
- ========== ==========
- |Hull_0| |Hull_1|
- ========== ==========
-
- .. |Hull_0| image:: images/Hull_Original_Image.jpg
- :align: middle
-
- .. |Hull_1| image:: images/Hull_Result.jpg
- :align: middle
+++ /dev/null
-.. _moments:
-
-
-Image Moments
-**************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :moments:`moments <>`
- * Use the OpenCV function :contour_area:`contourArea <>`
- * Use the OpenCV function :arc_length:`arcLength <>`
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ShapeDescriptors/moments_demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
- #include <stdlib.h>
-
- using namespace cv;
- using namespace std;
-
- Mat src; Mat src_gray;
- int thresh = 100;
- int max_thresh = 255;
- RNG rng(12345);
-
- /// Function header
- void thresh_callback(int, void* );
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Load source image and convert it to gray
- src = imread( argv[1], 1 );
-
- /// Convert image to gray and blur it
- cvtColor( src, src_gray, COLOR_BGR2GRAY );
- blur( src_gray, src_gray, Size(3,3) );
-
- /// Create Window
- char* source_window = "Source";
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, src );
-
- createTrackbar( " Canny thresh:", "Source", &thresh, max_thresh, thresh_callback );
- thresh_callback( 0, 0 );
-
- waitKey(0);
- return(0);
- }
-
- /* @function thresh_callback */
- void thresh_callback(int, void* )
- {
- Mat canny_output;
- vector<vector<Point> > contours;
- vector<Vec4i> hierarchy;
-
- /// Detect edges using canny
- Canny( src_gray, canny_output, thresh, thresh*2, 3 );
- /// Find contours
- findContours( canny_output, contours, hierarchy, RETR_TREE, CHAIN_APPROX_SIMPLE, Point(0, 0) );
-
- /// Get the moments
- vector<Moments> mu(contours.size() );
- for( int i = 0; i < contours.size(); i++ )
- { mu[i] = moments( contours[i], false ); }
-
- /// Get the mass centers:
- vector<Point2f> mc( contours.size() );
- for( int i = 0; i < contours.size(); i++ )
- { mc[i] = Point2f( mu[i].m10/mu[i].m00 , mu[i].m01/mu[i].m00 ); }
-
- /// Draw contours
- Mat drawing = Mat::zeros( canny_output.size(), CV_8UC3 );
- for( int i = 0; i< contours.size(); i++ )
- {
- Scalar color = Scalar( rng.uniform(0, 255), rng.uniform(0,255), rng.uniform(0,255) );
- drawContours( drawing, contours, i, color, 2, 8, hierarchy, 0, Point() );
- circle( drawing, mc[i], 4, color, -1, 8, 0 );
- }
-
- /// Show in a window
- namedWindow( "Contours", WINDOW_AUTOSIZE );
- imshow( "Contours", drawing );
-
- /// Calculate the area with the moments 00 and compare with the result of the OpenCV function
- printf("\t Info: Area and Contour Length \n");
- for( int i = 0; i< contours.size(); i++ )
- {
- printf(" * Contour[%d] - Area (M_00) = %.2f - Area OpenCV: %.2f - Length: %.2f \n", i, mu[i].m00, contourArea(contours[i]), arcLength( contours[i], true ) );
- Scalar color = Scalar( rng.uniform(0, 255), rng.uniform(0,255), rng.uniform(0,255) );
- drawContours( drawing, contours, i, color, 2, 8, hierarchy, 0, Point() );
- circle( drawing, mc[i], 4, color, -1, 8, 0 );
- }
- }
-
-Explanation
-============
-
-Result
-======
-
-#. Here it is:
-
- ========== ========== ==========
- |MU_0| |MU_1| |MU_2|
- ========== ========== ==========
-
- .. |MU_0| image:: images/Moments_Source_Image.jpg
- :width: 250pt
- :align: middle
-
- .. |MU_1| image:: images/Moments_Result1.jpg
- :width: 250pt
- :align: middle
-
- .. |MU_2| image:: images/Moments_Result2.jpg
- :width: 250pt
- :align: middle
+++ /dev/null
-.. _point_polygon_test:
-
-Point Polygon Test
-*******************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the OpenCV function :point_polygon_test:`pointPolygonTest <>`
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ShapeDescriptors/pointPolygonTest_demo.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
- #include <iostream>
- #include <stdio.h>
- #include <stdlib.h>
-
- using namespace cv;
- using namespace std;
-
- /* @function main */
- int main( int argc, char** argv )
- {
- /// Create an image
- const int r = 100;
- Mat src = Mat::zeros( Size( 4*r, 4*r ), CV_8UC1 );
-
- /// Create a sequence of points to make a contour:
- vector<Point2f> vert(6);
-
- vert[0] = Point( 1.5*r, 1.34*r );
- vert[1] = Point( 1*r, 2*r );
- vert[2] = Point( 1.5*r, 2.866*r );
- vert[3] = Point( 2.5*r, 2.866*r );
- vert[4] = Point( 3*r, 2*r );
- vert[5] = Point( 2.5*r, 1.34*r );
-
- /// Draw it in src
- for( int j = 0; j < 6; j++ )
- { line( src, vert[j], vert[(j+1)%6], Scalar( 255 ), 3, 8 ); }
-
- /// Get the contours
- vector<vector<Point> > contours; vector<Vec4i> hierarchy;
- Mat src_copy = src.clone();
-
- findContours( src_copy, contours, hierarchy, RETR_TREE, CHAIN_APPROX_SIMPLE);
-
- /// Calculate the distances to the contour
- Mat raw_dist( src.size(), CV_32FC1 );
-
- for( int j = 0; j < src.rows; j++ )
- { for( int i = 0; i < src.cols; i++ )
- { raw_dist.at<float>(j,i) = pointPolygonTest( contours[0], Point2f(i,j), true ); }
- }
-
- double minVal; double maxVal;
- minMaxLoc( raw_dist, &minVal, &maxVal, 0, 0, Mat() );
- minVal = abs(minVal); maxVal = abs(maxVal);
-
- /// Depicting the distances graphically
- Mat drawing = Mat::zeros( src.size(), CV_8UC3 );
-
- for( int j = 0; j < src.rows; j++ )
- { for( int i = 0; i < src.cols; i++ )
- {
- if( raw_dist.at<float>(j,i) < 0 )
- { drawing.at<Vec3b>(j,i)[0] = 255 - (int) abs(raw_dist.at<float>(j,i))*255/minVal; }
- else if( raw_dist.at<float>(j,i) > 0 )
- { drawing.at<Vec3b>(j,i)[2] = 255 - (int) raw_dist.at<float>(j,i)*255/maxVal; }
- else
- { drawing.at<Vec3b>(j,i)[0] = 255; drawing.at<Vec3b>(j,i)[1] = 255; drawing.at<Vec3b>(j,i)[2] = 255; }
- }
- }
-
- /// Create Window and show your results
- char* source_window = "Source";
- namedWindow( source_window, WINDOW_AUTOSIZE );
- imshow( source_window, src );
- namedWindow( "Distance", WINDOW_AUTOSIZE );
- imshow( "Distance", drawing );
-
- waitKey(0);
- return(0);
- }
-
-Explanation
-============
-
-Result
-======
-
-#. Here it is:
-
- ========== ==========
- |PPT_0| |PPT_1|
- ========== ==========
-
- .. |PPT_0| image:: images/Point_Polygon_Test_Source_Image.png
- :align: middle
-
- .. |PPT_1| image:: images/Point_Polygon_Test_Result.jpg
- :align: middle
+++ /dev/null
-.. _Table-Of-Content-ImgProc:
-
-*imgproc* module. Image Processing
------------------------------------------------------------
-
-In this section you will learn about the image processing (manipulation) functions inside OpenCV.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |ImageProcessing_1| **Title:** :ref:`Smoothing`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Let's take a look at some basic linear filters!
-
- ===================== ==============================================
-
- .. |ImageProcessing_1| image:: images/Smoothing_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |ImageProcessing_2| **Title:** :ref:`Morphology_1`
-
- *Compatibility:* > OpenCV 2.0
-
- Author: |Author_AnaH|
-
- Let's *change* the shape of objects!
-
- ===================== ==============================================
-
- .. |ImageProcessing_2| image:: images/Morphology_1_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================= ==================================================
- |Morphology_2| **Title:** :ref:`Morphology_2`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Here we investigate different morphology operators
-
- ================= ==================================================
-
- .. |Morphology_2| image:: images/Morphology_2_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |Pyramids| **Title:** :ref:`Pyramids`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- What if I need a bigger/smaller image?
-
- ===================== ==============================================
-
- .. |Pyramids| image:: images/Pyramids_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |Threshold| **Title:** :ref:`Basic_Threshold`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- After so much processing, it is time to decide which pixels stay!
-
- ===================== ==============================================
-
- .. |Threshold| image:: images/Threshold_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
-+
- ===================== ==============================================
- |Filter_2D| **Title:** :ref:`filter_2d`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn to design our own filters by using OpenCV functions
-
- ===================== ==============================================
-
- .. |Filter_2D| image:: images/imgtrans/Filter_2D_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
-+
- ===================== ==============================================
- |CopyMakeBorder| **Title:** :ref:`copyMakeBorderTutorial`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to pad our images!
-
- ===================== ==============================================
-
- .. |CopyMakeBorder| image:: images/imgtrans/CopyMakeBorder_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |SobelDerivatives| **Title:** :ref:`sobel_derivatives`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to calculate gradients and use them to detect edges!
-
- ===================== ==============================================
-
- .. |SobelDerivatives| image:: images/imgtrans/Sobel_Derivatives_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |LaplaceOperator| **Title:** :ref:`laplace_operator`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn about the *Laplace* operator and how to detect edges with it.
-
- ===================== ==============================================
-
- .. |LaplaceOperator| image:: images/imgtrans/Laplace_Operator_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |CannyDetector| **Title:** :ref:`canny_detector`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn a sophisticated alternative to detect edges.
-
- ===================== ==============================================
-
- .. |CannyDetector| image:: images/imgtrans/Canny_Detector_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |HoughLines| **Title:** :ref:`hough_lines`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to detect lines
-
- ===================== ==============================================
-
- .. |HoughLines| image:: images/imgtrans/Hough_Lines_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |HoughCircle| **Title:** :ref:`hough_circle`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to detect circles
-
- ===================== ==============================================
-
- .. |HoughCircle| image:: images/imgtrans/Hough_Circle_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |Remap| **Title:** :ref:`remap`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to manipulate pixels locations
-
- ===================== ==============================================
-
- .. |Remap| image:: images/imgtrans/Remap_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |WarpAffine| **Title:** :ref:`warp_affine`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to rotate, translate and scale our images
-
- ===================== ==============================================
-
- .. |WarpAffine| image:: images/imgtrans/Warp_Affine_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |HistEqualization| **Title:** :ref:`histogram_equalization`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to improve the contrast in our images
-
- ===================== ==============================================
-
- .. |HistEqualization| image:: images/histograms/Histogram_Equalization_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |HistCalculation| **Title:** :ref:`histogram_calculation`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to create and generate histograms
-
- ===================== ==============================================
-
- .. |HistCalculation| image:: images/histograms/Histogram_Calculation_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |HistComparison| **Title:** :ref:`histogram_comparison`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn to calculate metrics between histograms
-
- ===================== ==============================================
-
- .. |HistComparison| image:: images/histograms/Histogram_Comparison_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |BackProjection| **Title:** :ref:`back_projection`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to use histograms to find similar objects in images
-
- ===================== ==============================================
-
- .. |BackProjection| image:: images/histograms/Back_Projection_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |TemplateMatching| **Title:** :ref:`template_matching`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to match templates in an image
-
- ===================== ==============================================
-
- .. |TemplateMatching| image:: images/histograms/Template_Matching_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |FindContours| **Title:** :ref:`find_contours`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to find contours of objects in our image
-
- ===================== ==============================================
-
- .. |FindContours| image:: images/shapedescriptors/Find_Contours_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |Hull| **Title:** :ref:`hull`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to get hull contours and draw them!
-
- ===================== ==============================================
-
- .. |Hull| image:: images/shapedescriptors/Hull_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |BRC| **Title:** :ref:`bounding_rects_circles`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to obtain bounding boxes and circles for our contours.
-
- ===================== ==============================================
-
- .. |BRC| image:: images/shapedescriptors/Bounding_Rects_Circles_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
-
- ===================== ==============================================
- |BRE| **Title:** :ref:`bounding_rotated_ellipses`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to obtain rotated bounding boxes and ellipses for our contours.
-
- ===================== ==============================================
-
- .. |BRE| image:: images/shapedescriptors/Bounding_Rotated_Ellipses_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
-
- ===================== ==============================================
- |MU| **Title:** :ref:`moments`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn to calculate the moments of an image
-
- ===================== ==============================================
-
- .. |MU| image:: images/shapedescriptors/Moments_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-
-+
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
-
- ===================== ==============================================
- |PPT| **Title:** :ref:`point_polygon_test`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Where we learn how to calculate distances from the image to contours
-
- ===================== ==============================================
-
- .. |PPT| image:: images/shapedescriptors/Point_Polygon_Test_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../gausian_median_blur_bilateral_filter/gausian_median_blur_bilateral_filter
- ../erosion_dilatation/erosion_dilatation
- ../opening_closing_hats/opening_closing_hats
- ../pyramids/pyramids
- ../threshold/threshold
- ../imgtrans/filter_2d/filter_2d
- ../imgtrans/copyMakeBorder/copyMakeBorder
- ../imgtrans/sobel_derivatives/sobel_derivatives
- ../imgtrans/laplace_operator/laplace_operator
- ../imgtrans/canny_detector/canny_detector
- ../imgtrans/hough_lines/hough_lines
- ../imgtrans/hough_circle/hough_circle
- ../imgtrans/remap/remap
- ../imgtrans/warp_affine/warp_affine
- ../histograms/histogram_equalization/histogram_equalization
- ../histograms/histogram_calculation/histogram_calculation
- ../histograms/histogram_comparison/histogram_comparison
- ../histograms/back_projection/back_projection
- ../histograms/template_matching/template_matching
- ../shapedescriptors/find_contours/find_contours
- ../shapedescriptors/hull/hull
- ../shapedescriptors/bounding_rects_circles/bounding_rects_circles
- ../shapedescriptors/bounding_rotated_ellipses/bounding_rotated_ellipses
- ../shapedescriptors/moments/moments
- ../shapedescriptors/point_polygon_test/point_polygon_test
+++ /dev/null
-.. _Basic_Threshold:
-
-Basic Thresholding Operations
-*******************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Perform basic thresholding operations using OpenCV function :threshold:`threshold <>`
-
-
-Cool Theory
-============
-
-.. note::
- The explanation below belongs to the book **Learning OpenCV** by Bradski and Kaehler.
-
-What is Thresholding?
------------------------
-
-* The simplest segmentation method
-
-* Application example: Separate out regions of an image corresponding to objects which we want to analyze. This separation is based on the variation of intensity between the object pixels and the background pixels.
-
-* To differentiate the pixels we are interested in from the rest (which will eventually be rejected), we perform a comparison of each pixel intensity value with respect to a *threshold* (determined according to the problem to solve).
-
-* Once we have separated properly the important pixels, we can set them with a determined value to identify them (i.e. we can assign them a value of :math:`0` (black), :math:`255` (white) or any value that suits your needs).
-
- .. image:: images/Threshold_Tutorial_Theory_Example.jpg
- :alt: Threshold simple example
- :align: center
-
-Types of Thresholding
------------------------
-
-* OpenCV offers the function :threshold:`threshold <>` to perform thresholding operations.
-
-* We can effectuate :math:`5` types of Thresholding operations with this function. We will explain them in the following subsections.
-
-* To illustrate how these thresholding processes work, let's consider that we have a source image with pixels with intensity values :math:`src(x,y)`. The plot below depicts this. The horizontal blue line represents the threshold :math:`thresh` (fixed).
-
- .. image:: images/Threshold_Tutorial_Theory_Base_Figure.png
- :alt: Threshold Binary
- :align: center
-
-Threshold Binary
-^^^^^^^^^^^^^^^^^
-
-* This thresholding operation can be expressed as:
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{\texttt{maxVal}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
-
-* So, if the intensity of the pixel :math:`src(x,y)` is higher than :math:`thresh`, then the new pixel intensity is set to a :math:`MaxVal`. Otherwise, the pixels are set to :math:`0`.
-
- .. image:: images/Threshold_Tutorial_Theory_Binary.png
- :alt: Threshold Binary
- :align: center
-
-
-Threshold Binary, Inverted
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* This thresholding operation can be expressed as:
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{maxVal}}{otherwise}
-
-* If the intensity of the pixel :math:`src(x,y)` is higher than :math:`thresh`, then the new pixel intensity is set to a :math:`0`. Otherwise, it is set to :math:`MaxVal`.
-
- .. image:: images/Threshold_Tutorial_Theory_Binary_Inverted.png
- :alt: Threshold Binary Inverted
- :align: center
-
-Truncate
-^^^^^^^^^
-
-* This thresholding operation can be expressed as:
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{\texttt{threshold}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
-
-* The maximum intensity value for the pixels is :math:`thresh`, if :math:`src(x,y)` is greater, then its value is *truncated*. See figure below:
-
- .. image:: images/Threshold_Tutorial_Theory_Truncate.png
- :alt: Threshold Truncate
- :align: center
-
-
-
-Threshold to Zero
-^^^^^^^^^^^^^^^^^^
-
-* This operation can be expressed as:
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{\texttt{src}(x,y)}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
-
-* If :math:`src(x,y)` is lower than :math:`thresh`, the new pixel value will be set to :math:`0`.
-
- .. image:: images/Threshold_Tutorial_Theory_Zero.png
- :alt: Threshold Zero
- :align: center
-
-
-Threshold to Zero, Inverted
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* This operation can be expressed as:
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
-
-* If :math:`src(x,y)` is greater than :math:`thresh`, the new pixel value will be set to :math:`0`.
-
- .. image:: images/Threshold_Tutorial_Theory_Zero_Inverted.png
- :alt: Threshold Zero Inverted
- :align: center
-
-
-Code
-======
-
-The tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ImgProc/Threshold.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
- #include <stdlib.h>
- #include <stdio.h>
-
- using namespace cv;
-
- /// Global variables
-
- int threshold_value = 0;
- int threshold_type = 3;;
- int const max_value = 255;
- int const max_type = 4;
- int const max_BINARY_value = 255;
-
- Mat src, src_gray, dst;
- char* window_name = "Threshold Demo";
-
- char* trackbar_type = "Type: \n 0: Binary \n 1: Binary Inverted \n 2: Truncate \n 3: To Zero \n 4: To Zero Inverted";
- char* trackbar_value = "Value";
-
- /// Function headers
- void Threshold_Demo( int, void* );
-
- /*
- * @function main
- */
- int main( int argc, char** argv )
- {
- /// Load an image
- src = imread( argv[1], 1 );
-
- /// Convert the image to Gray
- cvtColor( src, src_gray, COLOR_RGB2GRAY );
-
- /// Create a window to display results
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
- /// Create Trackbar to choose type of Threshold
- createTrackbar( trackbar_type,
- window_name, &threshold_type,
- max_type, Threshold_Demo );
-
- createTrackbar( trackbar_value,
- window_name, &threshold_value,
- max_value, Threshold_Demo );
-
- /// Call the function to initialize
- Threshold_Demo( 0, 0 );
-
- /// Wait until user finishes program
- while(true)
- {
- int c;
- c = waitKey( 20 );
- if( (char)c == 27 )
- { break; }
- }
-
- }
-
-
- /*
- * @function Threshold_Demo
- */
- void Threshold_Demo( int, void* )
- {
- /* 0: Binary
- 1: Binary Inverted
- 2: Threshold Truncated
- 3: Threshold to Zero
- 4: Threshold to Zero Inverted
- */
-
- threshold( src_gray, dst, threshold_value, max_BINARY_value,threshold_type );
-
- imshow( window_name, dst );
- }
-
-
-
-Explanation
-=============
-
-
-#. Let's check the general structure of the program:
-
- * Load an image. If it is RGB we convert it to Grayscale. For this, remember that we can use the function :cvt_color:`cvtColor <>`:
-
- .. code-block:: cpp
-
- src = imread( argv[1], 1 );
-
- /// Convert the image to Gray
- cvtColor( src, src_gray, COLOR_RGB2GRAY );
-
-
- * Create a window to display the result
-
- .. code-block:: cpp
-
- namedWindow( window_name, WINDOW_AUTOSIZE );
-
- * Create :math:`2` trackbars for the user to enter user input:
-
- * **Type of thresholding**: Binary, To Zero, etc...
- * **Threshold value**
-
- .. code-block:: cpp
-
- createTrackbar( trackbar_type,
- window_name, &threshold_type,
- max_type, Threshold_Demo );
-
- createTrackbar( trackbar_value,
- window_name, &threshold_value,
- max_value, Threshold_Demo );
-
- * Wait until the user enters the threshold value, the type of thresholding (or until the program exits)
-
- * Whenever the user changes the value of any of the Trackbars, the function *Threshold_Demo* is called:
-
- .. code-block:: cpp
-
- /*
- * @function Threshold_Demo
- */
- void Threshold_Demo( int, void* )
- {
- /* 0: Binary
- 1: Binary Inverted
- 2: Threshold Truncated
- 3: Threshold to Zero
- 4: Threshold to Zero Inverted
- */
-
- threshold( src_gray, dst, threshold_value, max_BINARY_value,threshold_type );
-
- imshow( window_name, dst );
- }
-
- As you can see, the function :threshold:`threshold <>` is invoked. We give :math:`5` parameters:
-
- * *src_gray*: Our input image
- * *dst*: Destination (output) image
- * *threshold_value*: The :math:`thresh` value with respect to which the thresholding operation is made
- * *max_BINARY_value*: The value used with the Binary thresholding operations (to set the chosen pixels)
- * *threshold_type*: One of the :math:`5` thresholding operations. They are listed in the comment section of the function above.
-
-
-
-Results
-========
-
-#. After compiling this program, run it giving a path to an image as argument. For instance, for an input image as:
-
-
- .. image:: images/Threshold_Tutorial_Original_Image.jpg
- :alt: Threshold Original Image
- :align: center
-
-#. First, we try to threshold our image with a *binary threhold inverted*. We expect that the pixels brighter than the :math:`thresh` will turn dark, which is what actually happens, as we can see in the snapshot below (notice from the original image, that the doggie's tongue and eyes are particularly bright in comparison with the image, this is reflected in the output image).
-
-
- .. image:: images/Threshold_Tutorial_Result_Binary_Inverted.jpg
- :alt: Threshold Result Binary Inverted
- :align: center
-
-
-#. Now we try with the *threshold to zero*. With this, we expect that the darkest pixels (below the threshold) will become completely black, whereas the pixels with value greater than the threshold will keep its original value. This is verified by the following snapshot of the output image:
-
- .. image:: images/Threshold_Tutorial_Result_Zero.jpg
- :alt: Threshold Result Zero
- :align: center
+++ /dev/null
-
-.. _O4A_SDK:
-
-
-OpenCV4Android SDK
-******************
-
-This tutorial was designed to help you with installation and configuration of OpenCV4Android SDK.
-
-This guide was written with MS Windows 7 in mind, though it should work with GNU Linux and Apple
-Mac OS as well.
-
-This tutorial assumes you have the following software installed and configured:
-
-* JDK
-
-* Android SDK and NDK
-
-* Eclipse IDE
-
-* ADT and CDT plugins for Eclipse
-
- ..
-
-If you need help with anything of the above, you may refer to our :ref:`android_dev_intro` guide.
-
-If you encounter any error after thoroughly following these steps, feel free to contact us via
-`OpenCV4Android <https://groups.google.com/group/android-opencv/>`_ discussion group or
-OpenCV `Q&A forum <http://answers.opencv.org>`_. We'll do our best to help you out.
-
-Tegra Android Development Pack users
-====================================
-
-You may have used `Tegra Android Development Pack <http://developer.nvidia.com/tegra-android-development-pack>`_
-(**TADP**) released by **NVIDIA** for Android development environment setup.
-
-Beside Android development tools the TADP 2.0 includes OpenCV4Android SDK, so it can be already
-installed in your system and you can skip to :ref:`Running_OpenCV_Samples` section of this tutorial.
-
-More details regarding TADP can be found in the :ref:`android_dev_intro` guide.
-
-General info
-============
-
-OpenCV4Android SDK package enables development of Android applications with use of OpenCV library.
-
-The structure of package contents looks as follows:
-
-::
-
- OpenCV-2.4.9-android-sdk
- |_ apk
- | |_ OpenCV_2.4.9_binary_pack_armv7a.apk
- | |_ OpenCV_2.4.9_Manager_2.18_XXX.apk
- |
- |_ doc
- |_ samples
- |_ sdk
- | |_ etc
- | |_ java
- | |_ native
- | |_ 3rdparty
- | |_ jni
- | |_ libs
- | |_ armeabi
- | |_ armeabi-v7a
- | |_ x86
- |
- |_ LICENSE
- |_ README.android
-
-* :file:`sdk` folder contains OpenCV API and libraries for Android:
-
-* :file:`sdk/java` folder contains an Android library Eclipse project providing OpenCV Java API that
- can be imported into developer's workspace;
-
-* :file:`sdk/native` folder contains OpenCV C++ headers (for JNI code) and native Android libraries
- (\*\.so and \*\.a) for ARM-v5, ARM-v7a and x86 architectures;
-
-* :file:`sdk/etc` folder contains Haar and LBP cascades distributed with OpenCV.
-
-* :file:`apk` folder contains Android packages that should be installed on the target Android device
- to enable OpenCV library access via OpenCV Manager API (see details below).
-
- On production devices that have access to Google Play Market (and Internet) these packages will be
- installed from Market on the first start of an application using OpenCV Manager API.
- But devkits without Market or Internet connection require this packages to be installed manually.
- Install the `Manager.apk` and optional `binary_pack.apk` if it needed.
- See :ref:`manager_selection` for details.
-
- .. note:: Installation from Internet is the preferable way since OpenCV team may publish updated
- versions of this packages on the Market.
-
-* :file:`samples` folder contains sample applications projects and their prebuilt packages (APK).
- Import them into Eclipse workspace (like described below) and browse the code to learn possible
- ways of OpenCV use on Android.
-
-* :file:`doc` folder contains various OpenCV documentation in PDF format.
- It's also available online at http://docs.opencv.org.
-
- .. note:: The most recent docs (nightly build) are at http://docs.opencv.org/2.4.
- Generally, it's more up-to-date, but can refer to not-yet-released functionality.
-
-.. TODO: I'm not sure that this is the best place to talk about OpenCV Manager
-
-Starting from version 2.4.3 `OpenCV4Android SDK` uses `OpenCV Manager` API for library
-initialization. `OpenCV Manager` is an Android service based solution providing the following
-benefits for OpenCV applications developers:
-
-* Compact apk-size, since all applications use the same binaries from Manager and do not store
- native libs within themselves;
-
-* Hardware specific optimizations are automatically enabled on all supported platforms;
-
-* Automatic updates and bug fixes;
-
-* Trusted OpenCV library source. All packages with OpenCV are published on Google Play;
-
- ..
-
-For additional information on OpenCV Manager see the:
-
-* |OpenCV4Android_Slides|_
-
-* |OpenCV4Android_Reference|_
-
- ..
-
-.. |OpenCV4Android_Slides| replace:: Slides
-.. _OpenCV4Android_Slides: https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p
-.. |OpenCV4Android_Reference| replace:: Reference Manual
-.. _OpenCV4Android_Reference: http://docs.opencv.org/android/refman.html
-
-Manual OpenCV4Android SDK setup
-===============================
-
-Get the OpenCV4Android SDK
---------------------------
-
-#. Go to the `OpenCV download page on SourceForge <http://sourceforge.net/projects/opencvlibrary/files/opencv-android/>`_
- and download the latest available version. Currently it's |opencv_android_bin_pack_url|_.
-
-#. Create a new folder for Android with OpenCV development. For this tutorial we have unpacked
- OpenCV SDK to the :file:`C:\\Work\\OpenCV4Android\\` directory.
-
- .. note:: Better to use a path without spaces in it. Otherwise you may have problems with :command:`ndk-build`.
-
-#. Unpack the SDK archive into the chosen directory.
-
- You can unpack it using any popular archiver (e.g with |seven_zip|_):
-
- .. image:: images/android_package_7zip.png
- :alt: Exploring OpenCV package with 7-Zip
- :align: center
-
- On Unix you can use the following command:
-
- .. code-block:: bash
-
- unzip ~/Downloads/OpenCV-2.4.9-android-sdk.zip
-
-.. |opencv_android_bin_pack| replace:: :file:`OpenCV-2.4.9-android-sdk.zip`
-.. _opencv_android_bin_pack_url: http://sourceforge.net/projects/opencvlibrary/files/opencv-android/2.4.9/OpenCV-2.4.9-android-sdk.zip/download
-.. |opencv_android_bin_pack_url| replace:: |opencv_android_bin_pack|
-.. |seven_zip| replace:: 7-Zip
-.. _seven_zip: http://www.7-zip.org/
-
-Import OpenCV library and samples to the Eclipse
-------------------------------------------------
-
-#. Start Eclipse and choose your workspace location.
-
- We recommend to start working with OpenCV for Android from a new clean workspace. A new Eclipse
- workspace can for example be created in the folder where you have unpacked OpenCV4Android SDK package:
-
- .. image:: images/eclipse_1_choose_workspace.png
- :alt: Choosing C:\Work\android-opencv\ as workspace location
- :align: center
-
-#. Import OpenCV library and samples into workspace.
-
- OpenCV library is packed as a ready-for-use `Android Library Project
- <http://developer.android.com/guide/developing/projects/index.html#LibraryProjects>`_.
- You can simply reference it in your projects.
-
- Each sample included into the |opencv_android_bin_pack| is a regular Android project that already
- references OpenCV library. Follow the steps below to import OpenCV and samples into the workspace:
-
- .. note:: OpenCV samples are indeed **dependent** on OpenCV library project so don't forget to import it to your workspace as well.
-
- * Right click on the :guilabel:`Package Explorer` window and choose :guilabel:`Import...` option
- from the context menu:
-
- .. image:: images/eclipse_5_import_command.png
- :alt: Select Import... from context menu
- :align: center
-
- * In the main panel select :menuselection:`General --> Existing Projects into Workspace` and
- press :guilabel:`Next` button:
-
- .. image:: images/eclipse_6_import_existing_projects.png
- :alt: General > Existing Projects into Workspace
- :align: center
-
- * In the :guilabel:`Select root directory` field locate your OpenCV package folder. Eclipse
- should automatically locate OpenCV library and samples:
-
- .. image:: images/eclipse_7_select_projects.png
- :alt: Locate OpenCV library and samples
- :align: center
-
- * Click :guilabel:`Finish` button to complete the import operation.
-
- After clicking :guilabel:`Finish` button Eclipse will load all selected projects into workspace,
- and you have to wait some time while it is building OpenCV samples. Just give a minute to
- Eclipse to complete initialization.
-
- .. warning :: After the initial import, on a non-Windows (Linux and Mac OS) operating system Eclipse
- will still show build errors for applications with native C++ code. To resolve the
- issues, please do the following:
-
- Open :guilabel:`Project Properties -> C/C++ Build`, and replace "Build command" text
- to ``"${NDKROOT}/ndk-build"`` (remove .cmd at the end).
-
- .. note :: In some cases the build errors don't disappear, then try the following actions:
-
- * right click on ``OpenCV Library`` project -> :guilabel:`Android Tools -> Fix Project Properties`,
- then menu :guilabel:`Project -> Clean... -> Clean all`
- * right click on the project with errors -> :guilabel:`Properties -> Android`, make sure the
- ``Target`` is selected and is ``Android 3.0`` or higher
- * check the build errors in the :guilabel:`Problems` view window and try to resolve them by yourselves
-
- .. image:: images/eclipse_cdt_cfg4.png
- :alt: Configure CDT
- :align: center
-
- Once Eclipse completes build you will have the clean workspace without any build errors:
-
- .. image:: images/eclipse_10_crystal_clean.png
- :alt: OpenCV package imported into Eclipse
- :align: center
-
-.. _Running_OpenCV_Samples:
-
-Running OpenCV Samples
-----------------------
-
-At this point you should be able to build and run the samples. Keep in mind, that
-``face-detection`` and ``Tutorial 2 - Mixed Processing`` include some native code and
-require Android NDK and NDK/CDT plugin for Eclipse to build working applications. If you haven't
-installed these tools, see the corresponding section of :ref:`Android_Dev_Intro`.
-
-.. warning:: Please consider that some samples use Android Java Camera API, which is accessible
- with an AVD. But most of samples use OpenCV Native Camera which **may not work** with
- an emulator.
-
-.. note:: Recent *Android SDK tools, revision 19+* can run ARM v7a OS images but they available not
- for all Android versions.
-
-Well, running samples from Eclipse is very simple:
-
-* Connect your device with :command:`adb` tool from Android SDK or create an emulator with camera support.
-
- * See `Managing Virtual Devices
- <http://developer.android.com/guide/developing/devices/index.html>`_ document for help with Android Emulator.
- * See `Using Hardware Devices
- <http://developer.android.com/guide/developing/device.html>`_ for help with real devices (not emulators).
-
-
-* Select project you want to start in :guilabel:`Package Explorer` and just press :kbd:`Ctrl + F11`
- or select option :menuselection:`Run --> Run` from the main menu, or click :guilabel:`Run` button on the toolbar.
-
- .. note:: Android Emulator can take several minutes to start. So, please, be patient.
-
-* On the first run Eclipse will ask you about the running mode for your application:
-
- .. image:: images/eclipse_11_run_as.png
- :alt: Run sample as Android Application
- :align: center
-
-* Select the :guilabel:`Android Application` option and click :guilabel:`OK` button. Eclipse will install and run the sample.
-
- Chances are that on the first launch you will not have the `OpenCV Manager <https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p>`_ package installed.
- In this case you will see the following message:
-
- .. image:: images/android_emulator_opencv_manager_fail.png
- :alt: You will see this message if you have no OpenCV Manager installed
- :align: center
-
- To get rid of the message you will need to install `OpenCV Manager` and the appropriate `OpenCV binary pack`.
- Simply tap :menuselection:`Yes` if you have *Google Play Market* installed on your device/emulator. It will redirect you to the corresponding page on *Google Play Market*.
-
- If you have no access to the *Market*, which is often the case with emulators - you will need to install the packages from OpenCV4Android SDK folder manually. See :ref:`manager_selection` for details.
-
- .. code-block:: sh
- :linenos:
-
- <Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/apk/OpenCV_2.4.9_Manager_2.18_armv7a-neon.apk
-
- .. note:: ``armeabi``, ``armv7a-neon``, ``arm7a-neon-android8``, ``mips`` and ``x86`` stand for
- platform targets:
-
- * ``armeabi`` is for ARM v5 and ARM v6 architectures with Android API 8+,
-
- * ``armv7a-neon`` is for NEON-optimized ARM v7 with Android API 9+,
-
- * ``arm7a-neon-android8`` is for NEON-optimized ARM v7 with Android API 8,
-
- * ``mips`` is for MIPS architecture with Android API 9+,
-
- * ``x86`` is for Intel x86 CPUs with Android API 9+.
-
- If using hardware device for testing/debugging, run the following command to learn
- its CPU architecture:
-
- .. code-block:: sh
-
- adb shell getprop ro.product.cpu.abi
-
- If you're using an AVD emulator, go :menuselection:`Window > AVD Manager` to see the
- list of availible devices. Click :menuselection:`Edit` in the context menu of the
- selected device. In the window, which then pop-ups, find the CPU field.
-
- You may also see section :ref:`manager_selection` for details.
-
-
- When done, you will be able to run OpenCV samples on your device/emulator seamlessly.
-
-* Here is ``Sample - image-manipulations`` sample, running on top of stock camera-preview of the emulator.
-
- .. image:: images/emulator_canny.png
- :alt: 'Sample - image-manipulations' running Canny
- :align: center
-
-
-What's next
-===========
-
-Now, when you have your instance of OpenCV4Adroid SDK set up and configured,
-you may want to proceed to using OpenCV in your own application.
-You can learn how to do that in a separate :ref:`dev_with_OCV_on_Android` tutorial.
+++ /dev/null
-
-.. _Android_Dev_Intro:
-
-
-Introduction into Android Development
-*************************************
-
-This guide was designed to help you in learning Android development basics and setting up your
-working environment quickly. It was written with Windows 7 in mind, though it would work with Linux
-(Ubuntu), Mac OS X and any other OS supported by Android SDK.
-
-If you encounter any error after thoroughly following these steps, feel free to contact us via
-`OpenCV4Android <https://groups.google.com/group/android-opencv/>`_ discussion group or
-OpenCV `Q&A forum <http://answers.opencv.org>`_. We'll do our best to help you out.
-
-Preface
-=======
-Android is a Linux-based, open source mobile operating system developed by Open Handset Alliance
-led by Google. See the `Android home site <http://www.android.com/about/>`_ for general details.
-
-Development for Android significantly differs from development for other platforms.
-So before starting programming for Android we recommend you make sure that you are familiar with the
-following key topis:
-
-#. `Java <http://en.wikipedia.org/wiki/Java_(programming_language)>`_ programming language that is
- the primary development technology for Android OS. Also, you can find
- `Oracle docs on Java <http://docs.oracle.com/javase/>`_ useful.
-#. `Java Native Interface (JNI) <http://en.wikipedia.org/wiki/Java_Native_Interface>`_ that is a
- technology of running native code in Java virtual machine. Also, you can find
- `Oracle docs on JNI <http://docs.oracle.com/javase/7/docs/technotes/guides/jni/>`_ useful.
-#. `Android Activity <http://developer.android.com/training/basics/activity-lifecycle/starting.html>`_
- and its lifecycle, that is an essential Android API class.
-#. OpenCV development will certainly require some knowlege of the
- `Android Camera <http://developer.android.com/guide/topics/media/camera.html>`_ specifics.
-
-
-Quick environment setup for Android development
-===============================================
-
-If you are making a clean environment install, then you can try `Tegra Android Development Pack <https://developer.nvidia.com/tegra-android-development-pack>`_
-(**TADP**) released by **NVIDIA**.
-
- .. note:: Starting the *version 2.0* the TADP package includes *OpenCV for Tegra* SDK that is a regular *OpenCV4Android SDK* extended with Tegra-specific stuff.
-
-When unpacked, TADP will cover all of the environment setup automatically and you can skip the rest of the guide.
-
-If you are a beginner in Android development then we also recommend you to start with TADP.
-
- .. note:: *NVIDIA*\ 's Tegra Android Development Pack includes some special features for
- |Nvidia_Tegra_Platform|_ but its use is not limited to *Tegra* devices only.
-
-* You need at least *1.6 Gb* free disk space for the install.
-
-* TADP will download Android SDK platforms and Android NDK from Google's server, so Internet
- connection is required for the installation.
-
-* TADP may ask you to flash your development kit at the end of installation process. Just skip
- this step if you have no |Tegra_Development_Kit|_\ .
-
-* (``UNIX``) TADP will ask you for *root* in the middle of installation, so you need to be a
- member of *sudo* group.
-
- ..
-
-.. |Nvidia_Tegra_Platform| replace:: *NVIDIA*\ ’s Tegra platform
-.. _Nvidia_Tegra_Platform: http://www.nvidia.com/object/tegra-3-processor.html
-.. |Tegra_Development_Kit| replace:: Tegra Development Kit
-.. _Tegra_Development_Kit: http://developer.nvidia.com/mobile/tegra-hardware-sales-inquiries
-
-.. _Android_Environment_Setup_Lite:
-
-
-Manual environment setup for Android development
-================================================
-
-Development in Java
--------------------
-
-You need the following software to be installed in order to develop for Android in Java:
-
-#. **Sun JDK 6** (Sun JDK 7 is also possible)
-
- Visit `Java SE Downloads page <http://www.oracle.com/technetwork/java/javase/downloads/>`_
- and download an installer for your OS.
-
- Here is a detailed :abbr:`JDK (Java Development Kit)`
- `installation guide <http://source.android.com/source/initializing.html#installing-the-jdk>`_
- for Ubuntu and Mac OS (only JDK sections are applicable for OpenCV)
-
- .. note:: OpenJDK is not suitable for Android development, since Android SDK supports only Sun JDK.
- If you use Ubuntu, after installation of Sun JDK you should run the following command to set
- Sun java environment:
-
- .. code-block:: bash
-
- sudo update-java-alternatives --set java-6-sun
-
- .. TODO: Add a note on Sun/Oracle Java installation on Ubuntu 12.
-
-#. **Android SDK**
-
- Get the latest ``Android SDK`` from http://developer.android.com/sdk/index.html
-
- Here is Google's `install guide <http://developer.android.com/sdk/installing.html>`_ for the SDK.
-
- .. note:: You can choose downloading **ADT Bundle package** that in addition to Android SDK Tools includes
- Eclipse + ADT + NDK/CDT plugins, Android Platform-tools, the latest Android platform and the latest
- Android system image for the emulator - this is the best choice for those who is setting up Android
- development environment the first time!
-
- .. note:: If you are running x64 version of Ubuntu Linux, then you need ia32 shared libraries
- for use on amd64 and ia64 systems to be installed. You can install them with the
- following command:
-
- .. code-block:: bash
-
- sudo apt-get install ia32-libs
-
- For Red Hat based systems the following command might be helpful:
-
- .. code-block:: bash
-
- sudo yum install libXtst.i386
-
-#. **Android SDK components**
-
- You need the following SDK components to be installed:
-
- * *Android SDK Tools, revision 20* or newer.
-
- Older revisions should also work, but they are not recommended.
-
- * *SDK Platform Android 3.0* (``API 11``).
-
- The minimal platform supported by OpenCV Java API is **Android 2.2** (``API 8``). This is also
- the minimum API Level required for the provided samples to run.
- See the ``<uses-sdk android:minSdkVersion="8"/>`` tag in their **AndroidManifest.xml** files.
- But for successful compilation the **target** platform should be set to Android 3.0 (API 11) or higher. It will not prevent them from running on Android 2.2.
-
- .. image:: images/android_sdk_and_avd_manager.png
- :alt: Android SDK Manager
- :align: center
-
- See `Adding Platforms and Packages <http://developer.android.com/sdk/installing/adding-packages.html>`_
- for help with installing/updating SDK components.
-
-#. **Eclipse IDE**
-
- Check the `Android SDK System Requirements <http://developer.android.com/sdk/requirements.html>`_
- document for a list of Eclipse versions that are compatible with the Android SDK.
- For OpenCV 2.4.x we recommend **Eclipse 3.7 (Indigo)** or **Eclipse 4.2 (Juno)**. They work well for
- OpenCV under both Windows and Linux.
-
- If you have no Eclipse installed, you can get it from the `official site <http://www.eclipse.org/downloads/>`_.
-
-#. **ADT plugin for Eclipse**
-
- These instructions are copied from
- `Android Developers site <http://developer.android.com/sdk/installing/installing-adt.html>`_,
- check it out in case of any ADT-related problem.
-
- Assuming that you have Eclipse IDE installed, as described above, follow these steps to download
- and install the ADT plugin:
-
- #. Start Eclipse, then select :menuselection:`Help --> Install New Software...`
- #. Click :guilabel:`Add` (in the top-right corner).
- #. In the :guilabel:`Add Repository` dialog that appears, enter "ADT Plugin" for the Name and the
- following URL for the Location:
-
- https://dl-ssl.google.com/android/eclipse/
-
- #. Click :guilabel:`OK`
-
- .. note:: If you have trouble acquiring the plugin, try using "http" in the Location URL,
- instead of "https" (https is preferred for security reasons).
-
- #. In the :guilabel:`Available Software` dialog, select the checkbox next to
- :guilabel:`Developer Tools` and click :guilabel:`Next`.
- #. In the next window, you'll see a list of the tools to be downloaded. Click :guilabel:`Next`.
-
- .. note:: If you also plan to develop native C++ code with Android NDK don't forget to
- enable `NDK Plugins` installations as well.
-
- .. image:: images/eclipse_inst_adt.png
- :alt: ADT installation
- :align: center
-
-
- #. Read and accept the license agreements, then click :guilabel:`Finish`.
-
- .. note:: If you get a security warning saying that the authenticity or validity of the software
- can't be established, click :guilabel:`OK`.
-
- #. When the installation completes, restart Eclipse.
-
-Native development in C++
--------------------------
-
-You need the following software to be installed in order to develop for Android in C++:
-
-#. **Android NDK**
-
- To compile C++ code for Android platform you need ``Android Native Development Kit`` (*NDK*).
-
- You can get the latest version of NDK from the
- `download page <http://developer.android.com/tools/sdk/ndk/index.html>`_.
- To install Android NDK just extract the archive to some folder on your computer. Here are
- `installation instructions <http://developer.android.com/tools/sdk/ndk/index.html#Installing>`_.
-
- .. note:: Before start you can read official Android NDK documentation which is in the Android
- NDK archive, in the folder :file:`docs/`.
- The main article about using Android NDK build system is in the :file:`ANDROID-MK.html` file.
- Some additional information you can find in
- the :file:`APPLICATION-MK.html`, :file:`NDK-BUILD.html` files,
- and :file:`CPU-ARM-NEON.html`, :file:`CPLUSPLUS-SUPPORT.html`, :file:`PREBUILTS.html`.
-
-#. **CDT plugin for Eclipse**
-
- If you selected for installation the ``NDK plugins`` component of Eclipse ADT plugin (see the picture above) your Eclipse IDE
- should already have ``CDT plugin`` (that means ``C/C++ Development Tooling``).
- There are several possible ways to integrate compilation of C++ code by Android NDK into Eclipse
- compilation process. We recommend the approach based on Eclipse
- :abbr:`CDT(C/C++ Development Tooling)` Builder.
-
-
-Android application structure
-=============================
-
-Usually source code of an Android application has the following structure:
-
-+ :file:`root folder of the project/`
-
- - :file:`jni/`
-
- - :file:`libs/`
-
- - :file:`res/`
-
- - :file:`src/`
-
- - :file:`AndroidManifest.xml`
-
- - :file:`project.properties`
-
- - :file:`... other files ...`
-
-Where:
-
-* the :file:`src` folder contains Java code of the application,
-
-* the :file:`res` folder contains resources of the application (images, xml files describing UI
- layout, etc),
-
-* the :file:`libs` folder will contain native libraries after a successful build,
-
-* and the :file:`jni` folder contains C/C++ application source code and NDK's build scripts
- :file:`Android.mk` and :file:`Application.mk` producing the native libraries,
-
-* :file:`AndroidManifest.xml` file presents essential information about application to the Android
- system (name of the Application, name of main application's package, components of the
- application, required permissions, etc).
-
- It can be created using Eclipse wizard or :command:`android` tool from Android SDK.
-
-* :file:`project.properties` is a text file containing information about target Android platform
- and other build details. This file is generated by Eclipse or can be created with
- :command:`android` tool included in Android SDK.
-
-.. note:: Both :file:`AndroidManifest.xml` and :file:`project.properties` files are required to
- compile the C++ part of the application, since Android NDK build system relies on them.
- If any of these files does not exist, compile the Java part of the project before the C++ part.
-
-
-:file:`Android.mk` and :file:`Application.mk` scripts
-==================================================================
-
-The script :file:`Android.mk` usually has the following structure:
-
-.. code-block:: make
- :linenos:
-
- LOCAL_PATH := $(call my-dir)
-
- include $(CLEAR_VARS)
- LOCAL_MODULE := <module_name>
- LOCAL_SRC_FILES := <list of .c and .cpp project files>
- <some variable name> := <some variable value>
- ...
- <some variable name> := <some variable value>
-
- include $(BUILD_SHARED_LIBRARY)
-
-This is the minimal file :file:`Android.mk`, which builds C++ source code of an Android application.
-Note that the first two lines and the last line are mandatory for any :file:`Android.mk`.
-
-Usually the file :file:`Application.mk` is optional, but in case of project using OpenCV, when STL
-and exceptions are used in C++, it also should be created. Example of the file :file:`Application.mk`:
-
-.. code-block:: make
- :linenos:
-
- APP_STL := gnustl_static
- APP_CPPFLAGS := -frtti -fexceptions
- APP_ABI := all
-
-.. note:: We recommend setting ``APP_ABI := all`` for all targets. If you want to specify the
- target explicitly, use ``armeabi`` for ARMv5/ARMv6, ``armeabi-v7a`` for ARMv7, ``x86``
- for Intel Atom or ``mips`` for MIPS.
-
-
-.. _NDK_build_cli:
-
-Building application native part from command line
-==================================================
-
-Here is the standard way to compile C++ part of an Android application:
-
-.. warning:: We strongly reccomend using ``cmd.exe`` (standard Windows console) instead of Cygwin on
- **Windows**. Use the latter if only you're absolutely sure about, what you're doing. Cygwin
- is not really supported and we are unlikely to help you in case you encounter some
- problems with it. So, use it only if you're capable of handling the consequences yourself.
-
-#. Open console and go to the root folder of an Android application
-
- .. code-block:: bash
-
- cd <root folder of the project>/
-
-#. Run the following command
-
- .. code-block:: bash
-
- <path_where_NDK_is_placed>/ndk-build
-
- .. note:: On Windows we recommend to use ``ndk-build.cmd`` in standard Windows console (``cmd.exe``)
- rather than the similar ``bash`` script in ``Cygwin`` shell.
-
- .. image:: images/ndk_build.png
- :alt: NDK build
- :align: center
-
-#. After executing this command the C++ part of the source code is compiled.
-
-After that the Java part of the application can be (re)compiled (using either *Eclipse* or *Ant* build tool).
-
-.. note:: Some parameters can be set for the :command:`ndk-build`:
-
- **Example 1**: Verbose compilation
-
- .. code-block:: bash
-
- <path_where_NDK_is_placed>/ndk-build V=1
-
- **Example 2**: Rebuild all
-
- .. code-block:: bash
-
- <path_where_NDK_is_placed>/ndk-build -B
-
-.. _CDT_Builder:
-
-Building application native part from *Eclipse* (CDT Builder)
-=============================================================
-
-There are several possible ways to integrate compilation of native C++ code by Android NDK into
-Eclipse build process. We recommend the approach based on Eclipse
-:abbr:`CDT(C/C++ Development Tooling)` Builder.
-
-.. important:: OpenCV for Android package since version 2.4.2 contains sample projects
- pre-configured CDT Builders. For your own projects follow the steps below.
-
-#. Define the ``NDKROOT`` environment variable containing the path to Android NDK in your system
- (e.g. ``"X:\\Apps\\android-ndk-r8"`` or ``"/opt/android-ndk-r8"``).
-
- **On Windows** an environment variable can be set via
- :guilabel:`My Computer -> Properties -> Advanced -> Environment variables`.
- On Windows 7 it's also possible to use `setx <http://ss64.com/nt/setx.html>`_ command in a console session.
-
- **On Linux** and **MacOS** an environment variable can be set via appending a
- ``"export VAR_NAME=VAR_VALUE"`` line to the :file:`"~/.bashrc"` file and logging off and then on.
-
- .. note:: It's also possible to define the ``NDKROOT`` environment variable within Eclipse IDE,
- but it should be done for every new workspace you create. If you prefer this option better than setting system
- environment variable, open Eclipse menu :guilabel:`Window -> Preferences -> C/C++ -> Build -> Environment`,
- press the :guilabel:`Add...` button and set variable name to ``NDKROOT`` and value to local Android NDK path.
-
-#. After that you need to **restart Eclipse** to apply the changes.
-
-#. Open Eclipse and load the Android app project to configure.
-
-#. Add C/C++ Nature to the project via Eclipse menu :guilabel:`New -> Other -> C/C++ -> Convert to a C/C++ Project`.
-
- .. image:: images/eclipse_cdt_cfg1.png
- :alt: Configure CDT
- :align: center
-
- And:
-
- .. image:: images/eclipse_cdt_cfg2.png
- :alt: Configure CDT
- :align: center
-
-#. Select the project(s) to convert. Specify "Project type" = ``Makefile project``,
- "Toolchains" = ``Other Toolchain``.
-
- .. image:: images/eclipse_cdt_cfg3.png
- :alt: Configure CDT
- :align: center
-
-#. Open :guilabel:`Project Properties -> C/C++ Build`, uncheck ``Use default build command``,
- replace "Build command" text from ``"make"`` to
-
- ``"${NDKROOT}/ndk-build.cmd"`` on Windows,
-
- ``"${NDKROOT}/ndk-build"`` on Linux and MacOS.
-
- .. image:: images/eclipse_cdt_cfg4.png
- :alt: Configure CDT
- :align: center
-
-#. Go to :guilabel:`Behaviour` tab and change "Workbench build type" section like shown below:
-
- .. image:: images/eclipse_cdt_cfg5.png
- :alt: Configure CDT
- :align: center
-
-#. Press :guilabel:`OK` and make sure the ``ndk-build`` is successfully invoked when building the project.
-
- .. image:: images/eclipse_cdt_cfg6.png
- :alt: Configure CDT
- :align: center
-
-#. If you open your C++ source file in Eclipse editor, you'll see syntax error notifications.
- They are not real errors, but additional CDT configuring is required.
-
- .. image:: images/eclipse_cdt_cfg7.png
- :alt: Configure CDT
- :align: center
-
-#. Open :guilabel:`Project Properties -> C/C++ General -> Paths and Symbols` and add the following
- **Include** paths for **C++**:
-
- ::
-
- # for NDK r8 and prior:
- ${NDKROOT}/platforms/android-9/arch-arm/usr/include
- ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/include
- ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/libs/armeabi-v7a/include
- ${ProjDirPath}/../../sdk/native/jni/include
-
- ::
-
- # for NDK r8b and later:
- ${NDKROOT}/platforms/android-9/arch-arm/usr/include
- ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/4.6/include
- ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/4.6/libs/armeabi-v7a/include
- ${ProjDirPath}/../../sdk/native/jni/include
-
- The last path should be changed to the correct absolute or relative path to OpenCV4Android SDK location.
-
- This should clear the syntax error notifications in Eclipse C++ editor.
-
- .. image:: images/eclipse_cdt_cfg8.png
- :alt: Configure CDT
- :align: center
-
-
-Debugging and Testing
-=====================
-In this section we will give you some easy-to-follow instructions on how to set up an emulator or
-hardware device for testing and debugging an Android project.
-
-AVD
----
-AVD (*Android Virtual Device*) is not probably the most convenient way to test an OpenCV-dependent
-application, but sure the most uncomplicated one to configure.
-
-#. Assuming you already have *Android SDK* and *Eclipse IDE* installed, in Eclipse go
- :guilabel:`Window -> AVD Manager`.
-
- .. TODO: how to start AVD Manager without Eclipse...
-
-#. Press the :guilabel:`New` button in :guilabel:`AVD Manager` window.
-#. :guilabel:`Create new Android Virtual Device` window will let you select some properties for your
- new device, like target API level, size of SD-card and other.
-
- .. image:: images/AVD_create.png
- :alt: Configure builders
- :align: center
-
-#. When you click the :guilabel:`Create AVD` button, your new AVD will be availible in :guilabel:`AVD Manager`.
-#. Press :guilabel:`Start` to launch the device. Be aware that any AVD (a.k.a. Emulator) is usually
- much slower than a hardware Android device, so it may take up to several minutes to start.
-#. Go :guilabel:`Run -> Run/Debug` in Eclipse IDE to run your application in regular or debugging
- mode. :guilabel:`Device Chooser` will let you choose among the running devices or to start a new one.
-
-Hardware Device
----------------
-If you have an Android device, you can use it to test and debug your applications. This way is more
-authentic, though a little bit harder to set up. You need to make some actions for Windows and Linux
-operating systems to be able to work with Android devices. No extra actions are required for Mac OS.
-See detailed information on configuring hardware devices in subsections below.
-
-You may also consult the official
-`Android Developers site instructions <http://developer.android.com/tools/device.html>`_
-for more information.
-
-Windows host computer
-^^^^^^^^^^^^^^^^^^^^^
-
-#. Enable USB debugging on the Android device (via :guilabel:`Settings` menu).
-#. Attach the Android device to your PC with a USB cable.
-#. Go to :guilabel:`Start Menu` and **right-click** on :guilabel:`Computer`.
- Select :guilabel:`Manage` in the context menu. You may be asked for Administrative permissions.
-#. Select :guilabel:`Device Manager` in the left pane and find an unknown device in the list.
- You may try unplugging it and then plugging back in order to check whether it's your exact
- equipment appears in the list.
-
- .. image:: images/usb_device_connect_01.png
- :alt: Unknown device
- :align: center
-
-#. Try your luck installing `Google USB drivers` without any modifications: **right-click** on the
- unknown device, select :guilabel:`Properties` menu item --> :guilabel:`Details` tab -->
- :guilabel:`Update Driver` button.
-
- .. image:: images/usb_device_connect_05.png
- :alt: Device properties
- :align: center
-
-#. Select :guilabel:`Browse computer for driver software`.
-
- .. image:: images/usb_device_connect_06.png
- :alt: Browse for driver
- :align: center
-
-#. Specify the path to :file:`<Android SDK folder>/extras/google/usb_driver/` folder.
-
- .. image:: images/usb_device_connect_07.png
- :alt: Browse for driver
- :align: center
-
-#. If you get the prompt to install unverified drivers and report about success - you've finished
- with USB driver installation.
-
- .. image:: images/usb_device_connect_08.png
- :alt: Install prompt
- :align: center
-
- ` `
- .. FIXME: All such places should be replaced with something else! This is a bad separator.
-
- .. image:: images/usb_device_connect_09.png
- :alt: Installed OK
- :align: center
-
-#. Otherwise (getting the failure like shown below) follow the next steps.
-
- .. image:: images/usb_device_connect_12.png
- :alt: No driver
- :align: center
-
-#. Again **right-click** on the unknown device, select :guilabel:`Properties --> Details --> Hardware Ids`
- and copy the line like ``USB\VID_XXXX&PID_XXXX&MI_XX``.
-
- .. image:: images/usb_device_connect_02.png
- :alt: Device properties details
- :align: center
-
-#. Now open file :file:`<Android SDK folder>/extras/google/usb_driver/android_winusb.inf`. Select
- either ``Google.NTx86`` or ``Google.NTamd64`` section depending on your host system architecture.
-
- .. image:: images/usb_device_connect_03.png
- :alt: "android_winusb.inf"
- :align: center
-
-#. There should be a record like existing ones for your device and you need to add one manually.
-
- .. image:: images/usb_device_connect_04.png
- :alt: "android_winusb.inf"
- :align: center
-
-#. Save the :file:`android_winusb.inf` file and try to install the USB driver again.
-
- .. image:: images/usb_device_connect_05.png
- :alt: Device properties
- :align: center
-
- ` `
-
- .. image:: images/usb_device_connect_06.png
- :alt: Browse for driver
- :align: center
-
- ` `
-
- .. image:: images/usb_device_connect_07.png
- :alt: Browse for driver
- :align: center
-
-#. This time installation should go successfully.
-
- .. image:: images/usb_device_connect_08.png
- :alt: Install prompt
- :align: center
-
- ` `
-
- .. image:: images/usb_device_connect_09.png
- :alt: Installed OK
- :align: center
-
-#. And an unknown device is now recognized as an Android phone.
-
- .. image:: images/usb_device_connect_10.png
- :alt: "Known" device
- :align: center
-
-#. Successful device USB connection can be verified in console via ``adb devices`` command.
-
- .. image:: images/usb_device_connect_11.png
- :alt: "adb devices"
- :align: center
-
-#. Now, in Eclipse go :guilabel:`Run -> Run/Debug` to run your application in regular or debugging
- mode. :guilabel:`Device Chooser` will let you choose among the devices.
-
-Linux host computer
-^^^^^^^^^^^^^^^^^^^
-By default Linux doesn't recognize Android devices, but it's easy to fix this issue. On Ubuntu Linux
-you have to create a new **/etc/udev/rules.d/51-android.rules** configuration file that contains
-information about your Android device. You may find some Vendor ID's
-`here <http://developer.android.com/tools/device.html#VendorIds>`_ or execute :command:`lsusb`
-command to view VendorID of plugged Android device. Here is an example of such file for LG device:
-
-.. code-block:: guess
-
- SUBSYSTEM=="usb", ATTR{idVendor}=="1004", MODE="0666", GROUP="plugdev"
-
-Then restart your adb server (even better to restart the system), plug in your Android device and
-execute :command:`adb devices` command. You will see the list of attached devices:
-
-.. image:: images/usb_device_connect_ubuntu.png
- :alt: List of attached devices
- :align: center
-
-Mac OS host computer
-^^^^^^^^^^^^^^^^^^^^
-No actions are required, just connect your device via USB and run ``adb devices`` to check connection.
-
-What's next
-===========
-
-Now, when you have your development environment set up and configured, you may want to proceed to
-installing OpenCV4Android SDK. You can learn how to do that in a separate :ref:`O4A_SDK` tutorial.
+++ /dev/null
-
-.. _dev_with_OCV_on_Android:
-
-Android Development with OpenCV
-*******************************
-
-This tutorial has been created to help you use OpenCV library within your Android project.
-
-This guide was written with Windows 7 in mind, though it should work with any other OS supported by
-OpenCV4Android SDK.
-
-This tutorial assumes you have the following installed and configured:
-
-* JDK
-
-* Android SDK and NDK
-
-* Eclipse IDE
-
-* ADT and CDT plugins for Eclipse
-
- ..
-
-If you need help with anything of the above, you may refer to our :ref:`android_dev_intro` guide.
-
-This tutorial also assumes you have OpenCV4Android SDK already installed on your development
-machine and OpenCV Manager on your testing device correspondingly. If you need help with any of
-these, you may consult our :ref:`O4A_SDK` tutorial.
-
-If you encounter any error after thoroughly following these steps, feel free to contact us via
-`OpenCV4Android <https://groups.google.com/group/android-opencv/>`_ discussion group or OpenCV
-`Q&A forum <http://answers.opencv.org>`_ . We'll do our best to help you out.
-
-
-Using OpenCV Library Within Your Android Project
-================================================
-
-In this section we will explain how to make some existing project to use OpenCV.
-Starting with 2.4.2 release for Android, *OpenCV Manager* is used to provide apps with the best
-available version of OpenCV.
-You can get more information here: :ref:`Android_OpenCV_Manager` and in these
-`slides <https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p>`_.
-
-
-Java
-----
-
-Application Development with Async Initialization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Using async initialization is a **recommended** way for application development. It uses the OpenCV
-Manager to access OpenCV libraries externally installed in the target system.
-
-#. Add OpenCV library project to your workspace. Use menu
- :guilabel:`File -> Import -> Existing project in your workspace`.
-
- Press :guilabel:`Browse` button and locate OpenCV4Android SDK
- (:file:`OpenCV-2.4.9-android-sdk/sdk`).
-
- .. image:: images/eclipse_opencv_dependency0.png
- :alt: Add dependency from OpenCV library
- :align: center
-
-#. In application project add a reference to the OpenCV Java SDK in
- :guilabel:`Project -> Properties -> Android -> Library -> Add` select ``OpenCV Library - 2.4.9``.
-
- .. image:: images/eclipse_opencv_dependency1.png
- :alt: Add dependency from OpenCV library
- :align: center
-
-In most cases OpenCV Manager may be installed automatically from Google Play. For the case, when
-Google Play is not available, i.e. emulator, developer board, etc, you can install it manually
-using adb tool. See :ref:`manager_selection` for details.
-
-There is a very base code snippet implementing the async initialization. It shows basic principles.
-See the "15-puzzle" OpenCV sample for details.
-
-.. code-block:: java
- :linenos:
-
- public class Sample1Java extends Activity implements CvCameraViewListener {
-
- private BaseLoaderCallback mLoaderCallback = new BaseLoaderCallback(this) {
- @Override
- public void onManagerConnected(int status) {
- switch (status) {
- case LoaderCallbackInterface.SUCCESS:
- {
- Log.i(TAG, "OpenCV loaded successfully");
- mOpenCvCameraView.enableView();
- } break;
- default:
- {
- super.onManagerConnected(status);
- } break;
- }
- }
- };
-
- @Override
- public void onResume()
- {
- super.onResume();
- OpenCVLoader.initAsync(OpenCVLoader.OPENCV_VERSION_2_4_6, this, mLoaderCallback);
- }
-
- ...
- }
-
-It this case application works with OpenCV Manager in asynchronous fashion. ``OnManagerConnected``
-callback will be called in UI thread, when initialization finishes. Please note, that it is not
-allowed to use OpenCV calls or load OpenCV-dependent native libs before invoking this callback.
-Load your own native libraries that depend on OpenCV after the successful OpenCV initialization.
-Default ``BaseLoaderCallback`` implementation treat application context as Activity and calls
-``Activity.finish()`` method to exit in case of initialization failure. To override this behavior
-you need to override ``finish()`` method of ``BaseLoaderCallback`` class and implement your own
-finalization method.
-
-
-Application Development with Static Initialization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-According to this approach all OpenCV binaries are included into your application package. It is
-designed mostly for development purposes. This approach is deprecated for the production code,
-release package is recommended to communicate with OpenCV Manager via the async initialization
-described above.
-
-#. Add the OpenCV library project to your workspace the same way as for the async initialization
- above. Use menu :guilabel:`File -> Import -> Existing project in your workspace`,
- press :guilabel:`Browse` button and select OpenCV SDK path
- (:file:`OpenCV-2.4.9-android-sdk/sdk`).
-
- .. image:: images/eclipse_opencv_dependency0.png
- :alt: Add dependency from OpenCV library
- :align: center
-
-#. In the application project add a reference to the OpenCV4Android SDK in
- :guilabel:`Project -> Properties -> Android -> Library -> Add` select ``OpenCV Library - 2.4.9``;
-
- .. image:: images/eclipse_opencv_dependency1.png
- :alt: Add dependency from OpenCV library
- :align: center
-
-#. If your application project **doesn't have a JNI part**, just copy the corresponding OpenCV
- native libs from :file:`<OpenCV-2.4.9-android-sdk>/sdk/native/libs/<target_arch>` to your
- project directory to folder :file:`libs/<target_arch>`.
-
- In case of the application project **with a JNI part**, instead of manual libraries copying you
- need to modify your ``Android.mk`` file:
- add the following two code lines after the ``"include $(CLEAR_VARS)"`` and before
- ``"include path_to_OpenCV-2.4.9-android-sdk/sdk/native/jni/OpenCV.mk"``
-
- .. code-block:: make
- :linenos:
-
- OPENCV_CAMERA_MODULES:=on
- OPENCV_INSTALL_MODULES:=on
-
- The result should look like the following:
-
- .. code-block:: make
- :linenos:
-
- include $(CLEAR_VARS)
-
- # OpenCV
- OPENCV_CAMERA_MODULES:=on
- OPENCV_INSTALL_MODULES:=on
- include ../../sdk/native/jni/OpenCV.mk
-
- After that the OpenCV libraries will be copied to your application :file:`libs` folder during
- the JNI build.v
-
- Eclipse will automatically include all the libraries from the :file:`libs` folder to the
- application package (APK).
-
-#. The last step of enabling OpenCV in your application is Java initialization code before calling
- OpenCV API. It can be done, for example, in the static section of the ``Activity`` class:
-
- .. code-block:: java
- :linenos:
-
- static {
- if (!OpenCVLoader.initDebug()) {
- // Handle initialization error
- }
- }
-
- If you application includes other OpenCV-dependent native libraries you should load them
- **after** OpenCV initialization:
-
- .. code-block:: java
- :linenos:
-
- static {
- if (!OpenCVLoader.initDebug()) {
- // Handle initialization error
- } else {
- System.loadLibrary("my_jni_lib1");
- System.loadLibrary("my_jni_lib2");
- }
- }
-
-
-Native/C++
-----------
-
-To build your own Android application, using OpenCV as native part, the following steps should be
-taken:
-
-#. You can use an environment variable to specify the location of OpenCV package or just hardcode
- absolute or relative path in the :file:`jni/Android.mk` of your projects.
-
-#. The file :file:`jni/Android.mk` should be written for the current application using the common
- rules for this file.
-
- For detailed information see the Android NDK documentation from the Android NDK archive, in the
- file :file:`<path_where_NDK_is_placed>/docs/ANDROID-MK.html`.
-
-#. The following line:
-
- .. code-block:: make
-
- include C:\Work\OpenCV4Android\OpenCV-2.4.9-android-sdk\sdk\native\jni\OpenCV.mk
-
- Should be inserted into the :file:`jni/Android.mk` file **after** this line:
-
- .. code-block:: make
-
- include $(CLEAR_VARS)
-
-#. Several variables can be used to customize OpenCV stuff, but you **don't need** to use them when
- your application uses the `async initialization` via the `OpenCV Manager` API.
-
- .. note:: These variables should be set **before** the ``"include .../OpenCV.mk"`` line:
-
- .. code-block:: make
-
- OPENCV_INSTALL_MODULES:=on
-
- Copies necessary OpenCV dynamic libs to the project ``libs`` folder in order to include them
- into the APK.
-
- .. code-block:: make
-
- OPENCV_CAMERA_MODULES:=off
-
- Skip native OpenCV camera related libs copying to the project ``libs`` folder.
-
- .. code-block:: make
-
- OPENCV_LIB_TYPE:=STATIC
-
- Perform static linking with OpenCV. By default dynamic link is used and the project JNI lib
- depends on ``libopencv_java.so``.
-
-#. The file :file:`Application.mk` should exist and should contain lines:
-
- .. code-block:: make
-
- APP_STL := gnustl_static
- APP_CPPFLAGS := -frtti -fexceptions
-
- Also, the line like this one:
-
- .. code-block:: make
-
- APP_ABI := armeabi-v7a
-
- Should specify the application target platforms.
-
- In some cases a linkage error (like ``"In function 'cv::toUtf16(std::basic_string<...>...
- undefined reference to 'mbstowcs'"``) happens when building an application JNI library,
- depending on OpenCV. The following line in the :file:`Application.mk` usually fixes it:
-
- .. code-block:: make
-
- APP_PLATFORM := android-9
-
-
-#. Either use :ref:`manual <NDK_build_cli>` ``ndk-build`` invocation or
- :ref:`setup Eclipse CDT Builder <CDT_Builder>` to build native JNI lib before (re)building the Java
- part and creating an APK.
-
-
-Hello OpenCV Sample
-===================
-
-Here are basic steps to guide you trough the process of creating a simple OpenCV-centric
-application. It will be capable of accessing camera output, processing it and displaying the
-result.
-
-#. Open Eclipse IDE, create a new clean workspace, create a new Android project
- :menuselection:`File --> New --> Android Project`
-
-#. Set name, target, package and ``minSDKVersion`` accordingly. The minimal SDK version for build
- with OpenCV4Android SDK is 11. Minimal device API Level (for application manifest) is 8.
-
-#. Allow Eclipse to create default activity. Lets name the activity ``HelloOpenCvActivity``.
-
-#. Choose Blank Activity with full screen layout. Lets name the layout ``HelloOpenCvLayout``.
-
-#. Import OpenCV library project to your workspace.
-
-#. Reference OpenCV library within your project properties.
-
- .. image:: images/dev_OCV_reference.png
- :alt: Reference OpenCV library.
- :align: center
-
-#. Edit your layout file as xml file and pass the following layout there:
-
- .. code-block:: xml
- :linenos:
-
- <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
- xmlns:tools="http://schemas.android.com/tools"
- xmlns:opencv="http://schemas.android.com/apk/res-auto"
- android:layout_width="match_parent"
- android:layout_height="match_parent" >
-
- <org.opencv.android.JavaCameraView
- android:layout_width="fill_parent"
- android:layout_height="fill_parent"
- android:visibility="gone"
- android:id="@+id/HelloOpenCvView"
- opencv:show_fps="true"
- opencv:camera_id="any" />
-
- </LinearLayout>
-
-#. Add the following permissions to the :file:`AndroidManifest.xml` file:
-
- .. code-block:: xml
- :linenos:
-
- </application>
-
- <uses-permission android:name="android.permission.CAMERA"/>
-
- <uses-feature android:name="android.hardware.camera" android:required="false"/>
- <uses-feature android:name="android.hardware.camera.autofocus" android:required="false"/>
- <uses-feature android:name="android.hardware.camera.front" android:required="false"/>
- <uses-feature android:name="android.hardware.camera.front.autofocus" android:required="false"/>
-
-#. Set application theme in AndroidManifest.xml to hide title and system buttons.
-
- .. code-block:: xml
- :linenos:
-
- <application
- android:icon="@drawable/icon"
- android:label="@string/app_name"
- android:theme="@android:style/Theme.NoTitleBar.Fullscreen" >
-
-#. Add OpenCV library initialization to your activity. Fix errors by adding requited imports.
-
- .. code-block:: java
- :linenos:
-
- private BaseLoaderCallback mLoaderCallback = new BaseLoaderCallback(this) {
- @Override
- public void onManagerConnected(int status) {
- switch (status) {
- case LoaderCallbackInterface.SUCCESS:
- {
- Log.i(TAG, "OpenCV loaded successfully");
- mOpenCvCameraView.enableView();
- } break;
- default:
- {
- super.onManagerConnected(status);
- } break;
- }
- }
- };
-
- @Override
- public void onResume()
- {
- super.onResume();
- OpenCVLoader.initAsync(OpenCVLoader.OPENCV_VERSION_2_4_6, this, mLoaderCallback);
- }
-
-#. Defines that your activity implements ``CvCameraViewListener2`` interface and fix activity related
- errors by defining missed methods. For this activity define ``onCreate``, ``onDestroy`` and
- ``onPause`` and implement them according code snippet bellow. Fix errors by adding requited
- imports.
-
- .. code-block:: java
- :linenos:
-
- private CameraBridgeViewBase mOpenCvCameraView;
-
- @Override
- public void onCreate(Bundle savedInstanceState) {
- Log.i(TAG, "called onCreate");
- super.onCreate(savedInstanceState);
- getWindow().addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
- setContentView(R.layout.HelloOpenCvLayout);
- mOpenCvCameraView = (CameraBridgeViewBase) findViewById(R.id.HelloOpenCvView);
- mOpenCvCameraView.setVisibility(SurfaceView.VISIBLE);
- mOpenCvCameraView.setCvCameraViewListener(this);
- }
-
- @Override
- public void onPause()
- {
- super.onPause();
- if (mOpenCvCameraView != null)
- mOpenCvCameraView.disableView();
- }
-
- public void onDestroy() {
- super.onDestroy();
- if (mOpenCvCameraView != null)
- mOpenCvCameraView.disableView();
- }
-
- public void onCameraViewStarted(int width, int height) {
- }
-
- public void onCameraViewStopped() {
- }
-
- public Mat onCameraFrame(CvCameraViewFrame inputFrame) {
- return inputFrame.rgba();
- }
-
-#. Run your application on device or emulator.
-
-Lets discuss some most important steps. Every Android application with UI must implement Activity
-and View. By the first steps we create blank activity and default view layout. The simplest
-OpenCV-centric application must implement OpenCV initialization, create its own view to show
-preview from camera and implements ``CvCameraViewListener2`` interface to get frames from camera and
-process it.
-
-First of all we create our application view using xml layout. Our layout consists of the only
-one full screen component of class ``org.opencv.android.JavaCameraView``. This class is
-implemented inside OpenCV library. It is inherited from ``CameraBridgeViewBase``, that extends
-``SurfaceView`` and uses standard Android camera API. Alternatively you can use
-``org.opencv.android.NativeCameraView`` class, that implements the same interface, but uses
-``VideoCapture`` class as camera access back-end. ``opencv:show_fps="true"`` and
-``opencv:camera_id="any"`` options enable FPS message and allow to use any camera on device.
-Application tries to use back camera first.
-
-After creating layout we need to implement ``Activity`` class. OpenCV initialization process has
-been already discussed above. In this sample we use asynchronous initialization. Implementation of
-``CvCameraViewListener`` interface allows you to add processing steps after frame grabbing from
-camera and before its rendering on screen. The most important function is ``onCameraFrame``. It is
-callback function and it is called on retrieving frame from camera. The callback input is object
-of ``CvCameraViewFrame`` class that represents frame from camera.
-
-.. note::
- Do not save or use ``CvCameraViewFrame`` object out of ``onCameraFrame`` callback. This object
- does not have its own state and its behavior out of callback is unpredictable!
-
-It has ``rgba()`` and ``gray()`` methods that allows to get frame as RGBA and one channel gray scale
-``Mat`` respectively. It expects that ``onCameraFrame`` function returns RGBA frame that will be
-drawn on the screen.
+++ /dev/null
-.. _clojure_dev_intro:
-
-Introduction to OpenCV Development with Clojure
-***********************************************
-
-As of OpenCV 2.4.4, OpenCV supports desktop Java development using
-nearly the same interface as for Android development.
-
-`Clojure <http://clojure.org/>`_ is a contemporary LISP dialect hosted
-by the Java Virtual Machine and it offers a complete interoperability
-with the underlying JVM. This means that we should even be able to use
-the Clojure REPL (Read Eval Print Loop) as and interactive programmable
-interface to the underlying OpenCV engine.
-
-What we'll do in this tutorial
-==============================
-
-This tutorial will help you in setting up a basic Clojure environment
-for interactively learning OpenCV within the fully programmable
-CLojure REPL.
-
-Tutorial source code
---------------------
-
-You can find a runnable source code of the sample in the
-:file:`samples/java/clojure/simple-sample` folder of the OpenCV
-repository. After having installed OpenCV and Clojure as explained in
-the tutorial, issue the following command to run the sample from the
-command line.
-
-.. code:: bash
-
- cd path/to/samples/java/clojure/simple-sample
- lein run
-
-Preamble
-========
-
-For detailed instruction on installing OpenCV with desktop Java support
-refer to the `corresponding tutorial <http://docs.opencv.org/2.4.4-beta/doc/tutorials/introduction/desktop_java/java_dev_intro.html>`_.
-
-If you are in hurry, here is a minimum quick start guide to install
-OpenCV on Mac OS X:
-
- NOTE 1: I'm assuming you already installed
- `xcode <https://developer.apple.com/xcode/>`_,
- `jdk <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_
- and `Cmake <http://www.cmake.org/cmake/resources/software.html>`_.
-
-.. code:: bash
-
- cd ~/
- mkdir opt
- git clone https://github.com/Itseez/opencv.git
- cd opencv
- git checkout 2.4
- mkdir build
- cd build
- cmake -DBUILD_SHARED_LIBS=OFF ..
- ...
- ...
- make -j8
- # optional
- # make install
-
-Install Leiningen
-=================
-
-Once you installed OpenCV with desktop java support the only other
-requirement is to install
-`Leiningeng <https://github.com/technomancy/leiningen>`_ which allows
-you to manage the entire life cycle of your CLJ projects.
-
-The available `installation guide <https://github.com/technomancy/leiningen#installation>`_ is very easy to be followed:
-
-1. `Download the script <https://raw.github.com/technomancy/leiningen/stable/bin/lein>`_
-2. Place it on your ``$PATH`` (cf. ``~/bin`` is a good choice if it is
- on your ``path``.)
-3. Set the script to be executable. (i.e. ``chmod 755 ~/bin/lein``).
-
-If you work on Windows, follow `this instruction <https://github.com/technomancy/leiningen#windows>`_
-
-You now have both the OpenCV library and a fully installed basic Clojure
-environment. What is now needed is to configure the Clojure environment
-to interact with the OpenCV library.
-
-Install the localrepo Leiningen plugin
-=======================================
-
-The set of commands (tasks in Leiningen parlance) natively supported by
-Leiningen can be very easily extended by various plugins. One of them is
-the `lein-localrepo <https://github.com/kumarshantanu/lein-localrepo>`_
-plugin which allows to install any jar lib as an artifact in the local
-maven repository of your machine (typically in the ``~/.m2/repository``
-directory of your username).
-
-We're going to use this ``lein`` plugin to add to the local maven
-repository the opencv components needed by Java and Clojure to use the
-opencv lib.
-
-Generally speaking, if you want to use a plugin on project base only, it
-can be added directly to a CLJ project created by ``lein``.
-
-Instead, when you want a plugin to be available to any CLJ project in
-your username space, you can add it to the ``profiles.clj`` in the
-``~/.lein/`` directory.
-
-The ``lein-localrepo`` plugin will be useful to me in other CLJ
-projects where I need to call native libs wrapped by a Java interface.
-So I decide to make it available to any CLJ project:
-
-.. code:: bash
-
- mkdir ~/.lein
-
-Create a file named ``profiles.clj`` in the ``~/.lein`` directory and
-copy into it the following content:
-
-.. code:: clojure
-
- {:user {:plugins [[lein-localrepo "0.5.2"]]}}
-
-Here we're saying that the version release ``"0.5.2"`` of the
-``lein-localrepo`` plugin will be available to the ``:user`` profile for
-any CLJ project created by ``lein``.
-
-You do not need to do anything else to install the plugin because it
-will be automatically downloaded from a remote repository the very first
-time you issue any ``lein`` task.
-
-Install the java specific libs as local repository
-==================================================
-
-If you followed the standard documentation for installing OpenCV on your
-computer, you should find the following two libs under the directory
-where you built OpenCV:
-
-- the ``build/bin/opencv-247.jar`` java lib
-- the ``build/lib/libopencv_java247.dylib`` native lib (or ``.so`` in
- you built OpenCV a GNU/Linux OS)
-
-They are the only opencv libs needed by the JVM to interact with OpenCV.
-
-Take apart the needed opencv libs
----------------------------------
-
-Create a new directory to store in the above two libs. Start by copying
-into it the ``opencv-247.jar`` lib.
-
-.. code:: bash
-
- cd ~/opt
- mkdir clj-opencv
- cd clj-opencv
- cp ~/opt/opencv/build/bin/opencv-247.jar .
-
-First lib done.
-
-Now, to be able to add the ``libopencv_java247.dylib`` shared native lib
-to the local maven repository, we first need to package it as a jar
-file.
-
-The native lib has to be copied into a directories layout which mimics
-the names of your operating system and architecture. I'm using a Mac OS
-X with a X86 64 bit architecture. So my layout will be the following:
-
-.. code:: bash
-
- mkdir -p native/macosx/x86_64
-
-Copy into the ``x86_64`` directory the ``libopencv_java247.dylib`` lib.
-
-.. code:: bash
-
- cp ~/opt/opencv/build/lib/libopencv_java247.dylib native/macosx/x86_64/
-
-If you're running OpenCV from a different OS/Architecture pair, here
-is a summary of the mapping you can choose from.
-
-.. code:: bash
-
- OS
-
- Mac OS X -> macosx
- Windows -> windows
- Linux -> linux
- SunOS -> solaris
-
- Architectures
-
- amd64 -> x86_64
- x86_64 -> x86_64
- x86 -> x86
- i386 -> x86
- arm -> arm
- sparc -> sparc
-
-Package the native lib as a jar
--------------------------------
-
-Next you need to package the native lib in a jar file by using the
-``jar`` command to create a new jar file from a directory.
-
-.. code:: bash
-
- jar -cMf opencv-native-247.jar native
-
-Note that ehe ``M`` option instructs the ``jar`` command to not create
-a MANIFEST file for the artifact.
-
-Your directories layout should look like the following:
-
-.. code:: bash
-
- tree
- .
- |__ native
- | |__ macosx
- | |__ x86_64
- | |__ libopencv_java247.dylib
- |
- |__ opencv-247.jar
- |__ opencv-native-247.jar
-
- 3 directories, 3 files
-
-Locally install the jars
-------------------------
-
-We are now ready to add the two jars as artifacts to the local maven
-repository with the help of the ``lein-localrepo`` plugin.
-
-.. code:: bash
-
- lein localrepo install opencv-247.jar opencv/opencv 2.4.7
-
-Here the ``localrepo install`` task creates the ``2.4.7.`` release of
-the ``opencv/opencv`` maven artifact from the ``opencv-247.jar`` lib and
-then installs it into the local maven repository. The ``opencv/opencv``
-artifact will then be available to any maven compliant project
-(Leiningen is internally based on maven).
-
-Do the same thing with the native lib previously wrapped in a new jar
-file.
-
-.. code:: bash
-
- lein localrepo install opencv-native-247.jar opencv/opencv-native 2.4.7
-
-Note that the groupId, ``opencv``, of the two artifacts is the same. We
-are now ready to create a new CLJ project to start interacting with
-OpenCV.
-
-Create a project
-----------------
-
-Create a new CLJ project by using the ``lein new`` task from the
-terminal.
-
-.. code:: bash
-
- # cd in the directory where you work with your development projects (e.g. ~/devel)
- lein new simple-sample
- Generating a project called simple-sample based on the 'default' template.
- To see other templates (app, lein plugin, etc), try `lein help new`.
-
-The above task creates the following ``simple-sample`` directories
-layout:
-
-.. code:: bash
-
- tree simple-sample/
- simple-sample/
- |__ LICENSE
- |__ README.md
- |__ doc
- | |__ intro.md
- |
- |__ project.clj
- |__ resources
- |__ src
- | |__ simple_sample
- | |__ core.clj
- |__ test
- |__ simple_sample
- |__ core_test.clj
-
- 6 directories, 6 files
-
-We need to add the two ``opencv`` artifacts as dependencies of the newly
-created project. Open the ``project.clj`` and modify its dependencies
-section as follows:
-
-.. code:: bash
-
- (defproject simple-sample "0.1.0-SNAPSHOT"
- :description "FIXME: write description"
- :url "http://example.com/FIXME"
- :license {:name "Eclipse Public License"
- :url "http://www.eclipse.org/legal/epl-v10.html"}
- :dependencies [[org.clojure/clojure "1.5.1"]
- [opencv/opencv "2.4.7"] ; added line
- [opencv/opencv-native "2.4.7"]]) ;added line
-
-
-Note that The Clojure Programming Language is a jar artifact too. This
-is why Clojure is called an hosted language.
-
-To verify that everything went right issue the ``lein deps`` task. The
-very first time you run a ``lein`` task it will take sometime to
-download all the required dependencies before executing the task
-itself.
-
-.. code:: bash
-
- cd simple-sample
- lein deps
- ...
-
-The ``deps`` task reads and merges from the ``project.clj`` and the
-``~/.lein/profiles.clj`` files all the dependencies of the
-``simple-sample`` project and verifies if they have already been
-cached in the local maven repository. If the task returns without
-messages about not being able to retrieve the two new artifacts your
-installation is correct, otherwise go back and double check that you
-did everything right.
-
-REPLing with OpenCV
--------------------
-
-Now ``cd`` in the ``simple-sample`` directory and issue the following
-``lein`` task:
-
-.. code:: bash
-
- cd simple-sample
- lein repl
- ...
- ...
- nREPL server started on port 50907 on host 127.0.0.1
- REPL-y 0.3.0
- Clojure 1.5.1
- Docs: (doc function-name-here)
- (find-doc "part-of-name-here")
- Source: (source function-name-here)
- Javadoc: (javadoc java-object-or-class-here)
- Exit: Control+D or (exit) or (quit)
- Results: Stored in vars *1, *2, *3, an exception in *e
-
- user=>
-
-You can immediately interact with the REPL by issuing any CLJ expression
-to be evaluated.
-
-.. code:: clojure
-
- user=> (+ 41 1)
- 42
- user=> (println "Hello, OpenCV!")
- Hello, OpenCV!
- nil
- user=> (defn foo [] (str "bar"))
- #'user/foo
- user=> (foo)
- "bar"
-
-When ran from the home directory of a lein based project, even if the
-``lein repl`` task automatically loads all the project dependencies, you
-still need to load the opencv native library to be able to interact with
-the OpenCV.
-
-.. code:: clojure
-
- user=> (clojure.lang.RT/loadLibrary org.opencv.core.Core/NATIVE_LIBRARY_NAME)
- nil
-
-Then you can start interacting with OpenCV by just referencing the fully
-qualified names of its classes.
-
- NOTE 2: `Here <http://docs.opencv.org/java/>`_ you can find the
- full OpenCV Java API.
-
-.. code:: clojure
-
- user=> (org.opencv.core.Point. 0 0)
- #<Point {0.0, 0.0}>
-
-Here we created a two dimensions opencv ``Point`` instance. Even if all
-the java packages included within the java interface to OpenCV are
-immediately available from the CLJ REPL, it's very annoying to prefix
-the ``Point.`` instance constructors with the fully qualified package
-name.
-
-Fortunately CLJ offer a very easy way to overcome this annoyance by
-directly importing the ``Point`` class.
-
-.. code:: clojure
-
- user=> (import 'org.opencv.core.Point)
- org.opencv.core.Point
- user=> (def p1 (Point. 0 0))
- #'user/p1
- user=> p1
- #<Point {0.0, 0.0}>
- user=> (def p2 (Point. 100 100))
- #'user/p2
-
-We can even inspect the class of an instance and verify if the value of
-a symbol is an instance of a ``Point`` java class.
-
-.. code:: clojure
-
- user=> (class p1)
- org.opencv.core.Point
- user=> (instance? org.opencv.core.Point p1)
- true
-
-If we now want to use the opencv ``Rect`` class to create a rectangle,
-we again have to fully qualify its constructor even if it leaves in
-the same ``org.opencv.core`` package of the ``Point`` class.
-
-.. code:: clojure
-
- user=> (org.opencv.core.Rect. p1 p2)
- #<Rect {0, 0, 100x100}>
-
-Again, the CLJ importing facilities is very handy and let you to map
-more symbols in one shot.
-
-.. code:: clojure
-
- user=> (import '[org.opencv.core Point Rect Size])
- org.opencv.core.Size
- user=> (def r1 (Rect. p1 p2))
- #'user/r1
- user=> r1
- #<Rect {0, 0, 100x100}>
- user=> (class r1)
- org.opencv.core.Rect
- user=> (instance? org.opencv.core.Rect r1)
- true
- user=> (Size. 100 100)
- #<Size 100x100>
- user=> (def sq-100 (Size. 100 100))
- #'user/sq-100
- user=> (class sq-100)
- org.opencv.core.Size
- user=> (instance? org.opencv.core.Size sq-100)
- true
-
-Obviously you can call methods on instances as well.
-
-.. code:: clojure
-
- user=> (.area r1)
- 10000.0
- user=> (.area sq-100)
- 10000.0
-
-Or modify the value of a member field.
-
-.. code:: clojure
-
- user=> (set! (.x p1) 10)
- 10
- user=> p1
- #<Point {10.0, 0.0}>
- user=> (set! (.width sq-100) 10)
- 10
- user=> (set! (.height sq-100) 10)
- 10
- user=> (.area sq-100)
- 100.0
-
-If you find yourself not remembering a OpenCV class behavior, the
-REPL gives you the opportunity to easily search the corresponding
-javadoc documention:
-
-.. code:: clojure
-
- user=> (javadoc Rect)
- "http://www.google.com/search?btnI=I%27m%20Feeling%20Lucky&q=allinurl:org/opencv/core/Rect.html"
-
-Mimic the OpenCV Java Tutorial Sample in the REPL
--------------------------------------------------
-
-Let's now try to port to Clojure the `opencv java tutorial sample <http://docs.opencv.org/2.4.4-beta/doc/tutorials/introduction/desktop_java/java_dev_intro.html>`_.
-Instead of writing it in a source file we're going to evaluate it at the
-REPL.
-
-Following is the original Java source code of the cited sample.
-
-.. code:: java
-
- import org.opencv.core.Mat;
- import org.opencv.core.CvType;
- import org.opencv.core.Scalar;
-
- class SimpleSample {
-
- static{ System.loadLibrary("opencv_java244"); }
-
- public static void main(String[] args) {
- Mat m = new Mat(5, 10, CvType.CV_8UC1, new Scalar(0));
- System.out.println("OpenCV Mat: " + m);
- Mat mr1 = m.row(1);
- mr1.setTo(new Scalar(1));
- Mat mc5 = m.col(5);
- mc5.setTo(new Scalar(5));
- System.out.println("OpenCV Mat data:\n" + m.dump());
- }
-
- }
-
-Add injections to the project
------------------------------
-
-Before start coding, we'd like to eliminate the boring need of
-interactively loading the native opencv lib any time we start a new REPL
-to interact with it.
-
-First, stop the REPL by evaluating the ``(exit)`` expression at the REPL
-prompt.
-
-.. code:: clojure
-
- user=> (exit)
- Bye for now!
-
-Then open your ``project.clj`` file and edit it as follows:
-
-.. code:: clojure
-
- (defproject simple-sample "0.1.0-SNAPSHOT"
- ...
- :injections [(clojure.lang.RT/loadLibrary org.opencv.core.Core/NATIVE_LIBRARY_NAME)])
-
-Here we're saying to load the opencv native lib anytime we run the REPL
-in such a way that we have not anymore to remember to manually do it.
-
-Rerun the ``lein repl`` task
-
-.. code:: bash
-
- lein repl
- nREPL server started on port 51645 on host 127.0.0.1
- REPL-y 0.3.0
- Clojure 1.5.1
- Docs: (doc function-name-here)
- (find-doc "part-of-name-here")
- Source: (source function-name-here)
- Javadoc: (javadoc java-object-or-class-here)
- Exit: Control+D or (exit) or (quit)
- Results: Stored in vars *1, *2, *3, an exception in *e
-
- user=>
-
-Import the interested OpenCV java interfaces.
-
-.. code:: clojure
-
- user=> (import '[org.opencv.core Mat CvType Scalar])
- org.opencv.core.Scalar
-
-We're going to mimic almost verbatim the original OpenCV java tutorial
-to:
-
-- create a 5x10 matrix with all its elements intialized to 0
-- change the value of every element of the second row to 1
-- change the value of every element of the 6th column to 5
-- print the content of the obtained matrix
-
-.. code:: clojure
-
- user=> (def m (Mat. 5 10 CvType/CV_8UC1 (Scalar. 0 0)))
- #'user/m
- user=> (def mr1 (.row m 1))
- #'user/mr1
- user=> (.setTo mr1 (Scalar. 1 0))
- #<Mat Mat [ 1*10*CV_8UC1, isCont=true, isSubmat=true, nativeObj=0x7fc9dac49880, dataAddr=0x7fc9d9c98d5a ]>
- user=> (def mc5 (.col m 5))
- #'user/mc5
- user=> (.setTo mc5 (Scalar. 5 0))
- #<Mat Mat [ 5*1*CV_8UC1, isCont=false, isSubmat=true, nativeObj=0x7fc9d9c995a0, dataAddr=0x7fc9d9c98d55 ]>
- user=> (println (.dump m))
- [0, 0, 0, 0, 0, 5, 0, 0, 0, 0;
- 1, 1, 1, 1, 1, 5, 1, 1, 1, 1;
- 0, 0, 0, 0, 0, 5, 0, 0, 0, 0;
- 0, 0, 0, 0, 0, 5, 0, 0, 0, 0;
- 0, 0, 0, 0, 0, 5, 0, 0, 0, 0]
- nil
-
-If you are accustomed to a functional language all those abused and
-mutating nouns are going to irritate your preference for verbs. Even
-if the CLJ interop syntax is very handy and complete, there is still
-an impedance mismatch between any OOP language and any FP language
-(bein Scala a mixed paradigms programming language).
-
-To exit the REPL type ``(exit)``, ``ctr-D`` or ``(quit)`` at the REPL
-prompt.
-
-.. code:: clojure
-
- user=> (exit)
- Bye for now!
-
-Interactively load and blur an image
-------------------------------------
-
-In the next sample you will learn how to interactively load and blur and
-image from the REPL by using the following OpenCV methods:
-
-- the ``imread`` static method from the ``Highgui`` class to read an
- image from a file
-- the ``imwrite`` static method from the ``Highgui`` class to write an
- image to a file
-- the ``GaussianBlur`` static method from the ``Imgproc`` class to
- apply to blur the original image
-
-We're also going to use the ``Mat`` class which is returned from the
-``imread`` method and accpeted as the main argument to both the
-``GaussianBlur`` and the ``imwrite`` methods.
-
-Add an image to the project
----------------------------
-
-First we want to add an image file to a newly create directory for
-storing static resources of the project.
-
-.. image:: images/lena.png
- :alt: Original Image
- :align: center
-
-.. code:: bash
-
- mkdir -p resources/images
- cp ~/opt/opencv/doc/tutorials/introduction/desktop_java/images/lena.png resource/images/
-
-Read the image
---------------
-
-Now launch the REPL as usual and start by importing all the OpenCV
-classes we're going to use:
-
-.. code:: clojure
-
- lein repl
- nREPL server started on port 50624 on host 127.0.0.1
- REPL-y 0.3.0
- Clojure 1.5.1
- Docs: (doc function-name-here)
- (find-doc "part-of-name-here")
- Source: (source function-name-here)
- Javadoc: (javadoc java-object-or-class-here)
- Exit: Control+D or (exit) or (quit)
- Results: Stored in vars *1, *2, *3, an exception in *e
-
- user=> (import '[org.opencv.core Mat Size CvType]
- '[org.opencv.imgcodecs Imgcodecs]
- '[org.opencv.imgproc Imgproc])
- org.opencv.imgproc.Imgproc
-
-Now read the image from the ``resources/images/lena.png`` file.
-
-.. code:: clojure
-
- user=> (def lena (Highgui/imread "resources/images/lena.png"))
- #'user/lena
- user=> lena
- #<Mat Mat [ 512*512*CV_8UC3, isCont=true, isSubmat=false, nativeObj=0x7f9ab3054c40, dataAddr=0x19fea9010 ]>
-
-As you see, by simply evaluating the ``lena`` symbol we know that
-``lena.png`` is a ``512x512`` matrix of ``CV_8UC3`` elements type. Let's
-create a new ``Mat`` instance of the same dimensions and elements type.
-
-.. code:: clojure
-
- user=> (def blurred (Mat. 512 512 CvType/CV_8UC3))
- #'user/blurred
- user=>
-
-Now apply a ``GaussianBlur`` filter using ``lena`` as the source matrix
-and ``blurred`` as the destination matrix.
-
-.. code:: clojure
-
- user=> (Imgproc/GaussianBlur lena blurred (Size. 5 5) 3 3)
- nil
-
-As a last step just save the ``blurred`` matrix in a new image file.
-
-.. code:: clojure
-
- user=> (Highgui/imwrite "resources/images/blurred.png" blurred)
- true
- user=> (exit)
- Bye for now!
-
-Following is the new blurred image of Lena.
-
-.. image:: images/blurred.png
- :alt: Blurred Image
- :align: center
-
-Next Steps
-==========
-
-This tutorial only introduces the very basic environment set up to be
-able to interact with OpenCV in a CLJ REPL.
-
-I recommend any Clojure newbie to read the `Clojure Java Interop chapter <http://clojure.org/java_interop>`_ to get all you need to know
-to interoperate with any plain java lib that has not been wrapped in
-Clojure to make it usable in a more idiomatic and functional way within
-Clojure.
-
-The OpenCV Java API does not wrap the ``highgui`` module
-functionalities depending on ``Qt`` (e.g. ``namedWindow`` and
-``imshow``. If you want to create windows and show images into them
-while interacting with OpenCV from the REPL, at the moment you're left
-at your own. You could use Java Swing to fill the gap.
-
-
-License
--------
-
-Copyright © 2013 Giacomo (Mimmo) Cosenza aka Magomimmo
-
-Distributed under the BSD 3-clause License, the same of OpenCV.
+++ /dev/null
-
-.. _ARM-Linux-cross-compile:
-
-Cross compilation for ARM based Linux systems
-*********************************************
-
-This steps are tested on Ubuntu Linux 12.04, but should work for other Linux distributions.
-I case of other distributions package names and names of cross compilation tools may differ.
-There are several popular EABI versions that are used on ARM platform. This tutorial is
-written for *gnueabi* and *gnueabihf*, but other variants should work with minimal changes.
-
-
-Prerequisites
-=============
-
- * Host computer with Linux;
- * Git;
- * CMake 2.6 or higher;
- * Cross compilation tools for ARM: gcc, libstc++, etc. Depending on target platform you need
- to choose *gnueabi* or *gnueabihf* tools.
- Install command for *gnueabi*:
-
- .. code-block:: bash
-
- sudo apt-get install gcc-arm-linux-gnueabi
-
- Install command for *gnueabihf*:
-
- .. code-block:: bash
-
- sudo apt-get install gcc-arm-linux-gnueabihf
-
- * pkgconfig;
- * Python 2.6 for host system;
- * [optional] ffmpeg or libav development packages for armeabi(hf): libavcodec-dev, libavformat-dev, libswscale-dev;
- * [optional] GTK+2.x or higher, including headers (libgtk2.0-dev) for armeabi(hf);
- * [optional] libdc1394 2.x;
- * [optional] libjpeg-dev, libpng-dev, libtiff-dev, libjasper-dev for armeabi(hf).
-
-
-Getting OpenCV Source Code
-==========================
-
-You can use the latest stable OpenCV version available in *sourceforge* or you can grab the latest
-snapshot from our `Git repository <https://github.com/Itseez/opencv.git>`_.
-
-
-Getting the Latest Stable OpenCV Version
-----------------------------------------
-
-* Go to our `page on Sourceforge <http://sourceforge.net/projects/opencvlibrary>`_;
-
-* Download the source tarball and unpack it.
-
-
-Getting the Cutting-edge OpenCV from the Git Repository
--------------------------------------------------------
-
-Launch Git client and clone `OpenCV repository <http://github.com/itseez/opencv>`_
-
-In Linux it can be achieved with the following command in Terminal:
-
-.. code-block:: bash
-
- cd ~/<my_working _directory>
- git clone https://github.com/Itseez/opencv.git
-
-
-Building OpenCV
-===============
-
-#. Create a build directory, make it current and run the following command:
-
- .. code-block:: bash
-
- cmake [<some optional parameters>] -DCMAKE_TOOLCHAIN_FILE=<path to the OpenCV source directory>/platforms/linux/arm-gnueabi.toolchain.cmake <path to the OpenCV source directory>
-
- Toolchain uses *gnueabihf* EABI convention by default. Add ``-DSOFTFP=ON`` cmake argument to switch on softfp compiler.
-
- .. code-block:: bash
-
- cmake [<some optional parameters>] -DSOFTFP=ON -DCMAKE_TOOLCHAIN_FILE=<path to the OpenCV source directory>/platforms/linux/arm-gnueabi.toolchain.cmake <path to the OpenCV source directory>
-
- For example:
-
- .. code-block:: bash
-
- cd ~/opencv/platforms/linux
- mkdir -p build_hardfp
- cd build_hardfp
-
- cmake -DCMAKE_TOOLCHAIN_FILE=../arm-gnueabi.toolchain.cmake ../../..
-
-#. Run make in build (<cmake_binary_dir>) directory:
-
- .. code-block:: bash
-
- make
-
-.. note::
-
- Optionally you can strip symbols info from the created library via install/strip make target.
- This option produces smaller binary (~ twice smaller) but makes further debugging harder.
-
-Enable hardware optimizations
------------------------------
-
-Depending on target platform architecture different instruction sets can be used. By default
-compiler generates code for armv5l without VFPv3 and NEON extensions. Add ``-DENABLE_VFPV3=ON``
-to cmake command line to enable code generation for VFPv3 and ``-DENABLE_NEON=ON`` for using
-NEON SIMD extensions.
-
-TBB is supported on multi core ARM SoCs also.
-Add ``-DWITH_TBB=ON`` and ``-DBUILD_TBB=ON`` to enable it. Cmake scripts download TBB sources
-from official project site `<http://threadingbuildingblocks.org/>`_ and build it.
+++ /dev/null
-
-.. _Java_Dev_Intro:
-
-
-Introduction to Java Development
-********************************
-
-As of OpenCV 2.4.4, OpenCV supports desktop Java development using nearly the same interface as for
-Android development. This guide will help you to create your first Java (or Scala) application using OpenCV.
-We will use either `Apache Ant <http://ant.apache.org/>`_ or `Simple Build Tool (SBT) <http://www.scala-sbt.org/>`_ to build the application.
-
-If you want to use Eclipse head to :ref:`Java_Eclipse`. For further reading after this guide, look at the :ref:`Android_Dev_Intro` tutorials.
-
-What we'll do in this guide
-===========================
-
-In this guide, we will:
-
-* Get OpenCV with desktop Java support
-
-* Create an ``Ant`` or ``SBT`` project
-
-* Write a simple OpenCV application in Java or Scala
-
-The same process was used to create the samples in the :file:`samples/java` folder of the OpenCV repository,
-so consult those files if you get lost.
-
-Get proper OpenCV
-=================
-
-Starting from version 2.4.4 OpenCV includes desktop Java bindings.
-
-Download
---------
-
-The most simple way to get it is downloading the appropriate package of **version 2.4.4 or higher** from the
-`OpenCV SourceForge repository <http://sourceforge.net/projects/opencvlibrary/files/>`_.
-
-.. note:: Windows users can find the prebuilt files needed for Java development in
- the :file:`opencv/build/java/` folder inside the package.
- For other OSes it's required to build OpenCV from sources.
-
-Another option to get OpenCV sources is to clone `OpenCV git repository
-<https://github.com/Itseez/opencv/>`_.
-In order to build OpenCV with Java bindings you need :abbr:`JDK (Java Development Kit)`
-(we recommend `Oracle/Sun JDK 6 or 7 <http://www.oracle.com/technetwork/java/javase/downloads/>`_),
-`Apache Ant <http://ant.apache.org/>`_ and `Python` v2.6 or higher to be installed.
-
-Build
------
-
-Let's build OpenCV:
-
-.. code-block:: bash
-
- git clone git://github.com/Itseez/opencv.git
- cd opencv
- git checkout 2.4
- mkdir build
- cd build
-
-Generate a Makefile or a MS Visual Studio* solution, or whatever you use for
-building executables in your system:
-
-.. code-block:: bash
-
- cmake -DBUILD_SHARED_LIBS=OFF ..
-
-or
-
-.. code-block:: bat
-
- cmake -DBUILD_SHARED_LIBS=OFF -G "Visual Studio 10" ..
-
-.. note:: When OpenCV is built as a set of **static** libraries (``-DBUILD_SHARED_LIBS=OFF`` option)
- the Java bindings dynamic library is all-sufficient,
- i.e. doesn't depend on other OpenCV libs, but includes all the OpenCV code inside.
-
-Examine the output of CMake and ensure ``java`` is one of the modules "To be built".
-If not, it's likely you're missing a dependency. You should troubleshoot by looking
-through the CMake output for any Java-related tools that aren't found and installing them.
-
-.. image:: images/cmake_output.png
- :alt: CMake output
- :align: center
-
-.. note:: If ``CMake`` can't find Java in your system set the ``JAVA_HOME``
- environment variable with the path to installed JDK
- before running it. E.g.:
-
- .. code-block:: bash
-
- export JAVA_HOME=/usr/lib/jvm/java-6-oracle
- cmake -DBUILD_SHARED_LIBS=OFF ..
-
-
-Now start the build:
-
-.. code-block:: bash
-
- make -j8
-
-or
-
-.. code-block:: bat
-
- msbuild /m OpenCV.sln /t:Build /p:Configuration=Release /v:m
-
-Besides all this will create a ``jar`` containing the Java interface (:file:`bin/opencv-244.jar`)
-and a native dynamic library containing Java bindings and all the OpenCV stuff
-(:file:`lib/libopencv_java244.so` or :file:`bin/Release/opencv_java244.dll` respectively).
-We'll use these files later.
-
-Java sample with Ant
-====================
-
-.. note::
- The described sample is provided with OpenCV library in the :file:`opencv/samples/java/ant` folder.
-
-* Create a folder where you'll develop this sample application.
-
-* In this folder create the :file:`build.xml` file with the following content using any text editor:
-
- .. code-block:: xml
- :linenos:
-
- <project name="SimpleSample" basedir="." default="rebuild-run">
-
- <property name="src.dir" value="src"/>
-
- <property name="lib.dir" value="${ocvJarDir}"/>
- <path id="classpath">
- <fileset dir="${lib.dir}" includes="**/*.jar"/>
- </path>
-
- <property name="build.dir" value="build"/>
- <property name="classes.dir" value="${build.dir}/classes"/>
- <property name="jar.dir" value="${build.dir}/jar"/>
-
- <property name="main-class" value="${ant.project.name}"/>
-
-
- <target name="clean">
- <delete dir="${build.dir}"/>
- </target>
-
- <target name="compile">
- <mkdir dir="${classes.dir}"/>
- <javac includeantruntime="false" srcdir="${src.dir}" destdir="${classes.dir}" classpathref="classpath"/>
- </target>
-
- <target name="jar" depends="compile">
- <mkdir dir="${jar.dir}"/>
- <jar destfile="${jar.dir}/${ant.project.name}.jar" basedir="${classes.dir}">
- <manifest>
- <attribute name="Main-Class" value="${main-class}"/>
- </manifest>
- </jar>
- </target>
-
- <target name="run" depends="jar">
- <java fork="true" classname="${main-class}">
- <sysproperty key="java.library.path" path="${ocvLibDir}"/>
- <classpath>
- <path refid="classpath"/>
- <path location="${jar.dir}/${ant.project.name}.jar"/>
- </classpath>
- </java>
- </target>
-
- <target name="rebuild" depends="clean,jar"/>
-
- <target name="rebuild-run" depends="clean,run"/>
-
- </project>
-
- .. note::
- This XML file can be reused for building other Java applications.
- It describes a common folder structure in the lines 3 - 12 and common targets
- for compiling and running the application.
-
- When reusing this XML don't forget to modify the project name in the line 1,
- that is also the name of the `main` class (line 14).
- The paths to OpenCV `jar` and `jni lib` are expected as parameters
- (``"${ocvJarDir}"`` in line 5 and ``"${ocvLibDir}"`` in line 37), but
- you can hardcode these paths for your convenience.
- See `Ant documentation <http://ant.apache.org/manual/>`_ for detailed description
- of its build file format.
-
-* Create an :file:`src` folder next to the :file:`build.xml` file and a :file:`SimpleSample.java` file in it.
-
-* Put the following Java code into the :file:`SimpleSample.java` file:
- .. code-block:: java
-
- import org.opencv.core.Core;
- import org.opencv.core.Mat;
- import org.opencv.core.CvType;
- import org.opencv.core.Scalar;
-
- class SimpleSample {
-
- static{ System.loadLibrary(Core.NATIVE_LIBRARY_NAME); }
-
- public static void main(String[] args) {
- System.out.println("Welcome to OpenCV " + Core.VERSION);
- Mat m = new Mat(5, 10, CvType.CV_8UC1, new Scalar(0));
- System.out.println("OpenCV Mat: " + m);
- Mat mr1 = m.row(1);
- mr1.setTo(new Scalar(1));
- Mat mc5 = m.col(5);
- mc5.setTo(new Scalar(5));
- System.out.println("OpenCV Mat data:\n" + m.dump());
- }
-
- }
-
-* Run the following command in console in the folder containing :file:`build.xml`:
- .. code-block:: bash
-
- ant -DocvJarDir=path/to/dir/containing/opencv-244.jar -DocvLibDir=path/to/dir/containing/opencv_java244/native/library
-
- For example:
-
- .. code-block:: bat
-
- ant -DocvJarDir=X:\opencv-2.4.4\bin -DocvLibDir=X:\opencv-2.4.4\bin\Release
-
- The command should initiate [re]building and running the sample.
- You should see on the screen something like this:
-
- .. image:: images/ant_output.png
- :alt: run app with Ant
- :align: center
-
-
-SBT project for Java and Scala
-==============================
-
-Now we'll create a simple Java application using SBT. This serves as a brief introduction to
-those unfamiliar with this build tool. We're using SBT because it is particularly easy and powerful.
-
-First, download and install `SBT <http://www.scala-sbt.org/>`_ using the instructions on its `web site <http://www.scala-sbt.org/>`_.
-
-Next, navigate to a new directory where you'd like the application source to live (outside :file:`opencv` dir).
-Let's call it "JavaSample" and create a directory for it:
-
-.. code-block:: bash
-
- cd <somewhere outside opencv>
- mkdir JavaSample
-
-Now we will create the necessary folders and an SBT project:
-
-.. code-block:: bash
-
- cd JavaSample
- mkdir -p src/main/java # This is where SBT expects to find Java sources
- mkdir project # This is where the build definitions live
-
-Now open :file:`project/build.scala` in your favorite editor and paste the following.
-It defines your project:
-
-.. code-block:: scala
-
- import sbt._
- import Keys._
-
- object JavaSampleBuild extends Build {
- def scalaSettings = Seq(
- scalaVersion := "2.10.0",
- scalacOptions ++= Seq(
- "-optimize",
- "-unchecked",
- "-deprecation"
- )
- )
-
- def buildSettings =
- Project.defaultSettings ++
- scalaSettings
-
- lazy val root = {
- val settings = buildSettings ++ Seq(name := "JavaSample")
- Project(id = "JavaSample", base = file("."), settings = settings)
- }
- }
-
-Now edit :file:`project/plugins.sbt` and paste the following.
-This will enable auto-generation of an Eclipse project:
-
-.. code-block:: scala
-
- addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "2.1.0")
-
-Now run ``sbt`` from the :file:`JavaSample` root and from within SBT run ``eclipse`` to generate an eclipse project:
-
-.. code-block:: bash
-
- sbt # Starts the sbt console
- > eclipse # Running "eclipse" from within the sbt console
-
-You should see something like this:
-
-.. image:: images/sbt_eclipse.png
- :alt: SBT output
- :align: center
-
-You can now import the SBT project to Eclipse using :guilabel:`Import ... -> Existing projects into workspace`.
-Whether you actually do this is optional for the guide;
-we'll be using SBT to build the project, so if you choose to use Eclipse it will just serve as a text editor.
-
-To test that everything is working, create a simple "Hello OpenCV" application.
-Do this by creating a file :file:`src/main/java/HelloOpenCV.java` with the following contents:
-
-.. code-block:: java
-
- public class HelloOpenCV {
- public static void main(String[] args) {
- System.out.println("Hello, OpenCV");
- }
- }
-
-Now execute ``run`` from the sbt console, or more concisely, run ``sbt run`` from the command line:
-
-.. code-block:: bash
-
- sbt run
-
-You should see something like this:
-
-.. image:: images/sbt_run.png
- :alt: SBT run
- :align: center
-
-Running SBT samples
--------------------
-
-Now we'll create a simple face detection application using OpenCV.
-
-First, create a :file:`lib/` folder and copy the OpenCV jar into it.
-By default, SBT adds jars in the lib folder to the Java library search path.
-You can optionally rerun ``sbt eclipse`` to update your Eclipse project.
-
-.. code-block:: bash
-
- mkdir lib
- cp <opencv_dir>/build/bin/opencv_<version>.jar lib/
- sbt eclipse
-
-Next, create the directory :file:`src/main/resources` and download this Lena image into it:
-
-.. image:: images/lena.png
- :alt: Lena
- :align: center
-
-Make sure it's called :file:`"lena.png"`.
-Items in the resources directory are available to the Java application at runtime.
-
-Next, copy :file:`lbpcascade_frontalface.xml` from :file:`opencv/data/lbpcascades/` into the :file:`resources`
-directory:
-
-.. code-block:: bash
-
- cp <opencv_dir>/data/lbpcascades/lbpcascade_frontalface.xml src/main/resources/
-
-Now modify src/main/java/HelloOpenCV.java so it contains the following Java code:
-
-.. code-block:: java
-
- import org.opencv.core.Core;
- import org.opencv.core.Mat;
- import org.opencv.core.MatOfRect;
- import org.opencv.core.Point;
- import org.opencv.core.Rect;
- import org.opencv.core.Scalar;
- import org.opencv.imgcodecs.Imgcodecs;
- import org.opencv.objdetect.CascadeClassifier;
-
- //
- // Detects faces in an image, draws boxes around them, and writes the results
- // to "faceDetection.png".
- //
- class DetectFaceDemo {
- public void run() {
- System.out.println("\nRunning DetectFaceDemo");
-
- // Create a face detector from the cascade file in the resources
- // directory.
- CascadeClassifier faceDetector = new CascadeClassifier(getClass().getResource("/lbpcascade_frontalface.xml").getPath());
- Mat image = Imgcodecs.imread(getClass().getResource("/lena.png").getPath());
-
- // Detect faces in the image.
- // MatOfRect is a special container class for Rect.
- MatOfRect faceDetections = new MatOfRect();
- faceDetector.detectMultiScale(image, faceDetections);
-
- System.out.println(String.format("Detected %s faces", faceDetections.toArray().length));
-
- // Draw a bounding box around each face.
- for (Rect rect : faceDetections.toArray()) {
- Imgproc.rectangle(image, new Point(rect.x, rect.y), new Point(rect.x + rect.width, rect.y + rect.height), new Scalar(0, 255, 0));
- }
-
- // Save the visualized detection.
- String filename = "faceDetection.png";
- System.out.println(String.format("Writing %s", filename));
- Imgcodecs.imwrite(filename, image);
- }
- }
-
- public class HelloOpenCV {
- public static void main(String[] args) {
- System.out.println("Hello, OpenCV");
-
- // Load the native library.
- System.loadLibrary(Core.NATIVE_LIBRARY_NAME);
- new DetectFaceDemo().run();
- }
- }
-
-Note the call to ``System.loadLibrary(Core.NATIVE_LIBRARY_NAME)``.
-This command must be executed exactly once per Java process prior to using any native OpenCV methods.
-If you don't call it, you will get ``UnsatisfiedLink errors``.
-You will also get errors if you try to load OpenCV when it has already been loaded.
-
-Now run the face detection app using ``sbt run``:
-
-.. code-block:: bash
-
- sbt run
-
-You should see something like this:
-
-.. image:: images/sbt_run_face.png
- :alt: SBT run
- :align: center
-
-It should also write the following image to :file:`faceDetection.png`:
-
-.. image:: images/faceDetection.png
- :alt: Detected face
- :align: center
-
-You're done!
-Now you have a sample Java application working with OpenCV, so you can start the work on your own.
-We wish you good luck and many years of joyful life!
+++ /dev/null
-.. _Display_Image:
-
-Load and Display an Image
-*************************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Load an image (using :imread:`imread <>`)
- * Create a named OpenCV window (using :named_window:`namedWindow <>`)
- * Display an image in an OpenCV window (using :imshow:`imshow <>`)
-
-Source Code
-===========
-
-Download the source code from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/introduction/display_image/display_image.cpp>`_.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
- :language: cpp
- :tab-width: 4
- :linenos:
-
-Explanation
-============
-
-In OpenCV 2 we have multiple modules. Each one takes care of a different area or approach towards image processing. You could already observe this in the structure of the user guide of these tutorials itself. Before you use any of them you first need to include the header files where the content of each individual module is declared.
-
-You'll almost always end up using the:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + *core* section, as here are defined the basic building blocks of the library
- + *highgui* module, as this contains the functions for input and output operations
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
- :language: cpp
- :tab-width: 4
- :lines: 1-6
-
-We also include the *iostream* to facilitate console line output and input. To avoid data structure and function name conflicts with other libraries, OpenCV has its own namespace: *cv*. To avoid the need appending prior each of these the *cv::* keyword you can import the namespace in the whole file by using the lines:
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
- :language: cpp
- :tab-width: 4
- :lines: 8-9
-
-This is true for the STL library too (used for console I/O). Now, let's analyze the *main* function. We start up assuring that we acquire a valid image name argument from the command line. Otherwise take a picture by default: "HappyFish.jpg".
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
- :language: cpp
- :tab-width: 4
- :lines: 13-17
-
-Then create a *Mat* object that will store the data of the loaded image.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
- :language: cpp
- :tab-width: 4
- :lines: 19
-
-Now we call the :imread:`imread <>` function which loads the image name specified by the first argument (*argv[1]*). The second argument specifies the format in what we want the image. This may be:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + IMREAD_UNCHANGED (<0) loads the image as is (including the alpha channel if present)
- + IMREAD_GRAYSCALE ( 0) loads the image as an intensity one
- + IMREAD_COLOR (>0) loads the image in the RGB format
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
- :language: cpp
- :tab-width: 4
- :lines: 20
-
-.. note::
-
- OpenCV offers support for the image formats Windows bitmap (bmp), portable image formats (pbm, pgm, ppm) and Sun raster (sr, ras). With help of plugins (you need to specify to use them if you build yourself the library, nevertheless in the packages we ship present by default) you may also load image formats like JPEG (jpeg, jpg, jpe), JPEG 2000 (jp2 - codenamed in the CMake as Jasper), TIFF files (tiff, tif) and portable network graphics (png). Furthermore, OpenEXR is also a possibility.
-
-After checking that the image data was loaded correctly, we want to display our image, so we create an OpenCV window using the :named_window:`namedWindow <>` function. These are automatically managed by OpenCV once you create them. For this you need to specify its name and how it should handle the change of the image it contains from a size point of view. It may be:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + *WINDOW_AUTOSIZE* is the only supported one if you do not use the Qt backend. In this case the window size will take up the size of the image it shows. No resize permitted!
- + *WINDOW_NORMAL* on Qt you may use this to allow window resize. The image will resize itself according to the current window size. By using the | operator you also need to specify if you would like the image to keep its aspect ratio (*WINDOW_KEEPRATIO*) or not (*WINDOW_FREERATIO*).
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
- :language: cpp
- :lines: 28
- :tab-width: 4
-
-Finally, to update the content of the OpenCV window with a new image use the :imshow:`imshow <>` function. Specify the OpenCV window name to update and the image to use during this operation:
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
- :language: cpp
- :lines: 29
- :tab-width: 4
-
-Because we want our window to be displayed until the user presses a key (otherwise the program would end far too quickly), we use the :wait_key:`waitKey <>` function whose only parameter is just how long should it wait for a user input (measured in milliseconds). Zero means to wait forever.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
- :language: cpp
- :lines: 31
- :tab-width: 4
-
-Result
-=======
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Compile your code and then run the executable giving an image path as argument. If you're on Windows the executable will of course contain an *exe* extension too. Of course assure the image file is near your program file.
-
- .. code-block:: bash
-
- ./DisplayImage HappyFish.jpg
-
- * You should get a nice window as the one shown below:
-
- .. image:: images/Display_Image_Tutorial_Result.jpg
- :alt: Display Image Tutorial - Final Result
- :align: center
-
- .. raw:: html
-
- <div align="center">
- <iframe title="Introduction - Display an Image" width="560" height="349" src="http://www.youtube.com/embed/1OJEqpuaGc4?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _iOS-Installation:
-
-Installation in iOS
-*******************
-
-Required Packages
-=================
-
- * CMake 2.8.8 or higher
- * Xcode 4.2 or higher
-
-Getting the Cutting-edge OpenCV from Git Repository
----------------------------------------------------
-
-Launch GIT client and clone OpenCV repository from `here <http://github.com/itseez/opencv>`_
-
-In MacOS it can be done using the following command in Terminal:
-
-.. code-block:: bash
-
- cd ~/<my_working _directory>
- git clone https://github.com/Itseez/opencv.git
-
-
-Building OpenCV from Source, using CMake and Command Line
-=========================================================
-
-#. Make symbolic link for Xcode to let OpenCV build scripts find the compiler, header files etc.
-
- .. code-block:: bash
-
- cd /
- sudo ln -s /Applications/Xcode.app/Contents/Developer Developer
-
-#. Build OpenCV framework:
-
- .. code-block:: bash
-
- cd ~/<my_working_directory>
- python opencv/platforms/ios/build_framework.py ios
-
-If everything's fine, a few minutes later you will get ~/<my_working_directory>/ios/opencv2.framework. You can add this framework to your Xcode projects.
-
-Further Reading
-===============
-You can find several OpenCV+iOS tutorials here :ref:`Table-Of-Content-iOS`.
+++ /dev/null
-
-.. _Java_Eclipse:
-
-
-Using OpenCV Java with Eclipse
-*********************************************
-
-Since version 2.4.4 `OpenCV supports Java <http://opencv.org/opencv-java-api.html>`_. In this tutorial I will explain how to setup development environment for using OpenCV Java with Eclipse in **Windows**, so you can enjoy the benefits of garbage collected, very refactorable (rename variable, extract method and whatnot) modern language that enables you to write code with less effort and make less mistakes. Here we go.
-
-
-Configuring Eclipse
-===================
-
-First, obtain a fresh release of OpenCV `from download page <http://opencv.org/downloads.html>`_ and extract it under a simple location like ``C:\OpenCV-2.4.6\``. I am using version 2.4.6, but the steps are more or less the same for other versions.
-
-Now, we will define OpenCV as a user library in Eclipse, so we can reuse the configuration for any project. Launch Eclipse and select :guilabel:`Window --> Preferences` from the menu.
-
-.. image:: images/1-window-preferences.png
- :alt: Eclipse preferences
- :align: center
-
-Navigate under :guilabel:`Java --> Build Path --> User Libraries` and click :guilabel:`New...`.
-
-.. image:: images/2-user-library-new.png
- :alt: Creating a new library
- :align: center
-
-Enter a name, e.g. ``OpenCV-2.4.6``, for your new library.
-
-.. image:: images/3-library-name.png
- :alt: Naming the new library
- :align: center
-
-Now select your new user library and click :guilabel:`Add External JARs...`.
-
-.. image:: images/4-add-external-jars.png
- :alt: Adding external jar
- :align: center
-
-Browse through ``C:\OpenCV-2.4.6\build\java\`` and select ``opencv-246.jar``. After adding the jar, extend the :guilabel:`opencv-246.jar` and select :guilabel:`Native library location` and press :guilabel:`Edit...`.
-
-.. image:: images/5-native-library.png
- :alt: Selecting native library location 1
- :align: center
-
-Select :guilabel:`External Folder...` and browse to select the folder ``C:\OpenCV-2.4.6\build\java\x64``. If you have a 32-bit system you need to select the ``x86`` folder instead of ``x64``.
-
-.. image:: images/6-external-folder.png
- :alt: Selecting native library location 2
- :align: center
-
-Your user library configuration should look like this:
-
-.. image:: images/7-user-library-final.png
- :alt: Selecting native library location 2
- :align: center
-
-
-Testing the configuration on a new Java project
-=====================================================
-
-Now start creating a new Java project.
-
-.. image:: images/7_5-new-java-project.png
- :alt: Creating new Java project
- :align: center
-
-On the :guilabel:`Java Settings` step, under :guilabel:`Libraries` tab, select :guilabel:`Add Library...` and select :guilabel:`OpenCV-2.4.6`, then click :guilabel:`Finish`.
-
-.. image:: images/8-add-library.png
- :alt: Adding user defined library 1
- :align: center
-
-.. image:: images/9-select-user-lib.png
- :alt: Adding user defined library 2
- :align: center
-
-
-Libraries should look like this:
-
-.. image:: images/10-new-project-created.png
- :alt: Adding user defined library
- :align: center
-
-
-Now you have created and configured a new Java project it is time to test it. Create a new java file. Here is a starter code for your convenience:
-
-.. code-block:: java
-
- import org.opencv.core.Core;
- import org.opencv.core.CvType;
- import org.opencv.core.Mat;
-
- public class Hello
- {
- public static void main( String[] args )
- {
- System.loadLibrary( Core.NATIVE_LIBRARY_NAME );
- Mat mat = Mat.eye( 3, 3, CvType.CV_8UC1 );
- System.out.println( "mat = " + mat.dump() );
- }
- }
-
-When you run the code you should see 3x3 identity matrix as output.
-
-.. image:: images/11-the-code.png
- :alt: Adding user defined library
- :align: center
-
-That is it, whenever you start a new project just add the OpenCV user library that you have defined to your project and you are good to go. Enjoy your powerful, less painful development environment :)
\ No newline at end of file
+++ /dev/null
-.. _Linux_Eclipse_Usage:
-
-Using OpenCV with Eclipse (plugin CDT)
-****************************************
-
-.. note::
- Two ways, one by forming a project directly, and another by CMake
-
-Prerequisites
-===============
-
-1. Having installed `Eclipse <http://www.eclipse.org/>`_ in your workstation (only the CDT plugin for C/C++ is needed). You can follow the following steps:
-
- * Go to the Eclipse site
-
- * Download `Eclipse IDE for C/C++ Developers <http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/heliossr2>`_ . Choose the link according to your workstation.
-
-#. Having installed OpenCV. If not yet, go :ref:`here <Linux-Installation>`.
-
-Making a project
-=================
-
-1. Start Eclipse. Just run the executable that comes in the folder.
-
-#. Go to **File -> New -> C/C++ Project**
-
- .. image:: images/a0.png
- :alt: Eclipse Tutorial Screenshot 0
- :align: center
-
-#. Choose a name for your project (i.e. DisplayImage). An **Empty Project** should be okay for this example.
-
- .. image:: images/a1.png
- :alt: Eclipse Tutorial Screenshot 1
- :align: center
-
-#. Leave everything else by default. Press **Finish**.
-
-#. Your project (in this case DisplayImage) should appear in the **Project Navigator** (usually at the left side of your window).
-
- .. image:: images/a3.png
- :alt: Eclipse Tutorial Screenshot 3
- :align: center
-
-
-#. Now, let's add a source file using OpenCV:
-
- * Right click on **DisplayImage** (in the Navigator). **New -> Folder** .
-
- .. image:: images/a4.png
- :alt: Eclipse Tutorial Screenshot 4
- :align: center
-
- * Name your folder **src** and then hit **Finish**
-
- * Right click on your newly created **src** folder. Choose **New source file**:
-
- * Call it **DisplayImage.cpp**. Hit **Finish**
-
- .. image:: images/a7.png
- :alt: Eclipse Tutorial Screenshot 7
- :align: center
-
-#. So, now you have a project with a empty .cpp file. Let's fill it with some sample code (in other words, copy and paste the snippet below):
-
- .. code-block:: cpp
-
- #include <opencv2/opencv.hpp>
-
- using namespace cv;
-
- int main( int argc, char** argv )
- {
- Mat image;
- image = imread( argv[1], 1 );
-
- if( argc != 2 || !image.data )
- {
- printf( "No image data \n" );
- return -1;
- }
-
- namedWindow( "Display Image", WINDOW_AUTOSIZE );
- imshow( "Display Image", image );
-
- waitKey(0);
-
- return 0;
- }
-
-#. We are only missing one final step: To tell OpenCV where the OpenCV headers and libraries are. For this, do the following:
-
- * Go to **Project-->Properties**
-
- * In **C/C++ Build**, click on **Settings**. At the right, choose the **Tool Settings** Tab. Here we will enter the headers and libraries info:
-
- a. In **GCC C++ Compiler**, go to **Includes**. In **Include paths(-l)** you should include the path of the folder where opencv was installed. In our example, this is ``/usr/local/include/opencv``.
-
- .. image:: images/a9.png
- :alt: Eclipse Tutorial Screenshot 9
- :align: center
-
- .. note::
- If you do not know where your opencv files are, open the **Terminal** and type:
-
- .. code-block:: bash
-
- pkg-config --cflags opencv
-
- For instance, that command gave me this output:
-
- .. code-block:: bash
-
- -I/usr/local/include/opencv -I/usr/local/include
-
-
- b. Now go to **GCC C++ Linker**,there you have to fill two spaces:
-
- First in **Library search path (-L)** you have to write the path to where the opencv libraries reside, in my case the path is:
- ::
-
- /usr/local/lib
-
- Then in **Libraries(-l)** add the OpenCV libraries that you may need. Usually just the 3 first on the list below are enough (for simple applications) . In my case, I am putting all of them since I plan to use the whole bunch:
-
-
- opencv_core
- opencv_imgproc
- opencv_highgui
- opencv_ml
- opencv_video
- opencv_features2d
- opencv_calib3d
- opencv_objdetect
- opencv_contrib
- opencv_legacy
- opencv_flann
-
- .. image:: images/a10.png
- :alt: Eclipse Tutorial Screenshot 10
- :align: center
-
- If you don't know where your libraries are (or you are just psychotic and want to make sure the path is fine), type in **Terminal**:
-
- .. code-block:: bash
-
- pkg-config --libs opencv
-
-
- My output (in case you want to check) was:
- .. code-block:: bash
-
- -L/usr/local/lib -lopencv_core -lopencv_imgproc -lopencv_highgui -lopencv_ml -lopencv_video -lopencv_features2d -lopencv_calib3d -lopencv_objdetect -lopencv_contrib -lopencv_legacy -lopencv_flann
-
- Now you are done. Click **OK**
-
- * Your project should be ready to be built. For this, go to **Project->Build all**
-
- In the Console you should get something like
-
- .. image:: images/a12.png
- :alt: Eclipse Tutorial Screenshot 12
- :align: center
-
- If you check in your folder, there should be an executable there.
-
-Running the executable
-========================
-
-So, now we have an executable ready to run. If we were to use the Terminal, we would probably do something like:
-
-.. code-block:: bash
-
- cd <DisplayImage_directory>
- cd src
- ./DisplayImage ../images/HappyLittleFish.png
-
-Assuming that the image to use as the argument would be located in <DisplayImage_directory>/images/HappyLittleFish.png. We can still do this, but let's do it from Eclipse:
-
-
-#. Go to **Run->Run Configurations**
-
-#. Under C/C++ Application you will see the name of your executable + Debug (if not, click over C/C++ Application a couple of times). Select the name (in this case **DisplayImage Debug**).
-
-#. Now, in the right side of the window, choose the **Arguments** Tab. Write the path of the image file we want to open (path relative to the workspace/DisplayImage folder). Let's use **HappyLittleFish.png**:
-
- .. image:: images/a14.png
- :alt: Eclipse Tutorial Screenshot 14
- :align: center
-
-#. Click on the **Apply** button and then in Run. An OpenCV window should pop up with the fish image (or whatever you used).
-
- .. image:: images/a15.jpg
- :alt: Eclipse Tutorial Screenshot 15
- :align: center
-
-#. Congratulations! You are ready to have fun with OpenCV using Eclipse.
-
-==================================================
-V2: Using CMake+OpenCV with Eclipse (plugin CDT)
-==================================================
-
-Say you have or create a new file, *helloworld.cpp* in a directory called *foo*:
-
-.. code-block:: cpp
-
-
- #include <opencv2/opencv.hpp>
- using namespace cv;
-
- int main ( int argc, char **argv )
- {
- Mat img(480, 640, CV_8U);
- putText(img, "Hello World!", Point( 200, 400 ), FONT_HERSHEY_SIMPLEX | FONT_ITALIC, 1.0, Scalar( 255, 255, 0 ));
- imshow("My Window", img);
- waitKey();
- return 0;
- }
-
-1. Create a build directory, say, under *foo*: ``mkdir /build``. Then ``cd build``.
-
-#. Put a *CmakeLists.txt* file in build:
-
-.. code-block:: bash
-
- PROJECT( helloworld_proj )
- FIND_PACKAGE( OpenCV REQUIRED )
- ADD_EXECUTABLE( helloworld helloworld.cxx )
- TARGET_LINK_LIBRARIES( helloworld ${OpenCV_LIBS} )
-
-#. Run: ``cmake-gui ..`` and make sure you fill in where opencv was built.
-
-#. Then click ``configure`` and then ``generate``. If it's OK, **quit cmake-gui**
-
-#. Run ``make -j4`` *(the ``-j4`` is optional, it just tells the compiler to build in 4 threads)*. Make sure it builds.
-
-#. Start ``eclipse`` . Put the workspace in some directory but **not** in ``foo`` or ``foo\\build``
-
-#. Right click in the ``Project Explorer`` section. Select ``Import`` And then open the ``C/C++`` filter. Choose *Existing Code* as a Makefile Project``
-
-#. Name your project, say *helloworld*. Browse to the Existing Code location ``foo\\build`` (where you ran your cmake-gui from). Select *Linux GCC* in the *"Toolchain for Indexer Settings"* and press *Finish*.
-
-#. Right click in the ``Project Explorer`` section. Select ``Properties``. Under ``C/C++ Build``, set the *build directory:* from something like ``${workspace_loc:/helloworld}`` to ``${workspace_loc:/helloworld}/build`` since that's where you are building to.
-
- a. You can also optionally modify the ``Build command:`` from ``make`` to something like ``make VERBOSE=1 -j4`` which tells the compiler to produce detailed symbol files for debugging and also to compile in 4 parallel threads.
-
-#. Done!
+++ /dev/null
-.. _Linux_GCC_Usage:
-
-Using OpenCV with gcc and CMake
-*********************************
-
-.. note::
- We assume that you have successfully installed OpenCV in your workstation.
-
-.. container:: enumeratevisibleitemswithsquare
-
- * The easiest way of using OpenCV in your code is to use `CMake <http://www.cmake.org/>`_. A few advantages (taken from the Wiki):
-
- #. No need to change anything when porting between Linux and Windows
- #. Can easily be combined with other tools by CMake( i.e. Qt, ITK and VTK )
-
- * If you are not familiar with CMake, checkout the `tutorial <http://www.cmake.org/cmake/help/cmake_tutorial.html>`_ on its website.
-
-Steps
-======
-
-Create a program using OpenCV
--------------------------------
-
-Let's use a simple program such as DisplayImage.cpp shown below.
-
-.. code-block:: cpp
-
- #include <stdio.h>
- #include <opencv2/opencv.hpp>
-
- using namespace cv;
-
- int main(int argc, char** argv )
- {
- if ( argc != 2 )
- {
- printf("usage: DisplayImage.out <Image_Path>\n");
- return -1;
- }
-
- Mat image;
- image = imread( argv[1], 1 );
-
- if ( !image.data )
- {
- printf("No image data \n");
- return -1;
- }
- namedWindow("Display Image", WINDOW_AUTOSIZE );
- imshow("Display Image", image);
-
- waitKey(0);
-
- return 0;
- }
-
-Create a CMake file
----------------------
-Now you have to create your CMakeLists.txt file. It should look like this:
-
-.. code-block:: cmake
-
- cmake_minimum_required(VERSION 2.8)
- project( DisplayImage )
- find_package( OpenCV REQUIRED )
- include_directories( ${OpenCV_INCLUDE_DIRS} )
- add_executable( DisplayImage DisplayImage.cpp )
- target_link_libraries( DisplayImage ${OpenCV_LIBS} )
-
-Generate the executable
--------------------------
-This part is easy, just proceed as with any other project using CMake:
-
-.. code-block:: bash
-
- cd <DisplayImage_directory>
- cmake .
- make
-
-Result
---------
-By now you should have an executable (called DisplayImage in this case). You just have to run it giving an image location as an argument, i.e.:
-
-.. code-block:: bash
-
- ./DisplayImage lena.jpg
-
-You should get a nice window as the one shown below:
-
-.. image:: images/GCC_CMake_Example_Tutorial.jpg
- :alt: Display Image - Lena
- :align: center
+++ /dev/null
-.. _Linux-Installation:
-
-Installation in Linux
-*********************
-These steps have been tested for Ubuntu 10.04 but should work with other distros as well.
-
-Required Packages
-=================
-
-* GCC 4.4.x or later
-* CMake 2.8.7 or higher
-* Git
-* GTK+2.x or higher, including headers (libgtk2.0-dev)
-* pkg-config
-* Python 2.6 or later and Numpy 1.5 or later with developer packages (python-dev, python-numpy)
-* ffmpeg or libav development packages: libavcodec-dev, libavformat-dev, libswscale-dev
-* [optional] libtbb2 libtbb-dev
-* [optional] libdc1394 2.x
-* [optional] libjpeg-dev, libpng-dev, libtiff-dev, libjasper-dev, libdc1394-22-dev
-
-The packages can be installed using a terminal and the following commands or by using Synaptic Manager:
-
- .. code-block:: bash
-
- [compiler] sudo apt-get install build-essential
- [required] sudo apt-get install cmake git libgtk2.0-dev pkg-config libavcodec-dev libavformat-dev libswscale-dev
- [optional] sudo apt-get install python-dev python-numpy libtbb2 libtbb-dev libjpeg-dev libpng-dev libtiff-dev libjasper-dev libdc1394-22-dev
-
-Getting OpenCV Source Code
-==========================
-
-You can use the latest stable OpenCV version or you can grab the latest snapshot from our `Git repository <https://github.com/Itseez/opencv.git>`_.
-
-Getting the Latest Stable OpenCV Version
-----------------------------------------
-
-* Go to our `downloads page <http://opencv.org/downloads.html>`_.
-
-* Download the source archive and unpack it.
-
-Getting the Cutting-edge OpenCV from the Git Repository
--------------------------------------------------------
-
-Launch Git client and clone `OpenCV repository <http://github.com/itseez/opencv>`_.
-If you need modules from `OpenCV contrib repository <http://github.com/itseez/opencv_contrib>`_ then clone it too.
-
-For example
-
-.. code-block:: bash
-
- cd ~/<my_working_directory>
- git clone https://github.com/Itseez/opencv.git
- git clone https://github.com/Itseez/opencv_contrib.git
-
-Building OpenCV from Source Using CMake
-=======================================
-
-#. Create a temporary directory, which we denote as <cmake_build_dir>, where you want to put the generated Makefiles, project files as well the object files and output binaries and enter there.
-
- For example
-
- .. code-block:: bash
-
- cd ~/opencv
- mkdir build
- cd build
-
-#. Configuring. Run
- cmake [<some optional parameters>] <path to the OpenCV source directory>
-
- For example
-
- .. code-block:: bash
-
- cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/usr/local ..
-
- or cmake-gui
-
- * set full path to OpenCV source code, e.g. /home/user/opencv
- * set full path to <cmake_build_dir>, e.g. /home/user/opencv/build
- * set optional parameters
- * run: “Configure”
- * run: “Generate”
-
-#. Description of some parameters
-
- * build type: CMAKE_BUILD_TYPE=Release\\Debug
- * to build with modules from opencv_contrib set OPENCV_EXTRA_MODULES_PATH to <path to opencv_contrib/modules/>
- * set BUILD_DOCS for building documents
- * set BUILD_EXAMPLES to build all examples
-
-#. [optional] Building python. Set the following python parameters:
-
- * PYTHON2(3)_EXECUTABLE = <path to python>
- * PYTHON_INCLUDE_DIR = /usr/include/python<version>
- * PYTHON_INCLUDE_DIR2 = /usr/include/x86_64-linux-gnu/python<version>
- * PYTHON_LIBRARY = /usr/lib/x86_64-linux-gnu/libpython<version>.so
- * PYTHON2(3)_NUMPY_INCLUDE_DIRS = /usr/lib/python<version>/dist-packages/numpy/core/include/
-
-#. [optional] Building java.
-
- * Unset parameter: BUILD_SHARED_LIBS
- * It is useful also to unset BUILD_EXAMPLES, BUILD_TESTS, BUILD_PERF_TESTS - as they all will be statically linked with OpenCV and can take a lot of memory.
-
-#. Build. From build directory execute make, recomend to do it in several threads
-
- For example
-
- .. code-block:: bash
-
- make -j7 # runs 7 jobs in parallel
-
-#. [optional] Building documents. Enter <cmake_build_dir/doc/> and run make with target "html_docs"
-
- For example
-
- .. code-block:: bash
-
- cd ~/opencv/build/doc/
- make -j7 html_docs
-
-#. To install libraries, from build directory execute
-
- .. code-block:: bash
-
- sudo make install
-
-#. [optional] Running tests
-
- * Get the required test data from `OpenCV extra repository <https://github.com/Itseez/opencv_extra>`_.
-
- For example
-
- .. code-block:: bash
-
- git clone https://github.com/Itseez/opencv_extra.git
-
- * set OPENCV_TEST_DATA_PATH environment variable to <path to opencv_extra/testdata>.
-
- * execute tests from build directory.
-
- For example
-
- .. code-block:: bash
-
- <cmake_build_dir>/bin/opencv_test_core
-
-.. note::
-
- If the size of the created library is a critical issue (like in case of an Android build) you can use the ``install/strip`` command to get the smallest size as possible. The *stripped* version appears to be twice as small. However, we do not recommend using this unless those extra megabytes do really matter.
+++ /dev/null
-.. _Load_Save_Image:
-
-Load, Modify, and Save an Image
-*******************************
-
-.. note::
-
- We assume that by now you know how to load an image using :readwriteimage:`imread <imread>` and to display it in a window (using :user_interface:`imshow <imshow>`). Read the :ref:`Display_Image` tutorial otherwise.
-
-Goals
-======
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Load an image using :readwriteimage:`imread <imread>`
- * Transform an image from BGR to Grayscale format by using :miscellaneous_transformations:`cvtColor <cvtcolor>`
- * Save your transformed image in a file on disk (using :readwriteimage:`imwrite <imwrite>`)
-
-Code
-======
-
-Here it is:
-
-.. code-block:: cpp
- :linenos:
-
- #include <opencv2/opencv.hpp>
-
- using namespace cv;
-
- int main( int argc, char** argv )
- {
- char* imageName = argv[1];
-
- Mat image;
- image = imread( imageName, 1 );
-
- if( argc != 2 || !image.data )
- {
- printf( " No image data \n " );
- return -1;
- }
-
- Mat gray_image;
- cvtColor( image, gray_image, COLOR_BGR2GRAY );
-
- imwrite( "../../images/Gray_Image.jpg", gray_image );
-
- namedWindow( imageName, WINDOW_AUTOSIZE );
- namedWindow( "Gray image", WINDOW_AUTOSIZE );
-
- imshow( imageName, image );
- imshow( "Gray image", gray_image );
-
- waitKey(0);
-
- return 0;
- }
-
-Explanation
-============
-
-#. We begin by loading an image using :readwriteimage:`imread <imread>`, located in the path given by *imageName*. For this example, assume you are loading a RGB image.
-
-#. Now we are going to convert our image from BGR to Grayscale format. OpenCV has a really nice function to do this kind of transformations:
-
- .. code-block:: cpp
-
- cvtColor( image, gray_image, COLOR_BGR2GRAY );
-
- As you can see, :miscellaneous_transformations:`cvtColor <cvtcolor>` takes as arguments:
-
- .. container:: enumeratevisibleitemswithsquare
-
- * a source image (*image*)
- * a destination image (*gray_image*), in which we will save the converted image.
- * an additional parameter that indicates what kind of transformation will be performed. In this case we use **COLOR_BGR2GRAY** (because of :readwriteimage:`imread <imread>` has BGR default channel order in case of color images).
-
-#. So now we have our new *gray_image* and want to save it on disk (otherwise it will get lost after the program ends). To save it, we will use a function analagous to :readwriteimage:`imread <imread>`: :readwriteimage:`imwrite <imwrite>`
-
- .. code-block:: cpp
-
- imwrite( "../../images/Gray_Image.jpg", gray_image );
-
- Which will save our *gray_image* as *Gray_Image.jpg* in the folder *images* located two levels up of my current location.
-
-#. Finally, let's check out the images. We create two windows and use them to show the original image as well as the new one:
-
- .. code-block:: cpp
-
- namedWindow( imageName, WINDOW_AUTOSIZE );
- namedWindow( "Gray image", WINDOW_AUTOSIZE );
-
- imshow( imageName, image );
- imshow( "Gray image", gray_image );
-
-#. Add the *waitKey(0)* function call for the program to wait forever for an user key press.
-
-
-Result
-=======
-
-When you run your program you should get something like this:
-
- .. image:: images/Load_Save_Image_Result_1.jpg
- :alt: Load Save Image Result 1
- :align: center
-
-And if you check in your folder (in my case *images*), you should have a newly .jpg file named *Gray_Image.jpg*:
-
- .. image:: images/Load_Save_Image_Result_2.jpg
- :alt: Load Save Image Result 2
- :align: center
-
-Congratulations, you are done with this tutorial!
+++ /dev/null
-.. _Table-Of-Content-Introduction:
-
-Introduction to OpenCV
------------------------------------------------------------
-
-Here you can read tutorials about how to set up your computer to work with the OpenCV library.
-Additionally you can find very basic sample source code to introduce you to the
-world of the OpenCV.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-* **Linux**
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |Install_1| **Title:** :ref:`Linux-Installation`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will learn how to setup OpenCV in your computer!
-
- =========== ======================================================
-
- .. |Install_1| image:: images/ubuntu-logo.jpg
- :height: 90pt
- :width: 90pt
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |Usage_1| **Title:** :ref:`Linux_GCC_Usage`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will learn how to compile your first project using gcc and CMake
-
- =========== ======================================================
-
- .. |Usage_1| image:: images/gccegg-65.jpg
- :height: 90pt
- :width: 90pt
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |Usage_2| **Title:** :ref:`Linux_Eclipse_Usage`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will learn how to compile your first project using the Eclipse environment
-
- =========== ======================================================
-
- .. |Usage_2| image:: images/eclipse_cpp_logo.jpeg
- :height: 90pt
- :width: 90pt
-
-* **Windows**
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |WinInstal| **Title:** :ref:`Windows_Installation`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- You will learn how to setup OpenCV in your Windows Operating System!
-
- =========== ======================================================
-
- .. |WinInstal| image:: images/windows_logo.jpg
- :height: 90pt
- :width: 90pt
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |WinVSHowT| **Title:** :ref:`Windows_Visual_Studio_How_To`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_BernatG|
-
- You will learn what steps you need to perform in order to use the OpenCV library inside a new Microsoft Visual Studio project.
-
- =========== ======================================================
-
- .. |WinVSHowT| image:: images/visual-studio-2010-logo.jpg
- :height: 90pt
- :width: 90pt
-
- =========== ======================================================
- |WinVSVis| **Title:** :ref:`Windows_Visual_Studio_Image_Watch`
-
- *Compatibility:* >= OpenCV 2.4
-
- *Author:* Wolf Kienzle
-
- You will learn how to visualize OpenCV matrices and images within Visual Studio 2012.
-
- =========== ======================================================
-
- .. |WinVSVis| image:: images/visual_studio_image_watch.png
- :height: 90pt
- :width: 90pt
-
-* **Desktop Java**
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================ =================================================
- |JavaLogo| **Title:** :ref:`Java_Dev_Intro`
-
- *Compatibility:* > OpenCV 2.4.4
-
- *Authors:* |Author_EricCh| and |Author_AndreyP|
-
- Explains how to build and run a simple desktop Java application using Eclipse, Ant or the Simple Build Tool (SBT).
-
- ================ =================================================
-
- .. |JavaLogo| image:: images/Java_logo.png
- :height: 90pt
- :width: 90pt
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================ =================================================
- |EclipseLogo| **Title:** :ref:`Java_Eclipse`
-
- *Compatibility:* > OpenCV 2.4.4
-
- *Author:* |Author_BarisD|
-
- A tutorial on how to use OpenCV Java with Eclipse.
-
- ================ =================================================
-
- .. |EclipseLogo| image:: images/eclipse-logo.png
- :height: 90pt
- :width: 90pt
-
- ================ =================================================
- |ClojureLogo| **Title:** :ref:`clojure_dev_intro`
-
- *Compatibility:* > OpenCV 2.4.4
-
- *Author:* |Author_MimmoC|
-
- A tutorial on how to interactively use OpenCV from the Clojure REPL.
-
- ================ =================================================
-
- .. |ClojureLogo| image:: images/clojure-logo.png
- :height: 90pt
- :width: 90pt
-
-* **Android**
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================ =================================================
- |AndroidLogo| **Title:** :ref:`Android_Dev_Intro`
-
- *Compatibility:* > OpenCV 2.4.2
-
- *Author:* |Author_VsevolodG|
-
- Not a tutorial, but a guide introducing Android development basics and environment setup
-
- ================ =================================================
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================ =================================================
- |AndroidLogo| **Title:** :ref:`O4A_SDK`
-
- *Compatibility:* > OpenCV 2.4.2
-
- *Author:* |Author_VsevolodG|
-
- OpenCV4Android SDK: general info, installation, running samples
-
- ================ =================================================
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================ =================================================
- |AndroidLogo| **Title:** :ref:`dev_with_OCV_on_Android`
-
- *Compatibility:* > OpenCV 2.4.3
-
- *Author:* |Author_VsevolodG|
-
- Development with OpenCV4Android SDK
-
- ================ =================================================
-
- .. |AndroidLogo| image:: images/android_logo.png
- :height: 90pt
- :width: 90pt
-
-
-* **iOS**
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============= ======================================================
- |Install_iOS| **Title:** :ref:`iOS-Installation`
-
- *Compatibility:* > OpenCV 2.4.2
-
- *Author:* |Author_ArtemM|, |Author_EduardF|
-
- We will learn how to setup OpenCV for using it in iOS!
-
- ============= ======================================================
-
- .. |Install_iOS| image:: images/opencv_ios.png
- :width: 90pt
-
-* **Embedded Linux**
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== ======================================================
- |Usage_1| **Title:** :ref:`ARM-Linux-cross-compile`
-
- *Compatibility:* > OpenCV 2.4.4
-
- *Author:* |Author_AlexS|
-
- We will learn how to setup OpenCV cross compilation environment for ARM Linux.
-
- =========== ======================================================
-
-* **Common**
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============= ======================================================
- |Beginners_1| **Title:** :ref:`Display_Image`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will learn how to display an image using OpenCV
-
- ============= ======================================================
-
- .. |Beginners_1| image:: images/Display_Image_Tutorial_Result.jpg
- :height: 90pt
- :width: 90pt
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |Beginners_2| **Title:** :ref:`Load_Save_Image`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- We will learn how to save an Image in OpenCV...plus a small conversion to grayscale
-
- =============== ======================================================
-
- .. |Beginners_2| image:: images/Load_Save_Image_Result_1.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. We use a custom table of content format and as the table of content only informs Sphinx about the hierarchy of the files, no need to show it.
-.. toctree::
- :hidden:
-
- ../linux_install/linux_install
- ../linux_gcc_cmake/linux_gcc_cmake
- ../linux_eclipse/linux_eclipse
- ../windows_install/windows_install
- ../windows_visual_studio_Opencv/windows_visual_studio_Opencv
- ../windows_visual_studio_image_watch/windows_visual_studio_image_watch
- ../desktop_java/java_dev_intro
- ../java_eclipse/java_eclipse
- ../clojure_dev_intro/clojure_dev_intro
- ../android_binary_package/android_dev_intro
- ../android_binary_package/O4A_SDK
- ../android_binary_package/dev_with_OCV_on_Android
- ../ios_install/ios_install
- ../crosscompilation/arm_crosscompile_with_cmake
- ../display_image/display_image
- ../load_save_image/load_save_image
+++ /dev/null
-.. _Windows_Installation:
-
-Installation in Windows
-***********************
-
-.. include:: <isonum.txt>
-
-The description here was tested on Windows 7 SP1. Nevertheless, it should also work on any other relatively modern version of Windows OS. If you encounter errors after following the steps described below, feel free to contact us via our `OpenCV Q&A forum <http://answers.opencv.org>`_. We'll do our best to help you out.
-
-.. note:: To use the OpenCV library you have two options: :ref:`Windows_Install_Prebuild` or :ref:`CppTutWindowsMakeOwn`. While the first one is easier to complete, it only works if you are coding with the latest Microsoft Visual Studio IDE and doesn't take advantage of the most advanced technologies we integrate into our library.
-
-.. _Windows_Install_Prebuild:
-
-Installation by Using the Pre-built Libraries
-=============================================
-
-#. Launch a web browser of choice and go to our `page on Sourceforge <http://sourceforge.net/projects/opencvlibrary/files/opencv-win/>`_.
-
-#. Choose a build you want to use and download it.
-
- .. If you downloaded the source files present here see :ref:`CppTutWindowsMakeOwn`.
-
-#. Make sure you have admin rights. Unpack the self-extracting archive.
-
-#. You can check the installation at the chosen path as you can see below.
-
- .. image:: images/OpenCV_Install_Directory.png
- :alt: An example of how the installation directory should look in case of successful install.
- :align: center
-
-#. To finalize the installation go to the :ref:`WindowsSetPathAndEnviromentVariable` section.
-
-.. _CppTutWindowsMakeOwn:
-
-Installation by Making Your Own Libraries from the Source Files
-===============================================================
-
-You may find the content of this tutorial also inside the following videos: `Part 1 <https://www.youtube.com/watch?v=NnovZ1cTlMs>`_ and `Part 2 <https://www.youtube.com/watch?v=qGNWMcfWwPU>`_, hosted on YouTube.
-
-.. raw:: html
-
- <div align="center">
- <iframe title="Install OpenCV by using its source files - Part 1" width="560" height="349" src="http://www.youtube.com/embed/NnovZ1cTlMs?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- <iframe title="Install OpenCV by using its source files - Part 2" width="560" height="349" src="http://www.youtube.com/embed/qGNWMcfWwPU?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
-
-.. warning:: These videos above are long-obsolete and contain inaccurate information. Be careful, since solutions described in those videos are no longer supported and may even break your install.
-
-If you are building your own libraries you can take the source files from our `Git repository <https://github.com/Itseez/opencv.git>`_.
-
-Building the OpenCV library from scratch requires a couple of tools installed beforehand:
-
-.. |CMake| replace:: CMake
-.. _CMake: http://www.cmake.org/cmake/resources/software.html
-.. |TortoiseGit| replace:: TortoiseGit
-.. _TortoiseGit: http://code.google.com/p/tortoisegit/wiki/Download
-.. |Python_Libraries| replace:: Python libraries
-.. _Python_Libraries: http://www.python.org/downloads/
-.. |Numpy| replace:: Numpy
-.. _Numpy: http://numpy.scipy.org/
-.. |IntelTBB| replace:: Intel |copy| Threading Building Blocks (*TBB*)
-.. _IntelTBB: http://threadingbuildingblocks.org/file.php?fid=77
-.. |IntelIIP| replace:: Intel |copy| Integrated Performance Primitives (*IPP*)
-.. _IntelIIP: http://software.intel.com/en-us/articles/intel-ipp/
-.. |IntelIIPA| replace:: Intel |copy| IPP Asynchronous C/C++
-.. _IntelIIPA: http://software.intel.com/en-us/intel-ipp-preview
-.. |qtframework| replace:: Qt framework
-.. _qtframework: http://qt.nokia.com/downloads
-.. |Eigen| replace:: Eigen
-.. _Eigen: http://eigen.tuxfamily.org/index.php?title=Main_Page#Download
-.. |CUDA_Toolkit| replace:: CUDA Toolkit
-.. _CUDA_Toolkit: http://developer.nvidia.com/cuda-downloads
-.. |OpenEXR| replace:: OpenEXR
-.. _OpenEXR: http://www.openexr.com/downloads.html
-.. |OpenNI_Framework| replace:: OpenNI Framework
-.. _OpenNI_Framework: http://www.openni.org/
-.. |Miktex| replace:: Miktex
-.. _Miktex: http://miktex.org/2.9/setup
-.. |Sphinx| replace:: Sphinx
-.. _Sphinx: http://sphinx.pocoo.org/
-
-.. container:: enumeratevisibleitemswithsquare
-
- + An IDE of choice (preferably), or just a C\C++ compiler that will actually make the binary files. Here we will use the `Microsoft Visual Studio <https://www.microsoft.com/visualstudio/en-us>`_. However, you can use any other IDE that has a valid C\C++ compiler.
-
- + |CMake|_, which is a neat tool to make the project files (for your chosen IDE) from the OpenCV source files. It will also allow an easy configuration of the OpenCV build files, in order to make binary files that fits exactly to your needs.
-
- + Git to acquire the OpenCV source files. A good tool for this is |TortoiseGit|_. Alternatively, you can just download an archived version of the source files from our `page on Sourceforge <http://sourceforge.net/projects/opencvlibrary/files/opencv-win/>`_
-
-OpenCV may come in multiple flavors. There is a "core" section that will work on its own. Nevertheless, there is a couple of tools, libraries made by 3rd parties that offer services of which the OpenCV may take advantage. These will improve its capabilities in many ways. In order to use any of them, you need to download and install them on your system.
-
-.. container:: enumeratevisibleitemswithsquare
-
- + The |Python_Libraries|_ are required to build the *Python interface* of OpenCV. For now use the version :file:`2.7.{x}`. This is also a must if you want to build the *OpenCV documentation*.
-
- + |Numpy|_ is a scientific computing package for Python. Required for the *Python interface*.
-
- + |IntelTBB|_ is used inside OpenCV for parallel code snippets. Using this will make sure that the OpenCV library will take advantage of all the cores you have in your systems CPU.
-
- + |IntelIIP|_ may be used to improve the performance of color conversion, Haar training and DFT functions of the OpenCV library. Watch out, since this isn't a free service.
-
- + |IntelIIPA|_ is currently focused delivering Intel |copy| Graphics support for advanced image processing and computer vision functions.
-
- + OpenCV offers a somewhat fancier and more useful graphical user interface, than the default one by using the |qtframework|_. For a quick overview of what this has to offer look into the documentations *highgui* module, under the *Qt New Functions* section. Version 4.6 or later of the framework is required.
-
- + |Eigen|_ is a C++ template library for linear algebra.
-
- + The latest |CUDA_Toolkit|_ will allow you to use the power lying inside your GPU. This will drastically improve performance for some algorithms (e.g the HOG descriptor). Getting more and more of our algorithms to work on the GPUs is a constant effort of the OpenCV team.
-
- + |OpenEXR|_ source files are required for the library to work with this high dynamic range (HDR) image file format.
-
- + The |OpenNI_Framework|_ contains a set of open source APIs that provide support for natural interaction with devices via methods such as voice command recognition, hand gestures and body motion tracking.
-
- + |Miktex|_ is the best `TEX <https://secure.wikimedia.org/wikipedia/en/wiki/TeX>`_ implementation on the Windows OS. It is required to build the *OpenCV documentation*.
-
- + |Sphinx|_ is a python documentation generator and is the tool that will actually create the *OpenCV documentation*. This on its own requires a couple of tools installed, We will cover this in depth at the :ref:`How to Install Sphinx <HereInstallSphinx>` section.
-
-Now we will describe the steps to follow for a full build (using all the above frameworks, tools and libraries). If you do not need the support for some of these you can just freely skip this section.
-
-.. _WindowsBuildLibrary:
-
-Building the library
-^^^^^^^^^^^^^^^^^^^^
-
-1. Make sure you have a working IDE with a valid compiler. In case of the Microsoft Visual Studio just install it and make sure it starts up.
-
-#. Install |CMake|_. Simply follow the wizard, no need to add it to the path. The default install options are OK.
-
-#. Download and install an up-to-date version of msysgit from its `official site <http://code.google.com/p/msysgit/downloads/list>`_. There is also the portable version, which you need only to unpack to get access to the console version of Git. Supposing that for some of us it could be quite enough.
-
-#. Install |TortoiseGit|_. Choose the 32 or 64 bit version according to the type of OS you work in. While installing, locate your msysgit (if it doesn't do that automatically). Follow the wizard -- the default options are OK for the most part.
-
-#. Choose a directory in your file system, where you will download the OpenCV libraries to. I recommend creating a new one that has short path and no special charachters in it, for example :file:`D:/OpenCV`. For this tutorial I'll suggest you do so. If you use your own path and know, what you're doing -- it's OK.
-
- a) Clone the repository to the selected directory. After clicking *Clone* button, a window will appear where you can select from what repository you want to download source files (https://github.com/Itseez/opencv.git) and to what directory (:file:`D:/OpenCV`).
-
- #) Push the OK button and be patient as the repository is quite a heavy download. It will take some time depending on your Internet connection.
-
-#. In this section I will cover installing the 3rd party libraries.
-
- a) Download the |Python_Libraries|_ and install it with the default options. You will need a couple other python extensions. Luckily installing all these may be automated by a nice tool called `Setuptools <http://pypi.python.org/pypi/setuptools#downloads>`_. Download and install again.
-
- #) .. _HereInstallSphinx:
-
- Installing Sphinx is easy once you have installed *Setuptools*. This contains a little application that will automatically connect to the python databases and download the latest version of many python scripts. Start up a command window (enter *cmd* into the windows start menu and press enter) and use the *CD* command to navigate to your Python folders Script sub-folder. Here just pass to the *easy_install.exe* as argument the name of the program you want to install. Add the *sphinx* argument.
-
- .. image:: images/cmsdstartwindows.jpg
- :alt: The Windows Command Startup
- :align: center
-
- .. image:: images/Sphinx_Install.png
- :alt: How to start the command window
- :align: center
-
- .. note::
-
- The *CD* navigation command works only inside a drive. For example if you are somewhere in the *C:* drive you cannot use it this to go to another drive (like for example *D:*). To do so you first need to change drives letters. For this simply enter the command *D:*. Then you can use the *CD* to navigate to specific folder inside the drive. Bonus tip: you can clear the screen by using the *CLS* command.
-
- This will also install its prerequisites `Jinja2 <http://jinja.pocoo.org/docs/>`_ and `Pygments <http://pygments.org/>`_.
-
- #) The easiest way to install |Numpy|_ is to just download its binaries from the `sourceforga page <http://sourceforge.net/projects/numpy/files/NumPy/>`_. Make sure your download and install exactly the binary for your python version (so for version :file:`2.7`).
-
- #) Download the |Miktex|_ and install it. Again just follow the wizard. At the fourth step make sure you select for the *"Install missing packages on-the-fly"* the *Yes* option, as you can see on the image below. Again this will take quite some time so be patient.
-
- .. image:: images/MiktexInstall.png
- :alt: The Miktex Install Screen
- :align: center
-
- #) For the |IntelTBB|_ download the source files and extract it inside a directory on your system. For example let there be :file:`D:/OpenCV/dep`. For installing the |IntelIIP|_ the story is the same. For exctracting the archives I recommend using the `7-Zip <http://www.7-zip.org/>`_ application.
-
- .. image:: images/IntelTBB.png
- :alt: The Miktex Install Screen
- :align: center
-
- #) For the |IntelIIPA|_ download the source files and set environment variable **IPP_ASYNC_ROOT**. It should point to :file:`<your Program Files(x86) directory>/Intel/IPP Preview */ipp directory`. Here ``*`` denotes the particular preview name.
-
- #) In case of the |Eigen|_ library it is again a case of download and extract to the :file:`D:/OpenCV/dep` directory.
-
- #) Same as above with |OpenEXR|_.
-
- #) For the |OpenNI_Framework|_ you need to install both the `development build <http://www.openni.org/downloadfiles/opennimodules/openni-binaries/21-stable>`_ and the `PrimeSensor Module <http://www.openni.org/downloadfiles/opennimodules/openni-compliant-hardware-binaries/32-stable>`_.
-
- #) For the CUDA you need again two modules: the latest |CUDA_Toolkit|_ and the *CUDA Tools SDK*. Download and install both of them with a *complete* option by using the 32 or 64 bit setups according to your OS.
-
- #) In case of the |qtframework|_ you need to build yourself the binary files (unless you use the Microsoft Visual Studio 2008 with 32 bit compiler). To do this go to the `Qt Downloads <http://qt.nokia.com/downloads>`_ page. Download the source files (not the installers!!!):
-
- .. image:: images/qtDownloadThisPackage.png
- :alt: Download this Qt Package
- :align: center
-
- Extract it into a nice and short named directory like :file:`D:/OpenCV/dep/qt/` .
- Then you need to build it. Start up a *Visual* *Studio* *Command* *Prompt* (*2010*) by using the start menu search (or navigate through the start menu :menuselection:`All Programs --> Microsoft Visual Studio 2010 --> Visual Studio Tools --> Visual Studio Command Prompt (2010)`).
-
- .. image:: images/visualstudiocommandprompt.jpg
- :alt: The Visual Studio command prompt
- :align: center
-
- Now navigate to the extracted folder and enter inside it by using this console window. You should have a folder containing files like *Install*, *Make* and so on. Use the *dir* command to list files inside your current directory. Once arrived at this directory enter the following command:
-
- .. code-block:: bash
-
- configure.exe -release -no-webkit -no-phonon -no-phonon-backend -no-script -no-scripttools
- -no-qt3support -no-multimedia -no-ltcg
-
- Completing this will take around 10-20 minutes. Then enter the next command that will take a lot longer (can easily take even more than a full hour):
-
- .. code-block:: bash
-
- nmake
-
- After this set the Qt enviroment variables using the following command on Windows 7:
-
- .. code-block:: bash
-
- setx -m QTDIR D:/OpenCV/dep/qt/qt-everywhere-opensource-src-4.7.3
-
- .. |PathEditor| replace:: Path Editor
- .. _PathEditor: http://www.redfernplace.com/software-projects/patheditor/
-
- Also, add the built binary files path to the system path by using the |PathEditor|_. In our case this is :file:`D:/OpenCV/dep/qt/qt-everywhere-opensource-src-4.7.3/bin`.
-
- .. note::
-
- If you plan on doing Qt application development you can also install at this point the *Qt Visual Studio Add-in*. After this you can make and build Qt applications without using the *Qt Creator*. Everything is nicely integrated into Visual Studio.
-
-#. Now start the *CMake (cmake-gui)*. You may again enter it in the start menu search or get it from the :menuselection:`All Programs --> CMake 2.8 --> CMake (cmake-gui)`. First, select the directory for the source files of the OpenCV library (1). Then, specify a directory where you will build the binary files for OpenCV (2).
-
- .. image:: images/CMakeSelectBin.jpg
- :alt: Select the directories
- :align: center
-
- Press the Configure button to specify the compiler (and *IDE*) you want to use. Note that in case you can choose between different compilers for making either 64 bit or 32 bit libraries. Select the one you use in your application development.
-
- .. image:: images/CMake_Configure_Windows.jpg
- :alt: How CMake should look at build time.
- :align: center
-
- CMake will start out and based on your system variables will try to automatically locate as many packages as possible. You can modify the packages to use for the build in the :menuselection:`WITH --> WITH_X` menu points (where *X* is the package abbreviation). Here are a list of current packages you can turn on or off:
-
- .. image:: images/CMakeBuildWithWindowsGUI.jpg
- :alt: The packages OpenCV may use
- :align: center
-
- Select all the packages you want to use and press again the *Configure* button. For an easier overview of the build options make sure the *Grouped* option under the binary directory selection is turned on. For some of the packages CMake may not find all of the required files or directories. In case of these CMake will throw an error in its output window (located at the bottom of the GUI) and set its field values, to not found constants. For example:
-
- .. image:: images/CMakePackageNotFoundWindows.jpg
- :alt: Constant for not found packages
- :align: center
-
- .. image:: images/CMakeOutputPackageNotFound.jpg
- :alt: Error (warning) thrown in output window of the CMake GUI
- :align: center
-
- For these you need to manually set the queried directories or files path. After this press again the *Configure* button to see if the value entered by you was accepted or not. Do this until all entries are good and you cannot see errors in the field/value or the output part of the GUI.
- Now I want to emphasize an option that you will definitely love: :menuselection:`ENABLE --> ENABLE_SOLUTION_FOLDERS`. OpenCV will create many-many projects and turning this option will make sure that they are categorized inside directories in the *Solution Explorer*. It is a must have feature, if you ask me.
-
- .. image:: images/CMakeBuildOptionsOpenCV.jpg
- :alt: Set the Solution Folders and the parts you want to build
- :align: center
-
- Furthermore, you need to select what part of OpenCV you want to build.
-
- .. container:: enumeratevisibleitemswithsquare
-
- + *BUILD_DOCS* -> It creates two projects for building the documentation of OpenCV (there will be a separate project for building the HTML and the PDF files). Note that these aren't built together with the solution. You need to make an explicit build project command on these to do so.
- + *BUILD_EXAMPLES* -> OpenCV comes with many example applications from which you may learn most of the libraries capabilities. This will also come handy to easily try out if OpenCV is fully functional on your computer.
- + *BUILD_PACKAGE* -> Prior to version 2.3 with this you could build a project that will build an OpenCV installer. With this you can easily install your OpenCV flavor on other systems. For the latest source files of OpenCV it generates a new project that simply creates zip archive with OpenCV sources.
- + *BUILD_SHARED_LIBS* -> With this you can control to build DLL files (when turned on) or static library files (\*.lib) otherwise.
- + *BUILD_TESTS* -> Each module of OpenCV has a test project assigned to it. Building these test projects is also a good way to try out, that the modules work just as expected on your system too.
- + *BUILD_PERF_TESTS* -> There are also performance tests for many OpenCV functions. If you're concerned about performance, build them and run.
- + *BUILD_opencv_python* -> Self-explanatory. Create the binaries to use OpenCV from the Python language.
-
- Press again the *Configure* button and ensure no errors are reported. If this is the case you can tell CMake to create the project files by pushing the *Generate* button. Go to the build directory and open the created **OpenCV** solution.
- Depending on just how much of the above options you have selected the solution may contain quite a lot of projects so be tolerant on the IDE at the startup.
- Now you need to build both the *Release* and the *Debug* binaries. Use the drop-down menu on your IDE to change to another of these after building for one of them.
-
- .. image:: images/ChangeBuildVisualStudio.jpg
- :alt: Look here for changing the Build Type
- :align: center
-
- In the end you can observe the built binary files inside the bin directory:
-
- .. image:: images/OpenCVBuildResultWindows.jpg
- :alt: The Result of the build.
- :align: center
-
- For the documentation you need to explicitly issue the build commands on the *doc* project for the PDF files and on the *doc_html* for the HTML ones. Each of these will call *Sphinx* to do all the hard work. You can find the generated documentation inside the :file:`Build/Doc/_html` for the HTML pages and within the :file:`Build/Doc` the PDF manuals.
-
- .. image:: images/WindowsBuildDoc.png
- :alt: The Documentation Projects
- :align: center
-
- To collect the header and the binary files, that you will use during your own projects, into a separate directory (simillary to how the pre-built binaries ship) you need to explicitely build the *Install* project.
-
- .. image:: images/WindowsBuildInstall.png
- :alt: The Install Project
- :align: center
-
- This will create an *Install* directory inside the *Build* one collecting all the built binaries into a single place. Use this only after you built both the *Release* and *Debug* versions.
-
- To test your build just go into the :file:`Build/bin/Debug` or :file:`Build/bin/Release` directory and start a couple of applications like the *contours.exe*. If they run, you are done. Otherwise, something definitely went awfully wrong. In this case you should contact us at our :opencv_qa:`Q&A forum <>`.
- If everything is okay the *contours.exe* output should resemble the following image (if built with Qt support):
-
- .. image:: images/WindowsQtContoursOutput.png
- :alt: A good output result
- :align: center
-
- .. note::
-
- If you use the GPU module (CUDA libraries) make sure you also upgrade to the latest drivers of your GPU. Error messages containing invalid entries in (or cannot find) the nvcuda.dll are caused mostly by old video card drivers. For testing the GPU (if built) run the *performance_gpu.exe* sample application.
-
-.. _WindowsSetPathAndEnviromentVariable:
-
-Set the OpenCV enviroment variable and add it to the systems path
-=================================================================
-
-First we set an enviroment variable to make easier our work. This will hold the build directory of our OpenCV library that we use in our projects. Start up a command window and enter:
-
-::
-
- setx -m OPENCV_DIR D:\OpenCV\Build\x86\vc10 (suggested for Visual Studio 2010 - 32 bit Windows)
- setx -m OPENCV_DIR D:\OpenCV\Build\x64\vc10 (suggested for Visual Studio 2010 - 64 bit Windows)
-
- setx -m OPENCV_DIR D:\OpenCV\Build\x86\vc11 (suggested for Visual Studio 2012 - 32 bit Windows)
- setx -m OPENCV_DIR D:\OpenCV\Build\x64\vc11 (suggested for Visual Studio 2012 - 64 bit Windows)
-
-Here the directory is where you have your OpenCV binaries (*extracted* or *built*). You can have different platform (e.g. x64 instead of x86) or compiler type, so substitute appropriate value. Inside this you should have two folders called *lib* and *bin*. The -m should be added if you wish to make the settings computer wise, instead of user wise.
-
-If you built static libraries then you are done. Otherwise, you need to add the *bin* folders path to the systems path. This is because you will use the OpenCV library in form of *\"Dynamic-link libraries\"* (also known as **DLL**). Inside these are stored all the algorithms and information the OpenCV library contains. The operating system will load them only on demand, during runtime. However, to do this the operating system needs to know where they are. The systems **PATH** contains a list of folders where DLLs can be found. Add the OpenCV library path to this and the OS will know where to look if he ever needs the OpenCV binaries. Otherwise, you will need to copy the used DLLs right beside the applications executable file (*exe*) for the OS to find it, which is highly unpleasent if you work on many projects. To do this start up again the |PathEditor|_ and add the following new entry (right click in the application to bring up the menu):
-
-::
-
- %OPENCV_DIR%\bin
-
-.. image:: images/PathEditorOpenCVInsertNew.png
- :alt: Right click to insert new path manually.
- :align: center
-
-.. image:: images/PathEditorOpenCVSetPath.png
- :alt: Add the entry.
- :align: center
-
-Save it to the registry and you are done. If you ever change the location of your build directories or want to try out your applicaton with a different build all you will need to do is to update the OPENCV_DIR variable via the *setx* command inside a command window.
-
-Now you can continue reading the tutorials with the :ref:`Windows_Visual_Studio_How_To` section. There you will find out how to use the OpenCV library in your own projects with the help of the Microsoft Visual Studio IDE.
+++ /dev/null
-.. _Windows_Visual_Studio_How_To:
-
-How to build applications with OpenCV inside the *Microsoft Visual Studio*
-**************************************************************************
-
-Everything I describe here will apply to the C\\C++ interface of OpenCV.
-I start out from the assumption that you have read and completed with success the :ref:`Windows_Installation` tutorial. Therefore, before you go any further make sure you have an OpenCV directory that contains the OpenCV header files plus binaries and you have set the environment variables as :ref:`described here <WindowsSetPathAndEnviromentVariable>`.
-
-.. image:: images/OpenCV_Install_Directory.jpg
- :alt: You should have a folder looking like this.
- :align: center
-
-The OpenCV libraries, distributed by us, on the Microsoft Windows operating system are in a **D**\ ynamic **L**\ inked **L**\ ibraries (*DLL*). These have the advantage that all the content of the library are loaded only at runtime, on demand, and that countless programs may use the same library file. This means that if you have ten applications using the OpenCV library, no need to have around a version for each one of them. Of course you need to have the *dll* of the OpenCV on all systems where you want to run your application.
-
-Another approach is to use static libraries that have *lib* extensions. You may build these by using our source files as described in the :ref:`Windows_Installation` tutorial. When you use this the library will be built-in inside your *exe* file. So there is no chance that the user deletes them, for some reason. As a drawback your application will be larger one and as, it will take more time to load it during its startup.
-
-To build an application with OpenCV you need to do two things:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + *Tell* to the compiler how the OpenCV library *looks*. You do this by *showing* it the header files.
- + *Tell* to the linker from where to get the functions or data structures of OpenCV, when they are needed.
-
- If you use the *lib* system you must set the path where the library files are and specify in which one of them to look. During the build the linker will look into these libraries and add the definitions and implementation of all *used* functions and data structures to the executable file.
-
- If you use the *DLL* system you must again specify all this, however now for a different reason. This is a Microsoft OS specific stuff. It seems that the linker needs to know that where in the DLL to search for the data structure or function at the runtime. This information is stored inside *lib* files. Nevertheless, they aren't static libraries. They are so called import libraries. This is why when you make some *DLLs* in Windows you will also end up with some *lib* extension libraries. The good part is that at runtime only the *DLL* is required.
-
-To pass on all this information to the Visual Studio IDE you can either do it globally (so all your future projects will get these information) or locally (so only for you current project). The advantage of the global one is that you only need to do it once; however, it may be undesirable to clump all your projects all the time with all these information. In case of the global one how you do it depends on the Microsoft Visual Studio you use. There is a **2008 and previous versions** and a **2010 way** of doing it. Inside the global section of this tutorial I'll show what the main differences are.
-
-The base item of a project in Visual Studio is a solution. A solution may contain multiple projects. Projects are the building blocks of an application. Every project will realize something and you will have a main project in which you can put together this project puzzle. In case of the many simple applications (like many of the tutorials will be) you do not need to break down the application into modules. In these cases your main project will be the only existing one. Now go create a new solution inside Visual studio by going through the :menuselection:`File --> New --> Project` menu selection. Choose *Win32 Console Application* as type. Enter its name and select the path where to create it. Then in the upcoming dialog make sure you create an empty project.
-
-.. image:: images/NewProjectVisualStudio.jpg
- :alt: Which options to select
- :align: center
-
-The *local* method
-==================
-
-Every project is built separately from the others. Due to this every project has its own rule package. Inside this rule packages are stored all the information the *IDE* needs to know to build your project. For any application there are at least two build modes: a *Release* and a *Debug* one. The *Debug* has many features that exist so you can find and resolve easier bugs inside your application. In contrast the *Release* is an optimized version, where the goal is to make the application run as fast as possible or to be as small as possible. You may figure that these modes also require different rules to use during build. Therefore, there exist different rule packages for each of your build modes. These rule packages are called inside the IDE as *project properties* and you can view and modify them by using the *Property Manger*. You can bring up this with :menuselection:`View --> Property Pages`. Expand it and you can see the existing rule packages (called *Proporty Sheets*).
-
-.. image:: images/PropertyPageExample.jpg
- :alt: An example of Property Sheet
- :align: center
-
-The really useful stuff of these is that you may create a rule package *once* and you can later just add it to your new projects. Create it once and reuse it later. We want to create a new *Property Sheet* that will contain all the rules that the compiler and linker needs to know. Of course we will need a separate one for the Debug and the Release Builds. Start up with the Debug one as shown in the image below:
-
-.. image:: images/AddNewPropertySheet.jpg
- :alt: Add a new Property Sheet
- :align: center
-
-Use for example the *OpenCV_Debug* name. Then by selecting the sheet :menuselection:`Right Click --> Properties`. In the following I will show to set the OpenCV rules locally, as I find unnecessary to pollute projects with custom rules that I do not use it. Go the C++ groups General entry and under the *"Additional Include Directories"* add the path to your OpenCV include. If you don't have *"C/C++"* group, you should add any .c/.cpp file to the project.
-
-.. code-block:: bash
-
- $(OPENCV_DIR)\..\..\include
-
-.. image:: images/PropertySheetOpenCVInclude.jpg
- :alt: Add the include dir like this.
- :align: center
-
-When adding third party libraries settings it is generally a good idea to use the power behind the environment variables. The full location of the OpenCV library may change on each system. Moreover, you may even end up yourself with moving the install directory for some reason. If you would give explicit paths inside your property sheet your project will end up not working when you pass it further to someone else who has a different OpenCV install path. Moreover, fixing this would require to manually modifying every explicit path. A more elegant solution is to use the environment variables. Anything that you put inside a parenthesis started with a dollar sign will be replaced at runtime with the current environment variables value. Here comes in play the environment variable setting we already made in our :ref:`previous tutorial <WindowsSetPathAndEnviromentVariable>`.
-
-Next go to the :menuselection:`Linker --> General` and under the *"Additional Library Directories"* add the libs directory:
-
-.. code-block:: bash
-
- $(OPENCV_DIR)\lib
-
-.. image:: images/PropertySheetOpenCVLib.jpg
- :alt: Add the library folder like this.
- :align: center
-
-Then you need to specify the libraries in which the linker should look into. To do this go to the :menuselection:`Linker --> Input` and under the *"Additional Dependencies"* entry add the name of all modules which you want to use:
-
-.. image:: images/PropertySheetOpenCVLibrariesDebugSmple.jpg
- :alt: Add the debug library names here.
- :align: center
-
-.. image:: images/PropertySheetOpenCVLibrariesDebug.jpg
- :alt: Like this.
- :align: center
-
-The names of the libraries are as follow:
-
-.. code-block:: bash
-
- opencv_(The Name of the module)(The version Number of the library you use)d.lib
-
-A full list, for the latest version would contain:
-
-.. code-block:: bash
-
- opencv_calib3d300d.lib
- opencv_core300d.lib
- opencv_features2d300d.lib
- opencv_flann300d.lib
- opencv_highgui300d.lib
- opencv_imgcodecs300d.lib
- opencv_imgproc300d.lib
- opencv_ml300d.lib
- opencv_objdetect300d.lib
- opencv_photo300d.lib
- opencv_shape300d.lib
- opencv_stitching300d.lib
- opencv_superres300d.lib
- opencv_ts300d.lib
- opencv_video300d.lib
- opencv_videoio300d.lib
- opencv_videostab300d.lib
-
-
-The letter *d* at the end just indicates that these are the libraries required for the debug. Now click ok to save and do the same with a new property inside the Release rule section. Make sure to omit the *d* letters from the library names and to save the property sheets with the save icon above them.
-
-.. image:: images/PropertySheetOpenCVLibrariesRelease.jpg
- :alt: And the release ones.
- :align: center
-
-You can find your property sheets inside your projects directory. At this point it is a wise decision to back them up into some special directory, to always have them at hand in the future, whenever you create an OpenCV project. Note that for Visual Studio 2010 the file extension is *props*, while for 2008 this is *vsprops*.
-
-.. image:: images/PropertySheetInsideFolder.jpg
- :alt: And the release ones.
- :align: center
-
-Next time when you make a new OpenCV project just use the "Add Existing Property Sheet..." menu entry inside the Property Manager to easily add the OpenCV build rules.
-
-.. image:: images/PropertyPageAddExisting.jpg
- :alt: Use this option.
- :align: center
-
-The *global* method
-===================
-
-In case you find to troublesome to add the property pages to each and every one of your projects you can also add this rules to a *"global property page"*. However, this applies only to the additional include and library directories. The name of the libraries to use you still need to specify manually by using for instance: a Property page.
-
-In Visual Studio 2008 you can find this under the: :menuselection:`Tools --> Options --> Projects and Solutions --> VC++ Directories`.
-
-.. image:: images/VCDirectories2008.jpg
- :alt: VC++ Directories in VS 2008.
- :align: center
-
-In Visual Studio 2010 this has been moved to a global property sheet which is automatically added to every project you create:
-
-.. image:: images/VCDirectories2010.jpg
- :alt: VC++ Directories in VS 2010.
- :align: center
-
-The process is the same as described in case of the local approach. Just add the include directories by using the environment variable *OPENCV_DIR*.
-
-Test it!
-========
-
-Now to try this out download our little test :download:`source code <../../../../samples/cpp/tutorial_code/introduction/windows_visual_studio_Opencv/introduction_windows_vs.cpp>` or get it from the sample code folder of the OpenCV sources. Add this to your project and build it. Here's its content:
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/windows_visual_studio_Opencv/introduction_windows_vs.cpp
- :language: cpp
- :tab-width: 4
- :linenos:
-
-You can start a Visual Studio build from two places. Either inside from the *IDE* (keyboard combination: :kbd:`Control-F5`) or by navigating to your build directory and start the application with a double click. The catch is that these two **aren't** the same. When you start it from the *IDE* its current working directory is the projects directory, while otherwise it is the folder where the application file currently is (so usually your build directory). Moreover, in case of starting from the *IDE* the console window will not close once finished. It will wait for a keystroke of yours.
-
-.. |voila| unicode:: voil U+00E1
-
-This is important to remember when you code inside the code open and save commands. You're resources will be saved ( and queried for at opening!!!) relatively to your working directory. This is unless you give a full, explicit path as parameter for the I/O functions. In the code above we open :download:`this OpenCV logo<../../../../samples/data/opencv-logo.png>`. Before starting up the application make sure you place the image file in your current working directory. Modify the image file name inside the code to try it out on other images too. Run it and |voila|:
-
-.. image:: images/SuccessVisualStudioWindows.jpg
- :alt: You should have this.
- :align: center
-
-Command line arguments with Visual Studio
-=========================================
-
-Throughout some of our future tutorials you'll see that the programs main input method will be by giving a runtime argument. To do this you can just start up a commmand windows (:kbd:`cmd + Enter` in the start menu), navigate to your executable file and start it with an argument. So for example in case of my upper project this would look like:
-
-.. code-block:: bash
- :linenos:
-
- D:
- CD OpenCV\MySolutionName\Release
- MySolutionName.exe exampleImage.jpg
-
-Here I first changed my drive (if your project isn't on the OS local drive), navigated to my project and start it with an example image argument. While under Linux system it is common to fiddle around with the console window on the Microsoft Windows many people come to use it almost never. Besides, adding the same argument again and again while you are testing your application is, somewhat, a cumbersome task. Luckily, in the Visual Studio there is a menu to automate all this:
-
-.. image:: images/VisualStudioCommandLineArguments.jpg
- :alt: Visual Studio Command Line Arguments
- :align: center
-
-Specify here the name of the inputs and while you start your application from the Visual Studio enviroment you have automatic argument passing. In the next introductionary tutorial you'll see an in-depth explanation of the upper source code: :ref:`Display_Image`.
+++ /dev/null
-.. _Windows_Visual_Studio_Image_Watch:
-
-Image Watch: viewing in-memory images in the Visual Studio debugger
-*******************************************************************
-
-Image Watch is a plug-in for Microsoft Visual Studio that lets you to visualize in-memory images (*cv::Mat* or *IplImage\_* objects, for example) while debugging an application. This can be helpful for tracking down bugs, or for simply understanding what a given piece of code is doing.
-
-Prerequisites
-=============
-
-This tutorial assumes that you have the following available:
-
-#. Visual Studio 2012 Professional (or better) with Update 1 installed. Update 1 can be downloaded `here <http://www.microsoft.com/en-us/download/details.aspx?id=35774>`_.
-
-#. An OpenCV installation on your Windows machine (Tutorial: :ref:`Windows_Installation`).
-
-#. Ability to create and build OpenCV projects in Visual Studio (Tutorial: :ref:`Windows_Visual_Studio_How_To`).
-
-Installation
-============
-
-`Download <http://go.microsoft.com/fwlink/?LinkId=285460>`_ the Image Watch installer. The installer comes in a single file with extension .vsix (*Visual Studio Extension*). To launch it, simply double-click on the .vsix file in Windows Explorer. When the installer has finished, make sure to restart Visual Studio to complete the installation.
-
-Example
-========
-
-Image Watch works with any existing project that uses OpenCV image objects (for example, *cv::Mat*). In this example, we use a minimal test program that loads an image from a file and runs an edge detector. To build the program, create a console application project in Visual Studio, name it "image-watch-demo", and insert the source code below.
-
-.. code-block:: cpp
-
- // Test application for the Visual Studio Image Watch Debugger extension
-
- #include <iostream> // std::cout
- #include <opencv2/core/core.hpp> // cv::Mat
- #include <opencv2/imgcodecs/imgcodecs.hpp> // cv::imread()
- #include <opencv2/imgproc/imgproc.hpp> // cv::Canny()
-
- using namespace std;
- using namespace cv;
-
- void help()
- {
- cout
- << "----------------------------------------------------" << endl
- << "This is a test program for the Image Watch Debugger " << endl
- << "plug-in for Visual Studio. The program loads an " << endl
- << "image from a file and runs the Canny edge detector. " << endl
- << "No output is displayed or written to disk."
- << endl
- << "Usage:" << endl
- << "image-watch-demo inputimage" << endl
- << "----------------------------------------------------" << endl
- << endl;
- }
-
- int main(int argc, char *argv[])
- {
- help();
-
- if (argc != 2)
- {
- cout << "Wrong number of parameters" << endl;
- return -1;
- }
-
- cout << "Loading input image: " << argv[1] << endl;
- Mat input;
- input = imread(argv[1], IMREAD_COLOR);
-
- cout << "Detecting edges in input image" << endl;
- Mat edges;
- Canny(input, edges, 10, 100);
-
- return 0;
- }
-
-Make sure your active solution configuration (:menuselection:`Build --> Configuration Manager`) is set to a debug build (usually called "Debug"). This should disable compiler optimizations so that viewing variables in the debugger can work reliably.
-
-Build your solution (:menuselection:`Build --> Build Solution`, or press *F7*).
-
-Before continuing, do not forget to add the command line argument of your input image to your project (:menuselection:`Right click on project --> Properties --> Configuration Properties --> Debugging` and then set the field ``Command Arguments`` with the location of the image).
-
-Now set a breakpoint on the source line that says
-
-.. code-block:: cpp
-
- Mat edges;
-
-To set the breakpoint, right-click on the source line and select :menuselection:`Breakpoints --> Insert Breakpoint` from the context menu.
-
-Launch the program in the debugger (:menuselection:`Debug --> Start Debugging`, or hit *F5*). When the breakpoint is hit, the program is paused and Visual Studio displays a yellow instruction pointer at the breakpoint:
-
-.. image:: images/breakpoint.png
-
-Now you can inspect the state of you program. For example, you can bring up the *Locals* window (:menuselection:`Debug --> Windows --> Locals`), which will show the names and values of the variables in the current scope:
-
-.. image:: images/vs_locals.png
-
-Note that the built-in *Locals* window will display text only. This is where the Image Watch plug-in comes in. Image Watch is like another *Locals* window, but with an image viewer built into it. To bring up Image Watch, select :menuselection:`View --> Other Windows --> Image Watch`. Like Visual Studio's *Locals* window, Image Watch can dock to the Visual Studio IDE. Also, Visual Studio will remember whether you had Image Watch open, and where it was located between debugging sessions. This means you only have to do this once--the next time you start debugging, Image Watch will be back where you left it. Here's what the docked Image Watch window looks like at our breakpoint:
-
-.. image:: images/toolwindow.jpg
- :height: 320pt
-
-The radio button at the top left (*Locals/Watch*) selects what is shown in the *Image List* below: *Locals* lists all OpenCV image objects in the current scope (this list is automatically populated). *Watch* shows image expressions that have been pinned for continuous inspection (not described here, see `Image Watch documentation <http://go.microsoft.com/fwlink/?LinkId=285461>`_ for details). The image list shows basic information such as width, height, number of channels, and, if available, a thumbnail. In our example, the image list contains our two local image variables, *input* and *edges*.
-
-If an image has a thumbnail, left-clicking on that image will select it for detailed viewing in the *Image Viewer* on the right. The viewer lets you pan (drag mouse) and zoom (mouse wheel). It also displays the pixel coordinate and value at the current mouse position.
-
-.. image:: images/viewer.jpg
- :height: 160pt
-
-Note that the second image in the list, *edges*, is shown as "invalid". This indicates that some data members of this image object have corrupt or invalid values (for example, a negative image width). This is expected at this point in the program, since the C++ constructor for *edges* has not run yet, and so its members have undefined values (in debug mode they are usually filled with "0xCD" bytes).
-
-From here you can single-step through your code (:menuselection:`Debug->Step Over`, or press *F10*) and watch the pixels change: if you step once, over the *Mat edges;* statement, the *edges* image will change from "invalid" to "empty", which means that it is now in a valid state (default constructed), even though it has not been initialized yet (using *cv::Mat::create()*, for example). If you make one more step over the *cv::Canny()* call, you will see a thumbnail of the edge image appear in the image list.
-
-Now assume you want to do a visual sanity check of the *cv::Canny()* implementation. Bring the *edges* image into the viewer by selecting it in the *Image List* and zoom into a region with a clearly defined edge:
-
-.. image:: images/edges_zoom.png
- :height: 160pt
-
-Right-click on the *Image Viewer* to bring up the view context menu and enable :menuselection:`Link Views` (a check box next to the menu item indicates whether the option is enabled).
-
-.. image:: images/viewer_context_menu.png
- :height: 120pt
-
-The :menuselection:`Link Views` feature keeps the view region fixed when flipping between images of the same size. To see how this works, select the input image from the image list--you should now see the corresponding zoomed-in region in the input image:
-
-.. image:: images/input_zoom.png
- :height: 160pt
-
-You may also switch back and forth between viewing input and edges with your up/down cursor keys. That way you can easily verify that the detected edges line up nicely with the data in the input image.
-
-More ...
-====================
-
-Image watch has a number of more advanced features, such as
-
-#. pinning images to a *Watch* list for inspection across scopes or between debugging sessions
-
-#. clamping, thresholding, or diff'ing images directly inside the Watch window
-
-#. comparing an in-memory image against a reference image from a file
-
-Please refer to the online `Image Watch Documentation <http://go.microsoft.com/fwlink/?LinkId=285461>`_ for details--you also can get to the documentation page by clicking on the *Help* link in the Image Watch window:
-
-.. image:: images/help_button.jpg
- :height: 80pt
+++ /dev/null
-.. _OpenCViOSHelloWorld:
-
-OpenCV iOS Hello
-*******************************
-
-Goal
-====
-
-In this tutorial we will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Link OpenCV framework with Xcode
- * How to write simple Hello World application using OpenCV and Xcode.
-
-*Linking OpenCV iOS*
-======================
-Follow this step by step guide to link OpenCV to iOS.
-
-1. Create a new XCode project.
-
-2. Now we need to link *opencv2.framework* with Xcode. Select the project Navigator in the left hand panel and click on project name.
-
-3. Under the TARGETS click on Build Phases. Expand Link Binary With Libraries option.
-
-4. Click on Add others and go to directory where *opencv2.framework* is located and click open
-
-5. Now you can start writing your application.
-
-.. image:: images/linking_opencv_ios.png
- :alt: OpenCV iOS in Xcode
- :align: center
-
-*Hello OpenCV iOS Application*
-===============================
-
-Now we will learn how to write a simple Hello World Application in Xcode using OpenCV.
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Link your project with OpenCV as shown in previous section.
- * Open the file named *NameOfProject-Prefix.pch* ( replace NameOfProject with name of your project) and add the following lines of code.
-
-.. code-block:: cpp
-
- #ifdef __cplusplus
- #import <opencv2/opencv.hpp>
- #endif
-
-.. image:: images/header_directive.png
- :alt: header
- :align: center
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Add the following lines of code to viewDidLoad method in ViewController.m.
-.. code-block:: cpp
-
- UIAlertView * alert = [[UIAlertView alloc] initWithTitle:@"Hello!" message:@"Welcome to OpenCV" delegate:self cancelButtonTitle:@"Continue" otherButtonTitles:nil];
- [alert show];
-
-.. image:: images/view_did_load.png
- :alt: view did load
- :align: center
-
-.. container:: enumeratevisibleitemswithsquare
-
- * You are good to run the project.
-
-*Output*
-=========
-
-.. image:: images/output.png
- :alt: output
- :align: center
+++ /dev/null
-.. _OpenCViOSImageManipulation:
-
-OpenCV iOS - Image Processing
-*******************************
-
-Goal
-====
-
-In this tutorial we will learn how to do basic image processing using OpenCV in iOS.
-
-
-*Introduction*
-==============
-
-In *OpenCV* all the image processing operations are usually carried out on the *Mat* structure. In iOS however, to render an image on screen it have to be an instance of the *UIImage* class. To convert an *OpenCV Mat* to an *UIImage* we use the *Core Graphics* framework available in iOS. Below is the code needed to covert back and forth between Mat's and UIImage's.
-
-
-.. code-block:: cpp
-
- - (cv::Mat)cvMatFromUIImage:(UIImage *)image
- {
- CGColorSpaceRef colorSpace = CGImageGetColorSpace(image.CGImage);
- CGFloat cols = image.size.width;
- CGFloat rows = image.size.height;
-
- cv::Mat cvMat(rows, cols, CV_8UC4); // 8 bits per component, 4 channels (color channels + alpha)
-
- CGContextRef contextRef = CGBitmapContextCreate(cvMat.data, // Pointer to data
- cols, // Width of bitmap
- rows, // Height of bitmap
- 8, // Bits per component
- cvMat.step[0], // Bytes per row
- colorSpace, // Colorspace
- kCGImageAlphaNoneSkipLast |
- kCGBitmapByteOrderDefault); // Bitmap info flags
-
- CGContextDrawImage(contextRef, CGRectMake(0, 0, cols, rows), image.CGImage);
- CGContextRelease(contextRef);
-
- return cvMat;
- }
-
-.. code-block:: cpp
-
- - (cv::Mat)cvMatGrayFromUIImage:(UIImage *)image
- {
- CGColorSpaceRef colorSpace = CGImageGetColorSpace(image.CGImage);
- CGFloat cols = image.size.width;
- CGFloat rows = image.size.height;
-
- cv::Mat cvMat(rows, cols, CV_8UC1); // 8 bits per component, 1 channels
-
- CGContextRef contextRef = CGBitmapContextCreate(cvMat.data, // Pointer to data
- cols, // Width of bitmap
- rows, // Height of bitmap
- 8, // Bits per component
- cvMat.step[0], // Bytes per row
- colorSpace, // Colorspace
- kCGImageAlphaNoneSkipLast |
- kCGBitmapByteOrderDefault); // Bitmap info flags
-
- CGContextDrawImage(contextRef, CGRectMake(0, 0, cols, rows), image.CGImage);
- CGContextRelease(contextRef);
-
- return cvMat;
- }
-
-After the processing we need to convert it back to UIImage. The code below can handle both gray-scale and color image conversions (determined by the number of channels in the *if* statement).
-
-.. code-block:: cpp
-
- cv::Mat greyMat;
- cv::cvtColor(inputMat, greyMat, COLOR_BGR2GRAY);
-
-After the processing we need to convert it back to UIImage.
-
-.. code-block:: cpp
-
- -(UIImage *)UIImageFromCVMat:(cv::Mat)cvMat
- {
- NSData *data = [NSData dataWithBytes:cvMat.data length:cvMat.elemSize()*cvMat.total()];
- CGColorSpaceRef colorSpace;
-
- if (cvMat.elemSize() == 1) {
- colorSpace = CGColorSpaceCreateDeviceGray();
- } else {
- colorSpace = CGColorSpaceCreateDeviceRGB();
- }
-
- CGDataProviderRef provider = CGDataProviderCreateWithCFData((__bridge CFDataRef)data);
-
- // Creating CGImage from cv::Mat
- CGImageRef imageRef = CGImageCreate(cvMat.cols, //width
- cvMat.rows, //height
- 8, //bits per component
- 8 * cvMat.elemSize(), //bits per pixel
- cvMat.step[0], //bytesPerRow
- colorSpace, //colorspace
- kCGImageAlphaNone|kCGBitmapByteOrderDefault,// bitmap info
- provider, //CGDataProviderRef
- NULL, //decode
- false, //should interpolate
- kCGRenderingIntentDefault //intent
- );
-
-
- // Getting UIImage from CGImage
- UIImage *finalImage = [UIImage imageWithCGImage:imageRef];
- CGImageRelease(imageRef);
- CGDataProviderRelease(provider);
- CGColorSpaceRelease(colorSpace);
-
- return finalImage;
- }
-
-*Output*
-==================================
-
-.. image:: images/output.jpg
- :alt: header
- :align: center
-
-Check out an instance of running code with more Image Effects on `YouTube <http://www.youtube.com/watch?v=Ko3K_xdhJ1I>`_ .
-
-.. raw:: html
-
- <div align="center">
- <iframe width="560" height="350" src="http://www.youtube.com/embed/Ko3K_xdhJ1I" frameborder="0" allowfullscreen></iframe>
- </div>
+++ /dev/null
-.. _Table-Of-Content-iOS:
-
-**OpenCV iOS**
------------------------------------------------------------
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ===============================================================================
- |iOSOpenCV| **Title:** :ref:`OpenCViOSHelloWorld`
-
- *Compatibility:* > OpenCV 2.4.3
-
- *Author:* Charu Hans
-
- You will learn how to link OpenCV with iOS and write a basic application.
-
- ============ ===============================================================================
-
- .. |iOSOpenCV| image:: images/intro.png
- :height: 120pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================ ============================================================================
- |iOSOpenCVImg| **Title:** :ref:`OpenCViOSImageManipulation`
-
- *Compatibility:* > OpenCV 2.4.3
-
- *Author:* Charu Hans
-
- You will learn how to do simple image manipulation using OpenCV in iOS.
-
- ================ ============================================================================
-
- .. |iOSOpenCVImg| image:: images/image_effects.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================= ============================================================================
- |iOSOpenCVVideo| **Title:** :ref:`OpenCViOSVideoProcessing`
-
- *Compatibility:* > OpenCV 2.4.3
-
- *Author:* Eduard Feicho
-
- You will learn how to capture and process video from camera using OpenCV in iOS.
-
- ================= ============================================================================
-
- .. |iOSOpenCVVideo| image:: images/facedetect.jpg
- :height: 120pt
- :width: 90pt
-
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../hello/hello
- ../image_manipulation/image_manipulation
- ../video_processing/video_processing
+++ /dev/null
-.. _OpenCViOSVideoProcessing:
-
-OpenCV iOS - Video Processing
-*******************************
-
-This tutorial explains how to process video frames using the iPhone's camera and OpenCV.
-
-Prerequisites:
-==================
-
- * Xcode 4.3 or higher
- * Basic knowledge of iOS programming (Objective-C, Interface Builder)
-
-
-Including OpenCV library in your iOS project
-================================================
-
-The OpenCV library comes as a so-called framework, which you can directly drag-and-drop into your XCode project. Download the latest binary from <http://sourceforge.net/projects/opencvlibrary/files/opencv-ios/>. Alternatively follow this guide :ref:`iOS-Installation` to compile the framework manually. Once you have the framework, just drag-and-drop into XCode:
-
- .. image:: images/xcode_hello_ios_framework_drag_and_drop.png
-
-
-Also you have to locate the prefix header that is used for all header files in the project. The file is typically located at "ProjectName/Supporting Files/ProjectName-Prefix.pch". There, you have add an include statement to import the opencv library. However, make sure you include opencv before you include UIKit and Foundation, because else you will get some weird compile errors that some macros like min and max are defined multiple times. For example the prefix header could look like the following:
-
-.. code-block:: objc
- :linenos:
-
- //
- // Prefix header for all source files of the 'VideoFilters' target in the 'VideoFilters' project
- //
-
- #import <Availability.h>
-
- #ifndef __IPHONE_4_0
- #warning "This project uses features only available in iOS SDK 4.0 and later."
- #endif
-
- #ifdef __cplusplus
- #import <opencv2/opencv.hpp>
- #endif
-
- #ifdef __OBJC__
- #import <UIKit/UIKit.h>
- #import <Foundation/Foundation.h>
- #endif
-
-
-
-Example video frame processing project
---------------------------------------
-User Interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First, we create a simple iOS project, for example Single View Application. Then, we create and add an UIImageView and UIButton to start the camera and display the video frames. The storyboard could look like that:
-
- .. image:: images/xcode_hello_ios_viewcontroller_layout.png
-
-
-Make sure to add and connect the IBOutlets and IBActions to the corresponding ViewController:
-
-.. code-block:: objc
- :linenos:
-
- @interface ViewController : UIViewController
- {
- IBOutlet UIImageView* imageView;
- IBOutlet UIButton* button;
- }
-
- - (IBAction)actionStart:(id)sender;
-
- @end
-
-
-Adding the Camera
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We add a camera controller to the view controller and initialize it when the view has loaded:
-
-.. code-block:: objc
- :linenos:
-
- #import <opencv2/videoio/cap_ios.h>
- using namespace cv;
-
-
- @interface ViewController : UIViewController
- {
- ...
- CvVideoCamera* videoCamera;
- }
- ...
- @property (nonatomic, retain) CvVideoCamera* videoCamera;
-
- @end
-
-.. code-block:: objc
- :linenos:
-
- - (void)viewDidLoad
- {
- [super viewDidLoad];
- // Do any additional setup after loading the view, typically from a nib.
-
- self.videoCamera = [[CvVideoCamera alloc] initWithParentView:imageView];
- self.videoCamera.defaultAVCaptureDevicePosition = AVCaptureDevicePositionFront;
- self.videoCamera.defaultAVCaptureSessionPreset = AVCaptureSessionPreset352x288;
- self.videoCamera.defaultAVCaptureVideoOrientation = AVCaptureVideoOrientationPortrait;
- self.videoCamera.defaultFPS = 30;
- self.videoCamera.grayscale = NO;
- }
-
-In this case, we initialize the camera and provide the imageView as a target for rendering each frame. CvVideoCamera is basically a wrapper around AVFoundation, so we provie as properties some of the AVFoundation camera options. For example we want to use the front camera, set the video size to 352x288 and a video orientation (the video camera normally outputs in landscape mode, which results in transposed data when you design a portrait application).
-
-The property defaultFPS sets the FPS of the camera. If the processing is less fast than the desired FPS, frames are automatically dropped.
-
-The property grayscale=YES results in a different colorspace, namely "YUV (YpCbCr 4:2:0)", while grayscale=NO will output 32 bit BGRA.
-
-
-Additionally, we have to manually add framework dependencies of the opencv framework. Finally, you should have at least the following frameworks in your project:
-
-
-* opencv2
-
-* Accelerate
-
-* AssetsLibrary
-
-* AVFoundation
-
-* CoreGraphics
-
-* CoreImage
-
-* CoreMedia
-
-* CoreVideo
-
-* QuartzCore
-
-* UIKit
-
-* Foundation
-
-
- .. image:: images/xcode_hello_ios_frameworks_add_dependencies.png
-
-
-Processing frames
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We follow the delegation pattern, which is very common in iOS, to provide access to each camera frame. Basically, the View Controller has to implement the CvVideoCameraDelegate protocol and has to be set as delegate to the video camera:
-
-.. code-block:: objc
- :linenos:
-
- @interface ViewController : UIViewController<CvVideoCameraDelegate>
-
-
-
-.. code-block:: objc
- :linenos:
-
- - (void)viewDidLoad
- {
- ...
- self.videoCamera = [[CvVideoCamera alloc] initWithParentView:imageView];
- self.videoCamera.delegate = self;
- ...
- }
-
-
-.. code-block:: objc
- :linenos:
-
- #pragma mark - Protocol CvVideoCameraDelegate
-
- #ifdef __cplusplus
- - (void)processImage:(Mat&)image;
- {
- // Do some OpenCV stuff with the image
- }
- #endif
-
-Note that we are using C++ here (cv::Mat).
-Important: You have to rename the view controller's extension .m into .mm, so that the compiler compiles it under the assumption of Objective-C++ (Objective-C and C++ mixed). Then, __cplusplus is defined when the compiler is processing the file for C++ code. Therefore, we put our code within a block where __cplusplus is defined.
-
-
-Basic video processing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-From here you can start processing video frames. For example the following snippet color-inverts the image:
-
-
-.. code-block:: objc
- :linenos:
-
- - (void)processImage:(Mat&)image;
- {
- // Do some OpenCV stuff with the image
- Mat image_copy;
- cvtColor(image, image_copy, COLOR_BGR2GRAY);
-
- // invert image
- bitwise_not(image_copy, image_copy);
-
- //Convert BGR to BGRA (three channel to four channel)
- Mat bgr;
- cvtColor(image_copy, bgr, COLOR_GRAY2BGR);
-
- cvtColor(bgr, image, COLOR_BGR2BGRA);
- }
-
-
-Start!
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Finally, we have to tell the camera to actually start/stop working. The following code will start the camera when you press the button, assuming you connected the UI properly:
-
-.. code-block:: objc
- :linenos:
-
- #pragma mark - UI Actions
-
- - (IBAction)actionStart:(id)sender;
- {
- [self.videoCamera start];
- }
-
-
-
-Hints
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Try to avoid costly matrix copy operations as much as you can, especially if you are aiming for real-time. As the image data is passed as reference, work in-place, if possible.
-
-When you are working on grayscale data, turn set grayscale = YES as the YUV colorspace gives you directly access the luminance plane.
-
-The Accelerate framework provides some CPU-accelerated DSP filters, which come handy in your case.
+++ /dev/null
-.. _introductiontosvms:
-
-Introduction to Support Vector Machines
-***************************************
-
-Goal
-====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + Use the OpenCV functions :svms:`CvSVM::train <cvsvm-train>` to build a classifier based on SVMs and :svms:`CvSVM::predict <cvsvm-predict>` to test its performance.
-
-What is a SVM?
-==============
-
-A Support Vector Machine (SVM) is a discriminative classifier formally defined by a separating hyperplane. In other words, given labeled training data (*supervised learning*), the algorithm outputs an optimal hyperplane which categorizes new examples.
-
-In which sense is the hyperplane obtained optimal? Let's consider the following
-simple problem:
-
- For a linearly separable set of 2D-points which belong to one of two classes, find a separating straight line.
-
-.. image:: images/separating-lines.png
- :alt: A seperation example
- :align: center
-
-.. note:: In this example we deal with lines and points in the Cartesian plane instead of hyperplanes and vectors in a high dimensional space. This is a simplification of the problem.It is important to understand that this is done only because our intuition is better built from examples that are easy to imagine. However, the same concepts apply to tasks where the examples to classify lie in a space whose dimension is higher than two.
-
-In the above picture you can see that there exists multiple lines that offer a solution to the problem. Is any of them better than the others? We can intuitively define a criterion to estimate the worth of the lines:
-
- A line is bad if it passes too close to the points because it will be noise sensitive and it will not generalize correctly. Therefore, our goal should be to find the line passing as far as possible from all points.
-
-Then, the operation of the SVM algorithm is based on finding the hyperplane that gives the largest minimum distance to the training examples. Twice, this distance receives the important name of **margin** within SVM's theory. Therefore, the optimal separating hyperplane *maximizes* the margin of the training data.
-
-.. image:: images/optimal-hyperplane.png
- :alt: The Optimal hyperplane
- :align: center
-
-How is the optimal hyperplane computed?
-=======================================
-
-Let's introduce the notation used to define formally a hyperplane:
-
-.. math::
- f(x) = \beta_{0} + \beta^{T} x,
-
-where :math:`\beta` is known as the *weight vector* and :math:`\beta_{0}` as the *bias*.
-
-.. seealso:: A more in depth description of this and hyperplanes you can find in the section 4.5 (*Seperating Hyperplanes*) of the book: *Elements of Statistical Learning* by T. Hastie, R. Tibshirani and J. H. Friedman.
-
-The optimal hyperplane can be represented in an infinite number of different ways by scaling of :math:`\beta` and :math:`\beta_{0}`. As a matter of convention, among all the possible representations of the hyperplane, the one chosen is
-
-.. math::
- |\beta_{0} + \beta^{T} x| = 1
-
-where :math:`x` symbolizes the training examples closest to the hyperplane. In general, the training examples that are closest to the hyperplane are called **support vectors**. This representation is known as the **canonical hyperplane**.
-
-Now, we use the result of geometry that gives the distance between a point :math:`x` and a hyperplane :math:`(\beta, \beta_{0})`:
-
-.. math::
- \mathrm{distance} = \frac{|\beta_{0} + \beta^{T} x|}{||\beta||}.
-
-In particular, for the canonical hyperplane, the numerator is equal to one and the distance to the support vectors is
-
-.. math::
- \mathrm{distance}_{\text{ support vectors}} = \frac{|\beta_{0} + \beta^{T} x|}{||\beta||} = \frac{1}{||\beta||}.
-
-Recall that the margin introduced in the previous section, here denoted as :math:`M`, is twice the distance to the closest examples:
-
-.. math::
- M = \frac{2}{||\beta||}
-
-Finally, the problem of maximizing :math:`M` is equivalent to the problem of minimizing a function :math:`L(\beta)` subject to some constraints. The constraints model the requirement for the hyperplane to classify correctly all the training examples :math:`x_{i}`. Formally,
-
-.. math::
- \min_{\beta, \beta_{0}} L(\beta) = \frac{1}{2}||\beta||^{2} \text{ subject to } y_{i}(\beta^{T} x_{i} + \beta_{0}) \geq 1 \text{ } \forall i,
-
-where :math:`y_{i}` represents each of the labels of the training examples.
-
-This is a problem of Lagrangian optimization that can be solved using Lagrange multipliers to obtain the weight vector :math:`\beta` and the bias :math:`\beta_{0}` of the optimal hyperplane.
-
-Source Code
-===========
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/ml/introduction_to_svm/introduction_to_svm.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
-
-Explanation
-===========
-
-1. **Set up the training data**
-
- The training data of this exercise is formed by a set of labeled 2D-points that belong to one of two different classes; one of the classes consists of one point and the other of three points.
-
- .. code-block:: cpp
-
- float labels[4] = {1.0, -1.0, -1.0, -1.0};
- float trainingData[4][2] = {{501, 10}, {255, 10}, {501, 255}, {10, 501}};
-
- The function :svms:`CvSVM::train <cvsvm-train>` that will be used afterwards requires the training data to be stored as :basicstructures:`Mat <mat>` objects of floats. Therefore, we create these objects from the arrays defined above:
-
- .. code-block:: cpp
-
- Mat trainingDataMat(4, 2, CV_32FC1, trainingData);
- Mat labelsMat (4, 1, CV_32FC1, labels);
-
-2. **Set up SVM's parameters**
-
- In this tutorial we have introduced the theory of SVMs in the most simple case, when the training examples are spread into two classes that are linearly separable. However, SVMs can be used in a wide variety of problems (e.g. problems with non-linearly separable data, a SVM using a kernel function to raise the dimensionality of the examples, etc). As a consequence of this, we have to define some parameters before training the SVM. These parameters are stored in an object of the class :svms:`CvSVMParams <cvsvmparams>` .
-
- .. code-block:: cpp
-
- ml::SVM::Params params;
- params.svmType = ml::SVM::C_SVC;
- params.kernelType = ml::SVM::LINEAR;
- params.termCrit = TermCriteria(TermCriteria::MAX_ITER, 100, 1e-6);
-
- * *Type of SVM*. We choose here the type **ml::SVM::C_SVC** that can be used for n-class classification (n :math:`\geq` 2). This parameter is defined in the attribute *ml::SVM::Params.svmType*.
-
- .. note:: The important feature of the type of SVM **CvSVM::C_SVC** deals with imperfect separation of classes (i.e. when the training data is non-linearly separable). This feature is not important here since the data is linearly separable and we chose this SVM type only for being the most commonly used.
-
- * *Type of SVM kernel*. We have not talked about kernel functions since they are not interesting for the training data we are dealing with. Nevertheless, let's explain briefly now the main idea behind a kernel function. It is a mapping done to the training data to improve its resemblance to a linearly separable set of data. This mapping consists of increasing the dimensionality of the data and is done efficiently using a kernel function. We choose here the type **ml::SVM::LINEAR** which means that no mapping is done. This parameter is defined in the attribute *ml::SVMParams.kernel_type*.
-
- * *Termination criteria of the algorithm*. The SVM training procedure is implemented solving a constrained quadratic optimization problem in an **iterative** fashion. Here we specify a maximum number of iterations and a tolerance error so we allow the algorithm to finish in less number of steps even if the optimal hyperplane has not been computed yet. This parameter is defined in a structure :oldbasicstructures:`cvTermCriteria <cvtermcriteria>`.
-
-3. **Train the SVM**
-
- We call the method `CvSVM::train <http://docs.opencv.org/modules/ml/doc/support_vector_machines.html#cvsvm-train>`_ to build the SVM model.
-
- .. code-block:: cpp
-
- CvSVM SVM;
- SVM.train(trainingDataMat, labelsMat, Mat(), Mat(), params);
-
-4. **Regions classified by the SVM**
-
- The method :svms:`CvSVM::predict <cvsvm-predict>` is used to classify an input sample using a trained SVM. In this example we have used this method in order to color the space depending on the prediction done by the SVM. In other words, an image is traversed interpreting its pixels as points of the Cartesian plane. Each of the points is colored depending on the class predicted by the SVM; in green if it is the class with label 1 and in blue if it is the class with label -1.
-
- .. code-block:: cpp
-
- Vec3b green(0,255,0), blue (255,0,0);
-
- for (int i = 0; i < image.rows; ++i)
- for (int j = 0; j < image.cols; ++j)
- {
- Mat sampleMat = (Mat_<float>(1,2) << i,j);
- float response = SVM.predict(sampleMat);
-
- if (response == 1)
- image.at<Vec3b>(j, i) = green;
- else
- if (response == -1)
- image.at<Vec3b>(j, i) = blue;
- }
-
-5. **Support vectors**
-
- We use here a couple of methods to obtain information about the support vectors. The method :svms:`CvSVM::get_support_vector_count <cvsvm-get-support-vector>` outputs the total number of support vectors used in the problem and with the method :svms:`CvSVM::get_support_vector <cvsvm-get-support-vector>` we obtain each of the support vectors using an index. We have used this methods here to find the training examples that are support vectors and highlight them.
-
- .. code-block:: cpp
-
- int c = SVM.get_support_vector_count();
-
- for (int i = 0; i < c; ++i)
- {
- const float* v = SVM.get_support_vector(i); // get and then highlight with grayscale
- circle( image, Point( (int) v[0], (int) v[1]), 6, Scalar(128, 128, 128), thickness, lineType);
- }
-
-Results
-=======
-
-.. container:: enumeratevisibleitemswithsquare
-
- * The code opens an image and shows the training examples of both classes. The points of one class are represented with white circles and black ones are used for the other class.
-
- * The SVM is trained and used to classify all the pixels of the image. This results in a division of the image in a blue region and a green region. The boundary between both regions is the optimal separating hyperplane.
-
- * Finally the support vectors are shown using gray rings around the training examples.
-
-.. image:: images/svm_intro_result.png
- :alt: The seperated planes
- :align: center
+++ /dev/null
-.. _nonLinearSvmS:
-
-Support Vector Machines for Non-Linearly Separable Data
-*******************************************************
-
-Goal
-====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- + Define the optimization problem for SVMs when it is not possible to separate linearly the training data.
-
- + How to configure the parameters in :svms:`CvSVMParams <cvsvmparams>` to adapt your SVM for this class of problems.
-
-Motivation
-==========
-
-Why is it interesting to extend the SVM optimation problem in order to handle non-linearly separable training data? Most of the applications in which SVMs are used in computer vision require a more powerful tool than a simple linear classifier. This stems from the fact that in these tasks **the training data can be rarely separated using an hyperplane**.
-
-Consider one of these tasks, for example, face detection. The training data in this case is composed by a set of images that are faces and another set of images that are non-faces (*every other thing in the world except from faces*). This training data is too complex so as to find a representation of each sample (*feature vector*) that could make the whole set of faces linearly separable from the whole set of non-faces.
-
-Extension of the Optimization Problem
-=====================================
-
-Remember that using SVMs we obtain a separating hyperplane. Therefore, since the training data is now non-linearly separable, we must admit that the hyperplane found will misclassify some of the samples. This *misclassification* is a new variable in the optimization that must be taken into account. The new model has to include both the old requirement of finding the hyperplane that gives the biggest margin and the new one of generalizing the training data correctly by not allowing too many classification errors.
-
-We start here from the formulation of the optimization problem of finding the hyperplane which maximizes the **margin** (this is explained in the :ref:`previous tutorial <introductiontosvms>`):
-
-.. math::
- \min_{\beta, \beta_{0}} L(\beta) = \frac{1}{2}||\beta||^{2} \text{ subject to } y_{i}(\beta^{T} x_{i} + \beta_{0}) \geq 1 \text{ } \forall i
-
-There are multiple ways in which this model can be modified so it takes into account the misclassification errors. For example, one could think of minimizing the same quantity plus a constant times the number of misclassification errors in the training data, i.e.:
-
-.. math::
- \min ||\beta||^{2} + C \text{(\# misclassication errors)}
-
-However, this one is not a very good solution since, among some other reasons, we do not distinguish between samples that are misclassified with a small distance to their appropriate decision region or samples that are not. Therefore, a better solution will take into account the *distance of the misclassified samples to their correct decision regions*, i.e.:
-
-.. math::
- \min ||\beta||^{2} + C \text{(distance of misclassified samples to their correct regions)}
-
-For each sample of the training data a new parameter :math:`\xi_{i}` is defined. Each one of these parameters contains the distance from its corresponding training sample to their correct decision region. The following picture shows non-linearly separable training data from two classes, a separating hyperplane and the distances to their correct regions of the samples that are misclassified.
-
-.. image:: images/sample-errors-dist.png
- :alt: Samples misclassified and their distances to their correct regions
- :align: center
-
-.. note:: Only the distances of the samples that are misclassified are shown in the picture. The distances of the rest of the samples are zero since they lay already in their correct decision region.
-
-The red and blue lines that appear on the picture are the margins to each one of the decision regions. It is very **important** to realize that each of the :math:`\xi_{i}` goes from a misclassified training sample to the margin of its appropriate region.
-
-Finally, the new formulation for the optimization problem is:
-
-.. math::
- \min_{\beta, \beta_{0}} L(\beta) = ||\beta||^{2} + C \sum_{i} {\xi_{i}} \text{ subject to } y_{i}(\beta^{T} x_{i} + \beta_{0}) \geq 1 - \xi_{i} \text{ and } \xi_{i} \geq 0 \text{ } \forall i
-
-How should the parameter C be chosen? It is obvious that the answer to this question depends on how the training data is distributed. Although there is no general answer, it is useful to take into account these rules:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Large values of C give solutions with *less misclassification errors* but a *smaller margin*. Consider that in this case it is expensive to make misclassification errors. Since the aim of the optimization is to minimize the argument, few misclassifications errors are allowed.
-
- * Small values of C give solutions with *bigger margin* and *more classification errors*. In this case the minimization does not consider that much the term of the sum so it focuses more on finding a hyperplane with big margin.
-
-Source Code
-===========
-
-You may also find the source code and these video file in the :file:`samples/cpp/tutorial_code/gpu/non_linear_svms/non_linear_svms` folder of the OpenCV source library or :download:`download it from here <../../../../samples/cpp/tutorial_code/ml/non_linear_svms/non_linear_svms.cpp>`.
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/ml/non_linear_svms/non_linear_svms.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
- :lines: 1-12, 23-24, 27-
-
-Explanation
-===========
-
-1. **Set up the training data**
-
- The training data of this exercise is formed by a set of labeled 2D-points that belong to one of two different classes. To make the exercise more appealing, the training data is generated randomly using a uniform probability density functions (PDFs).
-
- We have divided the generation of the training data into two main parts.
-
- In the first part we generate data for both classes that is linearly separable.
-
- .. code-block:: cpp
-
- // Generate random points for the class 1
- Mat trainClass = trainData.rowRange(0, nLinearSamples);
- // The x coordinate of the points is in [0, 0.4)
- Mat c = trainClass.colRange(0, 1);
- rng.fill(c, RNG::UNIFORM, Scalar(1), Scalar(0.4 * WIDTH));
- // The y coordinate of the points is in [0, 1)
- c = trainClass.colRange(1,2);
- rng.fill(c, RNG::UNIFORM, Scalar(1), Scalar(HEIGHT));
-
- // Generate random points for the class 2
- trainClass = trainData.rowRange(2*NTRAINING_SAMPLES-nLinearSamples, 2*NTRAINING_SAMPLES);
- // The x coordinate of the points is in [0.6, 1]
- c = trainClass.colRange(0 , 1);
- rng.fill(c, RNG::UNIFORM, Scalar(0.6*WIDTH), Scalar(WIDTH));
- // The y coordinate of the points is in [0, 1)
- c = trainClass.colRange(1,2);
- rng.fill(c, RNG::UNIFORM, Scalar(1), Scalar(HEIGHT));
-
- In the second part we create data for both classes that is non-linearly separable, data that overlaps.
-
- .. code-block:: cpp
-
- // Generate random points for the classes 1 and 2
- trainClass = trainData.rowRange( nLinearSamples, 2*NTRAINING_SAMPLES-nLinearSamples);
- // The x coordinate of the points is in [0.4, 0.6)
- c = trainClass.colRange(0,1);
- rng.fill(c, RNG::UNIFORM, Scalar(0.4*WIDTH), Scalar(0.6*WIDTH));
- // The y coordinate of the points is in [0, 1)
- c = trainClass.colRange(1,2);
- rng.fill(c, RNG::UNIFORM, Scalar(1), Scalar(HEIGHT));
-
-2. **Set up SVM's parameters**
-
- .. seealso::
-
- In the previous tutorial :ref:`introductiontosvms` there is an explanation of the atributes of the class :svms:`CvSVMParams <cvsvmparams>` that we configure here before training the SVM.
-
- .. code-block:: cpp
-
- CvSVMParams params;
- params.svm_type = SVM::C_SVC;
- params.C = 0.1;
- params.kernel_type = SVM::LINEAR;
- params.term_crit = TermCriteria(TermCriteria::ITER, (int)1e7, 1e-6);
-
- There are just two differences between the configuration we do here and the one that was done in the :ref:`previous tutorial <introductiontosvms>` that we use as reference.
-
- * *CvSVM::C_SVC*. We chose here a small value of this parameter in order not to punish too much the misclassification errors in the optimization. The idea of doing this stems from the will of obtaining a solution close to the one intuitively expected. However, we recommend to get a better insight of the problem by making adjustments to this parameter.
-
- .. note:: Here there are just very few points in the overlapping region between classes, giving a smaller value to **FRAC_LINEAR_SEP** the density of points can be incremented and the impact of the parameter **CvSVM::C_SVC** explored deeply.
-
- * *Termination Criteria of the algorithm*. The maximum number of iterations has to be increased considerably in order to solve correctly a problem with non-linearly separable training data. In particular, we have increased in five orders of magnitude this value.
-
-3. **Train the SVM**
-
- We call the method :svms:`CvSVM::train <cvsvm-train>` to build the SVM model. Watch out that the training process may take a quite long time. Have patiance when your run the program.
-
- .. code-block:: cpp
-
- CvSVM svm;
- svm.train(trainData, labels, Mat(), Mat(), params);
-
-4. **Show the Decision Regions**
-
- The method :svms:`CvSVM::predict <cvsvm-predict>` is used to classify an input sample using a trained SVM. In this example we have used this method in order to color the space depending on the prediction done by the SVM. In other words, an image is traversed interpreting its pixels as points of the Cartesian plane. Each of the points is colored depending on the class predicted by the SVM; in dark green if it is the class with label 1 and in dark blue if it is the class with label 2.
-
- .. code-block:: cpp
-
- Vec3b green(0,100,0), blue (100,0,0);
- for (int i = 0; i < I.rows; ++i)
- for (int j = 0; j < I.cols; ++j)
- {
- Mat sampleMat = (Mat_<float>(1,2) << i, j);
- float response = svm.predict(sampleMat);
-
- if (response == 1) I.at<Vec3b>(j, i) = green;
- else if (response == 2) I.at<Vec3b>(j, i) = blue;
- }
-
-5. **Show the training data**
-
- The method :drawingFunc:`circle <circle>` is used to show the samples that compose the training data. The samples of the class labeled with 1 are shown in light green and in light blue the samples of the class labeled with 2.
-
- .. code-block:: cpp
-
- int thick = -1;
- int lineType = 8;
- float px, py;
- // Class 1
- for (int i = 0; i < NTRAINING_SAMPLES; ++i)
- {
- px = trainData.at<float>(i,0);
- py = trainData.at<float>(i,1);
- circle(I, Point( (int) px, (int) py ), 3, Scalar(0, 255, 0), thick, lineType);
- }
- // Class 2
- for (int i = NTRAINING_SAMPLES; i <2*NTRAINING_SAMPLES; ++i)
- {
- px = trainData.at<float>(i,0);
- py = trainData.at<float>(i,1);
- circle(I, Point( (int) px, (int) py ), 3, Scalar(255, 0, 0), thick, lineType);
- }
-
-6. **Support vectors**
-
- We use here a couple of methods to obtain information about the support vectors. The method :svms:`CvSVM::get_support_vector_count <cvsvm-get-support-vector>` outputs the total number of support vectors used in the problem and with the method :svms:`CvSVM::get_support_vector <cvsvm-get-support-vector>` we obtain each of the support vectors using an index. We have used this methods here to find the training examples that are support vectors and highlight them.
-
- .. code-block:: cpp
-
- thick = 2;
- lineType = 8;
- int x = svm.get_support_vector_count();
-
- for (int i = 0; i < x; ++i)
- {
- const float* v = svm.get_support_vector(i);
- circle( I, Point( (int) v[0], (int) v[1]), 6, Scalar(128, 128, 128), thick, lineType);
- }
-
-Results
-========
-
-.. container:: enumeratevisibleitemswithsquare
-
- * The code opens an image and shows the training examples of both classes. The points of one class are represented with light green and light blue ones are used for the other class.
-
- * The SVM is trained and used to classify all the pixels of the image. This results in a division of the image in a blue region and a green region. The boundary between both regions is the separating hyperplane. Since the training data is non-linearly separable, it can be seen that some of the examples of both classes are misclassified; some green points lay on the blue region and some blue points lay on the green one.
-
- * Finally the support vectors are shown using gray rings around the training examples.
-
-.. image:: images/svm_non_linear_result.png
- :alt: Training data and decision regions given by the SVM
- :width: 300pt
- :align: center
-
-You may observe a runtime instance of this on the `YouTube here <https://www.youtube.com/watch?v=vFv2yPcSo-Q>`_.
-
-.. raw:: html
-
- <div align="center">
- <iframe title="Support Vector Machines for Non-Linearly Separable Data" width="560" height="349" src="http://www.youtube.com/embed/vFv2yPcSo-Q?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
- </div>
+++ /dev/null
-.. _Table-Of-Content-Ml:
-
-*ml* module. Machine Learning
------------------------------------------------------------
-
-Use the powerfull machine learning classes for statistical classification, regression and clustering of data.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ==============================================
- |IntroSVM| **Title:** :ref:`introductiontosvms`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_FernandoI|
-
- Learn what a Suport Vector Machine is.
-
- ============ ==============================================
-
- .. |IntroSVM| image:: images/introduction_to_svm.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ==============================================
- |NonLinSVM| **Title:** :ref:`nonLinearSvmS`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_FernandoI|
-
- Here you will learn how to define the optimization problem for SVMs when it is not possible to separate linearly the training data.
-
- ============ ==============================================
-
- .. |NonLinSVM| image:: images/non_linear_svms.png
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../introduction_to_svm/introduction_to_svm
- ../non_linear_svms/non_linear_svms
+++ /dev/null
-.. _cascade_classifier:
-
-Cascade Classifier
-*******************
-
-Goal
-=====
-
-In this tutorial you will learn how to:
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Use the :cascade_classifier:`CascadeClassifier <>` class to detect objects in a video stream. Particularly, we will use the functions:
-
- * :cascade_classifier_load:`load <>` to load a .xml classifier file. It can be either a Haar or a LBP classifer
- * :cascade_classifier_detect_multiscale:`detectMultiScale <>` to perform the detection.
-
-
-Theory
-======
-
-Code
-====
-
-This tutorial code's is shown lines below. You can also download it from `here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/objectDetection/objectDetection.cpp>`_ . The second version (using LBP for face detection) can be `found here <https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/objectDetection/objectDetection2.cpp>`_
-
-.. code-block:: cpp
-
- #include "opencv2/objdetect.hpp"
- #include "opencv2/highgui.hpp"
- #include "opencv2/imgproc.hpp"
-
- #include <iostream>
- #include <stdio.h>
-
- using namespace std;
- using namespace cv;
-
- /* Function Headers */
- void detectAndDisplay( Mat frame );
-
- /* Global variables */
- String face_cascade_name = "haarcascade_frontalface_alt.xml";
- String eyes_cascade_name = "haarcascade_eye_tree_eyeglasses.xml";
- CascadeClassifier face_cascade;
- CascadeClassifier eyes_cascade;
- String window_name = "Capture - Face detection";
-
- /* @function main */
- int main( void )
- {
- VideoCapture capture;
- Mat frame;
-
- //-- 1. Load the cascades
- if( !face_cascade.load( face_cascade_name ) ){ printf("--(!)Error loading face cascade\n"); return -1; };
- if( !eyes_cascade.load( eyes_cascade_name ) ){ printf("--(!)Error loading eyes cascade\n"); return -1; };
-
- //-- 2. Read the video stream
- capture.open( -1 );
- if ( ! capture.isOpened() ) { printf("--(!)Error opening video capture\n"); return -1; }
-
- while ( capture.read(frame) )
- {
- if( frame.empty() )
- {
- printf(" --(!) No captured frame -- Break!");
- break;
- }
-
- //-- 3. Apply the classifier to the frame
- detectAndDisplay( frame );
-
- int c = waitKey(10);
- if( (char)c == 27 ) { break; } // escape
- }
- return 0;
- }
-
- /* @function detectAndDisplay */
- void detectAndDisplay( Mat frame )
- {
- std::vector<Rect> faces;
- Mat frame_gray;
-
- cvtColor( frame, frame_gray, COLOR_BGR2GRAY );
- equalizeHist( frame_gray, frame_gray );
-
- //-- Detect faces
- face_cascade.detectMultiScale( frame_gray, faces, 1.1, 2, 0|CASCADE_SCALE_IMAGE, Size(30, 30) );
-
- for( size_t i = 0; i < faces.size(); i++ )
- {
- Point center( faces[i].x + faces[i].width/2, faces[i].y + faces[i].height/2 );
- ellipse( frame, center, Size( faces[i].width/2, faces[i].height/2), 0, 0, 360, Scalar( 255, 0, 255 ), 4, 8, 0 );
-
- Mat faceROI = frame_gray( faces[i] );
- std::vector<Rect> eyes;
-
- //-- In each face, detect eyes
- eyes_cascade.detectMultiScale( faceROI, eyes, 1.1, 2, 0 |CASCADE_SCALE_IMAGE, Size(30, 30) );
-
- for( size_t j = 0; j < eyes.size(); j++ )
- {
- Point eye_center( faces[i].x + eyes[j].x + eyes[j].width/2, faces[i].y + eyes[j].y + eyes[j].height/2 );
- int radius = cvRound( (eyes[j].width + eyes[j].height)*0.25 );
- circle( frame, eye_center, radius, Scalar( 255, 0, 0 ), 4, 8, 0 );
- }
- }
- //-- Show what you got
- imshow( window_name, frame );
- }
-
-Explanation
-============
-
-Result
-======
-
-#. Here is the result of running the code above and using as input the video stream of a build-in webcam:
-
- .. image:: images/Cascade_Classifier_Tutorial_Result_Haar.jpg
- :align: center
- :height: 300pt
-
- Remember to copy the files *haarcascade_frontalface_alt.xml* and *haarcascade_eye_tree_eyeglasses.xml* in your current directory. They are located in *opencv/data/haarcascades*
-
-#. This is the result of using the file *lbpcascade_frontalface.xml* (LBP trained) for the face detection. For the eyes we keep using the file used in the tutorial.
-
- .. image:: images/Cascade_Classifier_Tutorial_Result_LBP.jpg
- :align: center
- :height: 300pt
+++ /dev/null
-.. _Table-Of-Content-ObjDetect:
-
-*objdetect* module. Object Detection
------------------------------------------------------------
-
-Ever wondered how your digital camera detects peoples and faces? Look here to find out!
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ===================== ==============================================
- |CascadeClassif| **Title:** :ref:`cascade_classifier`
-
- *Compatibility:* > OpenCV 2.0
-
- *Author:* |Author_AnaH|
-
- Here we learn how to use *objdetect* to find objects in our images or videos
-
- ===================== ==============================================
-
- .. |CascadeClassif| image:: images/Cascade_Classifier_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../cascade_classifier/cascade_classifier
+++ /dev/null
-.. _hdrimaging:
-
-High Dynamic Range Imaging
-***************************************
-
-Introduction
-------------------
-Today most digital images and imaging devices use 8 bits per channel thus limiting the dynamic range of the device to two orders of magnitude (actually 256 levels), while human eye can adapt to lighting conditions varying by ten orders of magnitude. When we take photographs of a real world scene bright regions may be overexposed, while the dark ones may be underexposed, so we can’t capture all details using a single exposure. HDR imaging works with images that use more that 8 bits per channel (usually 32-bit float values), allowing much wider dynamic range.
-
-There are different ways to obtain HDR images, but the most common one is to use photographs of the scene taken with different exposure values. To combine this exposures it is useful to know your camera’s response function and there are algorithms to estimate it. After the HDR image has been blended it has to be converted back to 8-bit to view it on usual displays. This process is called tonemapping. Additional complexities arise when objects of the scene or camera move between shots, since images with different exposures should be registered and aligned.
-
-In this tutorial we show how to generate and display HDR image from an exposure sequence. In our case images are already aligned and there are no moving objects. We also demonstrate an alternative approach called exposure fusion that produces low dynamic range image. Each step of HDR pipeline can be implemented using different algorithms so take a look at the reference manual to see them all.
-
-Exposure sequence
-------------------
-
-.. image:: images/memorial.png
- :height: 357pt
- :width: 242pt
- :alt: Exposure sequence
- :align: center
-
-Source Code
-===========
-
-.. literalinclude:: ../../../../samples/cpp/tutorial_code/photo/hdr_imaging/hdr_imaging.cpp
- :language: cpp
- :linenos:
- :tab-width: 4
-
-Explanation
-===========
-
-1. **Load images and exposure times**
-
- .. code-block:: cpp
-
- vector<Mat> images;
- vector<float> times;
- loadExposureSeq(argv[1], images, times);
-
- Firstly we load input images and exposure times from user-defined folder. The folder should contain images and *list.txt* - file that contains file names and inverse exposure times.
-
- For our image sequence the list is following:
-
- .. code-block:: none
-
- memorial00.png 0.03125
- memorial01.png 0.0625
- ...
- memorial15.png 1024
-
-2. **Estimate camera response**
-
- .. code-block:: cpp
-
- Mat response;
- Ptr<CalibrateDebevec> calibrate = createCalibrateDebevec();
- calibrate->process(images, response, times);
-
- It is necessary to know camera response function (CRF) for a lot of HDR construction algorithms. We use one of the calibration algorithms to estimate inverse CRF for all 256 pixel values.
-
-3. **Make HDR image**
-
- .. code-block:: cpp
-
- Mat hdr;
- Ptr<MergeDebevec> merge_debevec = createMergeDebevec();
- merge_debevec->process(images, hdr, times, response);
-
- We use Debevec's weighting scheme to construct HDR image using response calculated in the previous item.
-
-4. **Tonemap HDR image**
-
- .. code-block:: cpp
-
- Mat ldr;
- Ptr<TonemapDurand> tonemap = createTonemapDurand(2.2f);
- tonemap->process(hdr, ldr);
-
- Since we want to see our results on common LDR display we have to map our HDR image to 8-bit range preserving most details. It is the main goal of tonemapping methods. We use tonemapper with bilateral filtering and set 2.2 as the value for gamma correction.
-
-5. **Perform exposure fusion**
-
- .. code-block:: cpp
-
- Mat fusion;
- Ptr<MergeMertens> merge_mertens = createMergeMertens();
- merge_mertens->process(images, fusion);
-
- There is an alternative way to merge our exposures in case when we don't need HDR image. This process is called exposure fusion and produces LDR image that doesn't require gamma correction. It also doesn't use exposure values of the photographs.
-
-6. **Write results**
-
- .. code-block:: cpp
-
- imwrite("fusion.png", fusion * 255);
- imwrite("ldr.png", ldr * 255);
- imwrite("hdr.hdr", hdr);
-
- Now it's time to look at the results. Note that HDR image can't be stored in one of common image formats, so we save it to Radiance image (.hdr). Also all HDR imaging functions return results in [0, 1] range so we should multiply result by 255.
-
-Results
-=======
-
-Tonemapped image
-------------------
-
-.. image:: images/ldr.png
- :height: 357pt
- :width: 242pt
- :alt: Tonemapped image
- :align: center
-
-Exposure fusion
-------------------
-
-.. image:: images/fusion.png
- :height: 357pt
- :width: 242pt
- :alt: Exposure fusion
- :align: center
+++ /dev/null
-.. _Table-Of-Content-Photo:
-
-*photo* module. Computational photography
------------------------------------------------------------
-
-Use OpenCV for advanced photo processing.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ============ ==============================================
- |HDR| **Title:** :ref:`hdrimaging`
-
- *Compatibility:* > OpenCV 3.0
-
- *Author:* Fedor Morozov
-
- Learn how to create and process high dynamic range images.
-
- ============ ==============================================
-
- .. |HDR| image:: images/hdr.png
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../hdr_imaging/hdr_imaging
+++ /dev/null
-################
-OpenCV Tutorials
-################
-
-The following links describe a set of basic OpenCV tutorials. All the source code mentioned here is provided as part of the OpenCV regular releases, so check before you start copy & pasting the code. The list of tutorials below is automatically generated from reST files located in our GIT repository.
-
-As always, we would be happy to hear your comments and receive your contributions on any tutorial.
-
-* :ref:`Table-Of-Content-Introduction`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Introduct| You will learn how to setup OpenCV on your computer!
-
- =========== =======================================================
-
- .. |Introduct| image:: images/introduction.jpg
- :height: 80pt
- :width: 80pt
- :alt: Introduction Icon
-
-* :ref:`Table-Of-Content-Core`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Core| Here you will learn the about the basic building blocks of the library. A must read and know for understanding how to manipulate the images on a pixel level.
-
- =========== =======================================================
-
- .. |Core| image:: images/core.jpg
- :height: 80pt
- :width: 80pt
- :alt: core Icon
-
-* :ref:`Table-Of-Content-ImgProc`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |ImgProc| In this section you will learn about the image processing (manipulation) functions inside OpenCV.
-
- =========== =======================================================
-
- .. |ImgProc| image:: images/imgproc.jpg
- :height: 80pt
- :width: 80pt
- :alt: imgproc Icon
-
-* :ref:`Table-Of-Content-HighGui`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |HighGui| This section contains valuable tutorials about how to read/save your image/video files and how to use the built-in graphical user interface of the library.
-
- =========== =======================================================
-
- .. |HighGui| image:: images/highgui.jpg
- :height: 80pt
- :width: 80pt
- :alt: highgui Icon
-
-* :ref:`Table-Of-Content-Calib3D`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Calib3D| Although we got most of our images in a 2D format they do come from a 3D world. Here you will learn how to find out from the 2D images information about the 3D world.
-
- =========== =======================================================
-
- .. |Calib3D| image:: images/calib3d.jpg
- :height: 80pt
- :width: 80pt
- :alt: calib3d Icon
-
-* :ref:`Table-Of-Content-Feature2D`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Featur2D| Learn about how to use the feature points detectors, descriptors and matching framework found inside OpenCV.
-
- =========== =======================================================
-
- .. |Featur2D| image:: images/feature2D.jpg
- :height: 80pt
- :width: 80pt
- :alt: feature2D Icon
-
-* :ref:`Table-Of-Content-Video`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Video| Look here in order to find algorithms usable on your video streams like: motion extraction, feature tracking and foreground extractions.
-
- =========== =======================================================
-
- .. |Video| image:: images/video.jpg
- :height: 80pt
- :width: 80pt
- :alt: video Icon
-
-* :ref:`Table-Of-Content-ObjDetect`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |ObjDetect| Ever wondered how your digital camera detects peoples and faces? Look here to find out!
-
- =========== =======================================================
-
- .. |ObjDetect| image:: images/objdetect.jpg
- :height: 80pt
- :width: 80pt
- :alt: objdetect Icon
-
-* :ref:`Table-Of-Content-Ml`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |ml| Use the powerful machine learning classes for statistical classification, regression and clustering of data.
-
- =========== =======================================================
-
- .. |ml| image:: images/ml.jpg
- :height: 80pt
- :width: 80pt
- :alt: ml Icon
-
-* :ref:`Table-Of-Content-Photo`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |photo| Use OpenCV for advanced photo processing.
-
- =========== =======================================================
-
- .. |photo| image:: images/photo.png
- :height: 80pt
- :width: 80pt
- :alt: photo Icon
-
-* :ref:`Table-Of-Content-GPU`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |GPU| Squeeze out every little computation power from your system by using the power of your video card to run the OpenCV algorithms.
-
- =========== =======================================================
-
- .. |GPU| image:: images/gpu.jpg
- :height: 80pt
- :width: 80pt
- :alt: gpu icon
-
-* :ref:`Table-Of-Content-iOS`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |iOS| Run OpenCV and your vision apps on an iDevice
-
- =========== =======================================================
-
- .. |iOS| image:: images/opencv_ios.png
- :height: 80pt
- :width: 80pt
- :alt: gpu icon
-
-* :ref:`Table-Of-Content-Viz`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |Viz| These tutorials show how to use Viz module effectively.
-
- =========== =======================================================
-
- .. |Viz| image:: images/viz.jpg
- :height: 80pt
- :width: 80pt
- :alt: viz icon
-
-* :ref:`Table-Of-Content-General`
-
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =========== =======================================================
- |General| These tutorials are the bottom of the iceberg as they link together multiple of the modules presented above in order to solve complex problems.
-
- =========== =======================================================
-
- .. |General| image:: images/general.jpg
- :height: 80pt
- :width: 80pt
- :alt: General Icon
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :maxdepth: 2
- :hidden:
-
- introduction/table_of_content_introduction/table_of_content_introduction
- core/table_of_content_core/table_of_content_core
- imgproc/table_of_content_imgproc/table_of_content_imgproc
- highgui/table_of_content_highgui/table_of_content_highgui
- calib3d/table_of_content_calib3d/table_of_content_calib3d
- features2d/table_of_content_features2d/table_of_content_features2d
- video/table_of_content_video/table_of_content_video
- objdetect/table_of_content_objdetect/table_of_content_objdetect
- ml/table_of_content_ml/table_of_content_ml
- photo/table_of_content_photo/table_of_content_photo
- gpu/table_of_content_gpu/table_of_content_gpu
- ios/table_of_content_ios/table_of_content_ios
- viz/table_of_content_viz/table_of_content_viz
- general/table_of_content_general/table_of_content_general
+++ /dev/null
-.. _Background_Subtraction:
-
-How to Use Background Subtraction Methods
-*****************************************
-
-* Background subtraction (BS) is a common and widely used technique for generating a foreground mask (namely, a binary image containing the pixels belonging to moving objects in the scene) by using static cameras.
-
-* As the name suggests, BS calculates the foreground mask performing a subtraction between the current frame and a background model, containing the static part of the scene or, more in general, everything that can be considered as background given the characteristics of the observed scene.
-
- .. image:: images/Background_Subtraction_Tutorial_Scheme.png
- :alt: Background Subtraction - General Scheme
- :align: center
-
-* Background modeling consists of two main steps:
-
- #. Background Initialization;
- #. Background Update.
-
- In the first step, an initial model of the background is computed, while in the second step that model is updated in order to adapt to possible changes in the scene.
-
-* In this tutorial we will learn how to perform BS by using OpenCV. As input, we will use data coming from the publicly available data set `Background Models Challenge (BMC) <http://bmc.univ-bpclermont.fr/>`_ .
-
-Goals
-======
-
-In this tutorial you will learn how to:
-
- #. Read data from videos by using :video_capture:`VideoCapture <>` or image sequences by using :imread:`imread <>`;
- #. Create and update the background model by using :background_subtractor:`BackgroundSubtractor <>` class;
- #. Get and show the foreground mask by using :imshow:`imshow <>`;
- #. Save the output by using :imwrite:`imwrite <>` to quantitatively evaluate the results.
-
-Code
-=====
-
-In the following you can find the source code. We will let the user chose to process either a video file or a sequence of images.
-
-* Two different methods are used to generate two foreground masks:
- #. :background_subtractor_mog:`MOG <>`
- #. :background_subtractor_mog_two:`MOG2 <>`
-
-The results as well as the input data are shown on the screen.
-
-.. code-block:: cpp
-
- //opencv
- #include <opencv2/highgui/highgui.hpp>
- #include <opencv2/video/background_segm.hpp>
- //C
- #include <stdio.h>
- //C++
- #include <iostream>
- #include <sstream>
-
- using namespace cv;
- using namespace std;
-
- //global variables
- Mat frame; //current frame
- Mat fgMaskMOG; //fg mask generated by MOG method
- Mat fgMaskMOG2; //fg mask fg mask generated by MOG2 method
- Ptr<BackgroundSubtractor> pMOG; //MOG Background subtractor
- Ptr<BackgroundSubtractor> pMOG2; //MOG2 Background subtractor
- int keyboard;
-
- //function declarations
- void help();
- void processVideo(char* videoFilename);
- void processImages(char* firstFrameFilename);
-
- void help()
- {
- cout
- << "--------------------------------------------------------------------------" << endl
- << "This program shows how to use background subtraction methods provided by " << endl
- << " OpenCV. You can process both videos (-vid) and images (-img)." << endl
- << endl
- << "Usage:" << endl
- << "./bs {-vid <video filename>|-img <image filename>}" << endl
- << "for example: ./bs -vid video.avi" << endl
- << "or: ./bs -img /data/images/1.png" << endl
- << "--------------------------------------------------------------------------" << endl
- << endl;
- }
-
- int main(int argc, char* argv[])
- {
- //print help information
- help();
-
- //check for the input parameter correctness
- if(argc != 3) {
- cerr <<"Incorret input list" << endl;
- cerr <<"exiting..." << endl;
- return EXIT_FAILURE;
- }
-
- //create GUI windows
- namedWindow("Frame");
- namedWindow("FG Mask MOG");
- namedWindow("FG Mask MOG 2");
-
- //create Background Subtractor objects
- pMOG = createBackgroundSubtractorMOG(); //MOG approach
- pMOG2 = createBackgroundSubtractorMOG2(); //MOG2 approach
-
- if(strcmp(argv[1], "-vid") == 0) {
- //input data coming from a video
- processVideo(argv[2]);
- }
- else if(strcmp(argv[1], "-img") == 0) {
- //input data coming from a sequence of images
- processImages(argv[2]);
- }
- else {
- //error in reading input parameters
- cerr <<"Please, check the input parameters." << endl;
- cerr <<"Exiting..." << endl;
- return EXIT_FAILURE;
- }
- //destroy GUI windows
- destroyAllWindows();
- return EXIT_SUCCESS;
- }
-
- void processVideo(char* videoFilename) {
- //create the capture object
- VideoCapture capture(videoFilename);
- if(!capture.isOpened()){
- //error in opening the video input
- cerr << "Unable to open video file: " << videoFilename << endl;
- exit(EXIT_FAILURE);
- }
- //read input data. ESC or 'q' for quitting
- while( (char)keyboard != 'q' && (char)keyboard != 27 ){
- //read the current frame
- if(!capture.read(frame)) {
- cerr << "Unable to read next frame." << endl;
- cerr << "Exiting..." << endl;
- exit(EXIT_FAILURE);
- }
- //update the background model
- pMOG->apply(frame, fgMaskMOG);
- pMOG2->apply(frame, fgMaskMOG2);
- //get the frame number and write it on the current frame
- stringstream ss;
- rectangle(frame, cv::Point(10, 2), cv::Point(100,20),
- cv::Scalar(255,255,255), -1);
- ss << capture.get(CAP_PROP_POS_FRAMES);
- string frameNumberString = ss.str();
- putText(frame, frameNumberString.c_str(), cv::Point(15, 15),
- FONT_HERSHEY_SIMPLEX, 0.5 , cv::Scalar(0,0,0));
- //show the current frame and the fg masks
- imshow("Frame", frame);
- imshow("FG Mask MOG", fgMaskMOG);
- imshow("FG Mask MOG 2", fgMaskMOG2);
- //get the input from the keyboard
- keyboard = waitKey( 30 );
- }
- //delete capture object
- capture.release();
- }
-
- void processImages(char* fistFrameFilename) {
- //read the first file of the sequence
- frame = imread(fistFrameFilename);
- if(!frame.data){
- //error in opening the first image
- cerr << "Unable to open first image frame: " << fistFrameFilename << endl;
- exit(EXIT_FAILURE);
- }
- //current image filename
- string fn(fistFrameFilename);
- //read input data. ESC or 'q' for quitting
- while( (char)keyboard != 'q' && (char)keyboard != 27 ){
- //update the background model
- pMOG->apply(frame, fgMaskMOG);
- pMOG2->apply(frame, fgMaskMOG2);
- //get the frame number and write it on the current frame
- size_t index = fn.find_last_of("/");
- if(index == string::npos) {
- index = fn.find_last_of("\\");
- }
- size_t index2 = fn.find_last_of(".");
- string prefix = fn.substr(0,index+1);
- string suffix = fn.substr(index2);
- string frameNumberString = fn.substr(index+1, index2-index-1);
- istringstream iss(frameNumberString);
- int frameNumber = 0;
- iss >> frameNumber;
- rectangle(frame, cv::Point(10, 2), cv::Point(100,20),
- cv::Scalar(255,255,255), -1);
- putText(frame, frameNumberString.c_str(), cv::Point(15, 15),
- FONT_HERSHEY_SIMPLEX, 0.5 , cv::Scalar(0,0,0));
- //show the current frame and the fg masks
- imshow("Frame", frame);
- imshow("FG Mask MOG", fgMaskMOG);
- imshow("FG Mask MOG 2", fgMaskMOG2);
- //get the input from the keyboard
- keyboard = waitKey( 30 );
- //search for the next image in the sequence
- ostringstream oss;
- oss << (frameNumber + 1);
- string nextFrameNumberString = oss.str();
- string nextFrameFilename = prefix + nextFrameNumberString + suffix;
- //read the next frame
- frame = imread(nextFrameFilename);
- if(!frame.data){
- //error in opening the next image in the sequence
- cerr << "Unable to open image frame: " << nextFrameFilename << endl;
- exit(EXIT_FAILURE);
- }
- //update the path of the current frame
- fn.assign(nextFrameFilename);
- }
- }
-
-* The source file can be downloaded :download:`here <../../../../samples/cpp/tutorial_code/video/bg_sub.cpp>`.
-
-
-Explanation
-============
-
-We discuss the main parts of the above code:
-
-#. First, three Mat objects are allocated to store the current frame and two foreground masks, obtained by using two different BS algorithms.
-
- .. code-block:: cpp
-
- Mat frame; //current frame
- Mat fgMaskMOG; //fg mask generated by MOG method
- Mat fgMaskMOG2; //fg mask fg mask generated by MOG2 method
-
-#. Two :background_subtractor:`BackgroundSubtractor <>` objects will be used to generate the foreground masks. In this example, default parameters are used, but it is also possible to declare specific parameters in the create function.
-
- .. code-block:: cpp
-
- Ptr<BackgroundSubtractor> pMOG; //MOG Background subtractor
- Ptr<BackgroundSubtractor> pMOG2; //MOG2 Background subtractor
- ...
- //create Background Subtractor objects
- pMOG = createBackgroundSubtractorMOG(); //MOG approach
- pMOG2 = createBackgroundSubtractorMOG2(); //MOG2 approach
-
-#. The command line arguments are analysed. The user can chose between two options:
-
- * video files (by choosing the option -vid);
- * image sequences (by choosing the option -img).
-
- .. code-block:: cpp
-
- if(strcmp(argv[1], "-vid") == 0) {
- //input data coming from a video
- processVideo(argv[2]);
- }
- else if(strcmp(argv[1], "-img") == 0) {
- //input data coming from a sequence of images
- processImages(argv[2]);
- }
-
-#. Suppose you want to process a video file. The video is read until the end is reached or the user presses the button 'q' or the button 'ESC'.
-
- .. code-block:: cpp
-
- while( (char)keyboard != 'q' && (char)keyboard != 27 ){
- //read the current frame
- if(!capture.read(frame)) {
- cerr << "Unable to read next frame." << endl;
- cerr << "Exiting..." << endl;
- exit(EXIT_FAILURE);
- }
-
-#. Every frame is used both for calculating the foreground mask and for updating the background. If you want to change the learning rate used for updating the background model, it is possible to set a specific learning rate by passing a third parameter to the 'apply' method.
-
- .. code-block:: cpp
-
- //update the background model
- pMOG->apply(frame, fgMaskMOG);
- pMOG2->apply(frame, fgMaskMOG2);
-
-#. The current frame number can be extracted from the :video_capture:`VideoCapture <>` object and stamped in the top left corner of the current frame. A white rectangle is used to highlight the black colored frame number.
-
- .. code-block:: cpp
-
- //get the frame number and write it on the current frame
- stringstream ss;
- rectangle(frame, cv::Point(10, 2), cv::Point(100,20),
- cv::Scalar(255,255,255), -1);
- ss << capture.get(CAP_PROP_POS_FRAMES);
- string frameNumberString = ss.str();
- putText(frame, frameNumberString.c_str(), cv::Point(15, 15),
- FONT_HERSHEY_SIMPLEX, 0.5 , cv::Scalar(0,0,0));
-
-#. We are ready to show the current input frame and the results.
-
- .. code-block:: cpp
-
- //show the current frame and the fg masks
- imshow("Frame", frame);
- imshow("FG Mask MOG", fgMaskMOG);
- imshow("FG Mask MOG 2", fgMaskMOG2);
-
-#. The same operations listed above can be performed using a sequence of images as input. The processImage function is called and, instead of using a :video_capture:`VideoCapture <>` object, the images are read by using :imread:`imread <>`, after individuating the correct path for the next frame to read.
-
- .. code-block:: cpp
-
- //read the first file of the sequence
- frame = imread(fistFrameFilename);
- if(!frame.data){
- //error in opening the first image
- cerr << "Unable to open first image frame: " << fistFrameFilename << endl;
- exit(EXIT_FAILURE);
- }
- ...
- //search for the next image in the sequence
- ostringstream oss;
- oss << (frameNumber + 1);
- string nextFrameNumberString = oss.str();
- string nextFrameFilename = prefix + nextFrameNumberString + suffix;
- //read the next frame
- frame = imread(nextFrameFilename);
- if(!frame.data){
- //error in opening the next image in the sequence
- cerr << "Unable to open image frame: " << nextFrameFilename << endl;
- exit(EXIT_FAILURE);
- }
- //update the path of the current frame
- fn.assign(nextFrameFilename);
-
- Note that this example works only on image sequences in which the filename format is <n>.png, where n is the frame number (e.g., 7.png).
-
-Results
-=======
-
-* Given the following input parameters:
-
- .. code-block:: cpp
-
- -vid Video_001.avi
-
- The output of the program will look as the following:
-
- .. image:: images/Background_Subtraction_Tutorial_Result_1.png
- :alt: Background Subtraction - Video File
- :align: center
-
-* The video file Video_001.avi is part of the `Background Models Challenge (BMC) <http://bmc.univ-bpclermont.fr/>`_ data set and it can be downloaded from the following link `Video_001 <http://bmc.univ-bpclermont.fr/sites/default/files/videos/evaluation/Video_001.zip>`_ (about 32 MB).
-
-* If you want to process a sequence of images, then the '-img' option has to be chosen:
-
- .. code-block:: cpp
-
- -img 111_png/input/1.png
-
- The output of the program will look as the following:
-
- .. image:: images/Background_Subtraction_Tutorial_Result_2.png
- :alt: Background Subtraction - Image Sequence
- :align: center
-
-* The sequence of images used in this example is part of the `Background Models Challenge (BMC) <http://bmc.univ-bpclermont.fr/>`_ dataset and it can be downloaded from the following link `sequence 111 <http://bmc.univ-bpclermont.fr/sites/default/files/videos/learning/111_png.zip>`_ (about 708 MB). Please, note that this example works only on sequences in which the filename format is <n>.png, where n is the frame number (e.g., 7.png).
-
-Evaluation
-==========
-
-To quantitatively evaluate the results obtained, we need to:
-
-* Save the output images;
-* Have the ground truth images for the chosen sequence.
-
-In order to save the output images, we can use :imwrite:`imwrite <>`. Adding the following code allows for saving the foreground masks.
-
- .. code-block:: cpp
-
- string imageToSave = "output_MOG_" + frameNumberString + ".png";
- bool saved = imwrite(imageToSave, fgMaskMOG);
- if(!saved) {
- cerr << "Unable to save " << imageToSave << endl;
- }
-
-Once we have collected the result images, we can compare them with the ground truth data. There exist several publicly available sequences for background subtraction that come with ground truth data. If you decide to use the `Background Models Challenge (BMC) <http://bmc.univ-bpclermont.fr/>`_, then the result images can be used as input for the `BMC Wizard <http://bmc.univ-bpclermont.fr/?q=node/7>`_. The wizard can compute different measures about the accuracy of the results.
-
-References
-==========
-
-* Background Models Challenge (BMC) website, `<http://bmc.univ-bpclermont.fr/>`_
-
-* Antoine Vacavant, Thierry Chateau, Alexis Wilhelm and Laurent Lequievre. A Benchmark Dataset for Foreground/Background Extraction. In ACCV 2012, Workshop: Background Models Challenge, LNCS 7728, 291-300. November 2012, Daejeon, Korea.
+++ /dev/null
-.. _Table-Of-Content-Video:
-
-*video* module. Video analysis
------------------------------------------------------------
-
-Look here in order to find use on your video stream algorithms like: motion extraction, feature tracking and foreground extractions.
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- =============== ======================================================
- |BgSub| **Title:** :ref:`Background_Subtraction`
-
- *Compatibility:* > OpenCV 2.4.6
-
- *Author:* |Author_DomenicoB|
-
- We will learn how to extract foreground masks from both videos and sequences of images and to show them.
-
- =============== ======================================================
-
- .. |BgSub| image:: images/Background_Subtraction_Tutorial_Cover.jpg
- :height: 90pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../background_subtraction/background_subtraction
+++ /dev/null
-.. _creating_widgets:
-
-Creating Widgets
-****************
-
-Goal
-====
-
-In this tutorial you will learn how to
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Create your own widgets using WidgetAccessor and VTK.
- * Show your widget in the visualization window.
-
-Code
-====
-
-You can download the code from :download:`here <../../../../samples/cpp/tutorial_code/viz/creating_widgets.cpp>`.
-
-.. code-block:: cpp
-
- #include <opencv2/viz.hpp>
- #include <opencv2/viz/widget_accessor.hpp>
- #include <iostream>
-
- #include <vtkPoints.h>
- #include <vtkTriangle.h>
- #include <vtkCellArray.h>
- #include <vtkPolyData.h>
- #include <vtkPolyDataMapper.h>
- #include <vtkIdList.h>
- #include <vtkActor.h>
- #include <vtkProp.h>
-
- using namespace cv;
- using namespace std;
-
- /*
- * @class WTriangle
- * @brief Defining our own 3D Triangle widget
- */
- class WTriangle : public viz::Widget3D
- {
- public:
- WTriangle(const Point3f &pt1, const Point3f &pt2, const Point3f &pt3, const viz::Color & color = viz::Color::white());
- };
-
- /*
- * @function WTriangle::WTriangle
- */
- WTriangle::WTriangle(const Point3f &pt1, const Point3f &pt2, const Point3f &pt3, const viz::Color & color)
- {
- // Create a triangle
- vtkSmartPointer<vtkPoints> points = vtkSmartPointer<vtkPoints>::New();
- points->InsertNextPoint(pt1.x, pt1.y, pt1.z);
- points->InsertNextPoint(pt2.x, pt2.y, pt2.z);
- points->InsertNextPoint(pt3.x, pt3.y, pt3.z);
-
- vtkSmartPointer<vtkTriangle> triangle = vtkSmartPointer<vtkTriangle>::New();
- triangle->GetPointIds()->SetId(0,0);
- triangle->GetPointIds()->SetId(1,1);
- triangle->GetPointIds()->SetId(2,2);
-
- vtkSmartPointer<vtkCellArray> cells = vtkSmartPointer<vtkCellArray>::New();
- cells->InsertNextCell(triangle);
-
- // Create a polydata object
- vtkSmartPointer<vtkPolyData> polyData = vtkSmartPointer<vtkPolyData>::New();
-
- // Add the geometry and topology to the polydata
- polyData->SetPoints(points);
- polyData->SetPolys(cells);
-
- // Create mapper and actor
- vtkSmartPointer<vtkPolyDataMapper> mapper = vtkSmartPointer<vtkPolyDataMapper>::New();
- #if VTK_MAJOR_VERSION <= 5
- mapper->SetInput(polyData);
- #else
- mapper->SetInputData(polyData);
- #endif
-
- vtkSmartPointer<vtkActor> actor = vtkSmartPointer<vtkActor>::New();
- actor->SetMapper(mapper);
-
- // Store this actor in the widget in order that visualizer can access it
- viz::WidgetAccessor::setProp(*this, actor);
-
- // Set the color of the widget. This has to be called after WidgetAccessor.
- setColor(color);
- }
-
- /*
- * @function main
- */
- int main()
- {
- /// Create a window
- viz::Viz3d myWindow("Creating Widgets");
-
- /// Create a triangle widget
- WTriangle tw(Point3f(0.0,0.0,0.0), Point3f(1.0,1.0,1.0), Point3f(0.0,1.0,0.0), viz::Color::red());
-
- /// Show widget in the visualizer window
- myWindow.showWidget("TRIANGLE", tw);
-
- /// Start event loop
- myWindow.spin();
-
- return 0;
- }
-
-Explanation
-===========
-
-Here is the general structure of the program:
-
-* Extend Widget3D class to create a new 3D widget.
-
-.. code-block:: cpp
-
- class WTriangle : public viz::Widget3D
- {
- public:
- WTriangle(const Point3f &pt1, const Point3f &pt2, const Point3f &pt3, const viz::Color & color = viz::Color::white());
- };
-
-* Assign a VTK actor to the widget.
-
-.. code-block:: cpp
-
- // Store this actor in the widget in order that visualizer can access it
- viz::WidgetAccessor::setProp(*this, actor);
-
-* Set color of the widget.
-
-.. code-block:: cpp
-
- // Set the color of the widget. This has to be called after WidgetAccessor.
- setColor(color);
-
-* Construct a triangle widget and display it in the window.
-
-.. code-block:: cpp
-
- /// Create a triangle widget
- WTriangle tw(Point3f(0.0,0.0,0.0), Point3f(1.0,1.0,1.0), Point3f(0.0,1.0,0.0), viz::Color::red());
-
- /// Show widget in the visualizer window
- myWindow.showWidget("TRIANGLE", tw);
-
-Results
-=======
-
-Here is the result of the program.
-
-.. image:: images/red_triangle.png
- :alt: Creating Widgets
- :align: center
+++ /dev/null
-.. _launching_viz:
-
-Launching Viz
-*************
-
-Goal
-====
-
-In this tutorial you will learn how to
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Open a visualization window.
- * Access a window by its name.
- * Start event loop.
- * Start event loop for a given amount of time.
-
-Code
-====
-
-You can download the code from :download:`here <../../../../samples/cpp/tutorial_code/viz/launching_viz.cpp>`.
-
-.. code-block:: cpp
-
- #include <opencv2/viz.hpp>
- #include <iostream>
-
- using namespace cv;
- using namespace std;
-
- /*
- * @function main
- */
- int main()
- {
- /// Create a window
- viz::Viz3d myWindow("Viz Demo");
-
- /// Start event loop
- myWindow.spin();
-
- /// Event loop is over when pressed q, Q, e, E
- cout << "First event loop is over" << endl;
-
- /// Access window via its name
- viz::Viz3d sameWindow = viz::getWindowByName("Viz Demo");
-
- /// Start event loop
- sameWindow.spin();
-
- /// Event loop is over when pressed q, Q, e, E
- cout << "Second event loop is over" << endl;
-
- /// Event loop is over when pressed q, Q, e, E
- /// Start event loop once for 1 millisecond
- sameWindow.spinOnce(1, true);
- while(!sameWindow.wasStopped())
- {
- /// Interact with window
-
- /// Event loop for 1 millisecond
- sameWindow.spinOnce(1, true);
- }
-
- /// Once more event loop is stopped
- cout << "Last event loop is over" << endl;
- return 0;
- }
-
-Explanation
-===========
-
-Here is the general structure of the program:
-
-* Create a window.
-
-.. code-block:: cpp
-
- /// Create a window
- viz::Viz3d myWindow("Viz Demo");
-
-* Start event loop. This event loop will run until user terminates it by pressing **e**, **E**, **q**, **Q**.
-
-.. code-block:: cpp
-
- /// Start event loop
- myWindow.spin();
-
-* Access same window via its name. Since windows are implicitly shared, **sameWindow** is exactly the same with **myWindow**. If the name does not exist, a new window is created.
-
-.. code-block:: cpp
-
- /// Access window via its name
- viz::Viz3d sameWindow = viz::get("Viz Demo");
-
-* Start a controlled event loop. Once it starts, **wasStopped** is set to false. Inside the while loop, in each iteration, **spinOnce** is called to prevent event loop from completely stopping. Inside the while loop, user can execute other statements including those which interact with the window.
-
-.. code-block:: cpp
-
- /// Event loop is over when pressed q, Q, e, E
- /// Start event loop once for 1 millisecond
- sameWindow.spinOnce(1, true);
- while(!sameWindow.wasStopped())
- {
- /// Interact with window
-
- /// Event loop for 1 millisecond
- sameWindow.spinOnce(1, true);
- }
-
-Results
-=======
-
-Here is the result of the program.
-
-.. image:: images/window_demo.png
- :alt: Launching Viz
- :align: center
+++ /dev/null
-.. _Table-Of-Content-Viz:
-
-**OpenCV Viz**
------------------------------------------------------------
-
-.. include:: ../../definitions/tocDefinitions.rst
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================== ===============================================================================
- |VizLaunchingViz| **Title:** :ref:`launching_viz`
-
- *Compatibility:* > OpenCV 3.0.0
-
- *Author:* Ozan Tonkal
-
- You will learn how to launch a viz window.
-
- ================== ===============================================================================
-
- .. |VizLaunchingViz| image:: ../launching_viz/images/window_demo.png
- :height: 120pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================ ============================================================================
- |WidgetPose| **Title:** :ref:`widget_pose`
-
- *Compatibility:* > OpenCV 3.0.0
-
- *Author:* Ozan Tonkal
-
- You will learn how to change pose of a widget.
-
- ================ ============================================================================
-
- .. |WidgetPose| image:: ../widget_pose/images/widgetpose.png
- :height: 90pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================== ============================================================================
- |Transformations| **Title:** :ref:`transformations`
-
- *Compatibility:* > OpenCV 3.0.0
-
- *Author:* Ozan Tonkal
-
- You will learn how to transform between global and camera frames.
-
- ================== ============================================================================
-
- .. |Transformations| image:: ../transformations/images/global_view_point.png
- :height: 120pt
- :width: 90pt
-
-+
- .. tabularcolumns:: m{100pt} m{300pt}
- .. cssclass:: toctableopencv
-
- ================== ============================================================================
- |CreatingWidgets| **Title:** :ref:`creating_widgets`
-
- *Compatibility:* > OpenCV 3.0.0
-
- *Author:* Ozan Tonkal
-
- You will learn how to create your own widgets.
-
- ================== ============================================================================
-
- .. |CreatingWidgets| image:: ../creating_widgets/images/red_triangle.png
- :height: 120pt
- :width: 90pt
-
-.. raw:: latex
-
- \pagebreak
-
-.. toctree::
- :hidden:
-
- ../launching_viz/launching_viz
- ../widget_pose/widget_pose
- ../transformations/transformations
- ../creating_widgets/creating_widgets
+++ /dev/null
-.. _transformations:
-
-Transformations
-***************
-
-Goal
-====
-
-In this tutorial you will learn how to
-
-.. container:: enumeratevisibleitemswithsquare
-
- * How to use makeTransformToGlobal to compute pose
- * How to use makeCameraPose and Viz3d::setViewerPose
- * How to visualize camera position by axes and by viewing frustum
-
-Code
-====
-
-You can download the code from :download:`here <../../../../samples/cpp/tutorial_code/viz/transformations.cpp>`.
-
-.. code-block:: cpp
-
- #include <opencv2/viz.hpp>
- #include <iostream>
- #include <fstream>
-
- using namespace cv;
- using namespace std;
-
- /*
- * @function cvcloud_load
- * @brief load bunny.ply
- */
- Mat cvcloud_load()
- {
- Mat cloud(1, 1889, CV_32FC3);
- ifstream ifs("bunny.ply");
-
- string str;
- for(size_t i = 0; i < 12; ++i)
- getline(ifs, str);
-
- Point3f* data = cloud.ptr<cv::Point3f>();
- float dummy1, dummy2;
- for(size_t i = 0; i < 1889; ++i)
- ifs >> data[i].x >> data[i].y >> data[i].z >> dummy1 >> dummy2;
-
- cloud *= 5.0f;
- return cloud;
- }
-
- /*
- * @function main
- */
- int main(int argn, char **argv)
- {
- if (argn < 2)
- {
- cout << "Usage: " << endl << "./transformations [ G | C ]" << endl;
- return 1;
- }
-
- bool camera_pov = (argv[1][0] == 'C');
-
- /// Create a window
- viz::Viz3d myWindow("Coordinate Frame");
-
- /// Add coordinate axes
- myWindow.showWidget("Coordinate Widget", viz::WCoordinateSystem());
-
- /// Let's assume camera has the following properties
- Point3f cam_pos(3.0f,3.0f,3.0f), cam_focal_point(3.0f,3.0f,2.0f), cam_y_dir(-1.0f,0.0f,0.0f);
-
- /// We can get the pose of the cam using makeCameraPose
- Affine3f cam_pose = viz::makeCameraPose(cam_pos, cam_focal_point, cam_y_dir);
-
- /// We can get the transformation matrix from camera coordinate system to global using
- /// - makeTransformToGlobal. We need the axes of the camera
- Affine3f transform = viz::makeTransformToGlobal(Vec3f(0.0f,-1.0f,0.0f), Vec3f(-1.0f,0.0f,0.0f), Vec3f(0.0f,0.0f,-1.0f), cam_pos);
-
- /// Create a cloud widget.
- Mat bunny_cloud = cvcloud_load();
- viz::WCloud cloud_widget(bunny_cloud, viz::Color::green());
-
- /// Pose of the widget in camera frame
- Affine3f cloud_pose = Affine3f().translate(Vec3f(0.0f,0.0f,3.0f));
- /// Pose of the widget in global frame
- Affine3f cloud_pose_global = transform * cloud_pose;
-
- /// Visualize camera frame
- if (!camera_pov)
- {
- viz::WCameraPosition cpw(0.5); // Coordinate axes
- viz::WCameraPosition cpw_frustum(Vec2f(0.889484, 0.523599)); // Camera frustum
- myWindow.showWidget("CPW", cpw, cam_pose);
- myWindow.showWidget("CPW_FRUSTUM", cpw_frustum, cam_pose);
- }
-
- /// Visualize widget
- myWindow.showWidget("bunny", cloud_widget, cloud_pose_global);
-
- /// Set the viewer pose to that of camera
- if (camera_pov)
- myWindow.setViewerPose(cam_pose);
-
- /// Start event loop.
- myWindow.spin();
-
- return 0;
- }
-
-
-Explanation
-===========
-
-Here is the general structure of the program:
-
-* Create a visualization window.
-
-.. code-block:: cpp
-
- /// Create a window
- viz::Viz3d myWindow("Transformations");
-
-* Get camera pose from camera position, camera focal point and y direction.
-
-.. code-block:: cpp
-
- /// Let's assume camera has the following properties
- Point3f cam_pos(3.0f,3.0f,3.0f), cam_focal_point(3.0f,3.0f,2.0f), cam_y_dir(-1.0f,0.0f,0.0f);
-
- /// We can get the pose of the cam using makeCameraPose
- Affine3f cam_pose = viz::makeCameraPose(cam_pos, cam_focal_point, cam_y_dir);
-
-* Obtain transform matrix knowing the axes of camera coordinate system.
-
-.. code-block:: cpp
-
- /// We can get the transformation matrix from camera coordinate system to global using
- /// - makeTransformToGlobal. We need the axes of the camera
- Affine3f transform = viz::makeTransformToGlobal(Vec3f(0.0f,-1.0f,0.0f), Vec3f(-1.0f,0.0f,0.0f), Vec3f(0.0f,0.0f,-1.0f), cam_pos);
-
-* Create a cloud widget from bunny.ply file
-
-.. code-block:: cpp
-
- /// Create a cloud widget.
- Mat bunny_cloud = cvcloud_load();
- viz::WCloud cloud_widget(bunny_cloud, viz::Color::green());
-
-* Given the pose in camera coordinate system, estimate the global pose.
-
-.. code-block:: cpp
-
- /// Pose of the widget in camera frame
- Affine3f cloud_pose = Affine3f().translate(Vec3f(0.0f,0.0f,3.0f));
- /// Pose of the widget in global frame
- Affine3f cloud_pose_global = transform * cloud_pose;
-
-* If the view point is set to be global, visualize camera coordinate frame and viewing frustum.
-
-.. code-block:: cpp
-
- /// Visualize camera frame
- if (!camera_pov)
- {
- viz::WCameraPosition cpw(0.5); // Coordinate axes
- viz::WCameraPosition cpw_frustum(Vec2f(0.889484, 0.523599)); // Camera frustum
- myWindow.showWidget("CPW", cpw, cam_pose);
- myWindow.showWidget("CPW_FRUSTUM", cpw_frustum, cam_pose);
- }
-
-* Visualize the cloud widget with the estimated global pose
-
-.. code-block:: cpp
-
- /// Visualize widget
- myWindow.showWidget("bunny", cloud_widget, cloud_pose_global);
-
-* If the view point is set to be camera's, set viewer pose to **cam_pose**.
-
-.. code-block:: cpp
-
- /// Set the viewer pose to that of camera
- if (camera_pov)
- myWindow.setViewerPose(cam_pose);
-
-Results
-=======
-
-#. Here is the result from the camera point of view.
-
- .. image:: images/camera_view_point.png
- :alt: Camera Viewpoint
- :align: center
-
-#. Here is the result from global point of view.
-
- .. image:: images/global_view_point.png
- :alt: Global Viewpoint
- :align: center
+++ /dev/null
-.. _widget_pose:
-
-Pose of a widget
-****************
-
-Goal
-====
-
-In this tutorial you will learn how to
-
-.. container:: enumeratevisibleitemswithsquare
-
- * Add widgets to the visualization window
- * Use Affine3 to set pose of a widget
- * Rotating and translating a widget along an axis
-
-Code
-====
-
-You can download the code from :download:`here <../../../../samples/cpp/tutorial_code/viz/widget_pose.cpp>`.
-
-.. code-block:: cpp
-
- #include <opencv2/viz.hpp>
- #include <opencv2/calib3d.hpp>
- #include <iostream>
-
- using namespace cv;
- using namespace std;
-
- /*
- * @function main
- */
- int main()
- {
- /// Create a window
- viz::Viz3d myWindow("Coordinate Frame");
-
- /// Add coordinate axes
- myWindow.showWidget("Coordinate Widget", viz::WCoordinateSystem());
-
- /// Add line to represent (1,1,1) axis
- viz::WLine axis(Point3f(-1.0f,-1.0f,-1.0f), Point3f(1.0f,1.0f,1.0f));
- axis.setRenderingProperty(viz::LINE_WIDTH, 4.0);
- myWindow.showWidget("Line Widget", axis);
-
- /// Construct a cube widget
- viz::WCube cube_widget(Point3f(0.5,0.5,0.0), Point3f(0.0,0.0,-0.5), true, viz::Color::blue());
- cube_widget.setRenderingProperty(viz::LINE_WIDTH, 4.0);
-
- /// Display widget (update if already displayed)
- myWindow.showWidget("Cube Widget", cube_widget);
-
- /// Rodrigues vector
- Mat rot_vec = Mat::zeros(1,3,CV_32F);
- float translation_phase = 0.0, translation = 0.0;
- while(!myWindow.wasStopped())
- {
- /* Rotation using rodrigues */
- /// Rotate around (1,1,1)
- rot_vec.at<float>(0,0) += CV_PI * 0.01f;
- rot_vec.at<float>(0,1) += CV_PI * 0.01f;
- rot_vec.at<float>(0,2) += CV_PI * 0.01f;
-
- /// Shift on (1,1,1)
- translation_phase += CV_PI * 0.01f;
- translation = sin(translation_phase);
-
- Mat rot_mat;
- Rodrigues(rot_vec, rot_mat);
-
- /// Construct pose
- Affine3f pose(rot_mat, Vec3f(translation, translation, translation));
-
- myWindow.setWidgetPose("Cube Widget", pose);
-
- myWindow.spinOnce(1, true);
- }
-
- return 0;
- }
-
-Explanation
-===========
-
-Here is the general structure of the program:
-
-* Create a visualization window.
-
-.. code-block:: cpp
-
- /// Create a window
- viz::Viz3d myWindow("Coordinate Frame");
-
-* Show coordinate axes in the window using CoordinateSystemWidget.
-
-.. code-block:: cpp
-
- /// Add coordinate axes
- myWindow.showWidget("Coordinate Widget", viz::WCoordinateSystem());
-
-* Display a line representing the axis (1,1,1).
-
-.. code-block:: cpp
-
- /// Add line to represent (1,1,1) axis
- viz::WLine axis(Point3f(-1.0f,-1.0f,-1.0f), Point3f(1.0f,1.0f,1.0f));
- axis.setRenderingProperty(viz::LINE_WIDTH, 4.0);
- myWindow.showWidget("Line Widget", axis);
-
-* Construct a cube.
-
-.. code-block:: cpp
-
- /// Construct a cube widget
- viz::WCube cube_widget(Point3f(0.5,0.5,0.0), Point3f(0.0,0.0,-0.5), true, viz::Color::blue());
- cube_widget.setRenderingProperty(viz::LINE_WIDTH, 4.0);
- myWindow.showWidget("Cube Widget", cube_widget);
-
-* Create rotation matrix from rodrigues vector
-
-.. code-block:: cpp
-
- /// Rotate around (1,1,1)
- rot_vec.at<float>(0,0) += CV_PI * 0.01f;
- rot_vec.at<float>(0,1) += CV_PI * 0.01f;
- rot_vec.at<float>(0,2) += CV_PI * 0.01f;
-
- ...
-
- Mat rot_mat;
- Rodrigues(rot_vec, rot_mat);
-
-* Use Affine3f to set pose of the cube.
-
-.. code-block:: cpp
-
- /// Construct pose
- Affine3f pose(rot_mat, Vec3f(translation, translation, translation));
- myWindow.setWidgetPose("Cube Widget", pose);
-
-* Animate the rotation using wasStopped and spinOnce
-
-.. code-block:: cpp
-
- while(!myWindow.wasStopped())
- {
- ...
-
- myWindow.spinOnce(1, true);
- }
-
-Results
-=======
-
-Here is the result of the program.
-
-.. raw:: html
-
- <div align="center">
- <iframe width="420" height="315" src="https://www.youtube.com/embed/22HKMN657U0" frameborder="0" allowfullscreen></iframe>
- </div>
+++ /dev/null
-**********
-Features2d
-**********
-
-.. highlight:: cpp
-
-Detectors
-=========
-
-Descriptors
-===========
-
-Matching keypoints
-==================
-
-The code
---------
-We will start with a short sample ``opencv/samples/cpp/matcher_simple.cpp``: ::
-
- Mat img1 = imread(argv[1], IMREAD_GRAYSCALE);
- Mat img2 = imread(argv[2], IMREAD_GRAYSCALE);
- if(img1.empty() || img2.empty())
- {
- printf("Can't read one of the images\n");
- return -1;
- }
-
- // detecting keypoints
- SurfFeatureDetector detector(400);
- vector<KeyPoint> keypoints1, keypoints2;
- detector.detect(img1, keypoints1);
- detector.detect(img2, keypoints2);
-
- // computing descriptors
- SurfDescriptorExtractor extractor;
- Mat descriptors1, descriptors2;
- extractor.compute(img1, keypoints1, descriptors1);
- extractor.compute(img2, keypoints2, descriptors2);
-
- // matching descriptors
- BruteForceMatcher<L2<float> > matcher;
- vector<DMatch> matches;
- matcher.match(descriptors1, descriptors2, matches);
-
- // drawing the results
- namedWindow("matches", 1);
- Mat img_matches;
- drawMatches(img1, keypoints1, img2, keypoints2, matches, img_matches);
- imshow("matches", img_matches);
- waitKey(0);
-
-The code explained
-------------------
-
-Let us break the code down. ::
-
- Mat img1 = imread(argv[1], IMREAD_GRAYSCALE);
- Mat img2 = imread(argv[2], IMREAD_GRAYSCALE);
- if(img1.empty() || img2.empty())
- {
- printf("Can't read one of the images\n");
- return -1;
- }
-
-We load two images and check if they are loaded correctly.::
-
- // detecting keypoints
- Ptr<FeatureDetector> detector = FastFeatureDetector::create(15);
- vector<KeyPoint> keypoints1, keypoints2;
- detector->detect(img1, keypoints1);
- detector->detect(img2, keypoints2);
-
-First, we create an instance of a keypoint detector. All detectors inherit the abstract ``FeatureDetector`` interface, but the constructors are algorithm-dependent. The first argument to each detector usually controls the balance between the amount of keypoints and their stability. The range of values is different for different detectors (For instance, *FAST* threshold has the meaning of pixel intensity difference and usually varies in the region *[0,40]*. *SURF* threshold is applied to a Hessian of an image and usually takes on values larger than *100*), so use defaults in case of doubt. ::
-
- // computing descriptors
- Ptr<SURF> extractor = SURF::create();
- Mat descriptors1, descriptors2;
- extractor->compute(img1, keypoints1, descriptors1);
- extractor->compute(img2, keypoints2, descriptors2);
-
-We create an instance of descriptor extractor. The most of OpenCV descriptors inherit ``DescriptorExtractor`` abstract interface. Then we compute descriptors for each of the keypoints. The output ``Mat`` of the ``DescriptorExtractor::compute`` method contains a descriptor in a row *i* for each *i*-th keypoint. Note that the method can modify the keypoints vector by removing the keypoints such that a descriptor for them is not defined (usually these are the keypoints near image border). The method makes sure that the ouptut keypoints and descriptors are consistent with each other (so that the number of keypoints is equal to the descriptors row count). ::
-
- // matching descriptors
- BruteForceMatcher<L2<float> > matcher;
- vector<DMatch> matches;
- matcher.match(descriptors1, descriptors2, matches);
-
-Now that we have descriptors for both images, we can match them. First, we create a matcher that for each descriptor from image 2 does exhaustive search for the nearest descriptor in image 1 using Euclidean metric. Manhattan distance is also implemented as well as a Hamming distance for Brief descriptor. The output vector ``matches`` contains pairs of corresponding points indices. ::
-
- // drawing the results
- namedWindow("matches", 1);
- Mat img_matches;
- drawMatches(img1, keypoints1, img2, keypoints2, matches, img_matches);
- imshow("matches", img_matches);
- waitKey(0);
-
-The final part of the sample is about visualizing the matching results.
+++ /dev/null
-*******
-HighGUI
-*******
-
-.. highlight:: cpp
-
-Using Kinect and other OpenNI compatible depth sensors
-======================================================
-
-Depth sensors compatible with OpenNI (Kinect, XtionPRO, ...) are supported through ``VideoCapture`` class. Depth map, RGB image and some other formats of output can be retrieved by using familiar interface of ``VideoCapture``.
-
-In order to use depth sensor with OpenCV you should do the following preliminary steps:
-
-#.
- Install OpenNI library (from here http://www.openni.org/downloadfiles) and PrimeSensor Module for OpenNI (from here https://github.com/avin2/SensorKinect). The installation should be done to default folders listed in the instructions of these products, e.g.:
-
- .. code-block:: text
-
- OpenNI:
- Linux & MacOSX:
- Libs into: /usr/lib
- Includes into: /usr/include/ni
- Windows:
- Libs into: c:/Program Files/OpenNI/Lib
- Includes into: c:/Program Files/OpenNI/Include
- PrimeSensor Module:
- Linux & MacOSX:
- Bins into: /usr/bin
- Windows:
- Bins into: c:/Program Files/Prime Sense/Sensor/Bin
-
- If one or both products were installed to the other folders, the user should change corresponding CMake variables ``OPENNI_LIB_DIR``, ``OPENNI_INCLUDE_DIR`` or/and ``OPENNI_PRIME_SENSOR_MODULE_BIN_DIR``.
-
-#.
- Configure OpenCV with OpenNI support by setting ``WITH_OPENNI`` flag in CMake. If OpenNI is found in install folders OpenCV will be built with OpenNI library (see a status ``OpenNI`` in CMake log) whereas PrimeSensor Modules can not be found (see a status ``OpenNI PrimeSensor Modules`` in CMake log). Without PrimeSensor module OpenCV will be successfully compiled with OpenNI library, but ``VideoCapture`` object will not grab data from Kinect sensor.
-
-#.
- Build OpenCV.
-
-VideoCapture can retrieve the following data:
-
-#.
- data given from depth generator:
- * ``CAP_OPENNI_DEPTH_MAP`` - depth values in mm (CV_16UC1)
- * ``CAP_OPENNI_POINT_CLOUD_MAP`` - XYZ in meters (CV_32FC3)
- * ``CAP_OPENNI_DISPARITY_MAP`` - disparity in pixels (CV_8UC1)
- * ``CAP_OPENNI_DISPARITY_MAP_32F`` - disparity in pixels (CV_32FC1)
- * ``CAP_OPENNI_VALID_DEPTH_MASK`` - mask of valid pixels (not ocluded, not shaded etc.) (CV_8UC1)
-#.
- data given from RGB image generator:
- * ``CAP_OPENNI_BGR_IMAGE`` - color image (CV_8UC3)
- * ``CAP_OPENNI_GRAY_IMAGE`` - gray image (CV_8UC1)
-
-In order to get depth map from depth sensor use ``VideoCapture::operator >>``, e. g. ::
-
- VideoCapture capture( CAP_OPENNI );
- for(;;)
- {
- Mat depthMap;
- capture >> depthMap;
-
- if( waitKey( 30 ) >= 0 )
- break;
- }
-
-For getting several data maps use ``VideoCapture::grab`` and ``VideoCapture::retrieve``, e.g. ::
-
- VideoCapture capture(0); // or CAP_OPENNI
- for(;;)
- {
- Mat depthMap;
- Mat bgrImage;
-
- capture.grab();
-
- capture.retrieve( depthMap, CAP_OPENNI_DEPTH_MAP );
- capture.retrieve( bgrImage, CAP_OPENNI_BGR_IMAGE );
-
- if( waitKey( 30 ) >= 0 )
- break;
- }
-
-For setting and getting some property of sensor` data generators use ``VideoCapture::set`` and ``VideoCapture::get`` methods respectively, e.g. ::
-
- VideoCapture capture( CAP_OPENNI );
- capture.set( CAP_OPENNI_IMAGE_GENERATOR_OUTPUT_MODE, CAP_OPENNI_VGA_30HZ );
- cout << "FPS " << capture.get( CAP_OPENNI_IMAGE_GENERATOR+CAP_PROP_FPS ) << endl;
-
-Since two types of sensor's data generators are supported (image generator and depth generator), there are two flags that should be used to set/get property of the needed generator:
-
-* CAP_OPENNI_IMAGE_GENERATOR -- A flag for access to the image generator properties.
-
-* CAP_OPENNI_DEPTH_GENERATOR -- A flag for access to the depth generator properties. This flag value is assumed by default if neither of the two possible values of the property is not set.
-
-Some depth sensors (for example XtionPRO) do not have image generator. In order to check it you can get ``CAP_OPENNI_IMAGE_GENERATOR_PRESENT`` property.
-::
-
- bool isImageGeneratorPresent = capture.get( CAP_PROP_OPENNI_IMAGE_GENERATOR_PRESENT ) != 0; // or == 1
-
-
-Flags specifing the needed generator type must be used in combination with particular generator property. The following properties of cameras available through OpenNI interfaces are supported:
-
-*
- For image generator:
-
- - ``CAP_PROP_OPENNI_OUTPUT_MODE`` -- Three output modes are supported: ``CAP_OPENNI_VGA_30HZ`` used by default (image generator returns images in VGA resolution with 30 FPS), ``CAP_OPENNI_SXGA_15HZ`` (image generator returns images in SXGA resolution with 15 FPS) and ``CAP_OPENNI_SXGA_30HZ`` (image generator returns images in SXGA resolution with 30 FPS, the mode is supported by XtionPRO Live); depth generator's maps are always in VGA resolution.
-
-
-*
- For depth generator:
-
- - ``CAP_PROP_OPENNI_REGISTRATION`` -- Flag that registers the remapping depth map to image map by changing depth generator's view point (if the flag is ``"on"``) or sets this view point to its normal one (if the flag is ``"off"``). The registration process’s resulting images are pixel-aligned,which means that every pixel in the image is aligned to a pixel in the depth image.
-
- Next properties are available for getting only:
-
- - ``CAP_PROP_OPENNI_FRAME_MAX_DEPTH`` -- A maximum supported depth of Kinect in mm.
- - ``CAP_PROP_OPENNI_BASELINE`` -- Baseline value in mm.
- - ``CAP_PROP_OPENNI_FOCAL_LENGTH`` -- A focal length in pixels.
- - ``CAP_PROP_FRAME_WIDTH`` -- Frame width in pixels.
- - ``CAP_PROP_FRAME_HEIGHT`` -- Frame height in pixels.
- - ``CAP_PROP_FPS`` -- Frame rate in FPS.
-
-*
- Some typical flags combinations "generator type + property" are defined as single flags:
-
- - ``CAP_OPENNI_IMAGE_GENERATOR_OUTPUT_MODE = CAP_OPENNI_IMAGE_GENERATOR + CAP_PROP_OPENNI_OUTPUT_MODE``
- - ``CAP_OPENNI_DEPTH_GENERATOR_BASELINE = CAP_OPENNI_DEPTH_GENERATOR + CAP_PROP_OPENNI_BASELINE``
- - ``CAP_OPENNI_DEPTH_GENERATOR_FOCAL_LENGTH = CAP_OPENNI_DEPTH_GENERATOR + CAP_PROP_OPENNI_FOCAL_LENGTH``
- - ``CAP_OPENNI_DEPTH_GENERATOR_REGISTRATION = CAP_OPENNI_DEPTH_GENERATOR + CAP_PROP_OPENNI_REGISTRATION``
-
-For more information please refer to the example of usage openni_capture.cpp_ in ``opencv/samples/cpp`` folder.
-
-.. _openni_capture.cpp: https://github.com/Itseez/opencv/tree/master/samples/cpp/openni_capture.cpp
+++ /dev/null
-*******
-HighGUI
-*******
-
-.. highlight:: cpp
-
-Using Creative Senz3D and other Intel Perceptual Computing SDK compatible depth sensors
-=======================================================================================
-
-Depth sensors compatible with Intel Perceptual Computing SDK are supported through ``VideoCapture`` class. Depth map, RGB image and some other formats of output can be retrieved by using familiar interface of ``VideoCapture``.
-
-In order to use depth sensor with OpenCV you should do the following preliminary steps:
-
-#.
- Install Intel Perceptual Computing SDK (from here http://www.intel.com/software/perceptual).
-
-#.
- Configure OpenCV with Intel Perceptual Computing SDK support by setting ``WITH_INTELPERC`` flag in CMake. If Intel Perceptual Computing SDK is found in install folders OpenCV will be built with Intel Perceptual Computing SDK library (see a status ``INTELPERC`` in CMake log). If CMake process doesn't find Intel Perceptual Computing SDK installation folder automatically, the user should change corresponding CMake variables ``INTELPERC_LIB_DIR`` and ``INTELPERC_INCLUDE_DIR`` to the proper value.
-
-#.
- Build OpenCV.
-
-VideoCapture can retrieve the following data:
-
-#.
- data given from depth generator:
- * ``CAP_INTELPERC_DEPTH_MAP`` - each pixel is a 16-bit integer. The value indicates the distance from an object to the camera's XY plane or the Cartesian depth. (CV_16UC1)
- * ``CAP_INTELPERC_UVDEPTH_MAP`` - each pixel contains two 32-bit floating point values in the range of 0-1, representing the mapping of depth coordinates to the color coordinates. (CV_32FC2)
- * ``CAP_INTELPERC_IR_MAP`` - each pixel is a 16-bit integer. The value indicates the intensity of the reflected laser beam. (CV_16UC1)
-#.
- data given from RGB image generator:
- * ``CAP_INTELPERC_IMAGE`` - color image. (CV_8UC3)
-
-In order to get depth map from depth sensor use ``VideoCapture::operator >>``, e. g. ::
-
- VideoCapture capture( CAP_INTELPERC );
- for(;;)
- {
- Mat depthMap;
- capture >> depthMap;
-
- if( waitKey( 30 ) >= 0 )
- break;
- }
-
-For getting several data maps use ``VideoCapture::grab`` and ``VideoCapture::retrieve``, e.g. ::
-
- VideoCapture capture(CAP_INTELPERC);
- for(;;)
- {
- Mat depthMap;
- Mat image;
- Mat irImage;
-
- capture.grab();
-
- capture.retrieve( depthMap, CAP_INTELPERC_DEPTH_MAP );
- capture.retrieve( image, CAP_INTELPERC_IMAGE );
- capture.retrieve( irImage, CAP_INTELPERC_IR_MAP);
-
- if( waitKey( 30 ) >= 0 )
- break;
- }
-
-For setting and getting some property of sensor` data generators use ``VideoCapture::set`` and ``VideoCapture::get`` methods respectively, e.g. ::
-
- VideoCapture capture( CAP_INTELPERC );
- capture.set( CAP_INTELPERC_DEPTH_GENERATOR | CAP_PROP_INTELPERC_PROFILE_IDX, 0 );
- cout << "FPS " << capture.get( CAP_INTELPERC_DEPTH_GENERATOR+CAP_PROP_FPS ) << endl;
-
-Since two types of sensor's data generators are supported (image generator and depth generator), there are two flags that should be used to set/get property of the needed generator:
-
-* CAP_INTELPERC_IMAGE_GENERATOR -- a flag for access to the image generator properties.
-
-* CAP_INTELPERC_DEPTH_GENERATOR -- a flag for access to the depth generator properties. This flag value is assumed by default if neither of the two possible values of the property is set.
-
-For more information please refer to the example of usage intelperc_capture.cpp_ in ``opencv/samples/cpp`` folder.
-
-.. _intelperc_capture.cpp: https://github.com/Itseez/opencv/tree/master/samples/cpp/intelperc_capture.cpp
+++ /dev/null
-**********************
-Operations with images
-**********************
-
-.. highlight:: cpp
-
-Input/Output
-============
-
-Images
-------
-
-Load an image from a file: ::
-
- Mat img = imread(filename)
-
-If you read a jpg file, a 3 channel image is created by default. If you need a grayscale image, use: ::
-
- Mat img = imread(filename, 0);
-
-.. note:: format of the file is determined by its content (first few bytes)
-
-Save an image to a file: ::
-
- imwrite(filename, img);
-
-.. note:: format of the file is determined by its extension.
-
-.. note:: use ``imdecode`` and ``imencode`` to read and write image from/to memory rather than a file.
-
-XML/YAML
---------
-
-TBD
-
-Basic operations with images
-============================
-
-Accessing pixel intensity values
---------------------------------
-
-In order to get pixel intensity value, you have to know the type of an image and the number of channels. Here is an example for a single channel grey scale image (type 8UC1) and pixel coordinates x and y: ::
-
- Scalar intensity = img.at<uchar>(y, x);
-
-``intensity.val[0]`` contains a value from 0 to 255. Note the ordering of ``x`` and ``y``. Since in OpenCV images are represented by the same structure as matrices, we use the same convention for both cases - the 0-based row index (or y-coordinate) goes first and the 0-based column index (or x-coordinate) follows it. Alternatively, you can use the following notation: ::
-
- Scalar intensity = img.at<uchar>(Point(x, y));
-
-Now let us consider a 3 channel image with ``BGR`` color ordering (the default format returned by ``imread``): ::
-
- Vec3b intensity = img.at<Vec3b>(y, x);
- uchar blue = intensity.val[0];
- uchar green = intensity.val[1];
- uchar red = intensity.val[2];
-
-You can use the same method for floating-point images (for example, you can get such an image by running Sobel on a 3 channel image): ::
-
- Vec3f intensity = img.at<Vec3f>(y, x);
- float blue = intensity.val[0];
- float green = intensity.val[1];
- float red = intensity.val[2];
-
-The same method can be used to change pixel intensities: ::
-
- img.at<uchar>(y, x) = 128;
-
-There are functions in OpenCV, especially from calib3d module, such as ``projectPoints``, that take an array of 2D or 3D points in the form of ``Mat``. Matrix should contain exactly one column, each row corresponds to a point, matrix type should be 32FC2 or 32FC3 correspondingly. Such a matrix can be easily constructed from ``std::vector``: ::
-
- vector<Point2f> points;
- //... fill the array
- Mat pointsMat = Mat(points);
-
-One can access a point in this matrix using the same method ``Mat::at`` :
-
-::
-
- Point2f point = pointsMat.at<Point2f>(i, 0);
-
-
-Memory management and reference counting
-----------------------------------------
-
-``Mat`` is a structure that keeps matrix/image characteristics (rows and columns number, data type etc) and a pointer to data. So nothing prevents us from having several instances of ``Mat`` corresponding to the same data. A ``Mat`` keeps a reference count that tells if data has to be deallocated when a particular instance of ``Mat`` is destroyed. Here is an example of creating two matrices without copying data: ::
-
- std::vector<Point3f> points;
- // .. fill the array
- Mat pointsMat = Mat(points).reshape(1);
-
-As a result we get a 32FC1 matrix with 3 columns instead of 32FC3 matrix with 1 column. ``pointsMat`` uses data from ``points`` and will not deallocate the memory when destroyed. In this particular instance, however, developer has to make sure that lifetime of ``points`` is longer than of ``pointsMat``.
-If we need to copy the data, this is done using, for example, ``Mat::copyTo`` or ``Mat::clone``: ::
-
- Mat img = imread("image.jpg");
- Mat img1 = img.clone();
-
-To the contrary with C API where an output image had to be created by developer, an empty output ``Mat`` can be supplied to each function. Each implementation calls ``Mat::create`` for a destination matrix. This method allocates data for a matrix if it is empty. If it is not empty and has the correct size and type, the method does nothing. If, however, size or type are different from input arguments, the data is deallocated (and lost) and a new data is allocated. For example: ::
-
- Mat img = imread("image.jpg");
- Mat sobelx;
- Sobel(img, sobelx, CV_32F, 1, 0);
-
-Primitive operations
---------------------
-
-There is a number of convenient operators defined on a matrix. For example, here is how we can make a black image from an existing greyscale image ``img``: ::
-
- img = Scalar(0);
-
-Selecting a region of interest: ::
-
- Rect r(10, 10, 100, 100);
- Mat smallImg = img(r);
-
-A convertion from ``Mat`` to C API data structures: ::
-
- Mat img = imread("image.jpg");
- IplImage img1 = img;
- CvMat m = img;
-
-Note that there is no data copying here.
-
-Conversion from color to grey scale: ::
-
- Mat img = imread("image.jpg"); // loading a 8UC3 image
- Mat grey;
- cvtColor(img, grey, COLOR_BGR2GRAY);
-
-Change image type from 8UC1 to 32FC1: ::
-
- src.convertTo(dst, CV_32F);
-
-Visualizing images
-------------------
-
-It is very useful to see intermediate results of your algorithm during development process. OpenCV provides a convenient way of visualizing images. A 8U image can be shown using: ::
-
- Mat img = imread("image.jpg");
-
- namedWindow("image", WINDOW_AUTOSIZE);
- imshow("image", img);
- waitKey();
-
-A call to ``waitKey()`` starts a message passing cycle that waits for a key stroke in the ``"image"`` window. A ``32F`` image needs to be converted to ``8U`` type. For example: ::
-
- Mat img = imread("image.jpg");
- Mat grey;
- cvtColor(img, grey, COLOR_BGR2GRAY);
-
- Mat sobelx;
- Sobel(grey, sobelx, CV_32F, 1, 0);
-
- double minVal, maxVal;
- minMaxLoc(sobelx, &minVal, &maxVal); //find minimum and maximum intensities
- Mat draw;
- sobelx.convertTo(draw, CV_8U, 255.0/(maxVal - minVal), -minVal * 255.0/(maxVal - minVal));
-
- namedWindow("image", WINDOW_AUTOSIZE);
- imshow("image", draw);
- waitKey();
+++ /dev/null
-***************************
-Cascade Classifier Training
-***************************
-
-.. highlight:: cpp
-
-Introduction
-============
-The work with a cascade classifier inlcudes two major stages: training and detection.
-Detection stage is described in a documentation of ``objdetect`` module of general OpenCV documentation. Documentation gives some basic information about cascade classifier.
-Current guide is describing how to train a cascade classifier: preparation of a training data and running the training application.
-
-Important notes
----------------
-There are two applications in OpenCV to train cascade classifier: ``opencv_haartraining`` and ``opencv_traincascade``. ``opencv_traincascade`` is a newer version, written in C++ in accordance to OpenCV 2.x API. But the main difference between this two applications is that ``opencv_traincascade`` supports both Haar [Viola2001]_ and LBP [Liao2007]_ (Local Binary Patterns) features. LBP features are integer in contrast to Haar features, so both training and detection with LBP are several times faster then with Haar features. Regarding the LBP and Haar detection quality, it depends on training: the quality of training dataset first of all and training parameters too. It's possible to train a LBP-based classifier that will provide almost the same quality as Haar-based one.
-
-``opencv_traincascade`` and ``opencv_haartraining`` store the trained classifier in different file formats. Note, the newer cascade detection interface (see ``CascadeClassifier`` class in ``objdetect`` module) support both formats. ``opencv_traincascade`` can save (export) a trained cascade in the older format. But ``opencv_traincascade`` and ``opencv_haartraining`` can not load (import) a classifier in another format for the futher training after interruption.
-
-Note that ``opencv_traincascade`` application can use TBB for multi-threading. To use it in multicore mode OpenCV must be built with TBB.
-
-Also there are some auxilary utilities related to the training.
-
- * ``opencv_createsamples`` is used to prepare a training dataset of positive and test samples. ``opencv_createsamples`` produces dataset of positive samples in a format that is supported by both ``opencv_haartraining`` and ``opencv_traincascade`` applications. The output is a file with \*.vec extension, it is a binary format which contains images.
-
- * ``opencv_performance`` may be used to evaluate the quality of classifiers, but for trained by ``opencv_haartraining`` only. It takes a collection of marked up images, runs the classifier and reports the performance, i.e. number of found objects, number of missed objects, number of false alarms and other information.
-
-Since ``opencv_haartraining`` is an obsolete application, only ``opencv_traincascade`` will be described futher. ``opencv_createsamples`` utility is needed to prepare a training data for ``opencv_traincascade``, so it will be described too.
-
-
-Training data preparation
-=========================
-For training we need a set of samples. There are two types of samples: negative and positive. Negative samples correspond to non-object images. Positive samples correspond to images with detected objects. Set of negative samples must be prepared manually, whereas set of positive samples is created using ``opencv_createsamples`` utility.
-
-Negative Samples
-----------------
-Negative samples are taken from arbitrary images. These images must not contain detected objects. Negative samples are enumerated in a special file. It is a text file in which each line contains an image filename (relative to the directory of the description file) of negative sample image. This file must be created manually. Note that negative samples and sample images are also called background samples or background samples images, and are used interchangeably in this document. Described images may be of different sizes. But each image should be (but not nessesarily) larger then a training window size, because these images are used to subsample negative image to the training size.
-
-An example of description file:
-
-Directory structure:
-
- .. code-block:: text
-
- /img
- img1.jpg
- img2.jpg
- bg.txt
-
-File bg.txt:
-
- .. code-block:: text
-
- img/img1.jpg
- img/img2.jpg
-
-Positive Samples
-----------------
-Positive samples are created by ``opencv_createsamples`` utility. They may be created from a single image with object or from a collection of previously marked up images.
-
-Please note that you need a large dataset of positive samples before you give it to the mentioned utility, because it only applies perspective transformation. For example you may need only one positive sample for absolutely rigid object like an OpenCV logo, but you definetely need hundreds and even thousands of positive samples for faces. In the case of faces you should consider all the race and age groups, emotions and perhaps beard styles.
-
-So, a single object image may contain a company logo. Then a large set of positive samples is created from the given object image by random rotating, changing the logo intensity as well as placing the logo on arbitrary background. The amount and range of randomness can be controlled by command line arguments of ``opencv_createsamples`` utility.
-
-Command line arguments:
-
-* ``-vec <vec_file_name>``
-
- Name of the output file containing the positive samples for training.
-
-* ``-img <image_file_name>``
-
- Source object image (e.g., a company logo).
-
-* ``-bg <background_file_name>``
-
- Background description file; contains a list of images which are used as a background for randomly distorted versions of the object.
-
-* ``-num <number_of_samples>``
-
- Number of positive samples to generate.
-
-* ``-bgcolor <background_color>``
-
- Background color (currently grayscale images are assumed); the background color denotes the transparent color. Since there might be compression artifacts, the amount of color tolerance can be specified by ``-bgthresh``. All pixels withing ``bgcolor-bgthresh`` and ``bgcolor+bgthresh`` range are interpreted as transparent.
-
-* ``-bgthresh <background_color_threshold>``
-
-* ``-inv``
-
- If specified, colors will be inverted.
-
-* ``-randinv``
-
- If specified, colors will be inverted randomly.
-
-* ``-maxidev <max_intensity_deviation>``
-
- Maximal intensity deviation of pixels in foreground samples.
-
-* ``-maxxangle <max_x_rotation_angle>``
-
-* ``-maxyangle <max_y_rotation_angle>``
-
-* ``-maxzangle <max_z_rotation_angle>``
-
- Maximum rotation angles must be given in radians.
-
-* ``-show``
-
- Useful debugging option. If specified, each sample will be shown. Pressing ``Esc`` will continue the samples creation process without.
-
-* ``-w <sample_width>``
-
- Width (in pixels) of the output samples.
-
-* ``-h <sample_height>``
-
- Height (in pixels) of the output samples.
-
-For following procedure is used to create a sample object instance:
-The source image is rotated randomly around all three axes. The chosen angle is limited my ``-max?angle``. Then pixels having the intensity from [``bg_color-bg_color_threshold``; ``bg_color+bg_color_threshold``] range are interpreted as transparent. White noise is added to the intensities of the foreground. If the ``-inv`` key is specified then foreground pixel intensities are inverted. If ``-randinv`` key is specified then algorithm randomly selects whether inversion should be applied to this sample. Finally, the obtained image is placed onto an arbitrary background from the background description file, resized to the desired size specified by ``-w`` and ``-h`` and stored to the vec-file, specified by the ``-vec`` command line option.
-
-Positive samples also may be obtained from a collection of previously marked up images. This collection is described by a text file similar to background description file. Each line of this file corresponds to an image. The first element of the line is the filename. It is followed by the number of object instances. The following numbers are the coordinates of objects bounding rectangles (x, y, width, height).
-
-An example of description file:
-
-Directory structure:
-
- .. code-block:: text
-
- /img
- img1.jpg
- img2.jpg
- info.dat
-
-File info.dat:
-
- .. code-block:: text
-
- img/img1.jpg 1 140 100 45 45
- img/img2.jpg 2 100 200 50 50 50 30 25 25
-
-Image img1.jpg contains single object instance with the following coordinates of bounding rectangle: (140, 100, 45, 45). Image img2.jpg contains two object instances.
-
-In order to create positive samples from such collection, ``-info`` argument should be specified instead of ``-img``:
-
-* ``-info <collection_file_name>``
-
- Description file of marked up images collection.
-
-The scheme of samples creation in this case is as follows. The object instances are taken from images. Then they are resized to target samples size and stored in output vec-file. No distortion is applied, so the only affecting arguments are ``-w``, ``-h``, ``-show`` and ``-num``.
-
-``opencv_createsamples`` utility may be used for examining samples stored in positive samples file. In order to do this only ``-vec``, ``-w`` and ``-h`` parameters should be specified.
-
-Note that for training, it does not matter how vec-files with positive samples are generated. But ``opencv_createsamples`` utility is the only one way to collect/create a vector file of positive samples, provided by OpenCV.
-
-Example of vec-file is available here ``opencv/data/vec_files/trainingfaces_24-24.vec``. It can be used to train a face detector with the following window size: ``-w 24 -h 24``.
-
-Cascade Training
-================
-The next step is the training of classifier. As mentioned above ``opencv_traincascade`` or ``opencv_haartraining`` may be used to train a cascade classifier, but only the newer ``opencv_traincascade`` will be described futher.
-
-Command line arguments of ``opencv_traincascade`` application grouped by purposes:
-
-#.
-
- Common arguments:
-
- * ``-data <cascade_dir_name>``
-
- Where the trained classifier should be stored.
-
- * ``-vec <vec_file_name>``
-
- vec-file with positive samples (created by ``opencv_createsamples`` utility).
-
- * ``-bg <background_file_name>``
-
- Background description file.
-
- * ``-numPos <number_of_positive_samples>``
-
- * ``-numNeg <number_of_negative_samples>``
-
- Number of positive/negative samples used in training for every classifier stage.
-
- * ``-numStages <number_of_stages>``
-
- Number of cascade stages to be trained.
-
- * ``-precalcValBufSize <precalculated_vals_buffer_size_in_Mb>``
-
- Size of buffer for precalculated feature values (in Mb).
-
- * ``-precalcIdxBufSize <precalculated_idxs_buffer_size_in_Mb>``
-
- Size of buffer for precalculated feature indices (in Mb). The more memory you have the faster the training process.
-
- * ``-baseFormatSave``
-
- This argument is actual in case of Haar-like features. If it is specified, the cascade will be saved in the old format.
-
- * ``-numThreads <max_number_of_threads>``
-
- Maximum number of threads to use during training. Notice that
- the actual number of used threads may be lower, depending on
- your machine and compilation options.
-
-#.
-
- Cascade parameters:
-
- * ``-stageType <BOOST(default)>``
-
- Type of stages. Only boosted classifier are supported as a stage type at the moment.
-
- * ``-featureType<{HAAR(default), LBP}>``
-
- Type of features: ``HAAR`` - Haar-like features, ``LBP`` - local binary patterns.
-
- * ``-w <sampleWidth>``
-
- * ``-h <sampleHeight>``
-
- Size of training samples (in pixels). Must have exactly the same values as used during training samples creation (``opencv_createsamples`` utility).
-
-#.
-
- Boosted classifer parameters:
-
- * ``-bt <{DAB, RAB, LB, GAB(default)}>``
-
- Type of boosted classifiers: ``DAB`` - Discrete AdaBoost, ``RAB`` - Real AdaBoost, ``LB`` - LogitBoost, ``GAB`` - Gentle AdaBoost.
-
- * ``-minHitRate <min_hit_rate>``
-
- Minimal desired hit rate for each stage of the classifier. Overall hit rate may be estimated as (min_hit_rate^number_of_stages).
-
- * ``-maxFalseAlarmRate <max_false_alarm_rate>``
-
- Maximal desired false alarm rate for each stage of the classifier. Overall false alarm rate may be estimated as (max_false_alarm_rate^number_of_stages).
-
- * ``-weightTrimRate <weight_trim_rate>``
-
- Specifies whether trimming should be used and its weight. A decent choice is 0.95.
-
- * ``-maxDepth <max_depth_of_weak_tree>``
-
- Maximal depth of a weak tree. A decent choice is 1, that is case of stumps.
-
- * ``-maxWeakCount <max_weak_tree_count>``
-
- Maximal count of weak trees for every cascade stage. The boosted classifier (stage) will have so many weak trees (``<=maxWeakCount``), as needed to achieve the given ``-maxFalseAlarmRate``.
-
-#.
-
- Haar-like feature parameters:
-
- * ``-mode <BASIC (default) | CORE | ALL>``
-
- Selects the type of Haar features set used in training. ``BASIC`` use only upright features, while ``ALL`` uses the full set of upright and 45 degree rotated feature set. See [Rainer2002]_ for more details.
-
-#.
-
- Local Binary Patterns parameters:
-
- Local Binary Patterns don't have parameters.
-
-After the ``opencv_traincascade`` application has finished its work, the trained cascade will be saved in cascade.xml file in the folder, which was passed as ``-data`` parameter. Other files in this folder are created for the case of interrupted training, so you may delete them after completion of training.
-
-Training is finished and you can test you cascade classifier!
-
-.. [Viola2001] Paul Viola, Michael Jones. *Rapid Object Detection using a Boosted Cascade of Simple Features*. Conference on Computer Vision and Pattern Recognition (CVPR), 2001, pp. 511-518.
-
-.. [Rainer2002] Rainer Lienhart and Jochen Maydt. *An Extended Set of Haar-like Features for Rapid Object Detection*. Submitted to ICIP2002.
-
-.. [Liao2007] Shengcai Liao, Xiangxin Zhu, Zhen Lei, Lun Zhang and Stan Z. Li. *Learning Multi-scale Block Local Binary Patterns for Face Recognition*. International Conference on Biometrics (ICB), 2007, pp. 828-837.
+++ /dev/null
-#################
-OpenCV User Guide
-#################
-
-.. toctree::
- :maxdepth: 2
-
- ug_mat.rst
- ug_features2d.rst
- ug_highgui.rst
- ug_traincascade.rst
- ug_intelperc.rst
+++ /dev/null
-.. opencvstd documentation master file, created by
- sphinx-quickstart on Mon Feb 14 00:30:43 2011.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-Welcome to opencv documentation!
-================================
-
-.. toctree::
- :maxdepth: 2
-
- modules/refman.rst
- platforms/android/refman.rst
- doc/user_guide/user_guide.rst
- doc/tutorials/tutorials.rst
- doc/py_tutorials/py_tutorials.rst
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
+++ /dev/null
-*************************************************
-calib3d. Camera Calibration and 3D Reconstruction
-*************************************************
-
-.. toctree::
- :maxdepth: 2
-
- camera_calibration_and_3d_reconstruction
+++ /dev/null
-Camera Calibration and 3D Reconstruction
-========================================
-
-.. highlight:: cpp
-
-The functions in this section use a so-called pinhole camera model. In this model, a scene view is formed by projecting 3D points into the image plane
-using a perspective transformation.
-
-.. math::
-
- s \; m' = A [R|t] M'
-
-or
-
-.. math::
-
- s \vecthree{u}{v}{1} = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}
- \begin{bmatrix}
- r_{11} & r_{12} & r_{13} & t_1 \\
- r_{21} & r_{22} & r_{23} & t_2 \\
- r_{31} & r_{32} & r_{33} & t_3
- \end{bmatrix}
- \begin{bmatrix}
- X \\
- Y \\
- Z \\
- 1
- \end{bmatrix}
-
-where:
-
- * :math:`(X, Y, Z)` are the coordinates of a 3D point in the world coordinate space
- * :math:`(u, v)` are the coordinates of the projection point in pixels
- * :math:`A` is a camera matrix, or a matrix of intrinsic parameters
- * :math:`(cx, cy)` is a principal point that is usually at the image center
- * :math:`fx, fy` are the focal lengths expressed in pixel units.
-
-
-Thus, if an image from the camera is
-scaled by a factor, all of these parameters should
-be scaled (multiplied/divided, respectively) by the same factor. The
-matrix of intrinsic parameters does not depend on the scene viewed. So,
-once estimated, it can be re-used as long as the focal length is fixed (in
-case of zoom lens). The joint rotation-translation matrix
-:math:`[R|t]` is called a matrix of extrinsic parameters. It is used to describe the
-camera motion around a static scene, or vice versa, rigid motion of an
-object in front of a still camera. That is,
-:math:`[R|t]` translates
-coordinates of a point
-:math:`(X, Y, Z)` to a coordinate system,
-fixed with respect to the camera. The transformation above is equivalent
-to the following (when
-:math:`z \ne 0` ):
-
-.. math::
-
- \begin{array}{l}
- \vecthree{x}{y}{z} = R \vecthree{X}{Y}{Z} + t \\
- x' = x/z \\
- y' = y/z \\
- u = f_x*x' + c_x \\
- v = f_y*y' + c_y
- \end{array}
-
-Real lenses usually have some distortion, mostly
-radial distortion and slight tangential distortion. So, the above model
-is extended as:
-
-.. math::
-
- \begin{array}{l} \vecthree{x}{y}{z} = R \vecthree{X}{Y}{Z} + t \\ x' = x/z \\ y' = y/z \\ x'' = x' \frac{1 + k_1 r^2 + k_2 r^4 + k_3 r^6}{1 + k_4 r^2 + k_5 r^4 + k_6 r^6} + 2 p_1 x' y' + p_2(r^2 + 2 x'^2) + s_1 r^2 + s_2 r^4 \\ y'' = y' \frac{1 + k_1 r^2 + k_2 r^4 + k_3 r^6}{1 + k_4 r^2 + k_5 r^4 + k_6 r^6} + p_1 (r^2 + 2 y'^2) + 2 p_2 x' y' + s_1 r^2 + s_2 r^4 \\ \text{where} \quad r^2 = x'^2 + y'^2 \\ u = f_x*x'' + c_x \\ v = f_y*y'' + c_y \end{array}
-
-:math:`k_1`,
-:math:`k_2`,
-:math:`k_3`,
-:math:`k_4`,
-:math:`k_5`, and
-:math:`k_6` are radial distortion coefficients.
-:math:`p_1` and
-:math:`p_2` are tangential distortion coefficients.
-:math:`s_1`,
-:math:`s_2`,
-:math:`s_3`, and
-:math:`s_4`, are the thin prism distortion coefficients.
-Higher-order coefficients are not considered in OpenCV. In the functions below the coefficients are passed or returned as
-
-.. math::
-
- (k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])
-
-vector. That is, if the vector contains four elements, it means that
-:math:`k_3=0` .
-The distortion coefficients do not depend on the scene viewed. Thus, they also belong to the intrinsic camera parameters. And they remain the same regardless of the captured image resolution.
-If, for example, a camera has been calibrated on images of
-``320 x 240`` resolution, absolutely the same distortion coefficients can
-be used for ``640 x 480`` images from the same camera while
-:math:`f_x`,
-:math:`f_y`,
-:math:`c_x`, and
-:math:`c_y` need to be scaled appropriately.
-
-The functions below use the above model to do the following:
-
- * Project 3D points to the image plane given intrinsic and extrinsic parameters.
-
- * Compute extrinsic parameters given intrinsic parameters, a few 3D points, and their projections.
-
- * Estimate intrinsic and extrinsic camera parameters from several views of a known calibration pattern (every view is described by several 3D-2D point correspondences).
-
- * Estimate the relative position and orientation of the stereo camera "heads" and compute the *rectification* transformation that makes the camera optical axes parallel.
-
-.. note::
-
- * A calibration sample for 3 cameras in horizontal position can be found at opencv_source_code/samples/cpp/3calibration.cpp
- * A calibration sample based on a sequence of images can be found at opencv_source_code/samples/cpp/calibration.cpp
- * A calibration sample in order to do 3D reconstruction can be found at opencv_source_code/samples/cpp/build3dmodel.cpp
- * A calibration sample of an artificially generated camera and chessboard patterns can be found at opencv_source_code/samples/cpp/calibration_artificial.cpp
- * A calibration example on stereo calibration can be found at opencv_source_code/samples/cpp/stereo_calib.cpp
- * A calibration example on stereo matching can be found at opencv_source_code/samples/cpp/stereo_match.cpp
-
- * (Python) A camera calibration sample can be found at opencv_source_code/samples/python2/calibrate.py
-
-calibrateCamera
----------------
-Finds the camera intrinsic and extrinsic parameters from several views of a calibration pattern.
-
-.. ocv:function:: double calibrateCamera( InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints, Size imageSize, InputOutputArray cameraMatrix, InputOutputArray distCoeffs, OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, int flags=0, TermCriteria criteria=TermCriteria( TermCriteria::COUNT + TermCriteria::EPS, 30, DBL_EPSILON) )
-
-.. ocv:pyfunction:: cv2.calibrateCamera(objectPoints, imagePoints, imageSize, cameraMatrix, distCoeffs[, rvecs[, tvecs[, flags[, criteria]]]]) -> retval, cameraMatrix, distCoeffs, rvecs, tvecs
-
-.. ocv:cfunction:: double cvCalibrateCamera2( const CvMat* object_points, const CvMat* image_points, const CvMat* point_counts, CvSize image_size, CvMat* camera_matrix, CvMat* distortion_coeffs, CvMat* rotation_vectors=NULL, CvMat* translation_vectors=NULL, int flags=0, CvTermCriteria term_crit=cvTermCriteria( CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,DBL_EPSILON) )
-
- :param objectPoints: In the new interface it is a vector of vectors of calibration pattern points in the calibration pattern coordinate space. The outer vector contains as many elements as the number of the pattern views. If the same calibration pattern is shown in each view and it is fully visible, all the vectors will be the same. Although, it is possible to use partially occluded patterns, or even different patterns in different views. Then, the vectors will be different. The points are 3D, but since they are in a pattern coordinate system, then, if the rig is planar, it may make sense to put the model to a XY coordinate plane so that Z-coordinate of each input object point is 0.
-
- In the old interface all the vectors of object points from different views are concatenated together.
-
- :param imagePoints: In the new interface it is a vector of vectors of the projections of calibration pattern points. ``imagePoints.size()`` and ``objectPoints.size()`` and ``imagePoints[i].size()`` must be equal to ``objectPoints[i].size()`` for each ``i``.
-
- In the old interface all the vectors of object points from different views are concatenated together.
-
- :param point_counts: In the old interface this is a vector of integers, containing as many elements, as the number of views of the calibration pattern. Each element is the number of points in each view. Usually, all the elements are the same and equal to the number of feature points on the calibration pattern.
-
- :param imageSize: Size of the image used only to initialize the intrinsic camera matrix.
-
- :param cameraMatrix: Output 3x3 floating-point camera matrix :math:`A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}` . If ``CV_CALIB_USE_INTRINSIC_GUESS`` and/or ``CV_CALIB_FIX_ASPECT_RATIO`` are specified, some or all of ``fx, fy, cx, cy`` must be initialized before calling the function.
-
- :param distCoeffs: Output vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])` of 4, 5, 8 or 12 elements.
-
- :param rvecs: Output vector of rotation vectors (see :ocv:func:`Rodrigues` ) estimated for each pattern view. That is, each k-th rotation vector together with the corresponding k-th translation vector (see the next output parameter description) brings the calibration pattern from the model coordinate space (in which object points are specified) to the world coordinate space, that is, a real position of the calibration pattern in the k-th pattern view (k=0.. *M* -1).
-
- :param tvecs: Output vector of translation vectors estimated for each pattern view.
-
- :param flags: Different flags that may be zero or a combination of the following values:
-
- * **CV_CALIB_USE_INTRINSIC_GUESS** ``cameraMatrix`` contains valid initial values of ``fx, fy, cx, cy`` that are optimized further. Otherwise, ``(cx, cy)`` is initially set to the image center ( ``imageSize`` is used), and focal distances are computed in a least-squares fashion. Note, that if intrinsic parameters are known, there is no need to use this function just to estimate extrinsic parameters. Use :ocv:func:`solvePnP` instead.
-
- * **CV_CALIB_FIX_PRINCIPAL_POINT** The principal point is not changed during the global optimization. It stays at the center or at a different location specified when ``CV_CALIB_USE_INTRINSIC_GUESS`` is set too.
-
- * **CV_CALIB_FIX_ASPECT_RATIO** The functions considers only ``fy`` as a free parameter. The ratio ``fx/fy`` stays the same as in the input ``cameraMatrix`` . When ``CV_CALIB_USE_INTRINSIC_GUESS`` is not set, the actual input values of ``fx`` and ``fy`` are ignored, only their ratio is computed and used further.
-
- * **CV_CALIB_ZERO_TANGENT_DIST** Tangential distortion coefficients :math:`(p_1, p_2)` are set to zeros and stay zero.
-
- * **CV_CALIB_FIX_K1,...,CV_CALIB_FIX_K6** The corresponding radial distortion coefficient is not changed during the optimization. If ``CV_CALIB_USE_INTRINSIC_GUESS`` is set, the coefficient from the supplied ``distCoeffs`` matrix is used. Otherwise, it is set to 0.
-
- * **CV_CALIB_RATIONAL_MODEL** Coefficients k4, k5, and k6 are enabled. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the rational model and return 8 coefficients. If the flag is not set, the function computes and returns only 5 distortion coefficients.
-
- * **CALIB_THIN_PRISM_MODEL** Coefficients s1, s2, s3 and s4 are enabled. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the thin prism model and return 12 coefficients. If the flag is not set, the function computes and returns only 5 distortion coefficients.
-
- * **CALIB_FIX_S1_S2_S3_S4** The thin prism distortion coefficients are not changed during the optimization. If ``CV_CALIB_USE_INTRINSIC_GUESS`` is set, the coefficient from the supplied ``distCoeffs`` matrix is used. Otherwise, it is set to 0.
-
-
- :param criteria: Termination criteria for the iterative optimization algorithm.
-
- :param term_crit: same as ``criteria``.
-
-The function estimates the intrinsic camera
-parameters and extrinsic parameters for each of the views. The algorithm is based on [Zhang2000]_ and [BouguetMCT]_. The coordinates of 3D object points and their corresponding 2D projections
-in each view must be specified. That may be achieved by using an
-object with a known geometry and easily detectable feature points.
-Such an object is called a calibration rig or calibration pattern,
-and OpenCV has built-in support for a chessboard as a calibration
-rig (see
-:ocv:func:`findChessboardCorners` ). Currently, initialization
-of intrinsic parameters (when ``CV_CALIB_USE_INTRINSIC_GUESS`` is not set) is only implemented for planar calibration patterns
-(where Z-coordinates of the object points must be all zeros). 3D
-calibration rigs can also be used as long as initial ``cameraMatrix`` is provided.
-
-The algorithm performs the following steps:
-
-#.
- Compute the initial intrinsic parameters (the option only available for planar calibration patterns) or read them from the input parameters. The distortion coefficients are all set to zeros initially unless some of ``CV_CALIB_FIX_K?`` are specified.
-
-#.
- Estimate the initial camera pose as if the intrinsic parameters have been already known. This is done using
- :ocv:func:`solvePnP` .
-#.
- Run the global Levenberg-Marquardt optimization algorithm to minimize the reprojection error, that is, the total sum of squared distances between the observed feature points ``imagePoints`` and the projected (using the current estimates for camera parameters and the poses) object points ``objectPoints``. See :ocv:func:`projectPoints` for details.
-
-The function returns the final re-projection error.
-
-.. note::
-
- If you use a non-square (=non-NxN) grid and :ocv:func:`findChessboardCorners` for calibration, and ``calibrateCamera`` returns bad values (zero distortion coefficients, an image center very far from ``(w/2-0.5,h/2-0.5)``, and/or large differences between :math:`f_x` and :math:`f_y` (ratios of 10:1 or more)), then you have probably used ``patternSize=cvSize(rows,cols)`` instead of using ``patternSize=cvSize(cols,rows)`` in :ocv:func:`findChessboardCorners` .
-
-.. seealso::
-
- :ocv:func:`findChessboardCorners`,
- :ocv:func:`solvePnP`,
- :ocv:func:`initCameraMatrix2D`,
- :ocv:func:`stereoCalibrate`,
- :ocv:func:`undistort`
-
-
-
-calibrationMatrixValues
------------------------
-Computes useful camera characteristics from the camera matrix.
-
-.. ocv:function:: void calibrationMatrixValues( InputArray cameraMatrix, Size imageSize, double apertureWidth, double apertureHeight, double& fovx, double& fovy, double& focalLength, Point2d& principalPoint, double& aspectRatio )
-
-.. ocv:pyfunction:: cv2.calibrationMatrixValues(cameraMatrix, imageSize, apertureWidth, apertureHeight) -> fovx, fovy, focalLength, principalPoint, aspectRatio
-
- :param cameraMatrix: Input camera matrix that can be estimated by :ocv:func:`calibrateCamera` or :ocv:func:`stereoCalibrate` .
-
- :param imageSize: Input image size in pixels.
-
- :param apertureWidth: Physical width in mm of the sensor.
-
- :param apertureHeight: Physical height in mm of the sensor.
-
- :param fovx: Output field of view in degrees along the horizontal sensor axis.
-
- :param fovy: Output field of view in degrees along the vertical sensor axis.
-
- :param focalLength: Focal length of the lens in mm.
-
- :param principalPoint: Principal point in mm.
-
- :param aspectRatio: :math:`f_y/f_x`
-
-The function computes various useful camera characteristics from the previously estimated camera matrix.
-
-.. note::
-
- Do keep in mind that the unity measure 'mm' stands for whatever unit of measure one chooses for the chessboard pitch (it can thus be any value).
-
-composeRT
--------------
-Combines two rotation-and-shift transformations.
-
-.. ocv:function:: void composeRT( InputArray rvec1, InputArray tvec1, InputArray rvec2, InputArray tvec2, OutputArray rvec3, OutputArray tvec3, OutputArray dr3dr1=noArray(), OutputArray dr3dt1=noArray(), OutputArray dr3dr2=noArray(), OutputArray dr3dt2=noArray(), OutputArray dt3dr1=noArray(), OutputArray dt3dt1=noArray(), OutputArray dt3dr2=noArray(), OutputArray dt3dt2=noArray() )
-
-.. ocv:pyfunction:: cv2.composeRT(rvec1, tvec1, rvec2, tvec2[, rvec3[, tvec3[, dr3dr1[, dr3dt1[, dr3dr2[, dr3dt2[, dt3dr1[, dt3dt1[, dt3dr2[, dt3dt2]]]]]]]]]]) -> rvec3, tvec3, dr3dr1, dr3dt1, dr3dr2, dr3dt2, dt3dr1, dt3dt1, dt3dr2, dt3dt2
-
- :param rvec1: First rotation vector.
-
- :param tvec1: First translation vector.
-
- :param rvec2: Second rotation vector.
-
- :param tvec2: Second translation vector.
-
- :param rvec3: Output rotation vector of the superposition.
-
- :param tvec3: Output translation vector of the superposition.
-
- :param d*d*: Optional output derivatives of ``rvec3`` or ``tvec3`` with regard to ``rvec1``, ``rvec2``, ``tvec1`` and ``tvec2``, respectively.
-
-The functions compute:
-
-.. math::
-
- \begin{array}{l} \texttt{rvec3} = \mathrm{rodrigues} ^{-1} \left ( \mathrm{rodrigues} ( \texttt{rvec2} ) \cdot \mathrm{rodrigues} ( \texttt{rvec1} ) \right ) \\ \texttt{tvec3} = \mathrm{rodrigues} ( \texttt{rvec2} ) \cdot \texttt{tvec1} + \texttt{tvec2} \end{array} ,
-
-where :math:`\mathrm{rodrigues}` denotes a rotation vector to a rotation matrix transformation, and
-:math:`\mathrm{rodrigues}^{-1}` denotes the inverse transformation. See :ocv:func:`Rodrigues` for details.
-
-Also, the functions can compute the derivatives of the output vectors with regards to the input vectors (see :ocv:func:`matMulDeriv` ).
-The functions are used inside :ocv:func:`stereoCalibrate` but can also be used in your own code where Levenberg-Marquardt or another gradient-based solver is used to optimize a function that contains a matrix multiplication.
-
-
-
-computeCorrespondEpilines
------------------------------
-For points in an image of a stereo pair, computes the corresponding epilines in the other image.
-
-.. ocv:function:: void computeCorrespondEpilines( InputArray points, int whichImage, InputArray F, OutputArray lines )
-
-.. ocv:cfunction:: void cvComputeCorrespondEpilines( const CvMat* points, int which_image, const CvMat* fundamental_matrix, CvMat* correspondent_lines )
-
-.. ocv:pyfunction:: cv2.computeCorrespondEpilines(points, whichImage, F[, lines]) -> lines
-
- :param points: Input points. :math:`N \times 1` or :math:`1 \times N` matrix of type ``CV_32FC2`` or ``vector<Point2f>`` .
-
- :param whichImage: Index of the image (1 or 2) that contains the ``points`` .
-
- :param F: Fundamental matrix that can be estimated using :ocv:func:`findFundamentalMat` or :ocv:func:`stereoRectify` .
-
- :param lines: Output vector of the epipolar lines corresponding to the points in the other image. Each line :math:`ax + by + c=0` is encoded by 3 numbers :math:`(a, b, c)` .
-
-For every point in one of the two images of a stereo pair, the function finds the equation of the
-corresponding epipolar line in the other image.
-
-From the fundamental matrix definition (see
-:ocv:func:`findFundamentalMat` ),
-line
-:math:`l^{(2)}_i` in the second image for the point
-:math:`p^{(1)}_i` in the first image (when ``whichImage=1`` ) is computed as:
-
-.. math::
-
- l^{(2)}_i = F p^{(1)}_i
-
-And vice versa, when ``whichImage=2``,
-:math:`l^{(1)}_i` is computed from
-:math:`p^{(2)}_i` as:
-
-.. math::
-
- l^{(1)}_i = F^T p^{(2)}_i
-
-Line coefficients are defined up to a scale. They are normalized so that
-:math:`a_i^2+b_i^2=1` .
-
-
-
-convertPointsToHomogeneous
---------------------------
-Converts points from Euclidean to homogeneous space.
-
-.. ocv:function:: void convertPointsToHomogeneous( InputArray src, OutputArray dst )
-
-.. ocv:pyfunction:: cv2.convertPointsToHomogeneous(src[, dst]) -> dst
-
- :param src: Input vector of ``N``-dimensional points.
-
- :param dst: Output vector of ``N+1``-dimensional points.
-
-The function converts points from Euclidean to homogeneous space by appending 1's to the tuple of point coordinates. That is, each point ``(x1, x2, ..., xn)`` is converted to ``(x1, x2, ..., xn, 1)``.
-
-
-
-convertPointsFromHomogeneous
-----------------------------
-Converts points from homogeneous to Euclidean space.
-
-.. ocv:function:: void convertPointsFromHomogeneous( InputArray src, OutputArray dst )
-
-.. ocv:pyfunction:: cv2.convertPointsFromHomogeneous(src[, dst]) -> dst
-
- :param src: Input vector of ``N``-dimensional points.
-
- :param dst: Output vector of ``N-1``-dimensional points.
-
-The function converts points homogeneous to Euclidean space using perspective projection. That is, each point ``(x1, x2, ... x(n-1), xn)`` is converted to ``(x1/xn, x2/xn, ..., x(n-1)/xn)``. When ``xn=0``, the output point coordinates will be ``(0,0,0,...)``.
-
-
-
-convertPointsHomogeneous
-------------------------
-Converts points to/from homogeneous coordinates.
-
-.. ocv:function:: void convertPointsHomogeneous( InputArray src, OutputArray dst )
-
-.. ocv:cfunction:: void cvConvertPointsHomogeneous( const CvMat* src, CvMat* dst )
-
- :param src: Input array or vector of 2D, 3D, or 4D points.
-
- :param dst: Output vector of 2D, 3D, or 4D points.
-
-The function converts 2D or 3D points from/to homogeneous coordinates by calling either :ocv:func:`convertPointsToHomogeneous` or :ocv:func:`convertPointsFromHomogeneous`.
-
-.. note:: The function is obsolete. Use one of the previous two functions instead.
-
-
-
-correctMatches
---------------
-Refines coordinates of corresponding points.
-
-.. ocv:function:: void correctMatches( InputArray F, InputArray points1, InputArray points2, OutputArray newPoints1, OutputArray newPoints2 )
-
-.. ocv:pyfunction:: cv2.correctMatches(F, points1, points2[, newPoints1[, newPoints2]]) -> newPoints1, newPoints2
-
-.. ocv:cfunction:: void cvCorrectMatches( CvMat* F, CvMat* points1, CvMat* points2, CvMat* new_points1, CvMat* new_points2 )
-
- :param F: 3x3 fundamental matrix.
-
- :param points1: 1xN array containing the first set of points.
-
- :param points2: 1xN array containing the second set of points.
-
- :param newPoints1: The optimized points1.
-
- :param newPoints2: The optimized points2.
-
-The function implements the Optimal Triangulation Method (see Multiple View Geometry for details). For each given point correspondence points1[i] <-> points2[i], and a fundamental matrix F, it computes the corrected correspondences newPoints1[i] <-> newPoints2[i] that minimize the geometric error :math:`d(points1[i], newPoints1[i])^2 + d(points2[i],newPoints2[i])^2` (where :math:`d(a,b)` is the geometric distance between points :math:`a` and :math:`b` ) subject to the epipolar constraint :math:`newPoints2^T * F * newPoints1 = 0` .
-
-
-
-decomposeProjectionMatrix
---------------------------
-Decomposes a projection matrix into a rotation matrix and a camera matrix.
-
-.. ocv:function:: void decomposeProjectionMatrix( InputArray projMatrix, OutputArray cameraMatrix, OutputArray rotMatrix, OutputArray transVect, OutputArray rotMatrixX=noArray(), OutputArray rotMatrixY=noArray(), OutputArray rotMatrixZ=noArray(), OutputArray eulerAngles=noArray() )
-
-.. ocv:pyfunction:: cv2.decomposeProjectionMatrix(projMatrix[, cameraMatrix[, rotMatrix[, transVect[, rotMatrixX[, rotMatrixY[, rotMatrixZ[, eulerAngles]]]]]]]) -> cameraMatrix, rotMatrix, transVect, rotMatrixX, rotMatrixY, rotMatrixZ, eulerAngles
-
-.. ocv:cfunction:: void cvDecomposeProjectionMatrix( const CvMat * projMatr, CvMat * calibMatr, CvMat * rotMatr, CvMat * posVect, CvMat * rotMatrX=NULL, CvMat * rotMatrY=NULL, CvMat * rotMatrZ=NULL, CvPoint3D64f * eulerAngles=NULL )
-
- :param projMatrix: 3x4 input projection matrix P.
-
- :param cameraMatrix: Output 3x3 camera matrix K.
-
- :param rotMatrix: Output 3x3 external rotation matrix R.
-
- :param transVect: Output 4x1 translation vector T.
-
- :param rotMatrX: Optional 3x3 rotation matrix around x-axis.
-
- :param rotMatrY: Optional 3x3 rotation matrix around y-axis.
-
- :param rotMatrZ: Optional 3x3 rotation matrix around z-axis.
-
- :param eulerAngles: Optional three-element vector containing three Euler angles of rotation in degrees.
-
-The function computes a decomposition of a projection matrix into a calibration and a rotation matrix and the position of a camera.
-
-It optionally returns three rotation matrices, one for each axis, and three Euler angles that could be used in OpenGL. Note, there is always more than one sequence of rotations about the three principle axes that results in the same orientation of an object, eg. see [Slabaugh]_. Returned tree rotation matrices and corresponding three Euler angules are only one of the possible solutions.
-
-The function is based on
-:ocv:func:`RQDecomp3x3` .
-
-
-
-drawChessboardCorners
--------------------------
-Renders the detected chessboard corners.
-
-.. ocv:function:: void drawChessboardCorners( InputOutputArray image, Size patternSize, InputArray corners, bool patternWasFound )
-
-.. ocv:pyfunction:: cv2.drawChessboardCorners(image, patternSize, corners, patternWasFound) -> image
-
-.. ocv:cfunction:: void cvDrawChessboardCorners( CvArr* image, CvSize pattern_size, CvPoint2D32f* corners, int count, int pattern_was_found )
-
- :param image: Destination image. It must be an 8-bit color image.
-
- :param patternSize: Number of inner corners per a chessboard row and column ``(patternSize = cv::Size(points_per_row,points_per_column))``.
-
- :param corners: Array of detected corners, the output of ``findChessboardCorners``.
-
- :param patternWasFound: Parameter indicating whether the complete board was found or not. The return value of :ocv:func:`findChessboardCorners` should be passed here.
-
-The function draws individual chessboard corners detected either as red circles if the board was not found, or as colored corners connected with lines if the board was found.
-
-
-
-findChessboardCorners
--------------------------
-Finds the positions of internal corners of the chessboard.
-
-.. ocv:function:: bool findChessboardCorners( InputArray image, Size patternSize, OutputArray corners, int flags=CALIB_CB_ADAPTIVE_THRESH + CALIB_CB_NORMALIZE_IMAGE )
-
-.. ocv:pyfunction:: cv2.findChessboardCorners(image, patternSize[, corners[, flags]]) -> retval, corners
-
-.. ocv:cfunction:: int cvFindChessboardCorners( const void* image, CvSize pattern_size, CvPoint2D32f* corners, int* corner_count=NULL, int flags=CV_CALIB_CB_ADAPTIVE_THRESH+CV_CALIB_CB_NORMALIZE_IMAGE )
-
- :param image: Source chessboard view. It must be an 8-bit grayscale or color image.
-
- :param patternSize: Number of inner corners per a chessboard row and column ``( patternSize = cvSize(points_per_row,points_per_colum) = cvSize(columns,rows) )``.
-
- :param corners: Output array of detected corners.
-
- :param flags: Various operation flags that can be zero or a combination of the following values:
-
- * **CV_CALIB_CB_ADAPTIVE_THRESH** Use adaptive thresholding to convert the image to black and white, rather than a fixed threshold level (computed from the average image brightness).
-
- * **CV_CALIB_CB_NORMALIZE_IMAGE** Normalize the image gamma with :ocv:func:`equalizeHist` before applying fixed or adaptive thresholding.
-
- * **CV_CALIB_CB_FILTER_QUADS** Use additional criteria (like contour area, perimeter, square-like shape) to filter out false quads extracted at the contour retrieval stage.
-
- * **CALIB_CB_FAST_CHECK** Run a fast check on the image that looks for chessboard corners, and shortcut the call if none is found. This can drastically speed up the call in the degenerate condition when no chessboard is observed.
-
-The function attempts to determine
-whether the input image is a view of the chessboard pattern and
-locate the internal chessboard corners. The function returns a non-zero
-value if all of the corners are found and they are placed
-in a certain order (row by row, left to right in every row). Otherwise, if the function fails to find all the corners or reorder
-them, it returns 0. For example, a regular chessboard has 8 x 8
-squares and 7 x 7 internal corners, that is, points where the black squares touch each other.
-The detected coordinates are approximate, and to determine their positions more accurately, the function calls :ocv:func:`cornerSubPix`.
-You also may use the function :ocv:func:`cornerSubPix` with different parameters if returned coordinates are not accurate enough.
-
-Sample usage of detecting and drawing chessboard corners: ::
-
- Size patternsize(8,6); //interior number of corners
- Mat gray = ....; //source image
- vector<Point2f> corners; //this will be filled by the detected corners
-
- //CALIB_CB_FAST_CHECK saves a lot of time on images
- //that do not contain any chessboard corners
- bool patternfound = findChessboardCorners(gray, patternsize, corners,
- CALIB_CB_ADAPTIVE_THRESH + CALIB_CB_NORMALIZE_IMAGE
- + CALIB_CB_FAST_CHECK);
-
- if(patternfound)
- cornerSubPix(gray, corners, Size(11, 11), Size(-1, -1),
- TermCriteria(CV_TERMCRIT_EPS + CV_TERMCRIT_ITER, 30, 0.1));
-
- drawChessboardCorners(img, patternsize, Mat(corners), patternfound);
-
-.. note:: The function requires white space (like a square-thick border, the wider the better) around the board to make the detection more robust in various environments. Otherwise, if there is no border and the background is dark, the outer black squares cannot be segmented properly and so the square grouping and ordering algorithm fails.
-
-
-
-findCirclesGrid
--------------------
-Finds centers in the grid of circles.
-
-.. ocv:function:: bool findCirclesGrid( InputArray image, Size patternSize, OutputArray centers, int flags=CALIB_CB_SYMMETRIC_GRID, const Ptr<FeatureDetector> &blobDetector = makePtr<SimpleBlobDetector>() )
-
-.. ocv:pyfunction:: cv2.findCirclesGrid(image, patternSize[, centers[, flags[, blobDetector]]]) -> retval, centers
-
- :param image: grid view of input circles; it must be an 8-bit grayscale or color image.
-
- :param patternSize: number of circles per row and column ``( patternSize = Size(points_per_row, points_per_colum) )``.
-
- :param centers: output array of detected centers.
-
- :param flags: various operation flags that can be one of the following values:
-
- * **CALIB_CB_SYMMETRIC_GRID** uses symmetric pattern of circles.
-
- * **CALIB_CB_ASYMMETRIC_GRID** uses asymmetric pattern of circles.
-
- * **CALIB_CB_CLUSTERING** uses a special algorithm for grid detection. It is more robust to perspective distortions but much more sensitive to background clutter.
-
- :param blobDetector: feature detector that finds blobs like dark circles on light background.
-
-
-The function attempts to determine
-whether the input image contains a grid of circles. If it is, the function locates centers of the circles. The function returns a
-non-zero value if all of the centers have been found and they have been placed
-in a certain order (row by row, left to right in every row). Otherwise, if the function fails to find all the corners or reorder
-them, it returns 0.
-
-Sample usage of detecting and drawing the centers of circles: ::
-
- Size patternsize(7,7); //number of centers
- Mat gray = ....; //source image
- vector<Point2f> centers; //this will be filled by the detected centers
-
- bool patternfound = findCirclesGrid(gray, patternsize, centers);
-
- drawChessboardCorners(img, patternsize, Mat(centers), patternfound);
-
-.. note:: The function requires white space (like a square-thick border, the wider the better) around the board to make the detection more robust in various environments.
-
-
-
-solvePnP
-------------
-Finds an object pose from 3D-2D point correspondences.
-
-.. ocv:function:: bool solvePnP( InputArray objectPoints, InputArray imagePoints, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess=false, int flags=SOLVEPNP_ITERATIVE )
-
-.. ocv:pyfunction:: cv2.solvePnP(objectPoints, imagePoints, cameraMatrix, distCoeffs[, rvec[, tvec[, useExtrinsicGuess[, flags]]]]) -> retval, rvec, tvec
-
-.. ocv:cfunction:: void cvFindExtrinsicCameraParams2( const CvMat* object_points, const CvMat* image_points, const CvMat* camera_matrix, const CvMat* distortion_coeffs, CvMat* rotation_vector, CvMat* translation_vector, int use_extrinsic_guess=0 )
-
- :param objectPoints: Array of object points in the object coordinate space, 3xN/Nx3 1-channel or 1xN/Nx1 3-channel, where N is the number of points. ``vector<Point3f>`` can be also passed here.
-
- :param imagePoints: Array of corresponding image points, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel, where N is the number of points. ``vector<Point2f>`` can be also passed here.
-
- :param cameraMatrix: Input camera matrix :math:`A = \vecthreethree{fx}{0}{cx}{0}{fy}{cy}{0}{0}{1}` .
-
- :param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])` of 4, 5, 8 or 12 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
-
- :param rvec: Output rotation vector (see :ocv:func:`Rodrigues` ) that, together with ``tvec`` , brings points from the model coordinate system to the camera coordinate system.
-
- :param tvec: Output translation vector.
-
- :param useExtrinsicGuess: Parameter used for SOLVEPNP_ITERATIVE. If true (1), the function uses the provided ``rvec`` and ``tvec`` values as initial approximations of the rotation and translation vectors, respectively, and further optimizes them.
-
- :param flags: Method for solving a PnP problem:
-
- * **SOLVEPNP_ITERATIVE** Iterative method is based on Levenberg-Marquardt optimization. In this case the function finds such a pose that minimizes reprojection error, that is the sum of squared distances between the observed projections ``imagePoints`` and the projected (using :ocv:func:`projectPoints` ) ``objectPoints`` .
- * **SOLVEPNP_P3P** Method is based on the paper of X.S. Gao, X.-R. Hou, J. Tang, H.-F. Chang "Complete Solution Classification for the Perspective-Three-Point Problem". In this case the function requires exactly four object and image points.
- * **SOLVEPNP_EPNP** Method has been introduced by F.Moreno-Noguer, V.Lepetit and P.Fua in the paper "EPnP: Efficient Perspective-n-Point Camera Pose Estimation".
- * **SOLVEPNP_DLS** Method is based on the paper of Joel A. Hesch and Stergios I. Roumeliotis. "A Direct Least-Squares (DLS) Method for PnP".
- * **SOLVEPNP_UPNP** Method is based on the paper of A.Penate-Sanchez, J.Andrade-Cetto, F.Moreno-Noguer. "Exhaustive Linearization for Robust Camera Pose and Focal Length Estimation". In this case the function also estimates the parameters :math:`f_x` and :math:`f_y` assuming that both have the same value. Then the ``cameraMatrix`` is updated with the estimated focal length.
-
-The function estimates the object pose given a set of object points, their corresponding image projections, as well as the camera matrix and the distortion coefficients.
-
-.. note::
-
- * An example of how to use solvePnP for planar augmented reality can be found at opencv_source_code/samples/python2/plane_ar.py
-
-solvePnPRansac
-------------------
-Finds an object pose from 3D-2D point correspondences using the RANSAC scheme.
-
-.. ocv:function:: bool solvePnPRansac( InputArray objectPoints, InputArray imagePoints, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess=false, int iterationsCount = 100, float reprojectionError = 8.0, double confidence = 0.99, OutputArray inliers = noArray(), int flags = SOLVEPNP_ITERATIVE )
-
-.. ocv:pyfunction:: cv2.solvePnPRansac(objectPoints, imagePoints, cameraMatrix, distCoeffs[, rvec[, tvec[, useExtrinsicGuess[, iterationsCount[, reprojectionError[, minInliersCount[, inliers[, flags]]]]]]]]) -> rvec, tvec, inliers
-
- :param objectPoints: Array of object points in the object coordinate space, 3xN/Nx3 1-channel or 1xN/Nx1 3-channel, where N is the number of points. ``vector<Point3f>`` can be also passed here.
-
- :param imagePoints: Array of corresponding image points, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel, where N is the number of points. ``vector<Point2f>`` can be also passed here.
-
- :param cameraMatrix: Input camera matrix :math:`A = \vecthreethree{fx}{0}{cx}{0}{fy}{cy}{0}{0}{1}` .
-
- :param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])` of 4, 5, 8 or 12 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
-
- :param rvec: Output rotation vector (see :ocv:func:`Rodrigues` ) that, together with ``tvec`` , brings points from the model coordinate system to the camera coordinate system.
-
- :param tvec: Output translation vector.
-
- :param useExtrinsicGuess: Parameter used for SOLVEPNP_ITERATIVE. If true (1), the function uses the provided ``rvec`` and ``tvec`` values as initial approximations of the rotation and translation vectors, respectively, and further optimizes them.
-
- :param iterationsCount: Number of iterations.
-
- :param reprojectionError: Inlier threshold value used by the RANSAC procedure. The parameter value is the maximum allowed distance between the observed and computed point projections to consider it an inlier.
-
- :param confidence: The probability that the algorithm produces a useful result.
-
- :param inliers: Output vector that contains indices of inliers in ``objectPoints`` and ``imagePoints`` .
-
- :param flags: Method for solving a PnP problem (see :ocv:func:`solvePnP` ).
-
-The function estimates an object pose given a set of object points, their corresponding image projections, as well as the camera matrix and the distortion coefficients. This function finds such a pose that minimizes reprojection error, that is, the sum of squared distances between the observed projections ``imagePoints`` and the projected (using
-:ocv:func:`projectPoints` ) ``objectPoints``. The use of RANSAC makes the function resistant to outliers.
-
-.. note::
-
- * An example of how to use solvePNPRansac for object detection can be found at opencv_source_code/samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/
-
-
-findFundamentalMat
-----------------------
-Calculates a fundamental matrix from the corresponding points in two images.
-
-.. ocv:function:: Mat findFundamentalMat( InputArray points1, InputArray points2, int method=FM_RANSAC, double param1=3., double param2=0.99, OutputArray mask=noArray() )
-
-.. ocv:pyfunction:: cv2.findFundamentalMat(points1, points2[, method[, param1[, param2[, mask]]]]) -> retval, mask
-
-.. ocv:cfunction:: int cvFindFundamentalMat( const CvMat* points1, const CvMat* points2, CvMat* fundamental_matrix, int method=CV_FM_RANSAC, double param1=3., double param2=0.99, CvMat* status=NULL )
-
- :param points1: Array of ``N`` points from the first image. The point coordinates should be floating-point (single or double precision).
-
- :param points2: Array of the second image points of the same size and format as ``points1`` .
-
- :param method: Method for computing a fundamental matrix.
-
- * **CV_FM_7POINT** for a 7-point algorithm. :math:`N = 7`
- * **CV_FM_8POINT** for an 8-point algorithm. :math:`N \ge 8`
- * **CV_FM_RANSAC** for the RANSAC algorithm. :math:`N \ge 8`
- * **CV_FM_LMEDS** for the LMedS algorithm. :math:`N \ge 8`
-
- :param param1: Parameter used for RANSAC. It is the maximum distance from a point to an epipolar line in pixels, beyond which the point is considered an outlier and is not used for computing the final fundamental matrix. It can be set to something like 1-3, depending on the accuracy of the point localization, image resolution, and the image noise.
-
- :param param2: Parameter used for the RANSAC or LMedS methods only. It specifies a desirable level of confidence (probability) that the estimated matrix is correct.
-
- :param status: Output array of N elements, every element of which is set to 0 for outliers and to 1 for the other points. The array is computed only in the RANSAC and LMedS methods. For other methods, it is set to all 1's.
-
-The epipolar geometry is described by the following equation:
-
-.. math::
-
- [p_2; 1]^T F [p_1; 1] = 0
-
-where
-:math:`F` is a fundamental matrix,
-:math:`p_1` and
-:math:`p_2` are corresponding points in the first and the second images, respectively.
-
-The function calculates the fundamental matrix using one of four methods listed above and returns
-the found fundamental matrix. Normally just one matrix is found. But in case of the 7-point algorithm, the function may return up to 3 solutions (
-:math:`9 \times 3` matrix that stores all 3 matrices sequentially).
-
-The calculated fundamental matrix may be passed further to
-:ocv:func:`computeCorrespondEpilines` that finds the epipolar lines
-corresponding to the specified points. It can also be passed to
-:ocv:func:`stereoRectifyUncalibrated` to compute the rectification transformation. ::
-
- // Example. Estimation of fundamental matrix using the RANSAC algorithm
- int point_count = 100;
- vector<Point2f> points1(point_count);
- vector<Point2f> points2(point_count);
-
- // initialize the points here ... */
- for( int i = 0; i < point_count; i++ )
- {
- points1[i] = ...;
- points2[i] = ...;
- }
-
- Mat fundamental_matrix =
- findFundamentalMat(points1, points2, FM_RANSAC, 3, 0.99);
-
-findEssentialMat
-------------------
-Calculates an essential matrix from the corresponding points in two images.
-
-.. ocv:function:: Mat findEssentialMat( InputArray points1, InputArray points2, double focal=1.0, Point2d pp=Point2d(0, 0), int method=RANSAC, double prob=0.999, double threshold=1.0, OutputArray mask=noArray() )
-
- :param points1: Array of ``N`` ``(N >= 5)`` 2D points from the first image. The point coordinates should be floating-point (single or double precision).
-
- :param points2: Array of the second image points of the same size and format as ``points1`` .
-
- :param focal: focal length of the camera. Note that this function assumes that ``points1`` and ``points2`` are feature points from cameras with same focal length and principle point.
-
- :param pp: principle point of the camera.
-
- :param method: Method for computing a fundamental matrix.
-
- * **RANSAC** for the RANSAC algorithm.
- * **MEDS** for the LMedS algorithm.
-
- :param threshold: Parameter used for RANSAC. It is the maximum distance from a point to an epipolar line in pixels, beyond which the point is considered an outlier and is not used for computing the final fundamental matrix. It can be set to something like 1-3, depending on the accuracy of the point localization, image resolution, and the image noise.
-
- :param prob: Parameter used for the RANSAC or LMedS methods only. It specifies a desirable level of confidence (probability) that the estimated matrix is correct.
-
- :param mask: Output array of N elements, every element of which is set to 0 for outliers and to 1 for the other points. The array is computed only in the RANSAC and LMedS methods.
-
-This function estimates essential matrix based on the five-point algorithm solver in [Nister03]_. [SteweniusCFS]_ is also a related.
-The epipolar geometry is described by the following equation:
-
-.. math::
-
- [p_2; 1]^T K^T E K [p_1; 1] = 0 \\
-
- K =
- \begin{bmatrix}
- f & 0 & x_{pp} \\
- 0 & f & y_{pp} \\
- 0 & 0 & 1
- \end{bmatrix}
-
-where
-:math:`E` is an essential matrix,
-:math:`p_1` and
-:math:`p_2` are corresponding points in the first and the second images, respectively.
-The result of this function may be passed further to :ocv:func:`decomposeEssentialMat` or :ocv:func:`recoverPose` to recover the relative pose between cameras.
-
-decomposeEssentialMat
--------------------------
-Decompose an essential matrix to possible rotations and translation.
-
-.. ocv:function:: void decomposeEssentialMat( InputArray E, OutputArray R1, OutputArray R2, OutputArray t )
-
- :param E: The input essential matrix.
-
- :param R1: One possible rotation matrix.
-
- :param R2: Another possible rotation matrix.
-
- :param t: One possible translation.
-
-This function decompose an essential matrix ``E`` using svd decomposition [HartleyZ00]_. Generally 4 possible poses exists for a given ``E``.
-They are
-:math:`[R_1, t]`,
-:math:`[R_1, -t]`,
-:math:`[R_2, t]`,
-:math:`[R_2, -t]`.
-By decomposing ``E``, you can only get the direction of the translation, so the function returns unit ``t``.
-
-decomposeHomographyMat
---------------------------
-Decompose a homography matrix to rotation(s), translation(s) and plane normal(s).
-
-.. ocv:function:: int decomposeHomographyMat( InputArray H, InputArray K, OutputArrayOfArrays rotations, OutputArrayOfArrays translations, OutputArrayOfArrays normals)
-
- :param H: The input homography matrix between two images.
-
- :param K: The input intrinsic camera calibration matrix.
-
- :param rotations: Array of rotation matrices.
-
- :param translations: Array of translation matrices.
-
- :param normals: Array of plane normal matrices.
-
-This function extracts relative camera motion between two views observing a planar object from the homography ``H`` induced by the plane.
-The intrinsic camera matrix ``K`` must also be provided. The function may return up to four mathematical solution sets. At least two of the
-solutions may further be invalidated if point correspondences are available by applying positive depth constraint (all points must be in front of the camera).
-The decomposition method is described in detail in [Malis]_.
-
-
-recoverPose
----------------
-Recover relative camera rotation and translation from an estimated essential matrix and the corresponding points in two images, using cheirality check.
-Returns the number of inliers which pass the check.
-
-.. ocv:function:: int recoverPose( InputArray E, InputArray points1, InputArray points2, OutputArray R, OutputArray t, double focal = 1.0, Point2d pp = Point2d(0, 0), InputOutputArray mask = noArray())
-
- :param E: The input essential matrix.
-
- :param points1: Array of ``N`` 2D points from the first image. The point coordinates should be floating-point (single or double precision).
-
- :param points2: Array of the second image points of the same size and format as ``points1`` .
-
- :param R: Recovered relative rotation.
-
- :param t: Recoverd relative translation.
-
- :param focal: Focal length of the camera. Note that this function assumes that ``points1`` and ``points2`` are feature points from cameras with same focal length and principle point.
-
- :param pp: Principle point of the camera.
-
- :param mask: Input/output mask for inliers in ``points1`` and ``points2``.
- If it is not empty, then it marks inliers in ``points1`` and ``points2`` for then given essential matrix ``E``.
- Only these inliers will be used to recover pose.
- In the output mask only inliers which pass the cheirality check.
-
-This function decomposes an essential matrix using :ocv:func:`decomposeEssentialMat` and then verifies possible pose hypotheses by doing cheirality check.
-The cheirality check basically means that the triangulated 3D points should have positive depth. Some details can be found in [Nister03]_.
-
-This function can be used to process output ``E`` and ``mask`` from :ocv:func:`findEssentialMat`.
-In this scenario, ``points1`` and ``points2`` are the same input for :ocv:func:`findEssentialMat`. ::
-
- // Example. Estimation of fundamental matrix using the RANSAC algorithm
- int point_count = 100;
- vector<Point2f> points1(point_count);
- vector<Point2f> points2(point_count);
-
- // initialize the points here ... */
- for( int i = 0; i < point_count; i++ )
- {
- points1[i] = ...;
- points2[i] = ...;
- }
-
- double focal = 1.0;
- cv::Point2d pp(0.0, 0.0);
- Mat E, R, t, mask;
-
- E = findEssentialMat(points1, points2, focal, pp, RANSAC, 0.999, 1.0, mask);
- recoverPose(E, points1, points2, R, t, focal, pp, mask);
-
-
-
-findHomography
-------------------
-Finds a perspective transformation between two planes.
-
-.. ocv:function:: Mat findHomography( InputArray srcPoints, InputArray dstPoints, int method=0, double ransacReprojThreshold=3, OutputArray mask=noArray(), const int maxIters = 2000, const double confidence = 0.995)
-
-.. ocv:pyfunction:: cv2.findHomography(srcPoints, dstPoints[, method[, ransacReprojThreshold[, mask]]]) -> retval, mask
-
-.. ocv:cfunction:: int cvFindHomography( const CvMat* src_points, const CvMat* dst_points, CvMat* homography, int method=0, double ransacReprojThreshold=3, CvMat* mask=0, int maxIters = 2000, double confidence = 0.995)
-
- :param srcPoints: Coordinates of the points in the original plane, a matrix of the type ``CV_32FC2`` or ``vector<Point2f>`` .
-
- :param dstPoints: Coordinates of the points in the target plane, a matrix of the type ``CV_32FC2`` or a ``vector<Point2f>`` .
-
- :param method: Method used to computed a homography matrix. The following methods are possible:
-
- * **0** - a regular method using all the points
-
- * **RANSAC** - RANSAC-based robust method
-
- * **LMEDS** - Least-Median robust method
-
- :param ransacReprojThreshold: Maximum allowed reprojection error to treat a point pair as an inlier (used in the RANSAC method only). That is, if
-
- .. math::
-
- \| \texttt{dstPoints} _i - \texttt{convertPointsHomogeneous} ( \texttt{H} * \texttt{srcPoints} _i) \| > \texttt{ransacReprojThreshold}
-
- then the point :math:`i` is considered an outlier. If ``srcPoints`` and ``dstPoints`` are measured in pixels, it usually makes sense to set this parameter somewhere in the range of 1 to 10.
-
- :param mask: Optional output mask set by a robust method ( ``RANSAC`` or ``LMEDS`` ). Note that the input mask values are ignored.
-
- :param maxIters: The maximum number of RANSAC iterations, 2000 is the maximum it can be.
-
- :param confidence: Confidence level, between 0 and 1.
-
-The functions find and return the perspective transformation :math:`H` between the source and the destination planes:
-
-.. math::
-
- s_i \vecthree{x'_i}{y'_i}{1} \sim H \vecthree{x_i}{y_i}{1}
-
-so that the back-projection error
-
-.. math::
-
- \sum _i \left ( x'_i- \frac{h_{11} x_i + h_{12} y_i + h_{13}}{h_{31} x_i + h_{32} y_i + h_{33}} \right )^2+ \left ( y'_i- \frac{h_{21} x_i + h_{22} y_i + h_{23}}{h_{31} x_i + h_{32} y_i + h_{33}} \right )^2
-
-is minimized. If the parameter ``method`` is set to the default value 0, the function
-uses all the point pairs to compute an initial homography estimate with a simple least-squares scheme.
-
-However, if not all of the point pairs (
-:math:`srcPoints_i`, :math:`dstPoints_i` ) fit the rigid perspective transformation (that is, there
-are some outliers), this initial estimate will be poor.
-In this case, you can use one of the two robust methods. Both methods, ``RANSAC`` and ``LMeDS`` , try many different random subsets
-of the corresponding point pairs (of four pairs each), estimate
-the homography matrix using this subset and a simple least-square
-algorithm, and then compute the quality/goodness of the computed homography
-(which is the number of inliers for RANSAC or the median re-projection
-error for LMeDs). The best subset is then used to produce the initial
-estimate of the homography matrix and the mask of inliers/outliers.
-
-Regardless of the method, robust or not, the computed homography
-matrix is refined further (using inliers only in case of a robust
-method) with the Levenberg-Marquardt method to reduce the
-re-projection error even more.
-
-The method ``RANSAC`` can handle practically any ratio of outliers
-but it needs a threshold to distinguish inliers from outliers.
-The method ``LMeDS`` does not need any threshold but it works
-correctly only when there are more than 50% of inliers. Finally,
-if there are no outliers and the noise is rather small, use the default method (``method=0``).
-
-The function is used to find initial intrinsic and extrinsic matrices.
-Homography matrix is determined up to a scale. Thus, it is normalized so that
-:math:`h_{33}=1`. Note that whenever an H matrix cannot be estimated, an empty one will be returned.
-
-.. seealso::
-
- :ocv:func:`getAffineTransform`,
- :ocv:func:`getPerspectiveTransform`,
- :ocv:func:`estimateRigidTransform`,
- :ocv:func:`warpPerspective`,
- :ocv:func:`perspectiveTransform`
-
-.. note::
-
- * A example on calculating a homography for image matching can be found at opencv_source_code/samples/cpp/video_homography.cpp
-
-estimateAffine3D
---------------------
-Computes an optimal affine transformation between two 3D point sets.
-
-.. ocv:function:: int estimateAffine3D(InputArray src, InputArray dst, OutputArray out, OutputArray inliers, double ransacThreshold = 3, double confidence = 0.99)
-
-.. ocv:pyfunction:: cv2.estimateAffine3D(src, dst[, out[, inliers[, ransacThreshold[, confidence]]]]) -> retval, out, inliers
-
- :param src: First input 3D point set.
-
- :param dst: Second input 3D point set.
-
- :param out: Output 3D affine transformation matrix :math:`3 \times 4` .
-
- :param inliers: Output vector indicating which points are inliers.
-
- :param ransacThreshold: Maximum reprojection error in the RANSAC algorithm to consider a point as an inlier.
-
- :param confidence: Confidence level, between 0 and 1, for the estimated transformation. Anything between 0.95 and 0.99 is usually good enough. Values too close to 1 can slow down the estimation significantly. Values lower than 0.8-0.9 can result in an incorrectly estimated transformation.
-
-The function estimates an optimal 3D affine transformation between two 3D point sets using the RANSAC algorithm.
-
-
-filterSpeckles
---------------
-Filters off small noise blobs (speckles) in the disparity map
-
-.. ocv:function:: void filterSpeckles( InputOutputArray img, double newVal, int maxSpeckleSize, double maxDiff, InputOutputArray buf=noArray() )
-
-.. ocv:pyfunction:: cv2.filterSpeckles(img, newVal, maxSpeckleSize, maxDiff[, buf]) -> img, buf
-
- :param img: The input 16-bit signed disparity image
-
- :param newVal: The disparity value used to paint-off the speckles
-
- :param maxSpeckleSize: The maximum speckle size to consider it a speckle. Larger blobs are not affected by the algorithm
-
- :param maxDiff: Maximum difference between neighbor disparity pixels to put them into the same blob. Note that since StereoBM, StereoSGBM and may be other algorithms return a fixed-point disparity map, where disparity values are multiplied by 16, this scale factor should be taken into account when specifying this parameter value.
-
- :param buf: The optional temporary buffer to avoid memory allocation within the function.
-
-
-getOptimalNewCameraMatrix
------------------------------
-Returns the new camera matrix based on the free scaling parameter.
-
-.. ocv:function:: Mat getOptimalNewCameraMatrix( InputArray cameraMatrix, InputArray distCoeffs, Size imageSize, double alpha, Size newImgSize=Size(), Rect* validPixROI=0, bool centerPrincipalPoint=false )
-
-.. ocv:pyfunction:: cv2.getOptimalNewCameraMatrix(cameraMatrix, distCoeffs, imageSize, alpha[, newImgSize[, centerPrincipalPoint]]) -> retval, validPixROI
-
-.. ocv:cfunction:: void cvGetOptimalNewCameraMatrix( const CvMat* camera_matrix, const CvMat* dist_coeffs, CvSize image_size, double alpha, CvMat* new_camera_matrix, CvSize new_imag_size=cvSize(0,0), CvRect* valid_pixel_ROI=0, int center_principal_point=0 )
-
- :param cameraMatrix: Input camera matrix.
-
- :param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])` of 4, 5, 8 or 12 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
-
- :param imageSize: Original image size.
-
- :param alpha: Free scaling parameter between 0 (when all the pixels in the undistorted image are valid) and 1 (when all the source image pixels are retained in the undistorted image). See :ocv:func:`stereoRectify` for details.
-
- :param new_camera_matrix: Output new camera matrix.
-
- :param new_imag_size: Image size after rectification. By default,it is set to ``imageSize`` .
-
- :param validPixROI: Optional output rectangle that outlines all-good-pixels region in the undistorted image. See ``roi1, roi2`` description in :ocv:func:`stereoRectify` .
-
- :param centerPrincipalPoint: Optional flag that indicates whether in the new camera matrix the principal point should be at the image center or not. By default, the principal point is chosen to best fit a subset of the source image (determined by ``alpha``) to the corrected image.
-
-The function computes and returns
-the optimal new camera matrix based on the free scaling parameter. By varying this parameter, you may retrieve only sensible pixels ``alpha=0`` , keep all the original image pixels if there is valuable information in the corners ``alpha=1`` , or get something in between. When ``alpha>0`` , the undistortion result is likely to have some black pixels corresponding to "virtual" pixels outside of the captured distorted image. The original camera matrix, distortion coefficients, the computed new camera matrix, and ``newImageSize`` should be passed to
-:ocv:func:`initUndistortRectifyMap` to produce the maps for
-:ocv:func:`remap` .
-
-
-
-initCameraMatrix2D
-----------------------
-Finds an initial camera matrix from 3D-2D point correspondences.
-
-.. ocv:function:: Mat initCameraMatrix2D( InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints, Size imageSize, double aspectRatio=1.0 )
-
-.. ocv:pyfunction:: cv2.initCameraMatrix2D(objectPoints, imagePoints, imageSize[, aspectRatio]) -> retval
-
-.. ocv:cfunction:: void cvInitIntrinsicParams2D( const CvMat* object_points, const CvMat* image_points, const CvMat* npoints, CvSize image_size, CvMat* camera_matrix, double aspect_ratio=1. )
-
- :param objectPoints: Vector of vectors of the calibration pattern points in the calibration pattern coordinate space. In the old interface all the per-view vectors are concatenated. See :ocv:func:`calibrateCamera` for details.
-
- :param imagePoints: Vector of vectors of the projections of the calibration pattern points. In the old interface all the per-view vectors are concatenated.
-
- :param npoints: The integer vector of point counters for each view.
-
- :param imageSize: Image size in pixels used to initialize the principal point.
-
- :param aspectRatio: If it is zero or negative, both :math:`f_x` and :math:`f_y` are estimated independently. Otherwise, :math:`f_x = f_y * \texttt{aspectRatio}` .
-
-The function estimates and returns an initial camera matrix for the camera calibration process.
-Currently, the function only supports planar calibration patterns, which are patterns where each object point has z-coordinate =0.
-
-
-
-matMulDeriv
----------------
-Computes partial derivatives of the matrix product for each multiplied matrix.
-
-.. ocv:function:: void matMulDeriv( InputArray A, InputArray B, OutputArray dABdA, OutputArray dABdB )
-
-.. ocv:pyfunction:: cv2.matMulDeriv(A, B[, dABdA[, dABdB]]) -> dABdA, dABdB
-
- :param A: First multiplied matrix.
-
- :param B: Second multiplied matrix.
-
- :param dABdA: First output derivative matrix ``d(A*B)/dA`` of size :math:`\texttt{A.rows*B.cols} \times {A.rows*A.cols}` .
-
- :param dABdB: Second output derivative matrix ``d(A*B)/dB`` of size :math:`\texttt{A.rows*B.cols} \times {B.rows*B.cols}` .
-
-The function computes partial derivatives of the elements of the matrix product
-:math:`A*B` with regard to the elements of each of the two input matrices. The function is used to compute the Jacobian matrices in
-:ocv:func:`stereoCalibrate` but can also be used in any other similar optimization function.
-
-
-
-projectPoints
------------------
-Projects 3D points to an image plane.
-
-.. ocv:function:: void projectPoints( InputArray objectPoints, InputArray rvec, InputArray tvec, InputArray cameraMatrix, InputArray distCoeffs, OutputArray imagePoints, OutputArray jacobian=noArray(), double aspectRatio=0 )
-
-.. ocv:pyfunction:: cv2.projectPoints(objectPoints, rvec, tvec, cameraMatrix, distCoeffs[, imagePoints[, jacobian[, aspectRatio]]]) -> imagePoints, jacobian
-
-.. ocv:cfunction:: void cvProjectPoints2( const CvMat* object_points, const CvMat* rotation_vector, const CvMat* translation_vector, const CvMat* camera_matrix, const CvMat* distortion_coeffs, CvMat* image_points, CvMat* dpdrot=NULL, CvMat* dpdt=NULL, CvMat* dpdf=NULL, CvMat* dpdc=NULL, CvMat* dpddist=NULL, double aspect_ratio=0 )
-
- :param objectPoints: Array of object points, 3xN/Nx3 1-channel or 1xN/Nx1 3-channel (or ``vector<Point3f>`` ), where N is the number of points in the view.
-
- :param rvec: Rotation vector. See :ocv:func:`Rodrigues` for details.
-
- :param tvec: Translation vector.
-
- :param cameraMatrix: Camera matrix :math:`A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}` .
-
- :param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])` of 4, 5, 8 or 12 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
-
- :param imagePoints: Output array of image points, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel, or ``vector<Point2f>`` .
-
- :param jacobian: Optional output 2Nx(10+<numDistCoeffs>) jacobian matrix of derivatives of image points with respect to components of the rotation vector, translation vector, focal lengths, coordinates of the principal point and the distortion coefficients. In the old interface different components of the jacobian are returned via different output parameters.
-
- :param aspectRatio: Optional "fixed aspect ratio" parameter. If the parameter is not 0, the function assumes that the aspect ratio (*fx/fy*) is fixed and correspondingly adjusts the jacobian matrix.
-
-The function computes projections of 3D
-points to the image plane given intrinsic and extrinsic camera
-parameters. Optionally, the function computes Jacobians - matrices
-of partial derivatives of image points coordinates (as functions of all the
-input parameters) with respect to the particular parameters, intrinsic and/or
-extrinsic. The Jacobians are used during the global optimization
-in
-:ocv:func:`calibrateCamera`,
-:ocv:func:`solvePnP`, and
-:ocv:func:`stereoCalibrate` . The
-function itself can also be used to compute a re-projection error given the
-current intrinsic and extrinsic parameters.
-
-.. note:: By setting ``rvec=tvec=(0,0,0)`` or by setting ``cameraMatrix`` to a 3x3 identity matrix, or by passing zero distortion coefficients, you can get various useful partial cases of the function. This means that you can compute the distorted coordinates for a sparse set of points or apply a perspective transformation (and also compute the derivatives) in the ideal zero-distortion setup.
-
-
-
-reprojectImageTo3D
-----------------------
-Reprojects a disparity image to 3D space.
-
-.. ocv:function:: void reprojectImageTo3D( InputArray disparity, OutputArray _3dImage, InputArray Q, bool handleMissingValues=false, int ddepth=-1 )
-
-.. ocv:pyfunction:: cv2.reprojectImageTo3D(disparity, Q[, _3dImage[, handleMissingValues[, ddepth]]]) -> _3dImage
-
-.. ocv:cfunction:: void cvReprojectImageTo3D( const CvArr* disparityImage, CvArr* _3dImage, const CvMat* Q, int handleMissingValues=0 )
-
- :param disparity: Input single-channel 8-bit unsigned, 16-bit signed, 32-bit signed or 32-bit floating-point disparity image.
-
- :param _3dImage: Output 3-channel floating-point image of the same size as ``disparity`` . Each element of ``_3dImage(x,y)`` contains 3D coordinates of the point ``(x,y)`` computed from the disparity map.
-
- :param Q: :math:`4 \times 4` perspective transformation matrix that can be obtained with :ocv:func:`stereoRectify`.
-
- :param handleMissingValues: Indicates, whether the function should handle missing values (i.e. points where the disparity was not computed). If ``handleMissingValues=true``, then pixels with the minimal disparity that corresponds to the outliers (see :ocv:funcx:`StereoMatcher::compute` ) are transformed to 3D points with a very large Z value (currently set to 10000).
-
- :param ddepth: The optional output array depth. If it is ``-1``, the output image will have ``CV_32F`` depth. ``ddepth`` can also be set to ``CV_16S``, ``CV_32S`` or ``CV_32F``.
-
-The function transforms a single-channel disparity map to a 3-channel image representing a 3D surface. That is, for each pixel ``(x,y)`` andthe corresponding disparity ``d=disparity(x,y)`` , it computes:
-
-.. math::
-
- \begin{array}{l} [X \; Y \; Z \; W]^T = \texttt{Q} *[x \; y \; \texttt{disparity} (x,y) \; 1]^T \\ \texttt{\_3dImage} (x,y) = (X/W, \; Y/W, \; Z/W) \end{array}
-
-The matrix ``Q`` can be an arbitrary
-:math:`4 \times 4` matrix (for example, the one computed by
-:ocv:func:`stereoRectify`). To reproject a sparse set of points {(x,y,d),...} to 3D space, use
-:ocv:func:`perspectiveTransform` .
-
-
-
-RQDecomp3x3
----------------
-Computes an RQ decomposition of 3x3 matrices.
-
-.. ocv:function:: Vec3d RQDecomp3x3( InputArray src, OutputArray mtxR, OutputArray mtxQ, OutputArray Qx=noArray(), OutputArray Qy=noArray(), OutputArray Qz=noArray() )
-
-.. ocv:pyfunction:: cv2.RQDecomp3x3(src[, mtxR[, mtxQ[, Qx[, Qy[, Qz]]]]]) -> retval, mtxR, mtxQ, Qx, Qy, Qz
-
-.. ocv:cfunction:: void cvRQDecomp3x3( const CvMat * matrixM, CvMat * matrixR, CvMat * matrixQ, CvMat * matrixQx=NULL, CvMat * matrixQy=NULL, CvMat * matrixQz=NULL, CvPoint3D64f * eulerAngles=NULL )
-
- :param src: 3x3 input matrix.
-
- :param mtxR: Output 3x3 upper-triangular matrix.
-
- :param mtxQ: Output 3x3 orthogonal matrix.
-
- :param Qx: Optional output 3x3 rotation matrix around x-axis.
-
- :param Qy: Optional output 3x3 rotation matrix around y-axis.
-
- :param Qz: Optional output 3x3 rotation matrix around z-axis.
-
-The function computes a RQ decomposition using the given rotations. This function is used in
-:ocv:func:`decomposeProjectionMatrix` to decompose the left 3x3 submatrix of a projection matrix into a camera and a rotation matrix.
-
-It optionally returns three rotation matrices, one for each axis, and the three Euler angles in degrees (as the return value) that could be used in OpenGL. Note, there is always more than one sequence of rotations about the three principle axes that results in the same orientation of an object, eg. see [Slabaugh]_. Returned tree rotation matrices and corresponding three Euler angules are only one of the possible solutions.
-
-
-
-Rodrigues
--------------
-Converts a rotation matrix to a rotation vector or vice versa.
-
-.. ocv:function:: void Rodrigues(InputArray src, OutputArray dst, OutputArray jacobian=noArray())
-
-.. ocv:pyfunction:: cv2.Rodrigues(src[, dst[, jacobian]]) -> dst, jacobian
-
-.. ocv:cfunction:: int cvRodrigues2( const CvMat* src, CvMat* dst, CvMat* jacobian=0 )
-
- :param src: Input rotation vector (3x1 or 1x3) or rotation matrix (3x3).
-
- :param dst: Output rotation matrix (3x3) or rotation vector (3x1 or 1x3), respectively.
-
- :param jacobian: Optional output Jacobian matrix, 3x9 or 9x3, which is a matrix of partial derivatives of the output array components with respect to the input array components.
-
-.. math::
-
- \begin{array}{l} \theta \leftarrow norm(r) \\ r \leftarrow r/ \theta \\ R = \cos{\theta} I + (1- \cos{\theta} ) r r^T + \sin{\theta} \vecthreethree{0}{-r_z}{r_y}{r_z}{0}{-r_x}{-r_y}{r_x}{0} \end{array}
-
-Inverse transformation can be also done easily, since
-
-.. math::
-
- \sin ( \theta ) \vecthreethree{0}{-r_z}{r_y}{r_z}{0}{-r_x}{-r_y}{r_x}{0} = \frac{R - R^T}{2}
-
-A rotation vector is a convenient and most compact representation of a rotation matrix
-(since any rotation matrix has just 3 degrees of freedom). The representation is
-used in the global 3D geometry optimization procedures like
-:ocv:func:`calibrateCamera`,
-:ocv:func:`stereoCalibrate`, or
-:ocv:func:`solvePnP` .
-
-
-StereoMatcher
--------------
-.. ocv:class:: StereoMatcher : public Algorithm
-
-The base class for stereo correspondence algorithms.
-
-StereoMatcher::compute
------------------------
-Computes disparity map for the specified stereo pair
-
-.. ocv:function:: void StereoMatcher::compute( InputArray left, InputArray right, OutputArray disparity )
-
-.. ocv:pyfunction:: cv2.StereoBM.compute(left, right[, disparity]) -> disparity
-
- :param left: Left 8-bit single-channel image.
-
- :param right: Right image of the same size and the same type as the left one.
-
- :param disparity: Output disparity map. It has the same size as the input images. Some algorithms, like StereoBM or StereoSGBM compute 16-bit fixed-point disparity map (where each disparity value has 4 fractional bits), whereas other algorithms output 32-bit floating-point disparity map.
-
-
-StereoBM
---------
-.. ocv:class:: StereoBM : public StereoMatcher
-
-Class for computing stereo correspondence using the block matching algorithm, introduced and contributed to OpenCV by K. Konolige.
-
-.. Sample code:
-
- (Ocl) An example for using the stereoBM matching algorithm can be found at opencv_source_code/samples/ocl/stereo_match.cpp
-
-createStereoBM
-------------------
-Creates StereoBM object
-
-.. ocv:function:: Ptr<StereoBM> createStereoBM(int numDisparities=0, int blockSize=21)
-
-.. ocv:pyfunction:: cv2.createStereoBM([numDisparities[, blockSize]]) -> retval
-
- :param numDisparities: the disparity search range. For each pixel algorithm will find the best disparity from 0 (default minimum disparity) to ``numDisparities``. The search range can then be shifted by changing the minimum disparity.
-
- :param blockSize: the linear size of the blocks compared by the algorithm. The size should be odd (as the block is centered at the current pixel). Larger block size implies smoother, though less accurate disparity map. Smaller block size gives more detailed disparity map, but there is higher chance for algorithm to find a wrong correspondence.
-
-The function create ``StereoBM`` object. You can then call ``StereoBM::compute()`` to compute disparity for a specific stereo pair.
-
-
-StereoSGBM
-----------
-
-.. ocv:class:: StereoSGBM : public StereoMatcher
-
-The class implements the modified H. Hirschmuller algorithm [HH08]_ that differs from the original one as follows:
-
- * By default, the algorithm is single-pass, which means that you consider only 5 directions instead of 8. Set ``mode=StereoSGBM::MODE_HH`` in ``createStereoSGBM`` to run the full variant of the algorithm but beware that it may consume a lot of memory.
-
- * The algorithm matches blocks, not individual pixels. Though, setting ``blockSize=1`` reduces the blocks to single pixels.
-
- * Mutual information cost function is not implemented. Instead, a simpler Birchfield-Tomasi sub-pixel metric from [BT98]_ is used. Though, the color images are supported as well.
-
- * Some pre- and post- processing steps from K. Konolige algorithm ``StereoBM`` are included, for example: pre-filtering (``StereoBM::PREFILTER_XSOBEL`` type) and post-filtering (uniqueness check, quadratic interpolation and speckle filtering).
-
-.. note::
-
- * (Python) An example illustrating the use of the StereoSGBM matching algorithm can be found at opencv_source_code/samples/python2/stereo_match.py
-
-createStereoSGBM
---------------------------
-Creates StereoSGBM object
-
-.. ocv:function:: Ptr<StereoSGBM> createStereoSGBM( int minDisparity, int numDisparities, int blockSize, int P1=0, int P2=0, int disp12MaxDiff=0, int preFilterCap=0, int uniquenessRatio=0, int speckleWindowSize=0, int speckleRange=0, int mode=StereoSGBM::MODE_SGBM)
-
-.. ocv:pyfunction:: cv2.createStereoSGBM(minDisparity, numDisparities, blockSize[, P1[, P2[, disp12MaxDiff[, preFilterCap[, uniquenessRatio[, speckleWindowSize[, speckleRange[, mode]]]]]]]]) -> retval
-
- :param minDisparity: Minimum possible disparity value. Normally, it is zero but sometimes rectification algorithms can shift images, so this parameter needs to be adjusted accordingly.
-
- :param numDisparities: Maximum disparity minus minimum disparity. The value is always greater than zero. In the current implementation, this parameter must be divisible by 16.
-
- :param blockSize: Matched block size. It must be an odd number ``>=1`` . Normally, it should be somewhere in the ``3..11`` range.
-
- :param P1: The first parameter controlling the disparity smoothness. See below.
-
- :param P2: The second parameter controlling the disparity smoothness. The larger the values are, the smoother the disparity is. ``P1`` is the penalty on the disparity change by plus or minus 1 between neighbor pixels. ``P2`` is the penalty on the disparity change by more than 1 between neighbor pixels. The algorithm requires ``P2 > P1`` . See ``stereo_match.cpp`` sample where some reasonably good ``P1`` and ``P2`` values are shown (like ``8*number_of_image_channels*SADWindowSize*SADWindowSize`` and ``32*number_of_image_channels*SADWindowSize*SADWindowSize`` , respectively).
-
- :param disp12MaxDiff: Maximum allowed difference (in integer pixel units) in the left-right disparity check. Set it to a non-positive value to disable the check.
-
- :param preFilterCap: Truncation value for the prefiltered image pixels. The algorithm first computes x-derivative at each pixel and clips its value by ``[-preFilterCap, preFilterCap]`` interval. The result values are passed to the Birchfield-Tomasi pixel cost function.
-
- :param uniquenessRatio: Margin in percentage by which the best (minimum) computed cost function value should "win" the second best value to consider the found match correct. Normally, a value within the 5-15 range is good enough.
-
- :param speckleWindowSize: Maximum size of smooth disparity regions to consider their noise speckles and invalidate. Set it to 0 to disable speckle filtering. Otherwise, set it somewhere in the 50-200 range.
-
- :param speckleRange: Maximum disparity variation within each connected component. If you do speckle filtering, set the parameter to a positive value, it will be implicitly multiplied by 16. Normally, 1 or 2 is good enough.
-
- :param mode: Set it to ``StereoSGBM::MODE_HH`` to run the full-scale two-pass dynamic programming algorithm. It will consume O(W*H*numDisparities) bytes, which is large for 640x480 stereo and huge for HD-size pictures. By default, it is set to ``false`` .
-
-The first constructor initializes ``StereoSGBM`` with all the default parameters. So, you only have to set ``StereoSGBM::numDisparities`` at minimum. The second constructor enables you to set each parameter to a custom value.
-
-
-
-stereoCalibrate
--------------------
-Calibrates the stereo camera.
-
-.. ocv:function:: double stereoCalibrate( InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2, InputOutputArray cameraMatrix1, InputOutputArray distCoeffs1, InputOutputArray cameraMatrix2, InputOutputArray distCoeffs2, Size imageSize, OutputArray R, OutputArray T, OutputArray E, OutputArray F, int flags=CALIB_FIX_INTRINSIC ,TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, 1e-6))
-
-.. ocv:pyfunction:: cv2.stereoCalibrate(objectPoints, imagePoints1, imagePoints2, cameraMatrix1, distCoeffs1, cameraMatrix2, distCoeffs2, imageSize[, R[, T[, E[, F[, flags[, criteria]]]]]]) -> retval, cameraMatrix1, distCoeffs1, cameraMatrix2, distCoeffs2, R, T, E, F
-
-.. ocv:cfunction:: double cvStereoCalibrate( const CvMat* object_points, const CvMat* image_points1, const CvMat* image_points2, const CvMat* npoints, CvMat* camera_matrix1, CvMat* dist_coeffs1, CvMat* camera_matrix2, CvMat* dist_coeffs2, CvSize image_size, CvMat* R, CvMat* T, CvMat* E=0, CvMat* F=0, int flags=CV_CALIB_FIX_INTRINSIC, CvTermCriteria term_crit=cvTermCriteria( CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,1e-6) )
-
- :param objectPoints: Vector of vectors of the calibration pattern points.
-
- :param imagePoints1: Vector of vectors of the projections of the calibration pattern points, observed by the first camera.
-
- :param imagePoints2: Vector of vectors of the projections of the calibration pattern points, observed by the second camera.
-
- :param cameraMatrix1: Input/output first camera matrix: :math:`\vecthreethree{f_x^{(j)}}{0}{c_x^{(j)}}{0}{f_y^{(j)}}{c_y^{(j)}}{0}{0}{1}` , :math:`j = 0,\, 1` . If any of ``CV_CALIB_USE_INTRINSIC_GUESS`` , ``CV_CALIB_FIX_ASPECT_RATIO`` , ``CV_CALIB_FIX_INTRINSIC`` , or ``CV_CALIB_FIX_FOCAL_LENGTH`` are specified, some or all of the matrix components must be initialized. See the flags description for details.
-
- :param distCoeffs1: Input/output vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])` of 4, 5, 8 ot 12 elements. The output vector length depends on the flags.
-
- :param cameraMatrix2: Input/output second camera matrix. The parameter is similar to ``cameraMatrix1`` .
-
- :param distCoeffs2: Input/output lens distortion coefficients for the second camera. The parameter is similar to ``distCoeffs1`` .
-
- :param imageSize: Size of the image used only to initialize intrinsic camera matrix.
-
- :param R: Output rotation matrix between the 1st and the 2nd camera coordinate systems.
-
- :param T: Output translation vector between the coordinate systems of the cameras.
-
- :param E: Output essential matrix.
-
- :param F: Output fundamental matrix.
-
- :param term_crit: Termination criteria for the iterative optimization algorithm.
-
- :param flags: Different flags that may be zero or a combination of the following values:
-
- * **CV_CALIB_FIX_INTRINSIC** Fix ``cameraMatrix?`` and ``distCoeffs?`` so that only ``R, T, E`` , and ``F`` matrices are estimated.
-
- * **CV_CALIB_USE_INTRINSIC_GUESS** Optimize some or all of the intrinsic parameters according to the specified flags. Initial values are provided by the user.
-
- * **CV_CALIB_FIX_PRINCIPAL_POINT** Fix the principal points during the optimization.
-
- * **CV_CALIB_FIX_FOCAL_LENGTH** Fix :math:`f^{(j)}_x` and :math:`f^{(j)}_y` .
-
- * **CV_CALIB_FIX_ASPECT_RATIO** Optimize :math:`f^{(j)}_y` . Fix the ratio :math:`f^{(j)}_x/f^{(j)}_y` .
-
- * **CV_CALIB_SAME_FOCAL_LENGTH** Enforce :math:`f^{(0)}_x=f^{(1)}_x` and :math:`f^{(0)}_y=f^{(1)}_y` .
-
- * **CV_CALIB_ZERO_TANGENT_DIST** Set tangential distortion coefficients for each camera to zeros and fix there.
-
- * **CV_CALIB_FIX_K1,...,CV_CALIB_FIX_K6** Do not change the corresponding radial distortion coefficient during the optimization. If ``CV_CALIB_USE_INTRINSIC_GUESS`` is set, the coefficient from the supplied ``distCoeffs`` matrix is used. Otherwise, it is set to 0.
-
- * **CV_CALIB_RATIONAL_MODEL** Enable coefficients k4, k5, and k6. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the rational model and return 8 coefficients. If the flag is not set, the function computes and returns only 5 distortion coefficients.
-
- * **CALIB_THIN_PRISM_MODEL** Coefficients s1, s2, s3 and s4 are enabled. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the thin prism model and return 12 coefficients. If the flag is not set, the function computes and returns only 5 distortion coefficients.
-
- * **CALIB_FIX_S1_S2_S3_S4** The thin prism distortion coefficients are not changed during the optimization. If ``CV_CALIB_USE_INTRINSIC_GUESS`` is set, the coefficient from the supplied ``distCoeffs`` matrix is used. Otherwise, it is set to 0.
-
-The function estimates transformation between two cameras making a stereo pair. If you have a stereo camera where the relative position and orientation of two cameras is fixed, and if you computed poses of an object relative to the first camera and to the second camera, (R1, T1) and (R2, T2), respectively (this can be done with
-:ocv:func:`solvePnP` ), then those poses definitely relate to each other. This means that, given (
-:math:`R_1`,:math:`T_1` ), it should be possible to compute (
-:math:`R_2`,:math:`T_2` ). You only need to know the position and orientation of the second camera relative to the first camera. This is what the described function does. It computes (
-:math:`R`,:math:`T` ) so that:
-
-.. math::
-
- R_2=R*R_1
- T_2=R*T_1 + T,
-
-Optionally, it computes the essential matrix E:
-
-.. math::
-
- E= \vecthreethree{0}{-T_2}{T_1}{T_2}{0}{-T_0}{-T_1}{T_0}{0} *R
-
-where
-:math:`T_i` are components of the translation vector
-:math:`T` :
-:math:`T=[T_0, T_1, T_2]^T` . And the function can also compute the fundamental matrix F:
-
-.. math::
-
- F = cameraMatrix2^{-T} E cameraMatrix1^{-1}
-
-Besides the stereo-related information, the function can also perform a full calibration of each of two cameras. However, due to the high dimensionality of the parameter space and noise in the input data, the function can diverge from the correct solution. If the intrinsic parameters can be estimated with high accuracy for each of the cameras individually (for example, using
-:ocv:func:`calibrateCamera` ), you are recommended to do so and then pass ``CV_CALIB_FIX_INTRINSIC`` flag to the function along with the computed intrinsic parameters. Otherwise, if all the parameters are estimated at once, it makes sense to restrict some parameters, for example, pass ``CV_CALIB_SAME_FOCAL_LENGTH`` and ``CV_CALIB_ZERO_TANGENT_DIST`` flags, which is usually a reasonable assumption.
-
-Similarly to :ocv:func:`calibrateCamera` , the function minimizes the total re-projection error for all the points in all the available views from both cameras. The function returns the final value of the re-projection error.
-
-
-
-stereoRectify
------------------
-Computes rectification transforms for each head of a calibrated stereo camera.
-
-.. ocv:function:: void stereoRectify( InputArray cameraMatrix1, InputArray distCoeffs1, InputArray cameraMatrix2, InputArray distCoeffs2, Size imageSize, InputArray R, InputArray T, OutputArray R1, OutputArray R2, OutputArray P1, OutputArray P2, OutputArray Q, int flags=CALIB_ZERO_DISPARITY, double alpha=-1, Size newImageSize=Size(), Rect* validPixROI1=0, Rect* validPixROI2=0 )
-
-.. ocv:cfunction:: void cvStereoRectify( const CvMat* camera_matrix1, const CvMat* camera_matrix2, const CvMat* dist_coeffs1, const CvMat* dist_coeffs2, CvSize image_size, const CvMat* R, const CvMat* T, CvMat* R1, CvMat* R2, CvMat* P1, CvMat* P2, CvMat* Q=0, int flags=CV_CALIB_ZERO_DISPARITY, double alpha=-1, CvSize new_image_size=cvSize(0,0), CvRect* valid_pix_ROI1=0, CvRect* valid_pix_ROI2=0 )
-
- :param cameraMatrix1: First camera matrix.
-
- :param cameraMatrix2: Second camera matrix.
-
- :param distCoeffs1: First camera distortion parameters.
-
- :param distCoeffs2: Second camera distortion parameters.
-
- :param imageSize: Size of the image used for stereo calibration.
-
- :param R: Rotation matrix between the coordinate systems of the first and the second cameras.
-
- :param T: Translation vector between coordinate systems of the cameras.
-
- :param R1: Output 3x3 rectification transform (rotation matrix) for the first camera.
-
- :param R2: Output 3x3 rectification transform (rotation matrix) for the second camera.
-
- :param P1: Output 3x4 projection matrix in the new (rectified) coordinate systems for the first camera.
-
- :param P2: Output 3x4 projection matrix in the new (rectified) coordinate systems for the second camera.
-
- :param Q: Output :math:`4 \times 4` disparity-to-depth mapping matrix (see :ocv:func:`reprojectImageTo3D` ).
-
- :param flags: Operation flags that may be zero or ``CV_CALIB_ZERO_DISPARITY`` . If the flag is set, the function makes the principal points of each camera have the same pixel coordinates in the rectified views. And if the flag is not set, the function may still shift the images in the horizontal or vertical direction (depending on the orientation of epipolar lines) to maximize the useful image area.
-
- :param alpha: Free scaling parameter. If it is -1 or absent, the function performs the default scaling. Otherwise, the parameter should be between 0 and 1. ``alpha=0`` means that the rectified images are zoomed and shifted so that only valid pixels are visible (no black areas after rectification). ``alpha=1`` means that the rectified image is decimated and shifted so that all the pixels from the original images from the cameras are retained in the rectified images (no source image pixels are lost). Obviously, any intermediate value yields an intermediate result between those two extreme cases.
-
- :param newImageSize: New image resolution after rectification. The same size should be passed to :ocv:func:`initUndistortRectifyMap` (see the ``stereo_calib.cpp`` sample in OpenCV samples directory). When (0,0) is passed (default), it is set to the original ``imageSize`` . Setting it to larger value can help you preserve details in the original image, especially when there is a big radial distortion.
-
- :param validPixROI1: Optional output rectangles inside the rectified images where all the pixels are valid. If ``alpha=0`` , the ROIs cover the whole images. Otherwise, they are likely to be smaller (see the picture below).
-
- :param validPixROI2: Optional output rectangles inside the rectified images where all the pixels are valid. If ``alpha=0`` , the ROIs cover the whole images. Otherwise, they are likely to be smaller (see the picture below).
-
-The function computes the rotation matrices for each camera that (virtually) make both camera image planes the same plane. Consequently, this makes all the epipolar lines parallel and thus simplifies the dense stereo correspondence problem. The function takes the matrices computed by
-:ocv:func:`stereoCalibrate` as input. As output, it provides two rotation matrices and also two projection matrices in the new coordinates. The function distinguishes the following two cases:
-
-#.
- **Horizontal stereo**: the first and the second camera views are shifted relative to each other mainly along the x axis (with possible small vertical shift). In the rectified images, the corresponding epipolar lines in the left and right cameras are horizontal and have the same y-coordinate. P1 and P2 look like:
-
- .. math::
-
- \texttt{P1} = \begin{bmatrix} f & 0 & cx_1 & 0 \\ 0 & f & cy & 0 \\ 0 & 0 & 1 & 0 \end{bmatrix}
-
- .. math::
-
- \texttt{P2} = \begin{bmatrix} f & 0 & cx_2 & T_x*f \\ 0 & f & cy & 0 \\ 0 & 0 & 1 & 0 \end{bmatrix} ,
-
- where
- :math:`T_x` is a horizontal shift between the cameras and
- :math:`cx_1=cx_2` if ``CV_CALIB_ZERO_DISPARITY`` is set.
-
-#.
- **Vertical stereo**: the first and the second camera views are shifted relative to each other mainly in vertical direction (and probably a bit in the horizontal direction too). The epipolar lines in the rectified images are vertical and have the same x-coordinate. P1 and P2 look like:
-
- .. math::
-
- \texttt{P1} = \begin{bmatrix} f & 0 & cx & 0 \\ 0 & f & cy_1 & 0 \\ 0 & 0 & 1 & 0 \end{bmatrix}
-
- .. math::
-
- \texttt{P2} = \begin{bmatrix} f & 0 & cx & 0 \\ 0 & f & cy_2 & T_y*f \\ 0 & 0 & 1 & 0 \end{bmatrix} ,
-
- where
- :math:`T_y` is a vertical shift between the cameras and
- :math:`cy_1=cy_2` if ``CALIB_ZERO_DISPARITY`` is set.
-
-As you can see, the first three columns of ``P1`` and ``P2`` will effectively be the new "rectified" camera matrices.
-The matrices, together with ``R1`` and ``R2`` , can then be passed to
-:ocv:func:`initUndistortRectifyMap` to initialize the rectification map for each camera.
-
-See below the screenshot from the ``stereo_calib.cpp`` sample. Some red horizontal lines pass through the corresponding image regions. This means that the images are well rectified, which is what most stereo correspondence algorithms rely on. The green rectangles are ``roi1`` and ``roi2`` . You see that their interiors are all valid pixels.
-
-.. image:: pics/stereo_undistort.jpg
-
-
-
-stereoRectifyUncalibrated
------------------------------
-Computes a rectification transform for an uncalibrated stereo camera.
-
-.. ocv:function:: bool stereoRectifyUncalibrated( InputArray points1, InputArray points2, InputArray F, Size imgSize, OutputArray H1, OutputArray H2, double threshold=5 )
-
-.. ocv:pyfunction:: cv2.stereoRectifyUncalibrated(points1, points2, F, imgSize[, H1[, H2[, threshold]]]) -> retval, H1, H2
-
-.. ocv:cfunction:: int cvStereoRectifyUncalibrated( const CvMat* points1, const CvMat* points2, const CvMat* F, CvSize img_size, CvMat* H1, CvMat* H2, double threshold=5 )
-
- :param points1: Array of feature points in the first image.
-
- :param points2: The corresponding points in the second image. The same formats as in :ocv:func:`findFundamentalMat` are supported.
-
- :param F: Input fundamental matrix. It can be computed from the same set of point pairs using :ocv:func:`findFundamentalMat` .
-
- :param imgSize: Size of the image.
-
- :param H1: Output rectification homography matrix for the first image.
-
- :param H2: Output rectification homography matrix for the second image.
-
- :param threshold: Optional threshold used to filter out the outliers. If the parameter is greater than zero, all the point pairs that do not comply with the epipolar geometry (that is, the points for which :math:`|\texttt{points2[i]}^T*\texttt{F}*\texttt{points1[i]}|>\texttt{threshold}` ) are rejected prior to computing the homographies. Otherwise,all the points are considered inliers.
-
-The function computes the rectification transformations without knowing intrinsic parameters of the cameras and their relative position in the space, which explains the suffix "uncalibrated". Another related difference from
-:ocv:func:`stereoRectify` is that the function outputs not the rectification transformations in the object (3D) space, but the planar perspective transformations encoded by the homography matrices ``H1`` and ``H2`` . The function implements the algorithm
-[Hartley99]_.
-
-.. note::
-
- While the algorithm does not need to know the intrinsic parameters of the cameras, it heavily depends on the epipolar geometry. Therefore, if the camera lenses have a significant distortion, it would be better to correct it before computing the fundamental matrix and calling this function. For example, distortion coefficients can be estimated for each head of stereo camera separately by using :ocv:func:`calibrateCamera` . Then, the images can be corrected using :ocv:func:`undistort` , or just the point coordinates can be corrected with :ocv:func:`undistortPoints` .
-
-
-triangulatePoints
------------------
-Reconstructs points by triangulation.
-
-.. ocv:function:: void triangulatePoints( InputArray projMatr1, InputArray projMatr2, InputArray projPoints1, InputArray projPoints2, OutputArray points4D )
-
-.. ocv:pyfunction:: cv2.triangulatePoints(projMatr1, projMatr2, projPoints1, projPoints2[, points4D]) -> points4D
-
-.. ocv:cfunction:: void cvTriangulatePoints(CvMat* projMatr1, CvMat* projMatr2, CvMat* projPoints1, CvMat* projPoints2, CvMat* points4D)
-
- :param projMatr1: 3x4 projection matrix of the first camera.
-
- :param projMatr2: 3x4 projection matrix of the second camera.
-
- :param projPoints1: 2xN array of feature points in the first image. In case of c++ version it can be also a vector of feature points or two-channel matrix of size 1xN or Nx1.
-
- :param projPoints2: 2xN array of corresponding points in the second image. In case of c++ version it can be also a vector of feature points or two-channel matrix of size 1xN or Nx1.
-
- :param points4D: 4xN array of reconstructed points in homogeneous coordinates.
-
-The function reconstructs 3-dimensional points (in homogeneous coordinates) by using their observations with a stereo camera. Projections matrices can be obtained from :ocv:func:`stereoRectify`.
-
-.. note::
-
- Keep in mind that all input data should be of float type in order for this function to work.
-
-.. seealso::
-
- :ocv:func:`reprojectImageTo3D`
-
-fisheye
-----------
-
-The methods in this namespace use a so-called fisheye camera model. ::
-
- namespace fisheye
- {
- //! projects 3D points using fisheye model
- void projectPoints(InputArray objectPoints, OutputArray imagePoints, const Affine3d& affine,
- InputArray K, InputArray D, double alpha = 0, OutputArray jacobian = noArray());
-
- //! projects points using fisheye model
- void projectPoints(InputArray objectPoints, OutputArray imagePoints, InputArray rvec, InputArray tvec,
- InputArray K, InputArray D, double alpha = 0, OutputArray jacobian = noArray());
-
- //! distorts 2D points using fisheye model
- void distortPoints(InputArray undistorted, OutputArray distorted, InputArray K, InputArray D, double alpha = 0);
-
- //! undistorts 2D points using fisheye model
- void undistortPoints(InputArray distorted, OutputArray undistorted,
- InputArray K, InputArray D, InputArray R = noArray(), InputArray P = noArray());
-
- //! computing undistortion and rectification maps for image transform by cv::remap()
- //! If D is empty zero distortion is used, if R or P is empty identity matrixes are used
- void initUndistortRectifyMap(InputArray K, InputArray D, InputArray R, InputArray P,
- const cv::Size& size, int m1type, OutputArray map1, OutputArray map2);
-
- //! undistorts image, optionally changes resolution and camera matrix.
- void undistortImage(InputArray distorted, OutputArray undistorted,
- InputArray K, InputArray D, InputArray Knew = cv::noArray(), const Size& new_size = Size());
-
- //! estimates new camera matrix for undistortion or rectification
- void estimateNewCameraMatrixForUndistortRectify(InputArray K, InputArray D, const Size &image_size, InputArray R,
- OutputArray P, double balance = 0.0, const Size& new_size = Size(), double fov_scale = 1.0);
-
- //! performs camera calibaration
- double calibrate(InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints, const Size& image_size,
- InputOutputArray K, InputOutputArray D, OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, int flags = 0,
- TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 100, DBL_EPSILON));
-
- //! stereo rectification estimation
- void stereoRectify(InputArray K1, InputArray D1, InputArray K2, InputArray D2, const Size &imageSize, InputArray R, InputArray tvec,
- OutputArray R1, OutputArray R2, OutputArray P1, OutputArray P2, OutputArray Q, int flags, const Size &newImageSize = Size(),
- double balance = 0.0, double fov_scale = 1.0);
-
- //! performs stereo calibration
- double stereoCalibrate(InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2,
- InputOutputArray K1, InputOutputArray D1, InputOutputArray K2, InputOutputArray D2, Size imageSize,
- OutputArray R, OutputArray T, int flags = CALIB_FIX_INTRINSIC,
- TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 100, DBL_EPSILON));
- };
-
-
-Definitions:
-Let P be a point in 3D of coordinates X in the world reference frame (stored in the matrix X)
-The coordinate vector of P in the camera reference frame is:
-
-.. class:: center
-.. math::
-
- Xc = R X + T
-
-where R is the rotation matrix corresponding to the rotation vector om: R = rodrigues(om);
-call x, y and z the 3 coordinates of Xc:
-
-.. class:: center
-.. math::
- x = Xc_1 \\
- y = Xc_2 \\
- z = Xc_3
-
-The pinehole projection coordinates of P is [a; b] where
-
-.. class:: center
-.. math::
-
- a = x / z \ and \ b = y / z \\
- r^2 = a^2 + b^2 \\
- \theta = atan(r)
-
-Fisheye distortion:
-
-.. class:: center
-.. math::
-
- \theta_d = \theta (1 + k_1 \theta^2 + k_2 \theta^4 + k_3 \theta^6 + k_4 \theta^8)
-
-The distorted point coordinates are [x'; y'] where
-
-..class:: center
-.. math::
-
- x' = (\theta_d / r) x \\
- y' = (\theta_d / r) y
-
-Finally, convertion into pixel coordinates: The final pixel coordinates vector [u; v] where:
-
-.. class:: center
-.. math::
-
- u = f_x (x' + \alpha y') + c_x \\
- v = f_y yy + c_y
-
-fisheye::projectPoints
----------------------------
-Projects points using fisheye model
-
-.. ocv:function:: void fisheye::projectPoints(InputArray objectPoints, OutputArray imagePoints, const Affine3d& affine, InputArray K, InputArray D, double alpha = 0, OutputArray jacobian = noArray())
-
-.. ocv:function:: void fisheye::projectPoints(InputArray objectPoints, OutputArray imagePoints, InputArray rvec, InputArray tvec, InputArray K, InputArray D, double alpha = 0, OutputArray jacobian = noArray())
-
- :param objectPoints: Array of object points, 1xN/Nx1 3-channel (or ``vector<Point3f>`` ), where N is the number of points in the view.
-
- :param rvec: Rotation vector. See :ocv:func:`Rodrigues` for details.
-
- :param tvec: Translation vector.
-
- :param K: Camera matrix :math:`K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}`.
-
- :param D: Input vector of distortion coefficients :math:`(k_1, k_2, k_3, k_4)`.
-
- :param alpha: The skew coefficient.
-
- :param imagePoints: Output array of image points, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel, or ``vector<Point2f>``.
-
- :param jacobian: Optional output 2Nx15 jacobian matrix of derivatives of image points with respect to components of the focal lengths, coordinates of the principal point, distortion coefficients, rotation vector, translation vector, and the skew. In the old interface different components of the jacobian are returned via different output parameters.
-
-The function computes projections of 3D points to the image plane given intrinsic and extrinsic camera parameters. Optionally, the function computes Jacobians - matrices of partial derivatives of image points coordinates (as functions of all the input parameters) with respect to the particular parameters, intrinsic and/or extrinsic.
-
-fisheye::distortPoints
--------------------------
-Distorts 2D points using fisheye model.
-
-.. ocv:function:: void fisheye::distortPoints(InputArray undistorted, OutputArray distorted, InputArray K, InputArray D, double alpha = 0)
-
- :param undistorted: Array of object points, 1xN/Nx1 2-channel (or ``vector<Point2f>`` ), where N is the number of points in the view.
-
- :param K: Camera matrix :math:`K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}`.
-
- :param D: Input vector of distortion coefficients :math:`(k_1, k_2, k_3, k_4)`.
-
- :param alpha: The skew coefficient.
-
- :param distorted: Output array of image points, 1xN/Nx1 2-channel, or ``vector<Point2f>`` .
-
-fisheye::undistortPoints
------------------------------
-Undistorts 2D points using fisheye model
-
-.. ocv:function:: void fisheye::undistortPoints(InputArray distorted, OutputArray undistorted, InputArray K, InputArray D, InputArray R = noArray(), InputArray P = noArray())
-
- :param distorted: Array of object points, 1xN/Nx1 2-channel (or ``vector<Point2f>`` ), where N is the number of points in the view.
-
- :param K: Camera matrix :math:`K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}`.
-
- :param D: Input vector of distortion coefficients :math:`(k_1, k_2, k_3, k_4)`.
-
- :param R: Rectification transformation in the object space: 3x3 1-channel, or vector: 3x1/1x3 1-channel or 1x1 3-channel
-
- :param P: New camera matrix (3x3) or new projection matrix (3x4)
-
- :param undistorted: Output array of image points, 1xN/Nx1 2-channel, or ``vector<Point2f>`` .
-
-
-fisheye::initUndistortRectifyMap
--------------------------------------
-Computes undistortion and rectification maps for image transform by cv::remap(). If D is empty zero distortion is used, if R or P is empty identity matrixes are used.
-
-.. ocv:function:: void fisheye::initUndistortRectifyMap(InputArray K, InputArray D, InputArray R, InputArray P, const cv::Size& size, int m1type, OutputArray map1, OutputArray map2)
-
- :param K: Camera matrix :math:`K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}`.
-
- :param D: Input vector of distortion coefficients :math:`(k_1, k_2, k_3, k_4)`.
-
- :param R: Rectification transformation in the object space: 3x3 1-channel, or vector: 3x1/1x3 1-channel or 1x1 3-channel
-
- :param P: New camera matrix (3x3) or new projection matrix (3x4)
-
- :param size: Undistorted image size.
-
- :param m1type: Type of the first output map that can be CV_32FC1 or CV_16SC2 . See convertMaps() for details.
-
- :param map1: The first output map.
-
- :param map2: The second output map.
-
-fisheye::undistortImage
------------------------
-Transforms an image to compensate for fisheye lens distortion.
-
-.. ocv:function:: void fisheye::undistortImage(InputArray distorted, OutputArray undistorted, InputArray K, InputArray D, InputArray Knew = cv::noArray(), const Size& new_size = Size())
-
- :param distorted: image with fisheye lens distortion.
-
- :param K: Camera matrix :math:`K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}`.
-
- :param D: Input vector of distortion coefficients :math:`(k_1, k_2, k_3, k_4)`.
-
- :param Knew: Camera matrix of the distorted image. By default, it is the identity matrix but you may additionally scale and shift the result by using a different matrix.
-
- :param undistorted: Output image with compensated fisheye lens distortion.
-
-The function transforms an image to compensate radial and tangential lens distortion.
-
-The function is simply a combination of
-:ocv:func:`fisheye::initUndistortRectifyMap` (with unity ``R`` ) and
-:ocv:func:`remap` (with bilinear interpolation). See the former function for details of the transformation being performed.
-
-See below the results of undistortImage.
- * a\) result of :ocv:func:`undistort` of perspective camera model (all possible coefficients (k_1, k_2, k_3, k_4, k_5, k_6) of distortion were optimized under calibration)
- * b\) result of :ocv:func:`fisheye::undistortImage` of fisheye camera model (all possible coefficients (k_1, k_2, k_3, k_4) of fisheye distortion were optimized under calibration)
- * c\) original image was captured with fisheye lens
-
-Pictures a) and b) almost the same. But if we consider points of image located far from the center of image, we can notice that on image a) these points are distorted.
-
-.. image:: pics/fisheye_undistorted.jpg
-
-
-fisheye::estimateNewCameraMatrixForUndistortRectify
-----------------------------------------------------------
-Estimates new camera matrix for undistortion or rectification.
-
-.. ocv:function:: void fisheye::estimateNewCameraMatrixForUndistortRectify(InputArray K, InputArray D, const Size &image_size, InputArray R, OutputArray P, double balance = 0.0, const Size& new_size = Size(), double fov_scale = 1.0)
-
- :param K: Camera matrix :math:`K = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{_1}`.
-
- :param D: Input vector of distortion coefficients :math:`(k_1, k_2, k_3, k_4)`.
-
- :param R: Rectification transformation in the object space: 3x3 1-channel, or vector: 3x1/1x3 1-channel or 1x1 3-channel
-
- :param P: New camera matrix (3x3) or new projection matrix (3x4)
-
- :param balance: Sets the new focal length in range between the min focal length and the max focal length. Balance is in range of [0, 1].
-
- :param fov_scale: Divisor for new focal length.
-
-fisheye::stereoRectify
-------------------------------
-Stereo rectification for fisheye camera model
-
-.. ocv:function:: void fisheye::stereoRectify(InputArray K1, InputArray D1, InputArray K2, InputArray D2, const Size &imageSize, InputArray R, InputArray tvec, OutputArray R1, OutputArray R2, OutputArray P1, OutputArray P2, OutputArray Q, int flags, const Size &newImageSize = Size(), double balance = 0.0, double fov_scale = 1.0)
-
- :param K1: First camera matrix.
-
- :param K2: Second camera matrix.
-
- :param D1: First camera distortion parameters.
-
- :param D2: Second camera distortion parameters.
-
- :param imageSize: Size of the image used for stereo calibration.
-
- :param rotation: Rotation matrix between the coordinate systems of the first and the second cameras.
-
- :param tvec: Translation vector between coordinate systems of the cameras.
-
- :param R1: Output 3x3 rectification transform (rotation matrix) for the first camera.
-
- :param R2: Output 3x3 rectification transform (rotation matrix) for the second camera.
-
- :param P1: Output 3x4 projection matrix in the new (rectified) coordinate systems for the first camera.
-
- :param P2: Output 3x4 projection matrix in the new (rectified) coordinate systems for the second camera.
-
- :param Q: Output :math:`4 \times 4` disparity-to-depth mapping matrix (see :ocv:func:`reprojectImageTo3D` ).
-
- :param flags: Operation flags that may be zero or ``CV_CALIB_ZERO_DISPARITY`` . If the flag is set, the function makes the principal points of each camera have the same pixel coordinates in the rectified views. And if the flag is not set, the function may still shift the images in the horizontal or vertical direction (depending on the orientation of epipolar lines) to maximize the useful image area.
-
- :param alpha: Free scaling parameter. If it is -1 or absent, the function performs the default scaling. Otherwise, the parameter should be between 0 and 1. ``alpha=0`` means that the rectified images are zoomed and shifted so that only valid pixels are visible (no black areas after rectification). ``alpha=1`` means that the rectified image is decimated and shifted so that all the pixels from the original images from the cameras are retained in the rectified images (no source image pixels are lost). Obviously, any intermediate value yields an intermediate result between those two extreme cases.
-
- :param newImageSize: New image resolution after rectification. The same size should be passed to :ocv:func:`initUndistortRectifyMap` (see the ``stereo_calib.cpp`` sample in OpenCV samples directory). When (0,0) is passed (default), it is set to the original ``imageSize`` . Setting it to larger value can help you preserve details in the original image, especially when there is a big radial distortion.
-
- :param roi1: Optional output rectangles inside the rectified images where all the pixels are valid. If ``alpha=0`` , the ROIs cover the whole images. Otherwise, they are likely to be smaller (see the picture below).
-
- :param roi2: Optional output rectangles inside the rectified images where all the pixels are valid. If ``alpha=0`` , the ROIs cover the whole images. Otherwise, they are likely to be smaller (see the picture below).
-
- :param balance: Sets the new focal length in range between the min focal length and the max focal length. Balance is in range of [0, 1].
-
- :param fov_scale: Divisor for new focal length.
-
-
-
-fisheye::calibrate
-----------------------------
-Performs camera calibaration
-
-.. ocv:function:: double fisheye::calibrate(InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints, const Size& image_size, InputOutputArray K, InputOutputArray D, OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, int flags = 0, TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 100, DBL_EPSILON))
-
- :param objectPoints: vector of vectors of calibration pattern points in the calibration pattern coordinate space.
-
- :param imagePoints: vector of vectors of the projections of calibration pattern points. ``imagePoints.size()`` and ``objectPoints.size()`` and ``imagePoints[i].size()`` must be equal to ``objectPoints[i].size()`` for each ``i``.
-
- :param image_size: Size of the image used only to initialize the intrinsic camera matrix.
-
- :param K: Output 3x3 floating-point camera matrix :math:`A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}` . If ``fisheye::CALIB_USE_INTRINSIC_GUESS``/ is specified, some or all of ``fx, fy, cx, cy`` must be initialized before calling the function.
-
- :param D: Output vector of distortion coefficients :math:`(k_1, k_2, k_3, k_4)`.
-
- :param rvecs: Output vector of rotation vectors (see :ocv:func:`Rodrigues` ) estimated for each pattern view. That is, each k-th rotation vector together with the corresponding k-th translation vector (see the next output parameter description) brings the calibration pattern from the model coordinate space (in which object points are specified) to the world coordinate space, that is, a real position of the calibration pattern in the k-th pattern view (k=0.. *M* -1).
-
- :param tvecs: Output vector of translation vectors estimated for each pattern view.
-
- :param flags: Different flags that may be zero or a combination of the following values:
-
- * **fisheye::CALIB_USE_INTRINSIC_GUESS** ``cameraMatrix`` contains valid initial values of ``fx, fy, cx, cy`` that are optimized further. Otherwise, ``(cx, cy)`` is initially set to the image center ( ``imageSize`` is used), and focal distances are computed in a least-squares fashion.
-
- * **fisheye::CALIB_RECOMPUTE_EXTRINSIC** Extrinsic will be recomputed after each iteration of intrinsic optimization.
-
- * **fisheye::CALIB_CHECK_COND** The functions will check validity of condition number.
-
- * **fisheye::CALIB_FIX_SKEW** Skew coefficient (alpha) is set to zero and stay zero.
-
- * **fisheye::CALIB_FIX_K1..4** Selected distortion coefficients are set to zeros and stay zero.
-
- :param criteria: Termination criteria for the iterative optimization algorithm.
-
-
-fisheye::stereoCalibrate
-----------------------------
-Performs stereo calibration
-
-.. ocv:function:: double fisheye::stereoCalibrate(InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2, InputOutputArray K1, InputOutputArray D1, InputOutputArray K2, InputOutputArray D2, Size imageSize, OutputArray R, OutputArray T, int flags = CALIB_FIX_INTRINSIC, TermCriteria criteria = TermCriteria(TermCriteria::COUNT + TermCriteria::EPS, 100, DBL_EPSILON))
-
- :param objectPoints: Vector of vectors of the calibration pattern points.
-
- :param imagePoints1: Vector of vectors of the projections of the calibration pattern points, observed by the first camera.
-
- :param imagePoints2: Vector of vectors of the projections of the calibration pattern points, observed by the second camera.
-
- :param K1: Input/output first camera matrix: :math:`\vecthreethree{f_x^{(j)}}{0}{c_x^{(j)}}{0}{f_y^{(j)}}{c_y^{(j)}}{0}{0}{1}` , :math:`j = 0,\, 1` . If any of ``fisheye::CALIB_USE_INTRINSIC_GUESS`` , ``fisheye::CV_CALIB_FIX_INTRINSIC`` are specified, some or all of the matrix components must be initialized.
-
- :param D1: Input/output vector of distortion coefficients :math:`(k_1, k_2, k_3, k_4)` of 4 elements.
-
- :param K2: Input/output second camera matrix. The parameter is similar to ``K1`` .
-
- :param D2: Input/output lens distortion coefficients for the second camera. The parameter is similar to ``D1`` .
-
- :param imageSize: Size of the image used only to initialize intrinsic camera matrix.
-
- :param R: Output rotation matrix between the 1st and the 2nd camera coordinate systems.
-
- :param T: Output translation vector between the coordinate systems of the cameras.
-
- :param flags: Different flags that may be zero or a combination of the following values:
-
- * **fisheye::CV_CALIB_FIX_INTRINSIC** Fix ``K1, K2?`` and ``D1, D2?`` so that only ``R, T`` matrices are estimated.
-
- * **fisheye::CALIB_USE_INTRINSIC_GUESS** ``K1, K2`` contains valid initial values of ``fx, fy, cx, cy`` that are optimized further. Otherwise, ``(cx, cy)`` is initially set to the image center (``imageSize`` is used), and focal distances are computed in a least-squares fashion.
-
- * **fisheye::CALIB_RECOMPUTE_EXTRINSIC** Extrinsic will be recomputed after each iteration of intrinsic optimization.
-
- * **fisheye::CALIB_CHECK_COND** The functions will check validity of condition number.
-
- * **fisheye::CALIB_FIX_SKEW** Skew coefficient (alpha) is set to zero and stay zero.
-
- * **fisheye::CALIB_FIX_K1..4** Selected distortion coefficients are set to zeros and stay zero.
-
- :param criteria: Termination criteria for the iterative optimization algorithm.
-
-.. [BT98] Birchfield, S. and Tomasi, C. A pixel dissimilarity measure that is insensitive to image sampling. IEEE Transactions on Pattern Analysis and Machine Intelligence. 1998.
-
-.. [BouguetMCT] J.Y.Bouguet. MATLAB calibration tool. http://www.vision.caltech.edu/bouguetj/calib_doc/
-
-.. [Hartley99] Hartley, R.I., Theory and Practice of Projective Rectification. IJCV 35 2, pp 115-127 (1999)
-
-.. [HartleyZ00] Hartley, R. and Zisserman, A. Multiple View Geomtry in Computer Vision, Cambridge University Press, 2000.
-
-.. [HH08] Hirschmuller, H. Stereo Processing by Semiglobal Matching and Mutual Information, PAMI(30), No. 2, February 2008, pp. 328-341.
-
-.. [Nister03] Nistér, D. An efficient solution to the five-point relative pose problem, CVPR 2003.
-
-.. [SteweniusCFS] Stewénius, H., Calibrated Fivepoint solver. http://www.vis.uky.edu/~stewe/FIVEPOINT/
-
-.. [Slabaugh] Slabaugh, G.G. Computing Euler angles from a rotation matrix. http://www.soi.city.ac.uk/~sbbh653/publications/euler.pdf (verified: 2013-04-15)
-
-.. [Zhang2000] Z. Zhang. A Flexible New Technique for Camera Calibration. IEEE Transactions on Pattern Analysis and Machine Intelligence, 22(11):1330-1334, 2000.
-
-.. [Malis] Malis, E. and Vargas, M. Deeper understanding of the homography decomposition for vision-based control, Research Report 6303, INRIA (2007)
+++ /dev/null
-Basic Structures
-================
-
-.. highlight:: cpp
-
-DataType
---------
-.. ocv:class:: DataType
-
-Template "trait" class for OpenCV primitive data types. A primitive OpenCV data type is one of ``unsigned char``, ``bool``, ``signed char``, ``unsigned short``, ``signed short``, ``int``, ``float``, ``double``, or a tuple of values of one of these types, where all the values in the tuple have the same type. Any primitive type from the list can be defined by an identifier in the form ``CV_<bit-depth>{U|S|F}C(<number_of_channels>)``, for example: ``uchar`` ~ ``CV_8UC1``, 3-element floating-point tuple ~ ``CV_32FC3``, and so on. A universal OpenCV structure that is able to store a single instance of such a primitive data type is
-:ocv:class:`Vec`. Multiple instances of such a type can be stored in a ``std::vector``, ``Mat``, ``Mat_``, ``SparseMat``, ``SparseMat_``, or any other container that is able to store ``Vec`` instances.
-
-The ``DataType`` class is basically used to provide a description of such primitive data types without adding any fields or methods to the corresponding classes (and it is actually impossible to add anything to primitive C/C++ data types). This technique is known in C++ as class traits. It is not ``DataType`` itself that is used but its specialized versions, such as: ::
-
- template<> class DataType<uchar>
- {
- typedef uchar value_type;
- typedef int work_type;
- typedef uchar channel_type;
- enum { channel_type = CV_8U, channels = 1, fmt='u', type = CV_8U };
- };
- ...
- template<typename _Tp> DataType<std::complex<_Tp> >
- {
- typedef std::complex<_Tp> value_type;
- typedef std::complex<_Tp> work_type;
- typedef _Tp channel_type;
- // DataDepth is another helper trait class
- enum { depth = DataDepth<_Tp>::value, channels=2,
- fmt=(channels-1)*256+DataDepth<_Tp>::fmt,
- type=CV_MAKETYPE(depth, channels) };
- };
- ...
-
-The main purpose of this class is to convert compilation-time type information to an OpenCV-compatible data type identifier, for example: ::
-
- // allocates a 30x40 floating-point matrix
- Mat A(30, 40, DataType<float>::type);
-
- Mat B = Mat_<std::complex<double> >(3, 3);
- // the statement below will print 6, 2 /*, that is depth == CV_64F, channels == 2 */
- cout << B.depth() << ", " << B.channels() << endl;
-
-
-So, such traits are used to tell OpenCV which data type you are working with, even if such a type is not native to OpenCV. For example, the matrix ``B`` initialization above is compiled because OpenCV defines the proper specialized template class ``DataType<complex<_Tp> >`` . This mechanism is also useful (and used in OpenCV this way) for generic algorithms implementations.
-
-
-Point\_
--------
-.. ocv:class:: Point_
-
-::
-
- template<typename _Tp> class CV_EXPORTS Point_
- {
- public:
- typedef _Tp value_type;
-
- // various constructors
- Point_();
- Point_(_Tp _x, _Tp _y);
- Point_(const Point_& pt);
- Point_(const CvPoint& pt);
- Point_(const CvPoint2D32f& pt);
- Point_(const Size_<_Tp>& sz);
- Point_(const Vec<_Tp, 2>& v);
-
- Point_& operator = (const Point_& pt);
- //! conversion to another data type
- template<typename _Tp2> operator Point_<_Tp2>() const;
-
- //! conversion to the old-style C structures
- operator CvPoint() const;
- operator CvPoint2D32f() const;
- operator Vec<_Tp, 2>() const;
-
- //! dot product
- _Tp dot(const Point_& pt) const;
- //! dot product computed in double-precision arithmetics
- double ddot(const Point_& pt) const;
- //! cross-product
- double cross(const Point_& pt) const;
- //! checks whether the point is inside the specified rectangle
- bool inside(const Rect_<_Tp>& r) const;
-
- _Tp x, y; //< the point coordinates
- };
-
-Template class for 2D points specified by its coordinates
-:math:`x` and
-:math:`y` .
-An instance of the class is interchangeable with C structures, ``CvPoint`` and ``CvPoint2D32f`` . There is also a cast operator to convert point coordinates to the specified type. The conversion from floating-point coordinates to integer coordinates is done by rounding. Commonly, the conversion uses this
-operation for each of the coordinates. Besides the class members listed in the declaration above, the following operations on points are implemented: ::
-
- pt1 = pt2 + pt3;
- pt1 = pt2 - pt3;
- pt1 = pt2 * a;
- pt1 = a * pt2;
- pt1 = pt2 / a;
- pt1 += pt2;
- pt1 -= pt2;
- pt1 *= a;
- pt1 /= a;
- double value = norm(pt); // L2 norm
- pt1 == pt2;
- pt1 != pt2;
-
-For your convenience, the following type aliases are defined: ::
-
- typedef Point_<int> Point2i;
- typedef Point2i Point;
- typedef Point_<float> Point2f;
- typedef Point_<double> Point2d;
-
-Example: ::
-
- Point2f a(0.3f, 0.f), b(0.f, 0.4f);
- Point pt = (a + b)*10.f;
- cout << pt.x << ", " << pt.y << endl;
-
-
-Point3\_
---------
-.. ocv:class:: Point3_
-
-::
-
- template<typename _Tp> class CV_EXPORTS Point3_
- {
- public:
- typedef _Tp value_type;
-
- // various constructors
- Point3_();
- Point3_(_Tp _x, _Tp _y, _Tp _z);
- Point3_(const Point3_& pt);
- explicit Point3_(const Point_<_Tp>& pt);
- Point3_(const CvPoint3D32f& pt);
- Point3_(const Vec<_Tp, 3>& v);
-
- Point3_& operator = (const Point3_& pt);
- //! conversion to another data type
- template<typename _Tp2> operator Point3_<_Tp2>() const;
- //! conversion to the old-style CvPoint...
- operator CvPoint3D32f() const;
- //! conversion to cv::Vec<>
- operator Vec<_Tp, 3>() const;
-
- //! dot product
- _Tp dot(const Point3_& pt) const;
- //! dot product computed in double-precision arithmetics
- double ddot(const Point3_& pt) const;
- //! cross product of the 2 3D points
- Point3_ cross(const Point3_& pt) const;
-
- _Tp x, y, z; //< the point coordinates
- };
-
-Template class for 3D points specified by its coordinates
-:math:`x`,
-:math:`y` and
-:math:`z` .
-An instance of the class is interchangeable with the C structure ``CvPoint2D32f`` . Similarly to ``Point_`` , the coordinates of 3D points can be converted to another type. The vector arithmetic and comparison operations are also supported.
-
-The following ``Point3_<>`` aliases are available: ::
-
- typedef Point3_<int> Point3i;
- typedef Point3_<float> Point3f;
- typedef Point3_<double> Point3d;
-
-Size\_
-------
-.. ocv:class:: Size_
-
-::
-
- template<typename _Tp> class CV_EXPORTS Size_
- {
- public:
- typedef _Tp value_type;
-
- //! various constructors
- Size_();
- Size_(_Tp _width, _Tp _height);
- Size_(const Size_& sz);
- Size_(const CvSize& sz);
- Size_(const CvSize2D32f& sz);
- Size_(const Point_<_Tp>& pt);
-
- Size_& operator = (const Size_& sz);
- //! the area (width*height)
- _Tp area() const;
-
- //! conversion of another data type.
- template<typename _Tp2> operator Size_<_Tp2>() const;
-
- //! conversion to the old-style OpenCV types
- operator CvSize() const;
- operator CvSize2D32f() const;
-
- _Tp width, height; // the width and the height
- };
-
-Template class for specifying the size of an image or rectangle. The class includes two members called ``width`` and ``height``. The structure can be converted to and from the old OpenCV structures
-``CvSize`` and ``CvSize2D32f`` . The same set of arithmetic and comparison operations as for ``Point_`` is available.
-
-OpenCV defines the following ``Size_<>`` aliases: ::
-
- typedef Size_<int> Size2i;
- typedef Size2i Size;
- typedef Size_<float> Size2f;
-
-Rect\_
-------
-.. ocv:class:: Rect_
-
-::
-
- template<typename _Tp> class CV_EXPORTS Rect_
- {
- public:
- typedef _Tp value_type;
-
- //! various constructors
- Rect_();
- Rect_(_Tp _x, _Tp _y, _Tp _width, _Tp _height);
- Rect_(const Rect_& r);
- Rect_(const CvRect& r);
- Rect_(const Point_<_Tp>& org, const Size_<_Tp>& sz);
- Rect_(const Point_<_Tp>& pt1, const Point_<_Tp>& pt2);
-
- Rect_& operator = ( const Rect_& r );
- //! the top-left corner
- Point_<_Tp> tl() const;
- //! the bottom-right corner
- Point_<_Tp> br() const;
-
- //! size (width, height) of the rectangle
- Size_<_Tp> size() const;
- //! area (width*height) of the rectangle
- _Tp area() const;
-
- //! conversion to another data type
- template<typename _Tp2> operator Rect_<_Tp2>() const;
- //! conversion to the old-style CvRect
- operator CvRect() const;
-
- //! checks whether the rectangle contains the point
- bool contains(const Point_<_Tp>& pt) const;
-
- _Tp x, y, width, height; //< the top-left corner, as well as width and height of the rectangle
- };
-
-Template class for 2D rectangles, described by the following parameters:
-
-* Coordinates of the top-left corner. This is a default interpretation of ``Rect_::x`` and ``Rect_::y`` in OpenCV. Though, in your algorithms you may count ``x`` and ``y`` from the bottom-left corner.
-* Rectangle width and height.
-
-OpenCV typically assumes that the top and left boundary of the rectangle are inclusive, while the right and bottom boundaries are not. For example, the method ``Rect_::contains`` returns ``true`` if
-
-.. math::
-
- x \leq pt.x < x+width,
- y \leq pt.y < y+height
-
-Virtually every loop over an image
-ROI in OpenCV (where ROI is specified by ``Rect_<int>`` ) is implemented as: ::
-
- for(int y = roi.y; y < roi.y + roi.height; y++)
- for(int x = roi.x; x < roi.x + roi.width; x++)
- {
- // ...
- }
-
-
-In addition to the class members, the following operations on rectangles are implemented:
-
-*
- :math:`\texttt{rect} = \texttt{rect} \pm \texttt{point}` (shifting a rectangle by a certain offset)
-
-*
- :math:`\texttt{rect} = \texttt{rect} \pm \texttt{size}` (expanding or shrinking a rectangle by a certain amount)
-
-* ``rect += point, rect -= point, rect += size, rect -= size`` (augmenting operations)
-
-* ``rect = rect1 & rect2`` (rectangle intersection)
-
-* ``rect = rect1 | rect2`` (minimum area rectangle containing ``rect1`` and ``rect2`` )
-
-* ``rect &= rect1, rect |= rect1`` (and the corresponding augmenting operations)
-
-* ``rect == rect1, rect != rect1`` (rectangle comparison)
-
-This is an example how the partial ordering on rectangles can be established (rect1
-:math:`\subseteq` rect2): ::
-
- template<typename _Tp> inline bool
- operator <= (const Rect_<_Tp>& r1, const Rect_<_Tp>& r2)
- {
- return (r1 & r2) == r1;
- }
-
-
-For your convenience, the ``Rect_<>`` alias is available: ::
-
- typedef Rect_<int> Rect;
-
-RotatedRect
------------
-.. ocv:class:: RotatedRect
-
-::
-
- class CV_EXPORTS RotatedRect
- {
- public:
- //! various constructors
- RotatedRect();
- RotatedRect(const Point2f& center, const Size2f& size, float angle);
- RotatedRect(const CvBox2D& box);
- RotatedRect(const Point2f& point1, const Point2f& point2, const Point2f& point3);
-
- //! returns 4 vertices of the rectangle
- void points(Point2f pts[]) const;
- //! returns the minimal up-right rectangle containing the rotated rectangle
- Rect boundingRect() const;
- //! conversion to the old-style CvBox2D structure
- operator CvBox2D() const;
-
- Point2f center; //< the rectangle mass center
- Size2f size; //< width and height of the rectangle
- float angle; //< the rotation angle. When the angle is 0, 90, 180, 270 etc., the rectangle becomes an up-right rectangle.
- };
-
-The class represents rotated (i.e. not up-right) rectangles on a plane. Each rectangle is specified by the center point (mass center), length of each side (represented by cv::Size2f structure) and the rotation angle in degrees.
-
- .. ocv:function:: RotatedRect::RotatedRect()
- .. ocv:function:: RotatedRect::RotatedRect(const Point2f& center, const Size2f& size, float angle)
-
- :param center: The rectangle mass center.
- :param size: Width and height of the rectangle.
- :param angle: The rotation angle in a clockwise direction. When the angle is 0, 90, 180, 270 etc., the rectangle becomes an up-right rectangle.
- :param box: The rotated rectangle parameters as the obsolete CvBox2D structure.
- .. ocv:function:: RotatedRect::RotatedRect(const Point2f& point1, const Point2f& point2, const Point2f& point3)
-
- :param point1:
- :param point2:
- :param point3: Any 3 end points of the RotatedRect. They must be given in order (either clockwise or anticlockwise).
- .. ocv:function:: void RotatedRect::points( Point2f pts[] ) const
- .. ocv:function:: Rect RotatedRect::boundingRect() const
-
- :param pts: The points array for storing rectangle vertices.
-
-The sample below demonstrates how to use RotatedRect:
-
-::
-
- Mat image(200, 200, CV_8UC3, Scalar(0));
- RotatedRect rRect = RotatedRect(Point2f(100,100), Size2f(100,50), 30);
-
- Point2f vertices[4];
- rRect.points(vertices);
- for (int i = 0; i < 4; i++)
- line(image, vertices[i], vertices[(i+1)%4], Scalar(0,255,0));
-
- Rect brect = rRect.boundingRect();
- rectangle(image, brect, Scalar(255,0,0));
-
- imshow("rectangles", image);
- waitKey(0);
-
-.. image:: pics/rotatedrect.png
-
-.. seealso::
-
- :ocv:func:`CamShift` ,
- :ocv:func:`fitEllipse` ,
- :ocv:func:`minAreaRect` ,
- :ocv:struct:`CvBox2D`
-
-TermCriteria
-------------
-.. ocv:class:: TermCriteria
-
-::
-
- class CV_EXPORTS TermCriteria
- {
- public:
- enum
- {
- COUNT=1, //!< the maximum number of iterations or elements to compute
- MAX_ITER=COUNT, //!< ditto
- EPS=2 //!< the desired accuracy or change in parameters at which the iterative algorithm stops
- };
-
- //! default constructor
- TermCriteria();
- //! full constructor
- TermCriteria(int type, int maxCount, double epsilon);
- //! conversion from CvTermCriteria
- TermCriteria(const CvTermCriteria& criteria);
- //! conversion to CvTermCriteria
- operator CvTermCriteria() const;
-
- int type; //!< the type of termination criteria: COUNT, EPS or COUNT + EPS
- int maxCount; // the maximum number of iterations/elements
- double epsilon; // the desired accuracy
- };
-
-The class defining termination criteria for iterative algorithms. You can initialize it by default constructor and then override any parameters, or the structure may be fully initialized using the advanced variant of the constructor.
-
-TermCriteria::TermCriteria
---------------------------
-The constructors.
-
-.. ocv:function:: TermCriteria::TermCriteria()
-
-.. ocv:function:: TermCriteria::TermCriteria(int type, int maxCount, double epsilon)
-
- :param type: The type of termination criteria: ``TermCriteria::COUNT``, ``TermCriteria::EPS`` or ``TermCriteria::COUNT`` + ``TermCriteria::EPS``.
-
- :param maxCount: The maximum number of iterations or elements to compute.
-
- :param epsilon: The desired accuracy or change in parameters at which the iterative algorithm stops.
-
- :param criteria: Termination criteria in the deprecated ``CvTermCriteria`` format.
-
-
-Matx
-----
-.. ocv:class:: Matx
-
-Template class for small matrices whose type and size are known at compilation time: ::
-
- template<typename _Tp, int m, int n> class Matx {...};
-
- typedef Matx<float, 1, 2> Matx12f;
- typedef Matx<double, 1, 2> Matx12d;
- ...
- typedef Matx<float, 1, 6> Matx16f;
- typedef Matx<double, 1, 6> Matx16d;
-
- typedef Matx<float, 2, 1> Matx21f;
- typedef Matx<double, 2, 1> Matx21d;
- ...
- typedef Matx<float, 6, 1> Matx61f;
- typedef Matx<double, 6, 1> Matx61d;
-
- typedef Matx<float, 2, 2> Matx22f;
- typedef Matx<double, 2, 2> Matx22d;
- ...
- typedef Matx<float, 6, 6> Matx66f;
- typedef Matx<double, 6, 6> Matx66d;
-
-If you need a more flexible type, use :ocv:class:`Mat` . The elements of the matrix ``M`` are accessible using the ``M(i,j)`` notation. Most of the common matrix operations (see also
-:ref:`MatrixExpressions` ) are available. To do an operation on ``Matx`` that is not implemented, you can easily convert the matrix to
-``Mat`` and backwards. ::
-
- Matx33f m(1, 2, 3,
- 4, 5, 6,
- 7, 8, 9);
- cout << sum(Mat(m*m.t())) << endl;
-
-
-Vec
----
-.. ocv:class:: Vec
-
-Template class for short numerical vectors, a partial case of :ocv:class:`Matx`: ::
-
- template<typename _Tp, int n> class Vec : public Matx<_Tp, n, 1> {...};
-
- typedef Vec<uchar, 2> Vec2b;
- typedef Vec<uchar, 3> Vec3b;
- typedef Vec<uchar, 4> Vec4b;
-
- typedef Vec<short, 2> Vec2s;
- typedef Vec<short, 3> Vec3s;
- typedef Vec<short, 4> Vec4s;
-
- typedef Vec<int, 2> Vec2i;
- typedef Vec<int, 3> Vec3i;
- typedef Vec<int, 4> Vec4i;
-
- typedef Vec<float, 2> Vec2f;
- typedef Vec<float, 3> Vec3f;
- typedef Vec<float, 4> Vec4f;
- typedef Vec<float, 6> Vec6f;
-
- typedef Vec<double, 2> Vec2d;
- typedef Vec<double, 3> Vec3d;
- typedef Vec<double, 4> Vec4d;
- typedef Vec<double, 6> Vec6d;
-
-It is possible to convert ``Vec<T,2>`` to/from ``Point_``, ``Vec<T,3>`` to/from ``Point3_`` , and ``Vec<T,4>`` to :ocv:struct:`CvScalar` or :ocv:class:`Scalar_`. Use ``operator[]`` to access the elements of ``Vec``.
-
-All the expected vector operations are also implemented:
-
-* ``v1 = v2 + v3``
-* ``v1 = v2 - v3``
-* ``v1 = v2 * scale``
-* ``v1 = scale * v2``
-* ``v1 = -v2``
-* ``v1 += v2`` and other augmenting operations
-* ``v1 == v2, v1 != v2``
-* ``norm(v1)`` (euclidean norm)
-
-The ``Vec`` class is commonly used to describe pixel types of multi-channel arrays. See :ocv:class:`Mat` for details.
-
-Scalar\_
---------
-.. ocv:class:: Scalar_
-
-Template class for a 4-element vector derived from Vec.
-
-::
-
- template<typename _Tp> class CV_EXPORTS Scalar_ : public Vec<_Tp, 4>
- {
- public:
- //! various constructors
- Scalar_();
- Scalar_(_Tp v0, _Tp v1, _Tp v2=0, _Tp v3=0);
- Scalar_(const CvScalar& s);
- Scalar_(_Tp v0);
-
- //! returns a scalar with all elements set to v0
- static Scalar_<_Tp> all(_Tp v0);
- //! conversion to the old-style CvScalar
- operator CvScalar() const;
-
- //! conversion to another data type
- template<typename T2> operator Scalar_<T2>() const;
-
- //! per-element product
- Scalar_<_Tp> mul(const Scalar_<_Tp>& a, double scale=1 ) const;
-
- // returns (v0, -v1, -v2, -v3)
- Scalar_<_Tp> conj() const;
-
- // returns true iff v1 == v2 == v3 == 0
- bool isReal() const;
- };
-
- typedef Scalar_<double> Scalar;
-
-Being derived from ``Vec<_Tp, 4>`` , ``Scalar_`` and ``Scalar`` can be used just as typical 4-element vectors. In addition, they can be converted to/from ``CvScalar`` . The type ``Scalar`` is widely used in OpenCV to pass pixel values.
-
-Range
------
-.. ocv:class:: Range
-
-Template class specifying a continuous subsequence (slice) of a sequence.
-
-::
-
- class CV_EXPORTS Range
- {
- public:
- Range();
- Range(int _start, int _end);
- Range(const CvSlice& slice);
- int size() const;
- bool empty() const;
- static Range all();
- operator CvSlice() const;
-
- int start, end;
- };
-
-The class is used to specify a row or a column span in a matrix (
-:ocv:class:`Mat` ) and for many other purposes. ``Range(a,b)`` is basically the same as ``a:b`` in Matlab or ``a..b`` in Python. As in Python, ``start`` is an inclusive left boundary of the range and ``end`` is an exclusive right boundary of the range. Such a half-opened interval is usually denoted as
-:math:`[start,end)` .
-
-The static method ``Range::all()`` returns a special variable that means "the whole sequence" or "the whole range", just like " ``:`` " in Matlab or " ``...`` " in Python. All the methods and functions in OpenCV that take ``Range`` support this special ``Range::all()`` value. But, of course, in case of your own custom processing, you will probably have to check and handle it explicitly: ::
-
- void my_function(..., const Range& r, ....)
- {
- if(r == Range::all()) {
- // process all the data
- }
- else {
- // process [r.start, r.end)
- }
- }
-
-
-KeyPoint
---------
-.. ocv:class:: KeyPoint
-
- Data structure for salient point detectors.
-
- .. ocv:member:: Point2f pt
-
- coordinates of the keypoint
-
- .. ocv:member:: float size
-
- diameter of the meaningful keypoint neighborhood
-
- .. ocv:member:: float angle
-
- computed orientation of the keypoint (-1 if not applicable). Its possible values are in a range [0,360) degrees. It is measured relative to image coordinate system (y-axis is directed downward), ie in clockwise.
-
- .. ocv:member:: float response
-
- the response by which the most strong keypoints have been selected. Can be used for further sorting or subsampling
-
- .. ocv:member:: int octave
-
- octave (pyramid layer) from which the keypoint has been extracted
-
- .. ocv:member:: int class_id
-
- object id that can be used to clustered keypoints by an object they belong to
-
-KeyPoint::KeyPoint
-------------------
-The keypoint constructors
-
-.. ocv:function:: KeyPoint::KeyPoint()
-
-.. ocv:function:: KeyPoint::KeyPoint(Point2f _pt, float _size, float _angle=-1, float _response=0, int _octave=0, int _class_id=-1)
-
-.. ocv:function:: KeyPoint::KeyPoint(float x, float y, float _size, float _angle=-1, float _response=0, int _octave=0, int _class_id=-1)
-
-.. ocv:pyfunction:: cv2.KeyPoint([x, y, _size[, _angle[, _response[, _octave[, _class_id]]]]]) -> <KeyPoint object>
-
- :param x: x-coordinate of the keypoint
-
- :param y: y-coordinate of the keypoint
-
- :param _pt: x & y coordinates of the keypoint
-
- :param _size: keypoint diameter
-
- :param _angle: keypoint orientation
-
- :param _response: keypoint detector response on the keypoint (that is, strength of the keypoint)
-
- :param _octave: pyramid octave in which the keypoint has been detected
-
- :param _class_id: object id
-
-
-KeyPoint::convert
---------------------
-
-This method converts vector of keypoints to vector of points or the reverse, where each keypoint is assigned the same size and the same orientation.
-
-.. ocv:function:: void KeyPoint::convert(const std::vector<KeyPoint>& keypoints, std::vector<Point2f>& points2f, const std::vector<int>& keypointIndexes=std::vector<int>())
-
-.. ocv:function:: void KeyPoint::convert(const std::vector<Point2f>& points2f, std::vector<KeyPoint>& keypoints, float size=1, float response=1, int octave=0, int class_id=-1)
-
-.. ocv:pyfunction:: cv2.KeyPoint_convert(keypoints[, keypointIndexes]) -> points2f
-
-.. ocv:pyfunction:: cv2.KeyPoint_convert(points2f[, size[, response[, octave[, class_id]]]]) -> keypoints
-
- :param keypoints: Keypoints obtained from any feature detection algorithm like SIFT/SURF/ORB
-
- :param points2f: Array of (x,y) coordinates of each keypoint
-
- :param keypointIndexes: Array of indexes of keypoints to be converted to points. (Acts like a mask to convert only specified keypoints)
-
- :param _size: keypoint diameter
-
- :param _response: keypoint detector response on the keypoint (that is, strength of the keypoint)
-
- :param _octave: pyramid octave in which the keypoint has been detected
-
- :param _class_id: object id
-
-
-KeyPoint::overlap
---------------------
-
-This method computes overlap for pair of keypoints. Overlap is the ratio between area of keypoint regions' intersection and area of keypoint regions' union (considering keypoint region as circle). If they don't overlap, we get zero. If they coincide at same location with same size, we get 1.
-
-.. ocv:function:: float KeyPoint::overlap(const KeyPoint& kp1, const KeyPoint& kp2)
-
-.. ocv:pyfunction:: cv2.KeyPoint_overlap(kp1, kp2) -> retval
-
- :param kp1: First keypoint
-
- :param kp2: Second keypoint
-
-
-DMatch
-------
-.. ocv:class:: DMatch
-
-Class for matching keypoint descriptors: query descriptor index,
-train descriptor index, train image index, and distance between descriptors. ::
-
- class DMatch
- {
- public:
- DMatch() : queryIdx(-1), trainIdx(-1), imgIdx(-1),
- distance(std::numeric_limits<float>::max()) {}
- DMatch( int _queryIdx, int _trainIdx, float _distance ) :
- queryIdx(_queryIdx), trainIdx(_trainIdx), imgIdx(-1),
- distance(_distance) {}
- DMatch( int _queryIdx, int _trainIdx, int _imgIdx, float _distance ) :
- queryIdx(_queryIdx), trainIdx(_trainIdx), imgIdx(_imgIdx),
- distance(_distance) {}
-
- int queryIdx; // query descriptor index
- int trainIdx; // train descriptor index
- int imgIdx; // train image index
-
- float distance;
-
- // less is better
- bool operator<( const DMatch &m ) const;
- };
-
-
-Ptr
----
-.. ocv:class:: Ptr
-
-Template class for smart pointers with shared ownership. ::
-
- template<typename T>
- struct Ptr
- {
- typedef T element_type;
-
- Ptr();
-
- template<typename Y>
- explicit Ptr(Y* p);
- template<typename Y, typename D>
- Ptr(Y* p, D d);
-
- Ptr(const Ptr& o);
- template<typename Y>
- Ptr(const Ptr<Y>& o);
- template<typename Y>
- Ptr(const Ptr<Y>& o, T* p);
-
- ~Ptr();
-
- Ptr& operator = (const Ptr& o);
- template<typename Y>
- Ptr& operator = (const Ptr<Y>& o);
-
- void release();
-
- template<typename Y>
- void reset(Y* p);
- template<typename Y, typename D>
- void reset(Y* p, D d);
-
- void swap(Ptr& o);
-
- T* get() const;
-
- T& operator * () const;
- T* operator -> () const;
- operator T* () const;
-
- bool empty() const;
-
- template<typename Y>
- Ptr<Y> staticCast() const;
- template<typename Y>
- Ptr<Y> constCast() const;
- template<typename Y>
- Ptr<Y> dynamicCast() const;
- };
-
-
-A ``Ptr<T>`` pretends to be a pointer to an object of type T.
-Unlike an ordinary pointer, however, the object will be automatically
-cleaned up once all ``Ptr`` instances pointing to it are destroyed.
-
-``Ptr`` is similar to ``boost::shared_ptr`` that is part of the Boost library
-(http://www.boost.org/doc/libs/release/libs/smart_ptr/shared_ptr.htm)
-and ``std::shared_ptr`` from the `C++11 <http://en.wikipedia.org/wiki/C++11>`_ standard.
-
-This class provides the following advantages:
-
-*
- Default constructor, copy constructor, and assignment operator for an arbitrary C++ class
- or C structure. For some objects, like files, windows, mutexes, sockets, and others, a copy
- constructor or an assignment operator are difficult to define. For some other objects, like
- complex classifiers in OpenCV, copy constructors are absent and not easy to implement. Finally,
- some of complex OpenCV and your own data structures may be written in C.
- However, copy constructors and default constructors can simplify programming a lot. Besides,
- they are often required (for example, by STL containers). By using a ``Ptr`` to such an
- object instead of the object itself, you automatically get all of the necessary
- constructors and the assignment operator.
-
-*
- *O(1)* complexity of the above-mentioned operations. While some structures, like ``std::vector``,
- provide a copy constructor and an assignment operator, the operations may take a considerable
- amount of time if the data structures are large. But if the structures are put into a ``Ptr``,
- the overhead is small and independent of the data size.
-
-*
- Automatic and customizable cleanup, even for C structures. See the example below with ``FILE*``.
-
-*
- Heterogeneous collections of objects. The standard STL and most other C++ and OpenCV containers
- can store only objects of the same type and the same size. The classical solution to store objects
- of different types in the same container is to store pointers to the base class (``Base*``)
- instead but then you lose the automatic memory management. Again, by using ``Ptr<Base>``
- instead of raw pointers, you can solve the problem.
-
-A ``Ptr`` is said to *own* a pointer - that is, for each ``Ptr`` there is a pointer that will be deleted
-once all ``Ptr`` instances that own it are destroyed. The owned pointer may be null, in which case nothing is deleted.
-Each ``Ptr`` also *stores* a pointer. The stored pointer is the pointer the ``Ptr`` pretends to be;
-that is, the one you get when you use :ocv:func:`Ptr::get` or the conversion to ``T*``. It's usually
-the same as the owned pointer, but if you use casts or the general shared-ownership constructor, the two may diverge:
-the ``Ptr`` will still own the original pointer, but will itself point to something else.
-
-The owned pointer is treated as a black box. The only thing ``Ptr`` needs to know about it is how to
-delete it. This knowledge is encapsulated in the *deleter* - an auxiliary object that is associated
-with the owned pointer and shared between all ``Ptr`` instances that own it. The default deleter is
-an instance of ``DefaultDeleter``, which uses the standard C++ ``delete`` operator; as such it
-will work with any pointer allocated with the standard ``new`` operator.
-
-However, if the pointer must be deleted in a different way, you must specify a custom deleter upon
-``Ptr`` construction. A deleter is simply a callable object that accepts the pointer as its sole argument.
-For example, if you want to wrap ``FILE``, you may do so as follows::
-
- Ptr<FILE> f(fopen("myfile.txt", "w"), fclose);
- if(!f) throw ...;
- fprintf(f, ....);
- ...
- // the file will be closed automatically by f's destructor.
-
-Alternatively, if you want all pointers of a particular type to be deleted the same way,
-you can specialize ``DefaultDeleter<T>::operator()`` for that type, like this::
-
- namespace cv {
- template<> void DefaultDeleter<FILE>::operator ()(FILE * obj) const
- {
- fclose(obj);
- }
- }
-
-For convenience, the following types from the OpenCV C API already have such a specialization
-that calls the appropriate release function:
-
-* ``CvCapture``
-* :ocv:struct:`CvFileStorage`
-* ``CvHaarClassifierCascade``
-* :ocv:struct:`CvMat`
-* :ocv:struct:`CvMatND`
-* :ocv:struct:`CvMemStorage`
-* :ocv:struct:`CvSparseMat`
-* ``CvVideoWriter``
-* :ocv:struct:`IplImage`
-
-.. note:: The shared ownership mechanism is implemented with reference counting. As such,
- cyclic ownership (e.g. when object ``a`` contains a ``Ptr`` to object ``b``, which
- contains a ``Ptr`` to object ``a``) will lead to all involved objects never being
- cleaned up. Avoid such situations.
-
-.. note:: It is safe to concurrently read (but not write) a ``Ptr`` instance from multiple threads
- and therefore it is normally safe to use it in multi-threaded applications.
- The same is true for :ocv:class:`Mat` and other C++ OpenCV classes that use internal
- reference counts.
-
-Ptr::Ptr (null)
-------------------
-
-.. ocv:function:: Ptr::Ptr()
-
- The default constructor creates a null ``Ptr`` - one that owns and stores a null pointer.
-
-Ptr::Ptr (assuming ownership)
------------------------------
-
-.. ocv:function:: template<typename Y> Ptr::Ptr(Y* p)
-.. ocv:function:: template<typename Y, typename D> Ptr::Ptr(Y* p, D d)
-
- :param d: Deleter to use for the owned pointer.
- :param p: Pointer to own.
-
- If ``p`` is null, these are equivalent to the default constructor.
-
- Otherwise, these constructors assume ownership of ``p`` - that is, the created ``Ptr`` owns
- and stores ``p`` and assumes it is the sole owner of it. Don't use them if ``p`` is already
- owned by another ``Ptr``, or else ``p`` will get deleted twice.
-
- With the first constructor, ``DefaultDeleter<Y>()`` becomes the associated deleter (so ``p``
- will eventually be deleted with the standard ``delete`` operator). ``Y`` must be a complete
- type at the point of invocation.
-
- With the second constructor, ``d`` becomes the associated deleter.
-
- ``Y*`` must be convertible to ``T*``.
-
- .. note:: It is often easier to use :ocv:func:`makePtr` instead.
-
-Ptr::Ptr (sharing ownership)
-----------------------------
-
-.. ocv:function:: Ptr::Ptr(const Ptr& o)
-.. ocv:function:: template<typename Y> Ptr::Ptr(const Ptr<Y>& o)
-.. ocv:function:: template<typename Y> Ptr::Ptr(const Ptr<Y>& o, T* p)
-
- :param o: ``Ptr`` to share ownership with.
- :param p: Pointer to store.
-
- These constructors create a ``Ptr`` that shares ownership with another ``Ptr`` - that is,
- own the same pointer as ``o``.
-
- With the first two, the same pointer is stored, as well; for the second, ``Y*`` must be convertible to ``T*``.
-
- With the third, ``p`` is stored, and ``Y`` may be any type. This constructor allows to have completely
- unrelated owned and stored pointers, and should be used with care to avoid confusion. A relatively
- benign use is to create a non-owning ``Ptr``, like this::
-
- ptr = Ptr<T>(Ptr<T>(), dont_delete_me); // owns nothing; will not delete the pointer.
-
-Ptr::~Ptr
----------
-
-.. ocv:function:: Ptr::~Ptr()
-
- The destructor is equivalent to calling :ocv:func:`Ptr::release`.
-
-Ptr::operator =
-----------------
-
-.. ocv:function:: Ptr& Ptr::operator = (const Ptr& o)
-.. ocv:function:: template<typename Y> Ptr& Ptr::operator = (const Ptr<Y>& o)
-
- :param o: ``Ptr`` to share ownership with.
-
- Assignment replaces the current ``Ptr`` instance with one that owns and stores same
- pointers as ``o`` and then destroys the old instance.
-
-
-Ptr::release
-------------
-
-.. ocv:function:: void Ptr::release()
-
- If no other ``Ptr`` instance owns the owned pointer, deletes it with the associated deleter.
- Then sets both the owned and the stored pointers to ``NULL``.
-
-
-Ptr::reset
-----------
-
-.. ocv:function:: template<typename Y> void Ptr::reset(Y* p)
-.. ocv:function:: template<typename Y, typename D> void Ptr::reset(Y* p, D d)
-
- :param d: Deleter to use for the owned pointer.
- :param p: Pointer to own.
-
- ``ptr.reset(...)`` is equivalent to ``ptr = Ptr<T>(...)``.
-
-Ptr::swap
----------
-
-.. ocv:function:: void Ptr::swap(Ptr& o)
-
- :param o: ``Ptr`` to swap with.
-
- Swaps the owned and stored pointers (and deleters, if any) of this and ``o``.
-
-Ptr::get
---------
-
-.. ocv:function:: T* Ptr::get() const
-
- Returns the stored pointer.
-
-Ptr pointer emulation
----------------------
-
-.. ocv:function:: T& Ptr::operator * () const
-.. ocv:function:: T* Ptr::operator -> () const
-.. ocv:function:: Ptr::operator T* () const
-
- These operators are what allows ``Ptr`` to pretend to be a pointer.
-
- If ``ptr`` is a ``Ptr<T>``, then ``*ptr`` is equivalent to ``*ptr.get()``
- and ``ptr->foo`` is equivalent to ``ptr.get()->foo``. In addition, ``ptr``
- is implicitly convertible to ``T*``, and such conversion is equivalent to
- ``ptr.get()``. As a corollary, ``if (ptr)`` is equivalent to ``if (ptr.get())``.
- In other words, a ``Ptr`` behaves as if it was its own stored pointer.
-
-Ptr::empty
-----------
-
-.. ocv:function:: bool Ptr::empty() const
-
- ``ptr.empty()`` is equivalent to ``!ptr.get()``.
-
-Ptr casts
----------
-
-.. ocv:function:: template<typename Y> Ptr<Y> Ptr::staticCast() const
-.. ocv:function:: template<typename Y> Ptr<Y> Ptr::constCast() const
-.. ocv:function:: template<typename Y> Ptr<Y> Ptr::dynamicCast() const
-
- If ``ptr`` is a ``Ptr``, then ``ptr.fooCast<Y>()`` is equivalent to
- ``Ptr<Y>(ptr, foo_cast<Y>(ptr.get()))``. That is, these functions create
- a new ``Ptr`` with the same owned pointer and a cast stored pointer.
-
-Ptr global swap
----------------
-
-.. ocv:function:: template<typename T> void swap(Ptr<T>& ptr1, Ptr<T>& ptr2)
-
- Equivalent to ``ptr1.swap(ptr2)``. Provided to help write generic algorithms.
-
-Ptr comparisons
----------------
-
-.. ocv:function:: template<typename T> bool operator == (const Ptr<T>& ptr1, const Ptr<T>& ptr2)
-.. ocv:function:: template<typename T> bool operator != (const Ptr<T>& ptr1, const Ptr<T>& ptr2)
-
- Return whether ``ptr1.get()`` and ``ptr2.get()`` are equal and not equal, respectively.
-
-makePtr
--------
-
-.. ocv:function:: template<typename T> Ptr<T> makePtr()
-.. ocv:function:: template<typename T, typename A1> Ptr<T> makePtr(const A1& a1)
-.. ocv:function:: template<typename T, typename A1, typename A2> Ptr<T> makePtr(const A1& a1, const A2& a2)
-.. ocv:function:: template<typename T, typename A1, typename A2, typename A3> Ptr<T> makePtr(const A1& a1, const A2& a2, const A3& a3)
-
- (and so on...)
-
- ``makePtr<T>(...)`` is equivalent to ``Ptr<T>(new T(...))``. It is shorter than the latter, and
- it's marginally safer than using a constructor or :ocv:func:`Ptr::reset`, since it ensures that
- the owned pointer is new and thus not owned by any other ``Ptr`` instance.
-
- Unfortunately, perfect forwarding is impossible to implement in C++03, and so ``makePtr`` is limited
- to constructors of ``T`` that have up to 10 arguments, none of which are non-const references.
-
-Mat
----
-.. ocv:class:: Mat
-
-OpenCV C++ n-dimensional dense array class
-::
-
- class CV_EXPORTS Mat
- {
- public:
- // ... a lot of methods ...
- ...
-
- /*! includes several bit-fields:
- - the magic signature
- - continuity flag
- - depth
- - number of channels
- */
- int flags;
- //! the array dimensionality, >= 2
- int dims;
- //! the number of rows and columns or (-1, -1) when the array has more than 2 dimensions
- int rows, cols;
- //! pointer to the data
- uchar* data;
-
- //! pointer to the reference counter;
- // when array points to user-allocated data, the pointer is NULL
- int* refcount;
-
- // other members
- ...
- };
-
-The class ``Mat`` represents an n-dimensional dense numerical single-channel or multi-channel array. It can be used to store real or complex-valued vectors and matrices, grayscale or color images, voxel volumes, vector fields, point clouds, tensors, histograms (though, very high-dimensional histograms may be better stored in a ``SparseMat`` ). The data layout of the array
-:math:`M` is defined by the array ``M.step[]``, so that the address of element
-:math:`(i_0,...,i_{M.dims-1})`, where
-:math:`0\leq i_k<M.size[k]`, is computed as:
-
-.. math::
-
- addr(M_{i_0,...,i_{M.dims-1}}) = M.data + M.step[0]*i_0 + M.step[1]*i_1 + ... + M.step[M.dims-1]*i_{M.dims-1}
-
-In case of a 2-dimensional array, the above formula is reduced to:
-
-.. math::
-
- addr(M_{i,j}) = M.data + M.step[0]*i + M.step[1]*j
-
-Note that ``M.step[i] >= M.step[i+1]`` (in fact, ``M.step[i] >= M.step[i+1]*M.size[i+1]`` ). This means that 2-dimensional matrices are stored row-by-row, 3-dimensional matrices are stored plane-by-plane, and so on. ``M.step[M.dims-1]`` is minimal and always equal to the element size ``M.elemSize()`` .
-
-So, the data layout in ``Mat`` is fully compatible with ``CvMat``, ``IplImage``, and ``CvMatND`` types from OpenCV 1.x. It is also compatible with the majority of dense array types from the standard toolkits and SDKs, such as Numpy (ndarray), Win32 (independent device bitmaps), and others, that is, with any array that uses *steps* (or *strides*) to compute the position of a pixel. Due to this compatibility, it is possible to make a ``Mat`` header for user-allocated data and process it in-place using OpenCV functions.
-
-There are many different ways to create a ``Mat`` object. The most popular options are listed below:
-
-*
-
- Use the ``create(nrows, ncols, type)`` method or the similar ``Mat(nrows, ncols, type[, fillValue])`` constructor. A new array of the specified size and type is allocated. ``type`` has the same meaning as in the ``cvCreateMat`` method.
- For example, ``CV_8UC1`` means a 8-bit single-channel array, ``CV_32FC2`` means a 2-channel (complex) floating-point array, and so on.
-
- ::
-
- // make a 7x7 complex matrix filled with 1+3j.
- Mat M(7,7,CV_32FC2,Scalar(1,3));
- // and now turn M to a 100x60 15-channel 8-bit matrix.
- // The old content will be deallocated
- M.create(100,60,CV_8UC(15));
-
- ..
-
- As noted in the introduction to this chapter, ``create()`` allocates only a new array when the shape or type of the current array are different from the specified ones.
-
-*
-
- Create a multi-dimensional array:
-
- ::
-
- // create a 100x100x100 8-bit array
- int sz[] = {100, 100, 100};
- Mat bigCube(3, sz, CV_8U, Scalar::all(0));
-
- ..
-
- It passes the number of dimensions =1 to the ``Mat`` constructor but the created array will be 2-dimensional with the number of columns set to 1. So, ``Mat::dims`` is always >= 2 (can also be 0 when the array is empty).
-
-*
-
- Use a copy constructor or assignment operator where there can be an array or expression on the right side (see below). As noted in the introduction, the array assignment is an O(1) operation because it only copies the header and increases the reference counter. The ``Mat::clone()`` method can be used to get a full (deep) copy of the array when you need it.
-
-*
-
- Construct a header for a part of another array. It can be a single row, single column, several rows, several columns, rectangular region in the array (called a *minor* in algebra) or a diagonal. Such operations are also O(1) because the new header references the same data. You can actually modify a part of the array using this feature, for example:
-
- ::
-
- // add the 5-th row, multiplied by 3 to the 3rd row
- M.row(3) = M.row(3) + M.row(5)*3;
-
- // now copy the 7-th column to the 1-st column
- // M.col(1) = M.col(7); // this will not work
- Mat M1 = M.col(1);
- M.col(7).copyTo(M1);
-
- // create a new 320x240 image
- Mat img(Size(320,240),CV_8UC3);
- // select a ROI
- Mat roi(img, Rect(10,10,100,100));
- // fill the ROI with (0,255,0) (which is green in RGB space);
- // the original 320x240 image will be modified
- roi = Scalar(0,255,0);
-
- ..
-
- Due to the additional ``datastart`` and ``dataend`` members, it is possible to compute a relative sub-array position in the main *container* array using ``locateROI()``:
-
- ::
-
- Mat A = Mat::eye(10, 10, CV_32S);
- // extracts A columns, 1 (inclusive) to 3 (exclusive).
- Mat B = A(Range::all(), Range(1, 3));
- // extracts B rows, 5 (inclusive) to 9 (exclusive).
- // that is, C ~ A(Range(5, 9), Range(1, 3))
- Mat C = B(Range(5, 9), Range::all());
- Size size; Point ofs;
- C.locateROI(size, ofs);
- // size will be (width=10,height=10) and the ofs will be (x=1, y=5)
-
- ..
-
- As in case of whole matrices, if you need a deep copy, use the ``clone()`` method of the extracted sub-matrices.
-
-*
-
- Make a header for user-allocated data. It can be useful to do the following:
-
- #.
- Process "foreign" data using OpenCV (for example, when you implement a DirectShow* filter or a processing module for ``gstreamer``, and so on). For example:
-
- ::
-
- void process_video_frame(const unsigned char* pixels,
- int width, int height, int step)
- {
- Mat img(height, width, CV_8UC3, pixels, step);
- GaussianBlur(img, img, Size(7,7), 1.5, 1.5);
- }
-
- ..
-
- #.
- Quickly initialize small matrices and/or get a super-fast element access.
-
- ::
-
- double m[3][3] = {{a, b, c}, {d, e, f}, {g, h, i}};
- Mat M = Mat(3, 3, CV_64F, m).inv();
-
- ..
-
- Partial yet very common cases of this *user-allocated data* case are conversions from ``CvMat`` and ``IplImage`` to ``Mat``. For this purpose, there are special constructors taking pointers to ``CvMat`` or ``IplImage`` and the optional flag indicating whether to copy the data or not.
-
- Backward conversion from ``Mat`` to ``CvMat`` or ``IplImage`` is provided via cast operators ``Mat::operator CvMat() const`` and ``Mat::operator IplImage()``. The operators do NOT copy the data.
-
- ::
-
- IplImage* img = cvLoadImage("greatwave.jpg", 1);
- Mat mtx(img); // convert IplImage* -> Mat
- CvMat oldmat = mtx; // convert Mat -> CvMat
- CV_Assert(oldmat.cols == img->width && oldmat.rows == img->height &&
- oldmat.data.ptr == (uchar*)img->imageData && oldmat.step == img->widthStep);
-
- ..
-
-*
-
- Use MATLAB-style array initializers, ``zeros(), ones(), eye()``, for example:
-
- ::
-
- // create a double-precision identity martix and add it to M.
- M += Mat::eye(M.rows, M.cols, CV_64F);
-
- ..
-
-*
-
- Use a comma-separated initializer:
-
- ::
-
- // create a 3x3 double-precision identity matrix
- Mat M = (Mat_<double>(3,3) << 1, 0, 0, 0, 1, 0, 0, 0, 1);
-
- ..
-
- With this approach, you first call a constructor of the :ocv:class:`Mat_` class with the proper parameters, and then you just put ``<<`` operator followed by comma-separated values that can be constants, variables, expressions, and so on. Also, note the extra parentheses required to avoid compilation errors.
-
-Once the array is created, it is automatically managed via a reference-counting mechanism. If the array header is built on top of user-allocated data, you should handle the data by yourself.
-The array data is deallocated when no one points to it. If you want to release the data pointed by a array header before the array destructor is called, use ``Mat::release()`` .
-
-The next important thing to learn about the array class is element access. This manual already described how to compute an address of each array element. Normally, you are not required to use the formula directly in the code. If you know the array element type (which can be retrieved using the method ``Mat::type()`` ), you can access the element
-:math:`M_{ij}` of a 2-dimensional array as: ::
-
- M.at<double>(i,j) += 1.f;
-
-
-assuming that M is a double-precision floating-point array. There are several variants of the method ``at`` for a different number of dimensions.
-
-If you need to process a whole row of a 2D array, the most efficient way is to get the pointer to the row first, and then just use the plain C operator ``[]`` : ::
-
- // compute sum of positive matrix elements
- // (assuming that M isa double-precision matrix)
- double sum=0;
- for(int i = 0; i < M.rows; i++)
- {
- const double* Mi = M.ptr<double>(i);
- for(int j = 0; j < M.cols; j++)
- sum += std::max(Mi[j], 0.);
- }
-
-
-Some operations, like the one above, do not actually depend on the array shape. They just process elements of an array one by one (or elements from multiple arrays that have the same coordinates, for example, array addition). Such operations are called *element-wise*. It makes sense to check whether all the input/output arrays are continuous, namely, have no gaps at the end of each row. If yes, process them as a long single row: ::
-
- // compute the sum of positive matrix elements, optimized variant
- double sum=0;
- int cols = M.cols, rows = M.rows;
- if(M.isContinuous())
- {
- cols *= rows;
- rows = 1;
- }
- for(int i = 0; i < rows; i++)
- {
- const double* Mi = M.ptr<double>(i);
- for(int j = 0; j < cols; j++)
- sum += std::max(Mi[j], 0.);
- }
-
-
-In case of the continuous matrix, the outer loop body is executed just once. So, the overhead is smaller, which is especially noticeable in case of small matrices.
-
-Finally, there are STL-style iterators that are smart enough to skip gaps between successive rows: ::
-
- // compute sum of positive matrix elements, iterator-based variant
- double sum=0;
- MatConstIterator_<double> it = M.begin<double>(), it_end = M.end<double>();
- for(; it != it_end; ++it)
- sum += std::max(*it, 0.);
-
-
-The matrix iterators are random-access iterators, so they can be passed to any STL algorithm, including ``std::sort()`` .
-
-.. note::
-
- * An example demonstrating the serial out capabilities of cv::Mat can be found at opencv_source_code/samples/cpp/cout_mat.cpp
-
-.. _MatrixExpressions:
-
-Matrix Expressions
-------------------
-
-This is a list of implemented matrix operations that can be combined in arbitrary complex expressions
-(here ``A``, ``B`` stand for matrices ( ``Mat`` ), ``s`` for a scalar ( ``Scalar`` ),
-``alpha`` for a real-valued scalar ( ``double`` )):
-
-*
- Addition, subtraction, negation:
- ``A+B, A-B, A+s, A-s, s+A, s-A, -A``
-
-*
- Scaling:
- ``A*alpha``
-
-*
- Per-element multiplication and division:
- ``A.mul(B), A/B, alpha/A``
-
-*
- Matrix multiplication:
- ``A*B``
-
-*
- Transposition:
- ``A.t()`` (means ``A``\ :sup:`T`)
-
-*
- Matrix inversion and pseudo-inversion, solving linear systems and least-squares problems:
-
- ``A.inv([method])`` (~ ``A``\ :sup:`-1`) ``, A.inv([method])*B`` (~ ``X: AX=B``)
-
-*
- Comparison:
- ``A cmpop B, A cmpop alpha, alpha cmpop A``, where ``cmpop`` is one of ``: >, >=, ==, !=, <=, <``. The result of comparison is an 8-bit single channel mask whose elements are set to 255 (if the particular element or pair of elements satisfy the condition) or 0.
-
-*
- Bitwise logical operations: ``A logicop B, A logicop s, s logicop A, ~A``, where ``logicop`` is one of ``: &, |, ^``.
-
-*
- Element-wise minimum and maximum:
- ``min(A, B), min(A, alpha), max(A, B), max(A, alpha)``
-
-*
- Element-wise absolute value:
- ``abs(A)``
-
-*
- Cross-product, dot-product:
- ``A.cross(B)``
- ``A.dot(B)``
-
-*
- Any function of matrix or matrices and scalars that returns a matrix or a scalar, such as ``norm``, ``mean``, ``sum``, ``countNonZero``, ``trace``, ``determinant``, ``repeat``, and others.
-
-*
- Matrix initializers ( ``Mat::eye(), Mat::zeros(), Mat::ones()`` ), matrix comma-separated initializers, matrix constructors and operators that extract sub-matrices (see :ocv:class:`Mat` description).
-
-*
- ``Mat_<destination_type>()`` constructors to cast the result to the proper type.
-
-.. note:: Comma-separated initializers and probably some other operations may require additional explicit ``Mat()`` or ``Mat_<T>()`` constructor calls to resolve a possible ambiguity.
-
-Here are examples of matrix expressions:
-
-::
-
- // compute pseudo-inverse of A, equivalent to A.inv(DECOMP_SVD)
- SVD svd(A);
- Mat pinvA = svd.vt.t()*Mat::diag(1./svd.w)*svd.u.t();
-
- // compute the new vector of parameters in the Levenberg-Marquardt algorithm
- x -= (A.t()*A + lambda*Mat::eye(A.cols,A.cols,A.type())).inv(DECOMP_CHOLESKY)*(A.t()*err);
-
- // sharpen image using "unsharp mask" algorithm
- Mat blurred; double sigma = 1, threshold = 5, amount = 1;
- GaussianBlur(img, blurred, Size(), sigma, sigma);
- Mat lowConstrastMask = abs(img - blurred) < threshold;
- Mat sharpened = img*(1+amount) + blurred*(-amount);
- img.copyTo(sharpened, lowContrastMask);
-
-..
-
-
-Below is the formal description of the ``Mat`` methods.
-
-Mat::Mat
---------
-Various Mat constructors
-
-.. ocv:function:: Mat::Mat()
-
-.. ocv:function:: Mat::Mat(int rows, int cols, int type)
-
-.. ocv:function:: Mat::Mat(Size size, int type)
-
-.. ocv:function:: Mat::Mat(int rows, int cols, int type, const Scalar& s)
-
-.. ocv:function:: Mat::Mat(Size size, int type, const Scalar& s)
-
-.. ocv:function:: Mat::Mat(const Mat& m)
-
-.. ocv:function:: Mat::Mat(int rows, int cols, int type, void* data, size_t step=AUTO_STEP)
-
-.. ocv:function:: Mat::Mat(Size size, int type, void* data, size_t step=AUTO_STEP)
-
-.. ocv:function:: Mat::Mat( const Mat& m, const Range& rowRange, const Range& colRange=Range::all() )
-
-.. ocv:function:: Mat::Mat(const Mat& m, const Rect& roi)
-
-.. ocv:function:: template<typename T, int n> explicit Mat::Mat(const Vec<T, n>& vec, bool copyData=true)
-
-.. ocv:function:: template<typename T, int m, int n> explicit Mat::Mat(const Matx<T, m, n>& vec, bool copyData=true)
-
-.. ocv:function:: template<typename T> explicit Mat::Mat(const vector<T>& vec, bool copyData=false)
-
-.. ocv:function:: Mat::Mat(int ndims, const int* sizes, int type)
-
-.. ocv:function:: Mat::Mat(int ndims, const int* sizes, int type, const Scalar& s)
-
-.. ocv:function:: Mat::Mat(int ndims, const int* sizes, int type, void* data, const size_t* steps=0)
-
-.. ocv:function:: Mat::Mat(const Mat& m, const Range* ranges)
-
- :param ndims: Array dimensionality.
-
- :param rows: Number of rows in a 2D array.
-
- :param cols: Number of columns in a 2D array.
-
- :param roi: Region of interest.
-
- :param size: 2D array size: ``Size(cols, rows)`` . In the ``Size()`` constructor, the number of rows and the number of columns go in the reverse order.
-
- :param sizes: Array of integers specifying an n-dimensional array shape.
-
- :param type: Array type. Use ``CV_8UC1, ..., CV_64FC4`` to create 1-4 channel matrices, or ``CV_8UC(n), ..., CV_64FC(n)`` to create multi-channel (up to ``CV_CN_MAX`` channels) matrices.
-
- :param s: An optional value to initialize each matrix element with. To set all the matrix elements to the particular value after the construction, use the assignment operator ``Mat::operator=(const Scalar& value)`` .
-
- :param data: Pointer to the user data. Matrix constructors that take ``data`` and ``step`` parameters do not allocate matrix data. Instead, they just initialize the matrix header that points to the specified data, which means that no data is copied. This operation is very efficient and can be used to process external data using OpenCV functions. The external data is not automatically deallocated, so you should take care of it.
-
- :param step: Number of bytes each matrix row occupies. The value should include the padding bytes at the end of each row, if any. If the parameter is missing (set to ``AUTO_STEP`` ), no padding is assumed and the actual step is calculated as ``cols*elemSize()`` . See :ocv:func:`Mat::elemSize` .
-
- :param steps: Array of ``ndims-1`` steps in case of a multi-dimensional array (the last step is always set to the element size). If not specified, the matrix is assumed to be continuous.
-
- :param m: Array that (as a whole or partly) is assigned to the constructed matrix. No data is copied by these constructors. Instead, the header pointing to ``m`` data or its sub-array is constructed and associated with it. The reference counter, if any, is incremented. So, when you modify the matrix formed using such a constructor, you also modify the corresponding elements of ``m`` . If you want to have an independent copy of the sub-array, use ``Mat::clone()`` .
-
- :param img: Pointer to the old-style ``IplImage`` image structure. By default, the data is shared between the original image and the new matrix. But when ``copyData`` is set, the full copy of the image data is created.
-
- :param vec: STL vector whose elements form the matrix. The matrix has a single column and the number of rows equal to the number of vector elements. Type of the matrix matches the type of vector elements. The constructor can handle arbitrary types, for which there is a properly declared :ocv:class:`DataType` . This means that the vector elements must be primitive numbers or uni-type numerical tuples of numbers. Mixed-type structures are not supported. The corresponding constructor is explicit. Since STL vectors are not automatically converted to ``Mat`` instances, you should write ``Mat(vec)`` explicitly. Unless you copy the data into the matrix ( ``copyData=true`` ), no new elements will be added to the vector because it can potentially yield vector data reallocation, and, thus, the matrix data pointer will be invalid.
-
- :param copyData: Flag to specify whether the underlying data of the STL vector or the old-style ``CvMat`` or ``IplImage`` should be copied to (``true``) or shared with (``false``) the newly constructed matrix. When the data is copied, the allocated buffer is managed using ``Mat`` reference counting mechanism. While the data is shared, the reference counter is NULL, and you should not deallocate the data until the matrix is not destructed.
-
- :param rowRange: Range of the ``m`` rows to take. As usual, the range start is inclusive and the range end is exclusive. Use ``Range::all()`` to take all the rows.
-
- :param colRange: Range of the ``m`` columns to take. Use ``Range::all()`` to take all the columns.
-
- :param ranges: Array of selected ranges of ``m`` along each dimensionality.
-
-These are various constructors that form a matrix. As noted in the :ref:`AutomaticAllocation`,
-often the default constructor is enough, and the proper matrix will be allocated by an OpenCV function. The constructed matrix can further be assigned to another matrix or matrix expression or can be allocated with
-:ocv:func:`Mat::create` . In the former case, the old content is de-referenced.
-
-
-Mat::~Mat
----------
-The Mat destructor.
-
-.. ocv:function:: Mat::~Mat()
-
-The matrix destructor calls :ocv:func:`Mat::release` .
-
-
-Mat::operator =
----------------
-Provides matrix assignment operators.
-
-.. ocv:function:: Mat& Mat::operator = (const Mat& m)
-
-.. ocv:function:: Mat& Mat::operator =( const MatExpr& expr )
-
-.. ocv:function:: Mat& Mat::operator = (const Scalar& s)
-
- :param m: Assigned, right-hand-side matrix. Matrix assignment is an O(1) operation. This means that no data is copied but the data is shared and the reference counter, if any, is incremented. Before assigning new data, the old data is de-referenced via :ocv:func:`Mat::release` .
-
- :param expr: Assigned matrix expression object. As opposite to the first form of the assignment operation, the second form can reuse already allocated matrix if it has the right size and type to fit the matrix expression result. It is automatically handled by the real function that the matrix expressions is expanded to. For example, ``C=A+B`` is expanded to ``add(A, B, C)``, and :func:`add` takes care of automatic ``C`` reallocation.
-
- :param s: Scalar assigned to each matrix element. The matrix size or type is not changed.
-
-These are available assignment operators. Since they all are very different, make sure to read the operator parameters description.
-
-Mat::row
---------
-Creates a matrix header for the specified matrix row.
-
-.. ocv:function:: Mat Mat::row(int y) const
-
- :param y: A 0-based row index.
-
-The method makes a new header for the specified matrix row and returns it. This is an O(1) operation, regardless of the matrix size. The underlying data of the new matrix is shared with the original matrix. Here is the example of one of the classical basic matrix processing operations, ``axpy``, used by LU and many other algorithms: ::
-
- inline void matrix_axpy(Mat& A, int i, int j, double alpha)
- {
- A.row(i) += A.row(j)*alpha;
- }
-
-
-.. note::
-
- In the current implementation, the following code does not work as expected: ::
-
- Mat A;
- ...
- A.row(i) = A.row(j); // will not work
-
-
- This happens because ``A.row(i)`` forms a temporary header that is further assigned to another header. Remember that each of these operations is O(1), that is, no data is copied. Thus, the above assignment is not true if you may have expected the j-th row to be copied to the i-th row. To achieve that, you should either turn this simple assignment into an expression or use the :ocv:func:`Mat::copyTo` method: ::
-
- Mat A;
- ...
- // works, but looks a bit obscure.
- A.row(i) = A.row(j) + 0;
-
- // this is a bit longer, but the recommended method.
- A.row(j).copyTo(A.row(i));
-
-Mat::col
---------
-Creates a matrix header for the specified matrix column.
-
-.. ocv:function:: Mat Mat::col(int x) const
-
- :param x: A 0-based column index.
-
-The method makes a new header for the specified matrix column and returns it. This is an O(1) operation, regardless of the matrix size. The underlying data of the new matrix is shared with the original matrix. See also the
-:ocv:func:`Mat::row` description.
-
-
-Mat::rowRange
--------------
-Creates a matrix header for the specified row span.
-
-.. ocv:function:: Mat Mat::rowRange(int startrow, int endrow) const
-
-.. ocv:function:: Mat Mat::rowRange(const Range& r) const
-
- :param startrow: An inclusive 0-based start index of the row span.
-
- :param endrow: An exclusive 0-based ending index of the row span.
-
- :param r: :ocv:class:`Range` structure containing both the start and the end indices.
-
-The method makes a new header for the specified row span of the matrix. Similarly to
-:ocv:func:`Mat::row` and
-:ocv:func:`Mat::col` , this is an O(1) operation.
-
-Mat::colRange
--------------
-Creates a matrix header for the specified column span.
-
-.. ocv:function:: Mat Mat::colRange(int startcol, int endcol) const
-
-.. ocv:function:: Mat Mat::colRange(const Range& r) const
-
- :param startcol: An inclusive 0-based start index of the column span.
-
- :param endcol: An exclusive 0-based ending index of the column span.
-
- :param r: :ocv:class:`Range` structure containing both the start and the end indices.
-
-The method makes a new header for the specified column span of the matrix. Similarly to
-:ocv:func:`Mat::row` and
-:ocv:func:`Mat::col` , this is an O(1) operation.
-
-Mat::diag
----------
-Extracts a diagonal from a matrix, or creates a diagonal matrix.
-
-.. ocv:function:: Mat Mat::diag( int d=0 ) const
-
-.. ocv:function:: static Mat Mat::diag( const Mat& d )
-
- :param d: Single-column matrix that forms a diagonal matrix or index of the diagonal, with the following values:
-
- * **d=0** is the main diagonal.
-
- * **d>0** is a diagonal from the lower half. For example, ``d=1`` means the diagonal is set immediately below the main one.
-
- * **d<0** is a diagonal from the upper half. For example, ``d=1`` means the diagonal is set immediately above the main one.
-
-The method makes a new header for the specified matrix diagonal. The new matrix is represented as a single-column matrix. Similarly to
-:ocv:func:`Mat::row` and
-:ocv:func:`Mat::col` , this is an O(1) operation.
-
-Mat::clone
-----------
-Creates a full copy of the array and the underlying data.
-
-.. ocv:function:: Mat Mat::clone() const
-
-The method creates a full copy of the array. The original ``step[]`` is not taken into account. So, the array copy is a continuous array occupying ``total()*elemSize()`` bytes.
-
-
-Mat::copyTo
------------
-Copies the matrix to another one.
-
-.. ocv:function:: void Mat::copyTo( OutputArray m ) const
-.. ocv:function:: void Mat::copyTo( OutputArray m, InputArray mask ) const
-
- :param m: Destination matrix. If it does not have a proper size or type before the operation, it is reallocated.
-
- :param mask: Operation mask. Its non-zero elements indicate which matrix elements need to be copied.
-
-The method copies the matrix data to another matrix. Before copying the data, the method invokes ::
-
- m.create(this->size(), this->type());
-
-
-so that the destination matrix is reallocated if needed. While ``m.copyTo(m);`` works flawlessly, the function does not handle the case of a partial overlap between the source and the destination matrices.
-
-When the operation mask is specified, if the ``Mat::create`` call shown above reallocates the matrix, the newly allocated matrix is initialized with all zeros before copying the data.
-
-.. _Mat::convertTo:
-
-Mat::convertTo
---------------
-Converts an array to another data type with optional scaling.
-
-.. ocv:function:: void Mat::convertTo( OutputArray m, int rtype, double alpha=1, double beta=0 ) const
-
- :param m: output matrix; if it does not have a proper size or type before the operation, it is reallocated.
-
- :param rtype: desired output matrix type or, rather, the depth since the number of channels are the same as the input has; if ``rtype`` is negative, the output matrix will have the same type as the input.
-
- :param alpha: optional scale factor.
-
- :param beta: optional delta added to the scaled values.
-
-The method converts source pixel values to the target data type. ``saturate_cast<>`` is applied at the end to avoid possible overflows:
-
-.. math::
-
- m(x,y) = saturate \_ cast<rType>( \alpha (*this)(x,y) + \beta )
-
-
-Mat::assignTo
--------------
-Provides a functional form of ``convertTo``.
-
-.. ocv:function:: void Mat::assignTo( Mat& m, int type=-1 ) const
-
- :param m: Destination array.
-
- :param type: Desired destination array depth (or -1 if it should be the same as the source type).
-
-This is an internally used method called by the
-:ref:`MatrixExpressions` engine.
-
-Mat::setTo
-----------
-Sets all or some of the array elements to the specified value.
-
-.. ocv:function:: Mat& Mat::setTo( InputArray value, InputArray mask=noArray() )
-
- :param value: Assigned scalar converted to the actual array type.
-
- :param mask: Operation mask of the same size as ``*this``. This is an advanced variant of the ``Mat::operator=(const Scalar& s)`` operator.
-
-
-Mat::reshape
-------------
-Changes the shape and/or the number of channels of a 2D matrix without copying the data.
-
-.. ocv:function:: Mat Mat::reshape(int cn, int rows=0) const
-
- :param cn: New number of channels. If the parameter is 0, the number of channels remains the same.
-
- :param rows: New number of rows. If the parameter is 0, the number of rows remains the same.
-
-The method makes a new matrix header for ``*this`` elements. The new matrix may have a different size and/or different number of channels. Any combination is possible if:
-
-*
- No extra elements are included into the new matrix and no elements are excluded. Consequently, the product ``rows*cols*channels()`` must stay the same after the transformation.
-
-*
- No data is copied. That is, this is an O(1) operation. Consequently, if you change the number of rows, or the operation changes the indices of elements row in some other way, the matrix must be continuous. See
- :ocv:func:`Mat::isContinuous` .
-
-For example, if there is a set of 3D points stored as an STL vector, and you want to represent the points as a ``3xN`` matrix, do the following: ::
-
- std::vector<Point3f> vec;
- ...
-
- Mat pointMat = Mat(vec). // convert vector to Mat, O(1) operation
- reshape(1). // make Nx3 1-channel matrix out of Nx1 3-channel.
- // Also, an O(1) operation
- t(); // finally, transpose the Nx3 matrix.
- // This involves copying all the elements
-
-
-
-
-Mat::t
-------
-Transposes a matrix.
-
-.. ocv:function:: MatExpr Mat::t() const
-
-The method performs matrix transposition by means of matrix expressions. It does not perform the actual transposition but returns a temporary matrix transposition object that can be further used as a part of more complex matrix expressions or can be assigned to a matrix: ::
-
- Mat A1 = A + Mat::eye(A.size(), A.type())*lambda;
- Mat C = A1.t()*A1; // compute (A + lambda*I)^t * (A + lamda*I)
-
-
-Mat::inv
---------
-Inverses a matrix.
-
-.. ocv:function:: MatExpr Mat::inv(int method=DECOMP_LU) const
-
- :param method: Matrix inversion method. Possible values are the following:
-
- * **DECOMP_LU** is the LU decomposition. The matrix must be non-singular.
-
- * **DECOMP_CHOLESKY** is the Cholesky :math:`LL^T` decomposition for symmetrical positively defined matrices only. This type is about twice faster than LU on big matrices.
-
- * **DECOMP_SVD** is the SVD decomposition. If the matrix is singular or even non-square, the pseudo inversion is computed.
-
-The method performs a matrix inversion by means of matrix expressions. This means that a temporary matrix inversion object is returned by the method and can be used further as a part of more complex matrix expressions or can be assigned to a matrix.
-
-
-Mat::mul
---------
-Performs an element-wise multiplication or division of the two matrices.
-
-.. ocv:function:: MatExpr Mat::mul(InputArray m, double scale=1) const
-
- :param m: Another array of the same type and the same size as ``*this``, or a matrix expression.
-
- :param scale: Optional scale factor.
-
-The method returns a temporary object encoding per-element array multiplication, with optional scale. Note that this is not a matrix multiplication that corresponds to a simpler "*" operator.
-
-Example: ::
-
- Mat C = A.mul(5/B); // equivalent to divide(A, B, C, 5)
-
-
-Mat::cross
-----------
-Computes a cross-product of two 3-element vectors.
-
-.. ocv:function:: Mat Mat::cross(InputArray m) const
-
- :param m: Another cross-product operand.
-
-The method computes a cross-product of two 3-element vectors. The vectors must be 3-element floating-point vectors of the same shape and size. The result is another 3-element vector of the same shape and type as operands.
-
-
-Mat::dot
---------
-Computes a dot-product of two vectors.
-
-.. ocv:function:: double Mat::dot(InputArray m) const
-
- :param m: another dot-product operand.
-
-The method computes a dot-product of two matrices. If the matrices are not single-column or single-row vectors, the top-to-bottom left-to-right scan ordering is used to treat them as 1D vectors. The vectors must have the same size and type. If the matrices have more than one channel, the dot products from all the channels are summed together.
-
-
-Mat::zeros
-----------
-Returns a zero array of the specified size and type.
-
-.. ocv:function:: static MatExpr Mat::zeros(int rows, int cols, int type)
-.. ocv:function:: static MatExpr Mat::zeros(Size size, int type)
-.. ocv:function:: static MatExpr Mat::zeros( int ndims, const int* sz, int type )
-
- :param ndims: Array dimensionality.
-
- :param rows: Number of rows.
-
- :param cols: Number of columns.
-
- :param size: Alternative to the matrix size specification ``Size(cols, rows)`` .
-
- :param sz: Array of integers specifying the array shape.
-
- :param type: Created matrix type.
-
-The method returns a Matlab-style zero array initializer. It can be used to quickly form a constant array as a function parameter, part of a matrix expression, or as a matrix initializer. ::
-
- Mat A;
- A = Mat::zeros(3, 3, CV_32F);
-
-
-In the example above, a new matrix is allocated only if ``A`` is not a 3x3 floating-point matrix. Otherwise, the existing matrix ``A`` is filled with zeros.
-
-
-Mat::ones
--------------
-Returns an array of all 1's of the specified size and type.
-
-.. ocv:function:: static MatExpr Mat::ones(int rows, int cols, int type)
-.. ocv:function:: static MatExpr Mat::ones(Size size, int type)
-.. ocv:function:: static MatExpr Mat::ones( int ndims, const int* sz, int type )
-
- :param ndims: Array dimensionality.
-
- :param rows: Number of rows.
-
- :param cols: Number of columns.
-
- :param size: Alternative to the matrix size specification ``Size(cols, rows)`` .
-
- :param sz: Array of integers specifying the array shape.
-
- :param type: Created matrix type.
-
-The method returns a Matlab-style 1's array initializer, similarly to
-:ocv:func:`Mat::zeros`. Note that using this method you can initialize an array with an arbitrary value, using the following Matlab idiom: ::
-
- Mat A = Mat::ones(100, 100, CV_8U)*3; // make 100x100 matrix filled with 3.
-
-
-The above operation does not form a 100x100 matrix of 1's and then multiply it by 3. Instead, it just remembers the scale factor (3 in this case) and use it when actually invoking the matrix initializer.
-
-
-Mat::eye
-------------
-Returns an identity matrix of the specified size and type.
-
-.. ocv:function:: static MatExpr Mat::eye(int rows, int cols, int type)
-.. ocv:function:: static MatExpr Mat::eye(Size size, int type)
-
- :param rows: Number of rows.
-
- :param cols: Number of columns.
-
- :param size: Alternative matrix size specification as ``Size(cols, rows)`` .
-
- :param type: Created matrix type.
-
-The method returns a Matlab-style identity matrix initializer, similarly to
-:ocv:func:`Mat::zeros`. Similarly to
-:ocv:func:`Mat::ones`, you can use a scale operation to create a scaled identity matrix efficiently: ::
-
- // make a 4x4 diagonal matrix with 0.1's on the diagonal.
- Mat A = Mat::eye(4, 4, CV_32F)*0.1;
-
-
-Mat::create
----------------
-Allocates new array data if needed.
-
-.. ocv:function:: void Mat::create(int rows, int cols, int type)
-.. ocv:function:: void Mat::create(Size size, int type)
-.. ocv:function:: void Mat::create(int ndims, const int* sizes, int type)
-
- :param ndims: New array dimensionality.
-
- :param rows: New number of rows.
-
- :param cols: New number of columns.
-
- :param size: Alternative new matrix size specification: ``Size(cols, rows)``
-
- :param sizes: Array of integers specifying a new array shape.
-
- :param type: New matrix type.
-
-This is one of the key ``Mat`` methods. Most new-style OpenCV functions and methods that produce arrays call this method for each output array. The method uses the following algorithm:
-
-#.
- If the current array shape and the type match the new ones, return immediately. Otherwise, de-reference the previous data by calling
- :ocv:func:`Mat::release`.
-
-#.
- Initialize the new header.
-
-#.
- Allocate the new data of ``total()*elemSize()`` bytes.
-
-#.
- Allocate the new, associated with the data, reference counter and set it to 1.
-
-Such a scheme makes the memory management robust and efficient at the same time and helps avoid extra typing for you. This means that usually there is no need to explicitly allocate output arrays. That is, instead of writing: ::
-
- Mat color;
- ...
- Mat gray(color.rows, color.cols, color.depth());
- cvtColor(color, gray, COLOR_BGR2GRAY);
-
-
-you can simply write: ::
-
- Mat color;
- ...
- Mat gray;
- cvtColor(color, gray, COLOR_BGR2GRAY);
-
-
-because ``cvtColor`` , as well as the most of OpenCV functions, calls ``Mat::create()`` for the output array internally.
-
-
-Mat::addref
------------
-Increments the reference counter.
-
-.. ocv:function:: void Mat::addref()
-
-The method increments the reference counter associated with the matrix data. If the matrix header points to an external data set (see
-:ocv:func:`Mat::Mat` ), the reference counter is NULL, and the method has no effect in this case. Normally, to avoid memory leaks, the method should not be called explicitly. It is called implicitly by the matrix assignment operator. The reference counter increment is an atomic operation on the platforms that support it. Thus, it is safe to operate on the same matrices asynchronously in different threads.
-
-
-Mat::release
-------------
-Decrements the reference counter and deallocates the matrix if needed.
-
-.. ocv:function:: void Mat::release()
-
-The method decrements the reference counter associated with the matrix data. When the reference counter reaches 0, the matrix data is deallocated and the data and the reference counter pointers are set to NULL's. If the matrix header points to an external data set (see
-:ocv:func:`Mat::Mat` ), the reference counter is NULL, and the method has no effect in this case.
-
-This method can be called manually to force the matrix data deallocation. But since this method is automatically called in the destructor, or by any other method that changes the data pointer, it is usually not needed. The reference counter decrement and check for 0 is an atomic operation on the platforms that support it. Thus, it is safe to operate on the same matrices asynchronously in different threads.
-
-Mat::resize
------------
-Changes the number of matrix rows.
-
-.. ocv:function:: void Mat::resize( size_t sz )
-.. ocv:function:: void Mat::resize( size_t sz, const Scalar& s )
-
- :param sz: New number of rows.
- :param s: Value assigned to the newly added elements.
-
-The methods change the number of matrix rows. If the matrix is reallocated, the first ``min(Mat::rows, sz)`` rows are preserved. The methods emulate the corresponding methods of the STL vector class.
-
-
-Mat::reserve
-------------
-Reserves space for the certain number of rows.
-
-.. ocv:function:: void Mat::reserve( size_t sz )
-
- :param sz: Number of rows.
-
-The method reserves space for ``sz`` rows. If the matrix already has enough space to store ``sz`` rows, nothing happens. If the matrix is reallocated, the first ``Mat::rows`` rows are preserved. The method emulates the corresponding method of the STL vector class.
-
-Mat::push_back
---------------
-Adds elements to the bottom of the matrix.
-
-.. ocv:function:: template<typename T> void Mat::push_back(const T& elem)
-
-.. ocv:function:: void Mat::push_back( const Mat& m )
-
- :param elem: Added element(s).
- :param m: Added line(s).
-
-The methods add one or more elements to the bottom of the matrix. They emulate the corresponding method of the STL vector class. When ``elem`` is ``Mat`` , its type and the number of columns must be the same as in the container matrix.
-
-Mat::pop_back
--------------
-Removes elements from the bottom of the matrix.
-
-.. ocv:function:: template<typename T> void Mat::pop_back(size_t nelems=1)
-
- :param nelems: Number of removed rows. If it is greater than the total number of rows, an exception is thrown.
-
-The method removes one or more rows from the bottom of the matrix.
-
-
-Mat::locateROI
---------------
-Locates the matrix header within a parent matrix.
-
-.. ocv:function:: void Mat::locateROI( Size& wholeSize, Point& ofs ) const
-
- :param wholeSize: Output parameter that contains the size of the whole matrix containing ``*this`` as a part.
-
- :param ofs: Output parameter that contains an offset of ``*this`` inside the whole matrix.
-
-After you extracted a submatrix from a matrix using
-:ocv:func:`Mat::row`,
-:ocv:func:`Mat::col`,
-:ocv:func:`Mat::rowRange`,
-:ocv:func:`Mat::colRange` , and others, the resultant submatrix points just to the part of the original big matrix. However, each submatrix contains information (represented by ``datastart`` and ``dataend`` fields) that helps reconstruct the original matrix size and the position of the extracted submatrix within the original matrix. The method ``locateROI`` does exactly that.
-
-
-Mat::adjustROI
---------------
-Adjusts a submatrix size and position within the parent matrix.
-
-.. ocv:function:: Mat& Mat::adjustROI( int dtop, int dbottom, int dleft, int dright )
-
- :param dtop: Shift of the top submatrix boundary upwards.
-
- :param dbottom: Shift of the bottom submatrix boundary downwards.
-
- :param dleft: Shift of the left submatrix boundary to the left.
-
- :param dright: Shift of the right submatrix boundary to the right.
-
-The method is complimentary to
-:ocv:func:`Mat::locateROI` . The typical use of these functions is to determine the submatrix position within the parent matrix and then shift the position somehow. Typically, it can be required for filtering operations when pixels outside of the ROI should be taken into account. When all the method parameters are positive, the ROI needs to grow in all directions by the specified amount, for example: ::
-
- A.adjustROI(2, 2, 2, 2);
-
-
-In this example, the matrix size is increased by 4 elements in each direction. The matrix is shifted by 2 elements to the left and 2 elements up, which brings in all the necessary pixels for the filtering with the 5x5 kernel.
-
-``adjustROI`` forces the adjusted ROI to be inside of the parent matrix that is boundaries of the adjusted ROI are constrained by boundaries of the parent matrix. For example, if the submatrix ``A`` is located in the first row of a parent matrix and you called ``A.adjustROI(2, 2, 2, 2)`` then ``A`` will not be increased in the upward direction.
-
-The function is used internally by the OpenCV filtering functions, like
-:ocv:func:`filter2D` , morphological operations, and so on.
-
-.. seealso:: :ocv:func:`copyMakeBorder`
-
-
-Mat::operator()
----------------
-Extracts a rectangular submatrix.
-
-.. ocv:function:: Mat Mat::operator()( Range rowRange, Range colRange ) const
-
-.. ocv:function:: Mat Mat::operator()( const Rect& roi ) const
-
-.. ocv:function:: Mat Mat::operator()( const Range* ranges ) const
-
-
- :param rowRange: Start and end row of the extracted submatrix. The upper boundary is not included. To select all the rows, use ``Range::all()``.
-
- :param colRange: Start and end column of the extracted submatrix. The upper boundary is not included. To select all the columns, use ``Range::all()``.
-
- :param roi: Extracted submatrix specified as a rectangle.
-
- :param ranges: Array of selected ranges along each array dimension.
-
-The operators make a new header for the specified sub-array of ``*this`` . They are the most generalized forms of
-:ocv:func:`Mat::row`,
-:ocv:func:`Mat::col`,
-:ocv:func:`Mat::rowRange`, and
-:ocv:func:`Mat::colRange` . For example, ``A(Range(0, 10), Range::all())`` is equivalent to ``A.rowRange(0, 10)`` . Similarly to all of the above, the operators are O(1) operations, that is, no matrix data is copied.
-
-
-Mat::total
-----------
-Returns the total number of array elements.
-
-.. ocv:function:: size_t Mat::total() const
-
-The method returns the number of array elements (a number of pixels if the array represents an image).
-
-Mat::isContinuous
------------------
-Reports whether the matrix is continuous or not.
-
-.. ocv:function:: bool Mat::isContinuous() const
-
-The method returns ``true`` if the matrix elements are stored continuously without gaps at the end of each row. Otherwise, it returns ``false``. Obviously, ``1x1`` or ``1xN`` matrices are always continuous. Matrices created with
-:ocv:func:`Mat::create` are always continuous. But if you extract a part of the matrix using
-:ocv:func:`Mat::col`,
-:ocv:func:`Mat::diag` , and so on, or constructed a matrix header for externally allocated data, such matrices may no longer have this property.
-
-The continuity flag is stored as a bit in the ``Mat::flags`` field and is computed automatically when you construct a matrix header. Thus, the continuity check is a very fast operation, though theoretically it could be done as follows: ::
-
- // alternative implementation of Mat::isContinuous()
- bool myCheckMatContinuity(const Mat& m)
- {
- //return (m.flags & Mat::CONTINUOUS_FLAG) != 0;
- return m.rows == 1 || m.step == m.cols*m.elemSize();
- }
-
-
-The method is used in quite a few of OpenCV functions. The point is that element-wise operations (such as arithmetic and logical operations, math functions, alpha blending, color space transformations, and others) do not depend on the image geometry. Thus, if all the input and output arrays are continuous, the functions can process them as very long single-row vectors. The example below illustrates how an alpha-blending function can be implemented. ::
-
- template<typename T>
- void alphaBlendRGBA(const Mat& src1, const Mat& src2, Mat& dst)
- {
- const float alpha_scale = (float)std::numeric_limits<T>::max(),
- inv_scale = 1.f/alpha_scale;
-
- CV_Assert( src1.type() == src2.type() &&
- src1.type() == CV_MAKETYPE(DataType<T>::depth, 4) &&
- src1.size() == src2.size());
- Size size = src1.size();
- dst.create(size, src1.type());
-
- // here is the idiom: check the arrays for continuity and,
- // if this is the case,
- // treat the arrays as 1D vectors
- if( src1.isContinuous() && src2.isContinuous() && dst.isContinuous() )
- {
- size.width *= size.height;
- size.height = 1;
- }
- size.width *= 4;
-
- for( int i = 0; i < size.height; i++ )
- {
- // when the arrays are continuous,
- // the outer loop is executed only once
- const T* ptr1 = src1.ptr<T>(i);
- const T* ptr2 = src2.ptr<T>(i);
- T* dptr = dst.ptr<T>(i);
-
- for( int j = 0; j < size.width; j += 4 )
- {
- float alpha = ptr1[j+3]*inv_scale, beta = ptr2[j+3]*inv_scale;
- dptr[j] = saturate_cast<T>(ptr1[j]*alpha + ptr2[j]*beta);
- dptr[j+1] = saturate_cast<T>(ptr1[j+1]*alpha + ptr2[j+1]*beta);
- dptr[j+2] = saturate_cast<T>(ptr1[j+2]*alpha + ptr2[j+2]*beta);
- dptr[j+3] = saturate_cast<T>((1 - (1-alpha)*(1-beta))*alpha_scale);
- }
- }
- }
-
-
-This approach, while being very simple, can boost the performance of a simple element-operation by 10-20 percents, especially if the image is rather small and the operation is quite simple.
-
-Another OpenCV idiom in this function, a call of
-:ocv:func:`Mat::create` for the destination array, that allocates the destination array unless it already has the proper size and type. And while the newly allocated arrays are always continuous, you still need to check the destination array because :ocv:func:`Mat::create` does not always allocate a new matrix.
-
-
-Mat::elemSize
--------------
-Returns the matrix element size in bytes.
-
-.. ocv:function:: size_t Mat::elemSize() const
-
-The method returns the matrix element size in bytes. For example, if the matrix type is ``CV_16SC3`` , the method returns ``3*sizeof(short)`` or 6.
-
-
-Mat::elemSize1
---------------
-Returns the size of each matrix element channel in bytes.
-
-.. ocv:function:: size_t Mat::elemSize1() const
-
-The method returns the matrix element channel size in bytes, that is, it ignores the number of channels. For example, if the matrix type is ``CV_16SC3`` , the method returns ``sizeof(short)`` or 2.
-
-
-Mat::type
----------
-Returns the type of a matrix element.
-
-.. ocv:function:: int Mat::type() const
-
-The method returns a matrix element type. This is an identifier compatible with the ``CvMat`` type system, like ``CV_16SC3`` or 16-bit signed 3-channel array, and so on.
-
-
-Mat::depth
-----------
-Returns the depth of a matrix element.
-
-.. ocv:function:: int Mat::depth() const
-
-The method returns the identifier of the matrix element depth (the type of each individual channel). For example, for a 16-bit signed element array, the method returns ``CV_16S`` . A complete list of matrix types contains the following values:
-
-* ``CV_8U`` - 8-bit unsigned integers ( ``0..255`` )
-
-* ``CV_8S`` - 8-bit signed integers ( ``-128..127`` )
-
-* ``CV_16U`` - 16-bit unsigned integers ( ``0..65535`` )
-
-* ``CV_16S`` - 16-bit signed integers ( ``-32768..32767`` )
-
-* ``CV_32S`` - 32-bit signed integers ( ``-2147483648..2147483647`` )
-
-* ``CV_32F`` - 32-bit floating-point numbers ( ``-FLT_MAX..FLT_MAX, INF, NAN`` )
-
-* ``CV_64F`` - 64-bit floating-point numbers ( ``-DBL_MAX..DBL_MAX, INF, NAN`` )
-
-
-Mat::channels
--------------
-Returns the number of matrix channels.
-
-.. ocv:function:: int Mat::channels() const
-
-The method returns the number of matrix channels.
-
-
-Mat::step1
-----------
-Returns a normalized step.
-
-.. ocv:function:: size_t Mat::step1( int i=0 ) const
-
-The method returns a matrix step divided by
-:ocv:func:`Mat::elemSize1()` . It can be useful to quickly access an arbitrary matrix element.
-
-
-Mat::size
----------
-Returns a matrix size.
-
-.. ocv:function:: Size Mat::size() const
-
-The method returns a matrix size: ``Size(cols, rows)`` . When the matrix is more than 2-dimensional, the returned size is (-1, -1).
-
-
-Mat::empty
-----------
-Returns ``true`` if the array has no elements.
-
-.. ocv:function:: bool Mat::empty() const
-
-The method returns ``true`` if ``Mat::total()`` is 0 or if ``Mat::data`` is NULL. Because of ``pop_back()`` and ``resize()`` methods ``M.total() == 0`` does not imply that ``M.data == NULL`` .
-
-
-Mat::ptr
---------
-Returns a pointer to the specified matrix row.
-
-.. ocv:function:: uchar* Mat::ptr(int i0=0)
-
-.. ocv:function:: const uchar* Mat::ptr(int i0=0) const
-
-.. ocv:function:: template<typename _Tp> _Tp* Mat::ptr(int i0=0)
-
-.. ocv:function:: template<typename _Tp> const _Tp* Mat::ptr(int i0=0) const
-
- :param i0: A 0-based row index.
-
-The methods return ``uchar*`` or typed pointer to the specified matrix row. See the sample in
-:ocv:func:`Mat::isContinuous` to know how to use these methods.
-
-
-Mat::at
--------
-Returns a reference to the specified array element.
-
-.. ocv:function:: template<typename T> T& Mat::at(int i) const
-
-.. ocv:function:: template<typename T> const T& Mat::at(int i) const
-
-.. ocv:function:: template<typename T> T& Mat::at(int i, int j)
-
-.. ocv:function:: template<typename T> const T& Mat::at(int i, int j) const
-
-.. ocv:function:: template<typename T> T& Mat::at(Point pt)
-
-.. ocv:function:: template<typename T> const T& Mat::at(Point pt) const
-
-.. ocv:function:: template<typename T> T& Mat::at(int i, int j, int k)
-
-.. ocv:function:: template<typename T> const T& Mat::at(int i, int j, int k) const
-
-.. ocv:function:: template<typename T> T& Mat::at(const int* idx)
-
-.. ocv:function:: template<typename T> const T& Mat::at(const int* idx) const
-
- :param i: Index along the dimension 0
- :param j: Index along the dimension 1
- :param k: Index along the dimension 2
-
- :param pt: Element position specified as ``Point(j,i)`` .
-
- :param idx: Array of ``Mat::dims`` indices.
-
-The template methods return a reference to the specified array element. For the sake of higher performance, the index range checks are only performed in the Debug configuration.
-
-Note that the variants with a single index (i) can be used to access elements of single-row or single-column 2-dimensional arrays. That is, if, for example, ``A`` is a ``1 x N`` floating-point matrix and ``B`` is an ``M x 1`` integer matrix, you can simply write ``A.at<float>(k+4)`` and ``B.at<int>(2*i+1)`` instead of ``A.at<float>(0,k+4)`` and ``B.at<int>(2*i+1,0)`` , respectively.
-
-The example below initializes a Hilbert matrix: ::
-
- Mat H(100, 100, CV_64F);
- for(int i = 0; i < H.rows; i++)
- for(int j = 0; j < H.cols; j++)
- H.at<double>(i,j)=1./(i+j+1);
-
-
-
-Mat::begin
---------------
-Returns the matrix iterator and sets it to the first matrix element.
-
-.. ocv:function:: template<typename _Tp> MatIterator_<_Tp> Mat::begin()
-
-.. ocv:function:: template<typename _Tp> MatConstIterator_<_Tp> Mat::begin() const
-
-The methods return the matrix read-only or read-write iterators. The use of matrix iterators is very similar to the use of bi-directional STL iterators. In the example below, the alpha blending function is rewritten using the matrix iterators: ::
-
- template<typename T>
- void alphaBlendRGBA(const Mat& src1, const Mat& src2, Mat& dst)
- {
- typedef Vec<T, 4> VT;
-
- const float alpha_scale = (float)std::numeric_limits<T>::max(),
- inv_scale = 1.f/alpha_scale;
-
- CV_Assert( src1.type() == src2.type() &&
- src1.type() == DataType<VT>::type &&
- src1.size() == src2.size());
- Size size = src1.size();
- dst.create(size, src1.type());
-
- MatConstIterator_<VT> it1 = src1.begin<VT>(), it1_end = src1.end<VT>();
- MatConstIterator_<VT> it2 = src2.begin<VT>();
- MatIterator_<VT> dst_it = dst.begin<VT>();
-
- for( ; it1 != it1_end; ++it1, ++it2, ++dst_it )
- {
- VT pix1 = *it1, pix2 = *it2;
- float alpha = pix1[3]*inv_scale, beta = pix2[3]*inv_scale;
- *dst_it = VT(saturate_cast<T>(pix1[0]*alpha + pix2[0]*beta),
- saturate_cast<T>(pix1[1]*alpha + pix2[1]*beta),
- saturate_cast<T>(pix1[2]*alpha + pix2[2]*beta),
- saturate_cast<T>((1 - (1-alpha)*(1-beta))*alpha_scale));
- }
- }
-
-
-
-Mat::end
-------------
-Returns the matrix iterator and sets it to the after-last matrix element.
-
-.. ocv:function:: template<typename _Tp> MatIterator_<_Tp> Mat::end()
-
-.. ocv:function:: template<typename _Tp> MatConstIterator_<_Tp> Mat::end() const
-
-The methods return the matrix read-only or read-write iterators, set to the point following the last matrix element.
-
-
-Mat::forEach
-------------
-Invoke with arguments functor, and runs the functor over all matrix element.
-
-.. ocv:function:: template<typename _Tp, typename Functor> void Mat::forEach(Functor operation)
-
-.. ocv:function:: template<typename _Tp, typename Functor> void Mat::forEach(Functor operation) const
-
-The methos runs operation in parallel. Operation is passed by arguments. Operation have to be a function pointer, a function object or a lambda(C++11).
-
-All of below operation is equal. Put 0xFF to first channel of all matrix elements. ::
-
- Mat image(1920, 1080, CV_8UC3);
- typedef cv::Point3_<uint8_t> Pixel;
-
- // first. raw pointer access.
- for (int r = 0; r < image.rows; ++r) {
- Pixel* ptr = image.ptr<Pixel>(0, r);
- const Pixel* ptr_end = ptr + image.cols;
- for (; ptr != ptr_end; ++ptr) {
- ptr->x = 255;
- }
- }
-
-
- // Using MatIterator. (Simple but there are a Iterator's overhead)
- for (Pixel &p : cv::Mat_<Pixel>(image)) {
- p.x = 255;
- }
-
-
- // Parallel execution with function object.
- struct Operator {
- void operator ()(Pixel &pixel, const int * position) {
- pixel.x = 255;
- }
- };
- image.forEach<Pixel>(Operator());
-
-
- // Parallel execution using C++11 lambda.
- image.forEach<Pixel>([](Pixel &p, const int * position) -> void {
- p.x = 255;
- });
-
-position parameter is index of current pixel. ::
-
- // Creating 3D matrix (255 x 255 x 255) typed uint8_t,
- // and initialize all elements by the value which equals elements position.
- // i.e. pixels (x,y,z) = (1,2,3) is (b,g,r) = (1,2,3).
-
- int sizes[] = { 255, 255, 255 };
- typedef cv::Point3_<uint8_t> Pixel;
-
- Mat_<Pixel> image = Mat::zeros(3, sizes, CV_8UC3);
-
- image.forEachWithPosition([&](Pixel& pixel, const int position[]) -> void{
- pixel.x = position[0];
- pixel.y = position[1];
- pixel.z = position[2];
- });
-
-Mat\_
------
-.. ocv:class:: Mat_
-
-Template matrix class derived from
-:ocv:class:`Mat` . ::
-
- template<typename _Tp> class Mat_ : public Mat
- {
- public:
- // ... some specific methods
- // and
- // no new extra fields
- };
-
-
-The class ``Mat_<_Tp>`` is a "thin" template wrapper on top of the ``Mat`` class. It does not have any extra data fields. Nor this class nor ``Mat`` has any virtual methods. Thus, references or pointers to these two classes can be freely but carefully converted one to another. For example: ::
-
- // create a 100x100 8-bit matrix
- Mat M(100,100,CV_8U);
- // this will be compiled fine. no any data conversion will be done.
- Mat_<float>& M1 = (Mat_<float>&)M;
- // the program is likely to crash at the statement below
- M1(99,99) = 1.f;
-
-
-While ``Mat`` is sufficient in most cases, ``Mat_`` can be more convenient if you use a lot of element access operations and if you know matrix type at the compilation time. Note that ``Mat::at<_Tp>(int y, int x)`` and ``Mat_<_Tp>::operator ()(int y, int x)`` do absolutely the same and run at the same speed, but the latter is certainly shorter: ::
-
- Mat_<double> M(20,20);
- for(int i = 0; i < M.rows; i++)
- for(int j = 0; j < M.cols; j++)
- M(i,j) = 1./(i+j+1);
- Mat E, V;
- eigen(M,E,V);
- cout << E.at<double>(0,0)/E.at<double>(M.rows-1,0);
-
-
-To use ``Mat_`` for multi-channel images/matrices, pass ``Vec`` as a ``Mat_`` parameter: ::
-
- // allocate a 320x240 color image and fill it with green (in RGB space)
- Mat_<Vec3b> img(240, 320, Vec3b(0,255,0));
- // now draw a diagonal white line
- for(int i = 0; i < 100; i++)
- img(i,i)=Vec3b(255,255,255);
- // and now scramble the 2nd (red) channel of each pixel
- for(int i = 0; i < img.rows; i++)
- for(int j = 0; j < img.cols; j++)
- img(i,j)[2] ^= (uchar)(i ^ j);
-
-
-InputArray
-----------
-.. ocv:class:: InputArray
-
-This is the proxy class for passing read-only input arrays into OpenCV functions. It is defined as ::
-
- typedef const _InputArray& InputArray;
-
-where ``_InputArray`` is a class that can be constructed from ``Mat``, ``Mat_<T>``, ``Matx<T, m, n>``, ``std::vector<T>``, ``std::vector<std::vector<T> >`` or ``std::vector<Mat>``. It can also be constructed from a matrix expression.
-
-Since this is mostly implementation-level class, and its interface may change in future versions, we do not describe it in details. There are a few key things, though, that should be kept in mind:
-
- * When you see in the reference manual or in OpenCV source code a function that takes ``InputArray``, it means that you can actually pass ``Mat``, ``Matx``, ``vector<T>`` etc. (see above the complete list).
-
- * Optional input arguments: If some of the input arrays may be empty, pass ``cv::noArray()`` (or simply ``cv::Mat()`` as you probably did before).
-
- * The class is designed solely for passing parameters. That is, normally you *should not* declare class members, local and global variables of this type.
-
- * If you want to design your own function or a class method that can operate of arrays of multiple types, you can use ``InputArray`` (or ``OutputArray``) for the respective parameters. Inside a function you should use ``_InputArray::getMat()`` method to construct a matrix header for the array (without copying data). ``_InputArray::kind()`` can be used to distinguish ``Mat`` from ``vector<>`` etc., but normally it is not needed.
-
-Here is how you can use a function that takes ``InputArray`` ::
-
- std::vector<Point2f> vec;
- // points or a circle
- for( int i = 0; i < 30; i++ )
- vec.push_back(Point2f((float)(100 + 30*cos(i*CV_PI*2/5)),
- (float)(100 - 30*sin(i*CV_PI*2/5))));
- cv::transform(vec, vec, cv::Matx23f(0.707, -0.707, 10, 0.707, 0.707, 20));
-
-That is, we form an STL vector containing points, and apply in-place affine transformation to the vector using the 2x3 matrix created inline as ``Matx<float, 2, 3>`` instance.
-
-Here is how such a function can be implemented (for simplicity, we implement a very specific case of it, according to the assertion statement inside) ::
-
- void myAffineTransform(InputArray _src, OutputArray _dst, InputArray _m)
- {
- // get Mat headers for input arrays. This is O(1) operation,
- // unless _src and/or _m are matrix expressions.
- Mat src = _src.getMat(), m = _m.getMat();
- CV_Assert( src.type() == CV_32FC2 && m.type() == CV_32F && m.size() == Size(3, 2) );
-
- // [re]create the output array so that it has the proper size and type.
- // In case of Mat it calls Mat::create, in case of STL vector it calls vector::resize.
- _dst.create(src.size(), src.type());
- Mat dst = _dst.getMat();
-
- for( int i = 0; i < src.rows; i++ )
- for( int j = 0; j < src.cols; j++ )
- {
- Point2f pt = src.at<Point2f>(i, j);
- dst.at<Point2f>(i, j) = Point2f(m.at<float>(0, 0)*pt.x +
- m.at<float>(0, 1)*pt.y +
- m.at<float>(0, 2),
- m.at<float>(1, 0)*pt.x +
- m.at<float>(1, 1)*pt.y +
- m.at<float>(1, 2));
- }
- }
-
-There is another related type, ``InputArrayOfArrays``, which is currently defined as a synonym for ``InputArray``: ::
-
- typedef InputArray InputArrayOfArrays;
-
-It denotes function arguments that are either vectors of vectors or vectors of matrices. A separate synonym is needed to generate Python/Java etc. wrappers properly. At the function implementation level their use is similar, but ``_InputArray::getMat(idx)`` should be used to get header for the idx-th component of the outer vector and ``_InputArray::size().area()`` should be used to find the number of components (vectors/matrices) of the outer vector.
-
-
-OutputArray
------------
-.. ocv:class:: OutputArray : public InputArray
-
-This type is very similar to ``InputArray`` except that it is used for input/output and output function parameters. Just like with ``InputArray``, OpenCV users should not care about ``OutputArray``, they just pass ``Mat``, ``vector<T>`` etc. to the functions. The same limitation as for ``InputArray``: **Do not explicitly create OutputArray instances** applies here too.
-
-If you want to make your function polymorphic (i.e. accept different arrays as output parameters), it is also not very difficult. Take the sample above as the reference. Note that ``_OutputArray::create()`` needs to be called before ``_OutputArray::getMat()``. This way you guarantee that the output array is properly allocated.
-
-Optional output parameters. If you do not need certain output array to be computed and returned to you, pass ``cv::noArray()``, just like you would in the case of optional input array. At the implementation level, use ``_OutputArray::needed()`` to check if certain output array needs to be computed or not.
-
-There are several synonyms for ``OutputArray`` that are used to assist automatic Python/Java/... wrapper generators: ::
-
- typedef OutputArray OutputArrayOfArrays;
- typedef OutputArray InputOutputArray;
- typedef OutputArray InputOutputArrayOfArrays;
-
-NAryMatIterator
----------------
-.. ocv:class:: NAryMatIterator
-
-n-ary multi-dimensional array iterator. ::
-
- class CV_EXPORTS NAryMatIterator
- {
- public:
- //! the default constructor
- NAryMatIterator();
- //! the full constructor taking arbitrary number of n-dim matrices
- NAryMatIterator(const Mat** arrays, Mat* planes, int narrays=-1);
- //! the separate iterator initialization method
- void init(const Mat** arrays, Mat* planes, int narrays=-1);
-
- //! proceeds to the next plane of every iterated matrix
- NAryMatIterator& operator ++();
- //! proceeds to the next plane of every iterated matrix (postfix increment operator)
- NAryMatIterator operator ++(int);
-
- ...
- int nplanes; // the total number of planes
- };
-
-
-Use the class to implement unary, binary, and, generally, n-ary element-wise operations on multi-dimensional arrays. Some of the arguments of an n-ary function may be continuous arrays, some may be not. It is possible to use conventional
-``MatIterator`` 's for each array but incrementing all of the iterators after each small operations may be a big overhead. In this case consider using ``NAryMatIterator`` to iterate through several matrices simultaneously as long as they have the same geometry (dimensionality and all the dimension sizes are the same). On each iteration ``it.planes[0]``, ``it.planes[1]`` , ... will be the slices of the corresponding matrices.
-
-The example below illustrates how you can compute a normalized and threshold 3D color histogram: ::
-
- void computeNormalizedColorHist(const Mat& image, Mat& hist, int N, double minProb)
- {
- const int histSize[] = {N, N, N};
-
- // make sure that the histogram has a proper size and type
- hist.create(3, histSize, CV_32F);
-
- // and clear it
- hist = Scalar(0);
-
- // the loop below assumes that the image
- // is a 8-bit 3-channel. check it.
- CV_Assert(image.type() == CV_8UC3);
- MatConstIterator_<Vec3b> it = image.begin<Vec3b>(),
- it_end = image.end<Vec3b>();
- for( ; it != it_end; ++it )
- {
- const Vec3b& pix = *it;
- hist.at<float>(pix[0]*N/256, pix[1]*N/256, pix[2]*N/256) += 1.f;
- }
-
- minProb *= image.rows*image.cols;
- Mat plane;
- NAryMatIterator it(&hist, &plane, 1);
- double s = 0;
- // iterate through the matrix. on each iteration
- // it.planes[*] (of type Mat) will be set to the current plane.
- for(int p = 0; p < it.nplanes; p++, ++it)
- {
- threshold(it.planes[0], it.planes[0], minProb, 0, THRESH_TOZERO);
- s += sum(it.planes[0])[0];
- }
-
- s = 1./s;
- it = NAryMatIterator(&hist, &plane, 1);
- for(int p = 0; p < it.nplanes; p++, ++it)
- it.planes[0] *= s;
- }
-
-
-SparseMat
----------
-.. ocv:class:: SparseMat
-
-The class ``SparseMat`` represents multi-dimensional sparse numerical arrays. Such a sparse array can store elements of any type that
-:ocv:class:`Mat` can store. *Sparse* means that only non-zero elements are stored (though, as a result of operations on a sparse matrix, some of its stored elements can actually become 0. It is up to you to detect such elements and delete them using ``SparseMat::erase`` ). The non-zero elements are stored in a hash table that grows when it is filled so that the search time is O(1) in average (regardless of whether element is there or not). Elements can be accessed using the following methods:
-
-*
- Query operations (``SparseMat::ptr`` and the higher-level ``SparseMat::ref``, ``SparseMat::value`` and ``SparseMat::find``), for example:
-
- ::
-
- const int dims = 5;
- int size[] = {10, 10, 10, 10, 10};
- SparseMat sparse_mat(dims, size, CV_32F);
- for(int i = 0; i < 1000; i++)
- {
- int idx[dims];
- for(int k = 0; k < dims; k++)
- idx[k] = rand()
- sparse_mat.ref<float>(idx) += 1.f;
- }
-
- ..
-
-*
- Sparse matrix iterators. They are similar to ``MatIterator`` but different from :ocv:class:`NAryMatIterator`. That is, the iteration loop is familiar to STL users:
-
- ::
-
- // prints elements of a sparse floating-point matrix
- // and the sum of elements.
- SparseMatConstIterator_<float>
- it = sparse_mat.begin<float>(),
- it_end = sparse_mat.end<float>();
- double s = 0;
- int dims = sparse_mat.dims();
- for(; it != it_end; ++it)
- {
- // print element indices and the element value
- const SparseMat::Node* n = it.node();
- printf("(");
- for(int i = 0; i < dims; i++)
- printf("%d%s", n->idx[i], i < dims-1 ? ", " : ")");
- printf(": %g\n", it.value<float>());
- s += *it;
- }
- printf("Element sum is %g\n", s);
-
- ..
-
- If you run this loop, you will notice that elements are not enumerated in a logical order (lexicographical, and so on). They come in the same order as they are stored in the hash table (semi-randomly). You may collect pointers to the nodes and sort them to get the proper ordering. Note, however, that pointers to the nodes may become invalid when you add more elements to the matrix. This may happen due to possible buffer reallocation.
-
-*
- Combination of the above 2 methods when you need to process 2 or more sparse matrices simultaneously. For example, this is how you can compute unnormalized cross-correlation of the 2 floating-point sparse matrices:
-
- ::
-
- double cross_corr(const SparseMat& a, const SparseMat& b)
- {
- const SparseMat *_a = &a, *_b = &b;
- // if b contains less elements than a,
- // it is faster to iterate through b
- if(_a->nzcount() > _b->nzcount())
- std::swap(_a, _b);
- SparseMatConstIterator_<float> it = _a->begin<float>(),
- it_end = _a->end<float>();
- double ccorr = 0;
- for(; it != it_end; ++it)
- {
- // take the next element from the first matrix
- float avalue = *it;
- const Node* anode = it.node();
- // and try to find an element with the same index in the second matrix.
- // since the hash value depends only on the element index,
- // reuse the hash value stored in the node
- float bvalue = _b->value<float>(anode->idx,&anode->hashval);
- ccorr += avalue*bvalue;
- }
- return ccorr;
- }
-
- ..
-
-SparseMat::SparseMat
---------------------
-Various SparseMat constructors.
-
-.. ocv:function:: SparseMat::SparseMat()
-.. ocv:function:: SparseMat::SparseMat( int dims, const int* _sizes, int _type )
-.. ocv:function:: SparseMat::SparseMat( const SparseMat& m )
-.. ocv:function:: SparseMat::SparseMat( const Mat& m )
-
-
- :param m: Source matrix for copy constructor. If m is dense matrix (ocv:class:`Mat`) then it will be converted to sparse representation.
- :param dims: Array dimensionality.
- :param _sizes: Sparce matrix size on all dementions.
- :param _type: Sparse matrix data type.
-
-SparseMat::~SparseMat
----------------------
-SparseMat object destructor.
-
-.. ocv:function:: SparseMat::~SparseMat()
-
-SparseMat::operator=
---------------------
-Provides sparse matrix assignment operators.
-
-.. ocv:function:: SparseMat& SparseMat::operator = (const SparseMat& m)
-.. ocv:function:: SparseMat& SparseMat::operator = (const Mat& m)
-
- :param m: Matrix for assignment.
-
-The last variant is equivalent to the corresponding constructor with try1d=false.
-
-
-SparseMat::clone
-----------------
-Creates a full copy of the matrix.
-
-.. ocv:function:: SparseMat SparseMat::clone() const
-
-SparseMat::copyTo
------------------
-Copy all the data to the destination matrix.The destination will be reallocated if needed.
-
-.. ocv:function:: void SparseMat::copyTo( SparseMat& m ) const
-.. ocv:function:: void SparseMat::copyTo( Mat& m ) const
-
- :param m: Target for copiing.
-
-The last variant converts 1D or 2D sparse matrix to dense 2D matrix. If the sparse matrix is 1D, the result will be a single-column matrix.
-
-SparceMat::convertTo
---------------------
-Convert sparse matrix with possible type change and scaling.
-
-.. ocv:function:: void SparseMat::convertTo( SparseMat& m, int rtype, double alpha=1 ) const
-.. ocv:function:: void SparseMat::convertTo( Mat& m, int rtype, double alpha=1, double beta=0 ) const
-
- :param m: Destination matrix.
- :param rtype: Destination matrix type.
- :param alpha: Conversion multiplier.
-
-The first version converts arbitrary sparse matrix to dense matrix and multiplies all the matrix elements by the specified scalar.
-The second versiob converts sparse matrix to dense matrix with optional type conversion and scaling.
-When rtype=-1, the destination element type will be the same as the sparse matrix element type.
-Otherwise, rtype will specify the depth and the number of channels will remain the same as in the sparse matrix.
-
-SparseMat:create
-----------------
-Reallocates sparse matrix. If it was already of the proper size and type, it is simply cleared with clear(), otherwise,
-the old matrix is released (using release()) and the new one is allocated.
-
-.. ocv:function:: void SparseMat::create(int dims, const int* _sizes, int _type)
-
- :param dims: Array dimensionality.
- :param _sizes: Sparce matrix size on all dementions.
- :param _type: Sparse matrix data type.
-
-SparseMat::clear
-----------------
-Sets all the matrix elements to 0, which means clearing the hash table.
-
-.. ocv:function:: void SparseMat::clear()
-
-SparseMat::addref
------------------
-Manually increases reference counter to the header.
-
-.. ocv:function:: void SparseMat::addref()
-
-SparseMat::release
-------------------
-Decreses the header reference counter when it reaches 0. The header and all the underlying data are deallocated.
-
-.. ocv:function:: void SparseMat::release()
-
-SparseMat::CvSparseMat *
-------------------------
-Converts sparse matrix to the old-style representation. All the elements are copied.
-
-.. ocv:function:: SparseMat::operator CvSparseMat*() const
-
-SparseMat::elemSize
--------------------
-Size of each element in bytes (the matrix nodes will be bigger because of element indices and other SparseMat::Node elements).
-
-.. ocv:function:: size_t SparseMat::elemSize() const
-
-SparseMat::elemSize1
---------------------
-elemSize()/channels().
-
-.. ocv:function:: size_t SparseMat::elemSize() const
-
-SparseMat::type
----------------
-Returns the type of a matrix element.
-
-.. ocv:function:: int SparseMat::type() const
-
-The method returns a sparse matrix element type. This is an identifier compatible with the ``CvMat`` type system, like ``CV_16SC3`` or 16-bit signed 3-channel array, and so on.
-
-SparseMat::depth
-----------------
-Returns the depth of a sparse matrix element.
-
-.. ocv:function:: int SparseMat::depth() const
-
-The method returns the identifier of the matrix element depth (the type of each individual channel). For example, for a 16-bit signed 3-channel array, the method returns ``CV_16S``
-
-* ``CV_8U`` - 8-bit unsigned integers ( ``0..255`` )
-
-* ``CV_8S`` - 8-bit signed integers ( ``-128..127`` )
-
-* ``CV_16U`` - 16-bit unsigned integers ( ``0..65535`` )
-
-* ``CV_16S`` - 16-bit signed integers ( ``-32768..32767`` )
-
-* ``CV_32S`` - 32-bit signed integers ( ``-2147483648..2147483647`` )
-
-* ``CV_32F`` - 32-bit floating-point numbers ( ``-FLT_MAX..FLT_MAX, INF, NAN`` )
-
-* ``CV_64F`` - 64-bit floating-point numbers ( ``-DBL_MAX..DBL_MAX, INF, NAN`` )
-
-SparseMat::channels
--------------------
-Returns the number of matrix channels.
-
-.. ocv:function:: int SparseMat::channels() const
-
-The method returns the number of matrix channels.
-
-SparseMat::size
----------------
-Returns the array of sizes or matrix size by i dimension and 0 if the matrix is not allocated.
-
-.. ocv:function:: const int* SparseMat::size() const
-.. ocv:function:: int SparseMat::size(int i) const
-
- :param i: Dimention index.
-
-SparseMat::dims
----------------
-Returns the matrix dimensionality.
-
-.. ocv:function:: int SparseMat::dims() const
-
-SparseMat::nzcount
-------------------
-Returns the number of non-zero elements.
-
-.. ocv:function:: size_t SparseMat::nzcount() const
-
-SparseMat::hash
----------------
-Compute element hash value from the element indices.
-
-.. ocv:function:: size_t SparseMat::hash(int i0) const
-.. ocv:function:: size_t SparseMat::hash(int i0, int i1) const
-.. ocv:function:: size_t SparseMat::hash(int i0, int i1, int i2) const
-.. ocv:function:: size_t SparseMat::hash(const int* idx) const
-
- :param i0: The first dimension index.
- :param i1: The second dimension index.
- :param i2: The third dimension index.
- :param idx: Array of element indices for multidimensional matices.
-
-SparseMat::ptr
---------------
-Low-level element-access functions, special variants for 1D, 2D, 3D cases, and the generic one for n-D case.
-
-.. ocv:function:: uchar* SparseMat::ptr(int i0, bool createMissing, size_t* hashval=0)
-.. ocv:function:: uchar* SparseMat::ptr(int i0, int i1, bool createMissing, size_t* hashval=0)
-.. ocv:function:: uchar* SparseMat::ptr(int i0, int i1, int i2, bool createMissing, size_t* hashval=0)
-.. ocv:function:: uchar* SparseMat::ptr(const int* idx, bool createMissing, size_t* hashval=0)
-
- :param i0: The first dimension index.
- :param i1: The second dimension index.
- :param i2: The third dimension index.
- :param idx: Array of element indices for multidimensional matices.
- :param createMissing: Create new element with 0 value if it does not exist in SparseMat.
-
-Return pointer to the matrix element. If the element is there (it is non-zero), the pointer to it is returned.
-If it is not there and ``createMissing=false``, NULL pointer is returned. If it is not there and ``createMissing=true``,
-the new elementis created and initialized with 0. Pointer to it is returned. If the optional hashval pointer is not ``NULL``,
-the element hash value is not computed but ``hashval`` is taken instead.
-
-SparseMat::erase
-----------------
-Erase the specified matrix element. When there is no such an element, the methods do nothing.
-
-.. ocv:function:: void SparseMat::erase(int i0, int i1, size_t* hashval=0)
-.. ocv:function:: void SparseMat::erase(int i0, int i1, int i2, size_t* hashval=0)
-.. ocv:function:: void SparseMat::erase(const int* idx, size_t* hashval=0)
-
- :param i0: The first dimension index.
- :param i1: The second dimension index.
- :param i2: The third dimension index.
- :param idx: Array of element indices for multidimensional matices.
-
-SparseMat\_
------------
-.. ocv:class:: SparseMat_
-
-Template sparse n-dimensional array class derived from
-:ocv:class:`SparseMat` ::
-
- template<typename _Tp> class SparseMat_ : public SparseMat
- {
- public:
- typedef SparseMatIterator_<_Tp> iterator;
- typedef SparseMatConstIterator_<_Tp> const_iterator;
-
- // constructors;
- // the created matrix will have data type = DataType<_Tp>::type
- SparseMat_();
- SparseMat_(int dims, const int* _sizes);
- SparseMat_(const SparseMat& m);
- SparseMat_(const SparseMat_& m);
- SparseMat_(const Mat& m);
- SparseMat_(const CvSparseMat* m);
- // assignment operators; data type conversion is done when necessary
- SparseMat_& operator = (const SparseMat& m);
- SparseMat_& operator = (const SparseMat_& m);
- SparseMat_& operator = (const Mat& m);
-
- // equivalent to the correspoding parent class methods
- SparseMat_ clone() const;
- void create(int dims, const int* _sizes);
- operator CvSparseMat*() const;
-
- // overriden methods that do extra checks for the data type
- int type() const;
- int depth() const;
- int channels() const;
-
- // more convenient element access operations.
- // ref() is retained (but <_Tp> specification is not needed anymore);
- // operator () is equivalent to SparseMat::value<_Tp>
- _Tp& ref(int i0, size_t* hashval=0);
- _Tp operator()(int i0, size_t* hashval=0) const;
- _Tp& ref(int i0, int i1, size_t* hashval=0);
- _Tp operator()(int i0, int i1, size_t* hashval=0) const;
- _Tp& ref(int i0, int i1, int i2, size_t* hashval=0);
- _Tp operator()(int i0, int i1, int i2, size_t* hashval=0) const;
- _Tp& ref(const int* idx, size_t* hashval=0);
- _Tp operator()(const int* idx, size_t* hashval=0) const;
-
- // iterators
- SparseMatIterator_<_Tp> begin();
- SparseMatConstIterator_<_Tp> begin() const;
- SparseMatIterator_<_Tp> end();
- SparseMatConstIterator_<_Tp> end() const;
- };
-
-``SparseMat_`` is a thin wrapper on top of :ocv:class:`SparseMat` created in the same way as ``Mat_`` .
-It simplifies notation of some operations. ::
-
- int sz[] = {10, 20, 30};
- SparseMat_<double> M(3, sz);
- ...
- M.ref(1, 2, 3) = M(4, 5, 6) + M(7, 8, 9);
-
-
-Algorithm
----------
-.. ocv:class:: Algorithm
-
-::
-
- class CV_EXPORTS_W Algorithm
- {
- public:
- Algorithm();
- virtual ~Algorithm();
- string name() const;
-
- template<typename _Tp> typename ParamType<_Tp>::member_type get(const string& name) const;
- template<typename _Tp> typename ParamType<_Tp>::member_type get(const char* name) const;
-
- CV_WRAP int getInt(const string& name) const;
- CV_WRAP double getDouble(const string& name) const;
- CV_WRAP bool getBool(const string& name) const;
- CV_WRAP string getString(const string& name) const;
- CV_WRAP Mat getMat(const string& name) const;
- CV_WRAP vector<Mat> getMatVector(const string& name) const;
- CV_WRAP Ptr<Algorithm> getAlgorithm(const string& name) const;
-
- void set(const string& name, int value);
- void set(const string& name, double value);
- void set(const string& name, bool value);
- void set(const string& name, const string& value);
- void set(const string& name, const Mat& value);
- void set(const string& name, const vector<Mat>& value);
- void set(const string& name, const Ptr<Algorithm>& value);
- template<typename _Tp> void set(const string& name, const Ptr<_Tp>& value);
-
- CV_WRAP void setInt(const string& name, int value);
- CV_WRAP void setDouble(const string& name, double value);
- CV_WRAP void setBool(const string& name, bool value);
- CV_WRAP void setString(const string& name, const string& value);
- CV_WRAP void setMat(const string& name, const Mat& value);
- CV_WRAP void setMatVector(const string& name, const vector<Mat>& value);
- CV_WRAP void setAlgorithm(const string& name, const Ptr<Algorithm>& value);
- template<typename _Tp> void setAlgorithm(const string& name, const Ptr<_Tp>& value);
-
- void set(const char* name, int value);
- void set(const char* name, double value);
- void set(const char* name, bool value);
- void set(const char* name, const string& value);
- void set(const char* name, const Mat& value);
- void set(const char* name, const vector<Mat>& value);
- void set(const char* name, const Ptr<Algorithm>& value);
- template<typename _Tp> void set(const char* name, const Ptr<_Tp>& value);
-
- void setInt(const char* name, int value);
- void setDouble(const char* name, double value);
- void setBool(const char* name, bool value);
- void setString(const char* name, const string& value);
- void setMat(const char* name, const Mat& value);
- void setMatVector(const char* name, const vector<Mat>& value);
- void setAlgorithm(const char* name, const Ptr<Algorithm>& value);
- template<typename _Tp> void setAlgorithm(const char* name, const Ptr<_Tp>& value);
-
- CV_WRAP string paramHelp(const string& name) const;
- int paramType(const char* name) const;
- CV_WRAP int paramType(const string& name) const;
- CV_WRAP void getParams(CV_OUT vector<string>& names) const;
-
-
- virtual void write(FileStorage& fs) const;
- virtual void read(const FileNode& fn);
-
- typedef Algorithm* (*Constructor)(void);
- typedef int (Algorithm::*Getter)() const;
- typedef void (Algorithm::*Setter)(int);
-
- CV_WRAP static void getList(CV_OUT vector<string>& algorithms);
- CV_WRAP static Ptr<Algorithm> _create(const string& name);
- template<typename _Tp> static Ptr<_Tp> create(const string& name);
-
- virtual AlgorithmInfo* info() const /* TODO: make it = 0;*/ { return 0; }
- };
-
-This is a base class for all more or less complex algorithms in OpenCV, especially for classes of algorithms, for which there can be multiple implementations. The examples are stereo correspondence (for which there are algorithms like block matching, semi-global block matching, graph-cut etc.), background subtraction (which can be done using mixture-of-gaussians models, codebook-based algorithm etc.), optical flow (block matching, Lucas-Kanade, Horn-Schunck etc.).
-
-The class provides the following features for all derived classes:
-
- * so called "virtual constructor". That is, each Algorithm derivative is registered at program start and you can get the list of registered algorithms and create instance of a particular algorithm by its name (see ``Algorithm::create``). If you plan to add your own algorithms, it is good practice to add a unique prefix to your algorithms to distinguish them from other algorithms.
-
- * setting/retrieving algorithm parameters by name. If you used video capturing functionality from OpenCV videoio module, you are probably familar with ``cvSetCaptureProperty()``, ``cvGetCaptureProperty()``, ``VideoCapture::set()`` and ``VideoCapture::get()``. ``Algorithm`` provides similar method where instead of integer id's you specify the parameter names as text strings. See ``Algorithm::set`` and ``Algorithm::get`` for details.
-
- * reading and writing parameters from/to XML or YAML files. Every Algorithm derivative can store all its parameters and then read them back. There is no need to re-implement it each time.
-
-Here is example of SIFT use in your application via Algorithm interface: ::
-
- #include "opencv2/opencv.hpp"
- #include "opencv2/xfeatures2d.hpp"
-
- using namespace cv::xfeatures2d;
-
- ...
-
- Ptr<Feature2D> sift = SIFT::create();
-
- FileStorage fs("sift_params.xml", FileStorage::READ);
- if( fs.isOpened() ) // if we have file with parameters, read them
- {
- sift->read(fs["sift_params"]);
- fs.release();
- }
- else // else modify the parameters and store them; user can later edit the file to use different parameters
- {
- sift->setContrastThreshold(0.01f); // lower the contrast threshold, compared to the default value
-
- {
- WriteStructContext ws(fs, "sift_params", CV_NODE_MAP);
- sift->write(fs);
- }
- }
-
- Mat image = imread("myimage.png", 0), descriptors;
- vector<KeyPoint> keypoints;
- sift->detectAndCompute(image, noArray(), keypoints, descriptors);
-
-Algorithm::name
----------------
-Returns the algorithm name
-
-.. ocv:function:: String Algorithm::name() const
-
-Algorithm::get
---------------
-Returns the algorithm parameter
-
-.. ocv:function:: template<typename _Tp> typename ParamType<_Tp>::member_type Algorithm::get(const String& name) const
-
- :param name: The parameter name.
-
-The method returns value of the particular parameter. Since the compiler can not deduce the type of the returned parameter, you should specify it explicitly in angle brackets. Here are the allowed forms of get:
-
- * myalgo.get<int>("param_name")
- * myalgo.get<double>("param_name")
- * myalgo.get<bool>("param_name")
- * myalgo.get<String>("param_name")
- * myalgo.get<Mat>("param_name")
- * myalgo.get<vector<Mat> >("param_name")
- * myalgo.get<Algorithm>("param_name") (it returns Ptr<Algorithm>).
-
-In some cases the actual type of the parameter can be cast to the specified type, e.g. integer parameter can be cast to double, ``bool`` can be cast to ``int``. But "dangerous" transformations (string<->number, double->int, 1x1 Mat<->number, ...) are not performed and the method will throw an exception. In the case of ``Mat`` or ``vector<Mat>`` parameters the method does not clone the matrix data, so do not modify the matrices. Use ``Algorithm::set`` instead - slower, but more safe.
-
-
-Algorithm::set
---------------
-Sets the algorithm parameter
-
-.. ocv:function:: void Algorithm::set(const String& name, int value)
-.. ocv:function:: void Algorithm::set(const String& name, double value)
-.. ocv:function:: void Algorithm::set(const String& name, bool value)
-.. ocv:function:: void Algorithm::set(const String& name, const String& value)
-.. ocv:function:: void Algorithm::set(const String& name, const Mat& value)
-.. ocv:function:: void Algorithm::set(const String& name, const vector<Mat>& value)
-.. ocv:function:: void Algorithm::set(const String& name, const Ptr<Algorithm>& value)
-
- :param name: The parameter name.
- :param value: The parameter value.
-
-The method sets value of the particular parameter. Some of the algorithm parameters may be declared as read-only. If you try to set such a parameter, you will get exception with the corresponding error message.
-
-
-Algorithm::write
-----------------
-Stores algorithm parameters in a file storage
-
-.. ocv:function:: void Algorithm::write(FileStorage& fs) const
-
- :param fs: File storage.
-
-The method stores all the algorithm parameters (in alphabetic order) to the file storage. The method is virtual. If you define your own Algorithm derivative, your can override the method and store some extra information. However, it's rarely needed. Here are some examples:
-
- * SIFT feature detector (from xfeatures2d module). The class only stores algorithm parameters and no keypoints or their descriptors. Therefore, it's enough to store the algorithm parameters, which is what ``Algorithm::write()`` does. Therefore, there is no dedicated ``SIFT::write()``.
-
- * Background subtractor (from video module). It has the algorithm parameters and also it has the current background model. However, the background model is not stored. First, it's rather big. Then, if you have stored the background model, it would likely become irrelevant on the next run (because of shifted camera, changed background, different lighting etc.). Therefore, ``BackgroundSubtractorMOG`` and ``BackgroundSubtractorMOG2`` also rely on the standard ``Algorithm::write()`` to store just the algorithm parameters.
-
- * Expectation Maximization (from ml module). The algorithm finds mixture of gaussians that approximates user data best of all. In this case the model may be re-used on the next run to test new data against the trained statistical model. So EM needs to store the model. However, since the model is described by a few parameters that are available as read-only algorithm parameters (i.e. they are available via ``EM::get()``), EM also relies on ``Algorithm::write()`` to store both EM parameters and the model (represented by read-only algorithm parameters).
-
-
-Algorithm::read
----------------
-Reads algorithm parameters from a file storage
-
-.. ocv:function:: void Algorithm::read(const FileNode& fn)
-
- :param fn: File node of the file storage.
-
-The method reads all the algorithm parameters from the specified node of a file storage. Similarly to ``Algorithm::write()``, if you implement an algorithm that needs to read some extra data and/or re-compute some internal data, you may override the method.
-
-Algorithm::getList
-------------------
-Returns the list of registered algorithms
-
-.. ocv:function:: void Algorithm::getList(vector<String>& algorithms)
-
- :param algorithms: The output vector of algorithm names.
-
-This static method returns the list of registered algorithms in alphabetical order. Here is how to use it ::
-
- vector<String> algorithms;
- Algorithm::getList(algorithms);
- cout << "Algorithms: " << algorithms.size() << endl;
- for (size_t i=0; i < algorithms.size(); i++)
- cout << algorithms[i] << endl;
-
-
-Algorithm::create
------------------
-Creates algorithm instance by name
-
-.. ocv:function:: template<typename _Tp> Ptr<_Tp> Algorithm::create(const String& name)
-
- :param name: The algorithm name, one of the names returned by ``Algorithm::getList()``.
-
-This static method creates a new instance of the specified algorithm. If there is no such algorithm, the method will silently return a null pointer. Also, you should specify the particular ``Algorithm`` subclass as ``_Tp`` (or simply ``Algorithm`` if you do not know it at that point). ::
-
- Ptr<BackgroundSubtractor> bgfg = Algorithm::create<BackgroundSubtractor>("BackgroundSubtractor.MOG2");
-
-.. note:: This is important note about seemingly mysterious behavior of ``Algorithm::create()`` when it returns NULL while it should not. The reason is simple - ``Algorithm::create()`` resides in OpenCV`s core module and the algorithms are implemented in other modules. If you create algorithms dynamically, C++ linker may decide to throw away the modules where the actual algorithms are implemented, since you do not call any functions from the modules. To avoid this problem, you need to call ``initModule_<modulename>();`` somewhere in the beginning of the program before ``Algorithm::create()``. For example, call ``initModule_xfeatures2d()`` in order to use SURF/SIFT, call ``initModule_ml()`` to use expectation maximization etc.
-
-Creating Own Algorithms
------------------------
-
-The above methods are usually enough for users. If you want to make your own algorithm, derived from ``Algorithm``, you should basically follow a few conventions and add a little semi-standard piece of code to your class:
-
- * Make a class and specify ``Algorithm`` as its base class.
- * The algorithm parameters should be the class members. See ``Algorithm::get()`` for the list of possible types of the parameters.
- * Add public virtual method ``AlgorithmInfo* info() const;`` to your class.
- * Add constructor function, ``AlgorithmInfo`` instance and implement the ``info()`` method. The simplest way is to take https://github.com/Itseez/opencv/tree/master/modules/ml/src/ml_init.cpp as the reference and modify it according to the list of your parameters.
- * Add some public function (e.g. ``initModule_<mymodule>()``) that calls info() of your algorithm and put it into the same source file as ``info()`` implementation. This is to force C++ linker to include this object file into the target application. See ``Algorithm::create()`` for details.
+++ /dev/null
-Clustering
-==========
-
-.. highlight:: cpp
-
-kmeans
-------
-Finds centers of clusters and groups input samples around the clusters.
-
-.. ocv:function:: double kmeans( InputArray data, int K, InputOutputArray bestLabels, TermCriteria criteria, int attempts, int flags, OutputArray centers=noArray() )
-
-.. ocv:pyfunction:: cv2.kmeans(data, K, bestLabels, criteria, attempts, flags[, centers]) -> retval, bestLabels, centers
-
-.. ocv:cfunction:: int cvKMeans2( const CvArr* samples, int cluster_count, CvArr* labels, CvTermCriteria termcrit, int attempts=1, CvRNG* rng=0, int flags=0, CvArr* _centers=0, double* compactness=0 )
-
- :param samples: Floating-point matrix of input samples, one row per sample.
-
- :param data: Data for clustering. An array of N-Dimensional points with float coordinates is needed. Examples of this array can be:
-
- * ``Mat points(count, 2, CV_32F);``
-
- * ``Mat points(count, 1, CV_32FC2);``
-
- * ``Mat points(1, count, CV_32FC2);``
-
- * ``std::vector<cv::Point2f> points(sampleCount);``
-
- :param cluster_count: Number of clusters to split the set by.
-
- :param K: Number of clusters to split the set by.
-
- :param labels: Input/output integer array that stores the cluster indices for every sample.
-
- :param criteria: The algorithm termination criteria, that is, the maximum number of iterations and/or the desired accuracy. The accuracy is specified as ``criteria.epsilon``. As soon as each of the cluster centers moves by less than ``criteria.epsilon`` on some iteration, the algorithm stops.
-
- :param termcrit: The algorithm termination criteria, that is, the maximum number of iterations and/or the desired accuracy.
-
- :param attempts: Flag to specify the number of times the algorithm is executed using different initial labellings. The algorithm returns the labels that yield the best compactness (see the last function parameter).
-
- :param rng: CvRNG state initialized by RNG().
-
- :param flags: Flag that can take the following values:
-
- * **KMEANS_RANDOM_CENTERS** Select random initial centers in each attempt.
-
- * **KMEANS_PP_CENTERS** Use ``kmeans++`` center initialization by Arthur and Vassilvitskii [Arthur2007].
-
- * **KMEANS_USE_INITIAL_LABELS** During the first (and possibly the only) attempt, use the user-supplied labels instead of computing them from the initial centers. For the second and further attempts, use the random or semi-random centers. Use one of ``KMEANS_*_CENTERS`` flag to specify the exact method.
-
- :param centers: Output matrix of the cluster centers, one row per each cluster center.
-
- :param _centers: Output matrix of the cluster centers, one row per each cluster center.
-
- :param compactness: The returned value that is described below.
-
-The function ``kmeans`` implements a k-means algorithm that finds the
-centers of ``cluster_count`` clusters and groups the input samples
-around the clusters. As an output,
-:math:`\texttt{labels}_i` contains a 0-based cluster index for
-the sample stored in the
-:math:`i^{th}` row of the ``samples`` matrix.
-
-The function returns the compactness measure that is computed as
-
-.. math::
-
- \sum _i \| \texttt{samples} _i - \texttt{centers} _{ \texttt{labels} _i} \| ^2
-
-after every attempt. The best (minimum) value is chosen and the
-corresponding labels and the compactness value are returned by the function.
-Basically, you can use only the core of the function, set the number of
-attempts to 1, initialize labels each time using a custom algorithm, pass them with the
-( ``flags`` = ``KMEANS_USE_INITIAL_LABELS`` ) flag, and then choose the best (most-compact) clustering.
-
-.. note::
-
- * An example on K-means clustering can be found at opencv_source_code/samples/cpp/kmeans.cpp
-
- * (Python) An example on K-means clustering can be found at opencv_source_code/samples/python2/kmeans.py
-
-partition
--------------
-Splits an element set into equivalency classes.
-
-.. ocv:function:: template<typename _Tp, class _EqPredicate> int partition( const vector<_Tp>& vec, vector<int>& labels, _EqPredicate predicate=_EqPredicate())
-
- :param vec: Set of elements stored as a vector.
-
- :param labels: Output vector of labels. It contains as many elements as ``vec``. Each label ``labels[i]`` is a 0-based cluster index of ``vec[i]`` .
-
- :param predicate: Equivalence predicate (pointer to a boolean function of two arguments or an instance of the class that has the method ``bool operator()(const _Tp& a, const _Tp& b)`` ). The predicate returns ``true`` when the elements are certainly in the same class, and returns ``false`` if they may or may not be in the same class.
-
-The generic function ``partition`` implements an
-:math:`O(N^2)` algorithm for
-splitting a set of
-:math:`N` elements into one or more equivalency classes, as described in
-http://en.wikipedia.org/wiki/Disjoint-set_data_structure
-. The function
-returns the number of equivalency classes.
-
-.. [Arthur2007] Arthur and S. Vassilvitskii. k-means++: the advantages of careful seeding, Proceedings of the eighteenth annual ACM-SIAM symposium on Discrete algorithms, 2007
+++ /dev/null
-Command Line Parser
-===================
-
-.. highlight:: cpp
-
-CommandLineParser
------------------
-.. ocv:class:: CommandLineParser
-
-The CommandLineParser class is designed for command line arguments parsing
-
-
- .. ocv:function:: CommandLineParser::CommandLineParser( int argc, const char* const argv[], const String& keys )
-
- :param argc:
- :param argv:
- :param keys:
-
- .. ocv:function:: template<typename T> T CommandLineParser::get<T>(const String& name, bool space_delete = true)
-
- :param name:
- :param space_delete:
-
- .. ocv:function:: template<typename T> T CommandLineParser::get<T>(int index, bool space_delete = true)
-
- :param index:
- :param space_delete:
-
- .. ocv:function:: bool CommandLineParser::has(const String& name)
-
- :param name:
-
- .. ocv:function:: bool CommandLineParser::check()
-
-
- .. ocv:function:: void CommandLineParser::about( const String& message )
-
- :param message:
-
- .. ocv:function:: void CommandLineParser::printMessage()
-
- .. ocv:function:: void CommandLineParser::printErrors()
-
- .. ocv:function:: String CommandLineParser::getPathToApplication()
-
-
-The sample below demonstrates how to use CommandLineParser:
-
-::
-
- CommandLineParser parser(argc, argv, keys);
- parser.about("Application name v1.0.0");
-
- if (parser.has("help"))
- {
- parser.printMessage();
- return 0;
- }
-
- int N = parser.get<int>("N");
- double fps = parser.get<double>("fps");
- String path = parser.get<String>("path");
-
- use_time_stamp = parser.has("timestamp");
-
- String img1 = parser.get<String>(0);
- String img2 = parser.get<String>(1);
-
- int repeat = parser.get<int>(2);
-
- if (!parser.check())
- {
- parser.printErrors();
- return 0;
- }
-
-Syntax:
-
-::
-
- const String keys =
- "{help h usage ? | | print this message }"
- "{@image1 | | image1 for compare }"
- "{@image2 | | image2 for compare }"
- "{@repeat |1 | number }"
- "{path |. | path to file }"
- "{fps | -1.0 | fps for output video }"
- "{N count |100 | count of objects }"
- "{ts timestamp | | use time stamp }"
- ;
-
-Use:
-
-::
-
- # ./app -N=200 1.png 2.jpg 19 -ts
-
- # ./app -fps=aaa
- ERRORS:
- Exception: can not convert: [aaa] to [double]
+++ /dev/null
-****************************
-core. The Core Functionality
-****************************
-
-.. toctree::
- :maxdepth: 2
-
- basic_structures
- command_line_parser
- old_basic_structures
- dynamic_structures
- operations_on_arrays
- xml_yaml_persistence
- old_xml_yaml_persistence
- clustering
- utility_and_system_functions_and_macros
- opengl_interop
- ipp_async_converters
- optim
+++ /dev/null
-Dynamic Structures
-==================
-
-.. highlight:: c
-
-The section describes OpenCV 1.x API for creating growable sequences and other dynamic data structures allocated in ``CvMemStorage``. If you use the new C++, Python, Java etc interface, you will unlikely need this functionality. Use ``std::vector`` or other high-level data structures.
-
-CvMemStorage
-------------
-
-.. ocv:struct:: CvMemStorage
-
- A storage for various OpenCV dynamic data structures, such as ``CvSeq``, ``CvSet`` etc.
-
- .. ocv:member:: CvMemBlock* bottom
-
- the first memory block in the double-linked list of blocks
-
- .. ocv:member:: CvMemBlock* top
-
- the current partially allocated memory block in the list of blocks
-
- .. ocv:member:: CvMemStorage* parent
-
- the parent storage (if any) from which the new memory blocks are borrowed.
-
- .. ocv:member:: int free_space
-
- number of free bytes in the ``top`` block
-
- .. ocv:member:: int block_size
-
- the total size of the memory blocks
-
-Memory storage is a low-level structure used to store dynamically growing data structures such as sequences, contours, graphs, subdivisions, etc. It is organized as a list of memory blocks of equal size -
-``bottom`` field is the beginning of the list of blocks and ``top`` is the currently used block, but not necessarily the last block of the list. All blocks between ``bottom`` and ``top``, not including the
-latter, are considered fully occupied; all blocks between ``top`` and the last block, not including ``top``, are considered free and ``top`` itself is partly occupied - ``free_space`` contains the number of free bytes left in the end of ``top``.
-
-A new memory buffer that may be allocated explicitly by :ocv:cfunc:`MemStorageAlloc` function or implicitly by higher-level functions, such as :ocv:cfunc:`SeqPush`, :ocv:cfunc:`GraphAddEdge` etc.
-
-The buffer is put in the end of already allocated space in the ``top`` memory block, if there is enough free space. After allocation, ``free_space`` is decreased by the size of the allocated buffer plus some padding to keep the proper alignment. When the allocated buffer does not fit into the available portion of
-``top``, the next storage block from the list is taken as ``top`` and ``free_space`` is reset to the whole block size prior to the allocation.
-
-If there are no more free blocks, a new block is allocated (or borrowed from the parent, see :ocv:cfunc:`CreateChildMemStorage`) and added to the end of list. Thus, the storage behaves as a stack with ``bottom`` indicating bottom of the stack and the pair (``top``, ``free_space``)
-indicating top of the stack. The stack top may be saved via :ocv:cfunc:`SaveMemStoragePos`, restored via
-:ocv:cfunc:`RestoreMemStoragePos`, or reset via :ocv:cfunc:`ClearMemStorage`.
-
-CvMemBlock
-----------
-
-.. ocv:struct:: CvMemBlock
-
-The structure :ocv:struct:`CvMemBlock` represents a single block of memory storage. The actual data in the memory blocks follows the header.
-
-CvMemStoragePos
----------------
-
-.. ocv:struct:: CvMemStoragePos
-
-The structure stores the position in the memory storage. It is used by :ocv:cfunc:`SaveMemStoragePos` and :ocv:cfunc:`RestoreMemStoragePos`.
-
-CvSeq
------
-
-.. ocv:struct:: CvSeq
-
- Dynamically growing sequence.
-
- .. ocv:member:: int flags
-
- sequence flags, including the sequence signature (CV_SEQ_MAGIC_VAL or CV_SET_MAGIC_VAL), type of the elements and some other information about the sequence.
-
- .. ocv:member:: int header_size
-
- size of the sequence header. It should be sizeof(CvSeq) at minimum. See :ocv:cfunc:`CreateSeq`.
-
- .. ocv:member:: CvSeq* h_prev
- .. ocv:member:: CvSeq* h_next
- .. ocv:member:: CvSeq* v_prev
- .. ocv:member:: CvSeq* v_next
-
- pointers to another sequences in a sequence tree. Sequence trees are used to store hierarchical contour structures, retrieved by :ocv:cfunc:`FindContours`
-
- .. ocv:member:: int total
-
- the number of sequence elements
-
- .. ocv:member:: int elem_size
-
- size of each sequence element in bytes
-
- .. ocv:member:: CvMemStorage* storage
-
- memory storage where the sequence resides. It can be a NULL pointer.
-
- .. ocv:member:: CvSeqBlock* first
-
- pointer to the first data block
-
-The structure ``CvSeq`` is a base for all of OpenCV dynamic data structures.
-There are two types of sequences - dense and sparse. The base type for dense
-sequences is :ocv:struct:`CvSeq` and such sequences are used to represent
-growable 1d arrays - vectors, stacks, queues, and deques. They have no gaps
-in the middle - if an element is removed from the middle or inserted
-into the middle of the sequence, the elements from the closer end are
-shifted. Sparse sequences have :ocv:struct:`CvSet` as a base class and they are
-discussed later in more detail. They are sequences of nodes; each may be either occupied or free as indicated by the node flag. Such sequences are used for unordered data structures such as sets of elements, graphs, hash tables and so forth.
-
-
-CvSlice
--------
-
-.. ocv:struct:: CvSlice
-
- A sequence slice. In C++ interface the class :ocv:class:`Range` should be used instead.
-
- .. ocv:member:: int start_index
-
- inclusive start index of the sequence slice
-
- .. ocv:member:: int end_index
-
- exclusive end index of the sequence slice
-
-There are helper functions to construct the slice and to compute its length:
-
-.. ocv:cfunction:: CvSlice cvSlice( int start, int end )
-
- :param start: Inclusive left boundary.
-
- :param end: Exclusive right boundary.
-
-::
-
- #define CV_WHOLE_SEQ_END_INDEX 0x3fffffff
- #define CV_WHOLE_SEQ cvSlice(0, CV_WHOLE_SEQ_END_INDEX)
-
-.. ocv:cfunction:: int cvSliceLength( CvSlice slice, const CvSeq* seq )
-
- :param slice: The slice of sequence.
-
- :param seq: Source sequence.
-
-Calculates the sequence slice length.
-
-Some of functions that operate on sequences take a ``CvSlice slice`` parameter that is often set to the whole sequence (CV_WHOLE_SEQ) by default. Either of the ``start_index`` and ``end_index`` may be negative or exceed the sequence length. If they are equal, the slice is considered empty (i.e., contains no elements). Because sequences are treated as circular structures, the slice may select a
-few elements in the end of a sequence followed by a few elements at the beginning of the sequence. For example, ``cvSlice(-2, 3)`` in the case of a 10-element sequence will select a 5-element slice, containing the pre-last (8th), last (9th), the very first (0th), second (1th) and third (2nd)
-elements. The functions normalize the slice argument in the following way:
-
- #. :ocv:cfunc:`SliceLength` is called to determine the length of the slice,
- #. ``start_index`` of the slice is normalized similarly to the argument of :ocv:cfunc:`GetSeqElem` (i.e., negative indices are allowed). The actual slice to process starts at the normalized ``start_index`` and lasts :ocv:cfunc:`SliceLength` elements (again, assuming the sequence is a circular structure).
-
-If a function does not accept a slice argument, but you want to process only a part of the sequence, the sub-sequence may be extracted using the :ocv:cfunc:`SeqSlice` function, or stored into a continuous
-buffer with :ocv:cfunc:`CvtSeqToArray` (optionally, followed by :ocv:cfunc:`MakeSeqHeaderForArray`).
-
-CvSet
------
-
-.. ocv:struct:: CvSet
-
-The structure ``CvSet`` is a base for OpenCV 1.x sparse data structures. It is derived from :ocv:struct:`CvSeq` and includes an additional member ``free_elems`` - a list of free nodes. Every node of the set, whether free or not, is an element of the underlying sequence. While there are no restrictions on elements of dense sequences, the set (and derived structures) elements must start with an integer field and be able to fit CvSetElem structure, because these two fields (an integer followed by a pointer) are required for the organization of a node set with the list of free nodes. If a node is free, the ``flags``
-field is negative (the most-significant bit, or MSB, of the field is set), and the ``next_free`` points to the next free node (the first free node is referenced by the ``free_elems`` field of :ocv:struct:`CvSet`). And if a node is occupied, the ``flags`` field is positive and contains the node index that may be retrieved using the (``set_elem->flags & CV_SET_ELEM_IDX_MASK``) expressions, the rest of the node content is determined by the user. In particular, the occupied nodes are not linked as the free nodes are, so the second field can be used for such a link as well as for some different purpose. The macro ``CV_IS_SET_ELEM(set_elem_ptr)`` can be used to determined whether the specified node is occupied or not.
-
-Initially the set and the free node list are empty. When a new node is requested from the set, it is taken from the list of free nodes, which is then updated. If the list appears to be empty, a new sequence block is allocated and all the nodes within the block are joined in the list of free nodes. Thus, the ``total``
-field of the set is the total number of nodes both occupied and free. When an occupied node is released, it is added to the list of free nodes. The node released last will be occupied first.
-
-``CvSet`` is used to represent graphs (:ocv:struct:`CvGraph`), sparse multi-dimensional arrays (:ocv:struct:`CvSparseMat`), and planar subdivisions (``CvSubdiv2D``).
-
-CvSetElem
----------
-
-.. ocv:struct:: CvSetElem
-
-The structure is represent single element of :ocv:struct:`CvSet`. It consists of two fields: element data pointer and flags.
-
-CvGraph
--------
-.. ocv:struct:: CvGraph
-
-The structure ``CvGraph`` is a base for graphs used in OpenCV 1.x. It inherits from
-:ocv:struct:`CvSet`, that is, it is considered as a set of vertices. Besides, it contains another set as a member, a set of graph edges. Graphs in OpenCV are represented using adjacency lists format.
-
-CvGraphVtx
-----------
-.. ocv:struct:: CvGraphVtx
-
-The structure represents single vertex in :ocv:struct:`CvGraph`. It consists of two filds: pointer to first edge and flags.
-
-CvGraphEdge
------------
-.. ocv:struct:: CvGraphEdge
-
-The structure represents edge in :ocv:struct:`CvGraph`. Each edge consists of:
-
-- Two pointers to the starting and ending vertices (vtx[0] and vtx[1] respectively);
-- Two pointers to next edges for the starting and ending vertices, where
- next[0] points to the next edge in the vtx[0] adjacency list and
- next[1] points to the next edge in the vtx[1] adjacency list;
-- Weight;
-- Flags.
-
-CvGraphScanner
---------------
-
-.. ocv:struct:: CvGraphScanner
-
-The structure ``CvGraphScanner`` is used for depth-first graph traversal. See discussion of the functions below.
-
-
-CvTreeNodeIterator
-------------------
-
-.. ocv:struct:: CvTreeNodeIterator
-
-The structure ``CvTreeNodeIterator`` is used to traverse trees of sequences.
-
-ClearGraph
-----------
-Clears a graph.
-
-.. ocv:cfunction:: void cvClearGraph( CvGraph* graph )
-
- :param graph: Graph
-
-The function removes all vertices and edges from a graph. The function has O(1) time complexity.
-
-ClearMemStorage
----------------
-Clears memory storage.
-
-.. ocv:cfunction:: void cvClearMemStorage( CvMemStorage* storage )
-
- :param storage: Memory storage
-
-The function resets the top (free space boundary) of the storage to the very beginning. This function does not deallocate any memory. If the storage has a parent, the function returns
-all blocks to the parent.
-
-ClearSeq
---------
-Clears a sequence.
-
-.. ocv:cfunction:: void cvClearSeq( CvSeq* seq )
-
- :param seq: Sequence
-
-The function removes all elements from a sequence. The function does not return the memory to the storage block, but this memory is reused later when new elements are added to the sequence. The function has
-'O(1)' time complexity.
-
-.. note:: It is impossible to deallocate a sequence, i.e. free space in the memory storage occupied by the sequence. Instead, call :ocv:cfunc:`ClearMemStorage` or :ocv:cfunc:`ReleaseMemStorage` from time to time somewhere in a top-level processing loop.
-
-ClearSet
---------
-Clears a set.
-
-.. ocv:cfunction:: void cvClearSet( CvSet* set_header )
-
- :param set_header: Cleared set
-
-The function removes all elements from set. It has O(1) time complexity.
-
-CloneGraph
-----------
-Clones a graph.
-
-.. ocv:cfunction:: CvGraph* cvCloneGraph( const CvGraph* graph, CvMemStorage* storage )
-
- :param graph: The graph to copy
-
- :param storage: Container for the copy
-
-The function creates a full copy of the specified graph. If the
-graph vertices or edges have pointers to some external data, it can still be
-shared between the copies. The vertex and edge indices in the new graph
-may be different from the original because the function defragments
-the vertex and edge sets.
-
-CloneSeq
---------
-Creates a copy of a sequence.
-
-.. ocv:cfunction:: CvSeq* cvCloneSeq( const CvSeq* seq, CvMemStorage* storage=NULL )
-
- :param seq: Sequence
-
- :param storage: The destination storage block to hold the new sequence header and the copied data, if any. If it is NULL, the function uses the storage block containing the input sequence.
-
-The function makes a complete copy of the input sequence and returns it.
-
-The call ``cvCloneSeq( seq, storage )`` is equivalent to ``cvSeqSlice( seq, CV_WHOLE_SEQ, storage, 1 )``.
-
-
-CreateChildMemStorage
----------------------
-Creates child memory storage.
-
-.. ocv:cfunction:: CvMemStorage* cvCreateChildMemStorage(CvMemStorage* parent)
-
- :param parent: Parent memory storage
-
-The function creates a child memory
-storage that is similar to simple memory storage except for the
-differences in the memory allocation/deallocation mechanism. When a
-child storage needs a new block to add to the block list, it tries
-to get this block from the parent. The first unoccupied parent block
-available is taken and excluded from the parent block list. If no blocks
-are available, the parent either allocates a block or borrows one from
-its own parent, if any. In other words, the chain, or a more complex
-structure, of memory storages where every storage is a child/parent of
-another is possible. When a child storage is released or even cleared,
-it returns all blocks to the parent. In other aspects, child storage
-is the same as simple storage.
-
-Child storage is useful in the following situation. Imagine
-that the user needs to process dynamic data residing in a given storage area and
-put the result back to that same storage area. With the simplest approach,
-when temporary data is resided in the same storage area as the input and
-output data, the storage area will look as follows after processing:
-
-Dynamic data processing without using child storage
-
-.. image:: pics/memstorage1.png
-
-That is, garbage appears in the middle of the storage. However, if
-one creates a child memory storage at the beginning of processing,
-writes temporary data there, and releases the child storage at the end,
-no garbage will appear in the source/destination storage:
-
-Dynamic data processing using a child storage
-
-.. image:: pics/memstorage2.png
-
-CreateGraph
------------
-Creates an empty graph.
-
-.. ocv:cfunction:: CvGraph* cvCreateGraph( int graph_flags, int header_size, int vtx_size, int edge_size, CvMemStorage* storage )
-
-
- :param graph_flags: Type of the created graph. Usually, it is either ``CV_SEQ_KIND_GRAPH`` for generic unoriented graphs and ``CV_SEQ_KIND_GRAPH | CV_GRAPH_FLAG_ORIENTED`` for generic oriented graphs.
-
- :param header_size: Graph header size; may not be less than ``sizeof(CvGraph)``
-
- :param vtx_size: Graph vertex size; the custom vertex structure must start with :ocv:struct:`CvGraphVtx` (use ``CV_GRAPH_VERTEX_FIELDS()`` )
-
- :param edge_size: Graph edge size; the custom edge structure must start with :ocv:struct:`CvGraphEdge` (use ``CV_GRAPH_EDGE_FIELDS()`` )
-
- :param storage: The graph container
-
-The function creates an empty graph and returns a pointer to it.
-
-CreateGraphScanner
-------------------
-Creates structure for depth-first graph traversal.
-
-.. ocv:cfunction:: CvGraphScanner* cvCreateGraphScanner( CvGraph* graph, CvGraphVtx* vtx=NULL, int mask=CV_GRAPH_ALL_ITEMS )
-
-
- :param graph: Graph
-
- :param vtx: Initial vertex to start from. If NULL, the traversal starts from the first vertex (a vertex with the minimal index in the sequence of vertices).
-
- :param mask: Event mask indicating which events are of interest to the user (where :ocv:cfunc:`NextGraphItem` function returns control to the user) It can be ``CV_GRAPH_ALL_ITEMS`` (all events are of interest) or a combination of the following flags:
-
- * **CV_GRAPH_VERTEX** stop at the graph vertices visited for the first time
-
- * **CV_GRAPH_TREE_EDGE** stop at tree edges ( ``tree edge`` is the edge connecting the last visited vertex and the vertex to be visited next)
-
- * **CV_GRAPH_BACK_EDGE** stop at back edges ( ``back edge`` is an edge connecting the last visited vertex with some of its ancestors in the search tree)
-
- * **CV_GRAPH_FORWARD_EDGE** stop at forward edges ( ``forward edge`` is an edge connecting the last visited vertex with some of its descendants in the search tree. The forward edges are only possible during oriented graph traversal)
-
- * **CV_GRAPH_CROSS_EDGE** stop at cross edges ( ``cross edge`` is an edge connecting different search trees or branches of the same tree. The ``cross edges`` are only possible during oriented graph traversal)
-
- * **CV_GRAPH_ANY_EDGE** stop at any edge ( ``tree, back, forward`` , and ``cross edges`` )
-
- * **CV_GRAPH_NEW_TREE** stop in the beginning of every new search tree. When the traversal procedure visits all vertices and edges reachable from the initial vertex (the visited vertices together with tree edges make up a tree), it searches for some unvisited vertex in the graph and resumes the traversal process from that vertex. Before starting a new tree (including the very first tree when ``cvNextGraphItem`` is called for the first time) it generates a ``CV_GRAPH_NEW_TREE`` event. For unoriented graphs, each search tree corresponds to a connected component of the graph.
-
- * **CV_GRAPH_BACKTRACKING** stop at every already visited vertex during backtracking - returning to already visited vertexes of the traversal tree.
-
-The function creates a structure for depth-first graph traversal/search. The initialized structure is used in the
-:ocv:cfunc:`NextGraphItem`
-function - the incremental traversal procedure.
-
-CreateMemStorage
-----------------
-Creates memory storage.
-
-.. ocv:cfunction:: CvMemStorage* cvCreateMemStorage( int block_size=0 )
-
- :param block_size: Size of the storage blocks in bytes. If it is 0, the block size is set to a default value - currently it is about 64K.
-
-The function creates an empty memory storage. See
-:ocv:struct:`CvMemStorage`
-description.
-
-CreateSeq
----------
-Creates a sequence.
-
-.. ocv:cfunction:: CvSeq* cvCreateSeq( int seq_flags, size_t header_size, size_t elem_size, CvMemStorage* storage )
-
-
- :param seq_flags: Flags of the created sequence. If the sequence is not passed to any function working with a specific type of sequences, the sequence value may be set to 0, otherwise the appropriate type must be selected from the list of predefined sequence types.
-
- :param header_size: Size of the sequence header; must be greater than or equal to ``sizeof(CvSeq)`` . If a specific type or its extension is indicated, this type must fit the base type header.
-
- :param elem_size: Size of the sequence elements in bytes. The size must be consistent with the sequence type. For example, for a sequence of points to be created, the element type ``CV_SEQ_ELTYPE_POINT`` should be specified and the parameter ``elem_size`` must be equal to ``sizeof(CvPoint)`` .
-
- :param storage: Sequence location
-
-The function creates a sequence and returns
-the pointer to it. The function allocates the sequence header in
-the storage block as one continuous chunk and sets the structure
-fields
-``flags``
-,
-``elemSize``
-,
-``headerSize``
-, and
-``storage``
-to passed values, sets
-``delta_elems``
-to the
-default value (that may be reassigned using the
-:ocv:cfunc:`SetSeqBlockSize`
-function), and clears other header fields, including the space following
-the first
-``sizeof(CvSeq)``
-bytes.
-
-CreateSet
----------
-Creates an empty set.
-
-.. ocv:cfunction:: CvSet* cvCreateSet( int set_flags, int header_size, int elem_size, CvMemStorage* storage )
-
- :param set_flags: Type of the created set
-
- :param header_size: Set header size; may not be less than ``sizeof(CvSet)``
-
- :param elem_size: Set element size; may not be less than :ocv:struct:`CvSetElem`
-
- :param storage: Container for the set
-
-The function creates an empty set with a specified header size and element size, and returns the pointer to the set. This function is just a thin layer on top of
-:ocv:cfunc:`CreateSeq`.
-
-CvtSeqToArray
--------------
-Copies a sequence to one continuous block of memory.
-
-.. ocv:cfunction:: void* cvCvtSeqToArray( const CvSeq* seq, void* elements, CvSlice slice=CV_WHOLE_SEQ )
-
- :param seq: Sequence
-
- :param elements: Pointer to the destination array that must be large enough. It should be a pointer to data, not a matrix header.
-
- :param slice: The sequence portion to copy to the array
-
-The function copies the entire sequence or subsequence to the specified buffer and returns the pointer to the buffer.
-
-EndWriteSeq
------------
-Finishes the process of writing a sequence.
-
-.. ocv:cfunction:: CvSeq* cvEndWriteSeq( CvSeqWriter* writer )
-
- :param writer: Writer state
-
-The function finishes the writing process and
-returns the pointer to the written sequence. The function also truncates
-the last incomplete sequence block to return the remaining part of the
-block to memory storage. After that, the sequence can be read and
-modified safely. See
-:ocv:cfunc:`StartWriteSeq`
-and
-:ocv:cfunc:`StartAppendToSeq`
-
-FindGraphEdge
--------------
-Finds an edge in a graph.
-
-.. ocv:cfunction:: CvGraphEdge* cvFindGraphEdge( const CvGraph* graph, int start_idx, int end_idx )
-
- :param graph: Graph
-
- :param start_idx: Index of the starting vertex of the edge
-
- :param end_idx: Index of the ending vertex of the edge. For an unoriented graph, the order of the vertex parameters does not matter.
-
-::
-
- #define cvGraphFindEdge cvFindGraphEdge
-
-..
-
-The function finds the graph edge connecting two specified vertices and returns a pointer to it or NULL if the edge does not exist.
-
-FindGraphEdgeByPtr
-------------------
-Finds an edge in a graph by using its pointer.
-
-.. ocv:cfunction:: CvGraphEdge* cvFindGraphEdgeByPtr( const CvGraph* graph, const CvGraphVtx* start_vtx, const CvGraphVtx* end_vtx )
-
- :param graph: Graph
-
- :param start_vtx: Pointer to the starting vertex of the edge
-
- :param end_vtx: Pointer to the ending vertex of the edge. For an unoriented graph, the order of the vertex parameters does not matter.
-
-::
-
- #define cvGraphFindEdgeByPtr cvFindGraphEdgeByPtr
-
-..
-
-The function finds the graph edge connecting two specified vertices and returns pointer to it or NULL if the edge does not exists.
-
-FlushSeqWriter
---------------
-Updates sequence headers from the writer.
-
-.. ocv:cfunction:: void cvFlushSeqWriter( CvSeqWriter* writer )
-
- :param writer: Writer state
-
-The function is intended to enable the user to
-read sequence elements, whenever required, during the writing process,
-e.g., in order to check specific conditions. The function updates the
-sequence headers to make reading from the sequence possible. The writer
-is not closed, however, so that the writing process can be continued at
-any time. If an algorithm requires frequent flushes, consider using
-:ocv:cfunc:`SeqPush`
-instead.
-
-GetGraphVtx
------------
-Finds a graph vertex by using its index.
-
-.. ocv:cfunction:: CvGraphVtx* cvGetGraphVtx( CvGraph* graph, int vtx_idx )
-
- :param graph: Graph
-
- :param vtx_idx: Index of the vertex
-
-The function finds the graph vertex by using its index and returns the pointer to it or NULL if the vertex does not belong to the graph.
-
-GetSeqElem
-----------
-Returns a pointer to a sequence element according to its index.
-
-.. ocv:cfunction:: schar* cvGetSeqElem( const CvSeq* seq, int index )
-
- :param seq: Sequence
-
- :param index: Index of element
-
-::
-
- #define CV_GET_SEQ_ELEM( TYPE, seq, index ) (TYPE*)cvGetSeqElem( (CvSeq*)(seq), (index) )
-
-..
-
-
-The function finds the element with the given
-index in the sequence and returns the pointer to it. If the element
-is not found, the function returns 0. The function supports negative
-indices, where -1 stands for the last sequence element, -2 stands for
-the one before last, etc. If the sequence is most likely to consist of
-a single sequence block or the desired element is likely to be located
-in the first block, then the macro
-``CV_GET_SEQ_ELEM( elemType, seq, index )``
-should be used, where the parameter
-``elemType``
-is the
-type of sequence elements (
-:ocv:struct:`CvPoint`
-for example), the parameter
-``seq``
-is a sequence, and the parameter
-``index``
-is the index
-of the desired element. The macro checks first whether the desired element
-belongs to the first block of the sequence and returns it if it does;
-otherwise the macro calls the main function
-``GetSeqElem``
-. Negative
-indices always cause the
-:ocv:cfunc:`GetSeqElem`
-call. The function has O(1)
-time complexity assuming that the number of blocks is much smaller than the
-number of elements.
-
-GetSeqReaderPos
----------------
-Returns the current reader position.
-
-.. ocv:cfunction:: int cvGetSeqReaderPos( CvSeqReader* reader )
-
- :param reader: Reader state
-
-The function returns the current reader position (within 0 ...
-``reader->seq->total``
-- 1).
-
-GetSetElem
-----------
-Finds a set element by its index.
-
-.. ocv:cfunction:: CvSetElem* cvGetSetElem( const CvSet* set_header, int idx )
-
- :param set_header: Set
-
- :param idx: Index of the set element within a sequence
-
-The function finds a set element by its index. The function returns the pointer to it or 0 if the index is invalid or the corresponding node is free. The function supports negative indices as it uses
-:ocv:cfunc:`GetSeqElem`
-to locate the node.
-
-GraphAddEdge
-------------
-Adds an edge to a graph.
-
-.. ocv:cfunction:: int cvGraphAddEdge( CvGraph* graph, int start_idx, int end_idx, const CvGraphEdge* edge=NULL, CvGraphEdge** inserted_edge=NULL )
-
- :param graph: Graph
-
- :param start_idx: Index of the starting vertex of the edge
-
- :param end_idx: Index of the ending vertex of the edge. For an unoriented graph, the order of the vertex parameters does not matter.
-
- :param edge: Optional input parameter, initialization data for the edge
-
- :param inserted_edge: Optional output parameter to contain the address of the inserted edge
-
-The function connects two specified vertices. The function returns 1 if the edge has been added successfully, 0 if the edge connecting the two vertices exists already and -1 if either of the vertices was not found, the starting and the ending vertex are the same, or there is some other critical situation. In the latter case (i.e., when the result is negative), the function also reports an error by default.
-
-GraphAddEdgeByPtr
------------------
-Adds an edge to a graph by using its pointer.
-
-.. ocv:cfunction:: int cvGraphAddEdgeByPtr( CvGraph* graph, CvGraphVtx* start_vtx, CvGraphVtx* end_vtx, const CvGraphEdge* edge=NULL, CvGraphEdge** inserted_edge=NULL )
-
- :param graph: Graph
-
- :param start_vtx: Pointer to the starting vertex of the edge
-
- :param end_vtx: Pointer to the ending vertex of the edge. For an unoriented graph, the order of the vertex parameters does not matter.
-
- :param edge: Optional input parameter, initialization data for the edge
-
- :param inserted_edge: Optional output parameter to contain the address of the inserted edge within the edge set
-
-The function connects two specified vertices. The
-function returns 1 if the edge has been added successfully, 0 if the
-edge connecting the two vertices exists already, and -1 if either of the
-vertices was not found, the starting and the ending vertex are the same
-or there is some other critical situation. In the latter case (i.e., when
-the result is negative), the function also reports an error by default.
-
-GraphAddVtx
------------
-Adds a vertex to a graph.
-
-.. ocv:cfunction:: int cvGraphAddVtx( CvGraph* graph, const CvGraphVtx* vtx=NULL, CvGraphVtx** inserted_vtx=NULL )
-
- :param graph: Graph
-
- :param vtx: Optional input argument used to initialize the added vertex (only user-defined fields beyond ``sizeof(CvGraphVtx)`` are copied)
-
- :param inserted_vtx: Optional output argument. If not ``NULL`` , the address of the new vertex is written here.
-
-The function adds a vertex to the graph and returns the vertex index.
-
-GraphEdgeIdx
-------------
-Returns the index of a graph edge.
-
-.. ocv:cfunction:: int cvGraphEdgeIdx( CvGraph* graph, CvGraphEdge* edge )
-
- :param graph: Graph
-
- :param edge: Pointer to the graph edge
-
-The function returns the index of a graph edge.
-
-GraphRemoveEdge
----------------
-Removes an edge from a graph.
-
-.. ocv:cfunction:: void cvGraphRemoveEdge( CvGraph* graph, int start_idx, int end_idx )
-
- :param graph: Graph
-
- :param start_idx: Index of the starting vertex of the edge
-
- :param end_idx: Index of the ending vertex of the edge. For an unoriented graph, the order of the vertex parameters does not matter.
-
-The function removes the edge connecting two specified vertices. If the vertices are not connected [in that order], the function does nothing.
-
-GraphRemoveEdgeByPtr
---------------------
-Removes an edge from a graph by using its pointer.
-
-.. ocv:cfunction:: void cvGraphRemoveEdgeByPtr( CvGraph* graph, CvGraphVtx* start_vtx, CvGraphVtx* end_vtx )
-
- :param graph: Graph
-
- :param start_vtx: Pointer to the starting vertex of the edge
-
- :param end_vtx: Pointer to the ending vertex of the edge. For an unoriented graph, the order of the vertex parameters does not matter.
-
-The function removes the edge connecting two specified vertices. If the vertices are not connected [in that order], the function does nothing.
-
-GraphRemoveVtx
---------------
-Removes a vertex from a graph.
-
-.. ocv:cfunction:: int cvGraphRemoveVtx( CvGraph* graph, int index )
-
- :param graph: Graph
-
- :param index: Index of the removed vertex
-
-The function removes a vertex from a graph
-together with all the edges incident to it. The function reports an error
-if the input vertex does not belong to the graph. The return value is the
-number of edges deleted, or -1 if the vertex does not belong to the graph.
-
-GraphRemoveVtxByPtr
--------------------
-Removes a vertex from a graph by using its pointer.
-
-.. ocv:cfunction:: int cvGraphRemoveVtxByPtr( CvGraph* graph, CvGraphVtx* vtx )
-
- :param graph: Graph
-
- :param vtx: Pointer to the removed vertex
-
-The function removes a vertex from the graph by using its pointer together with all the edges incident to it. The function reports an error if the vertex does not belong to the graph. The return value is the number of edges deleted, or -1 if the vertex does not belong to the graph.
-
-GraphVtxDegree
---------------
-Counts the number of edges incident to the vertex.
-
-.. ocv:cfunction:: int cvGraphVtxDegree( const CvGraph* graph, int vtx_idx )
-
- :param graph: Graph
-
- :param vtx_idx: Index of the graph vertex
-
-The function returns the number of edges incident to the specified vertex, both incoming and outgoing. To count the edges, the following code is used:
-
-::
-
- CvGraphEdge* edge = vertex->first; int count = 0;
- while( edge )
- {
- edge = CV_NEXT_GRAPH_EDGE( edge, vertex );
- count++;
- }
-
-..
-
-The macro
-``CV_NEXT_GRAPH_EDGE( edge, vertex )``
-returns the edge incident to
-``vertex``
-that follows after
-``edge``
-.
-
-GraphVtxDegreeByPtr
--------------------
-Finds an edge in a graph.
-
-.. ocv:cfunction:: int cvGraphVtxDegreeByPtr( const CvGraph* graph, const CvGraphVtx* vtx )
-
- :param graph: Graph
-
- :param vtx: Pointer to the graph vertex
-
-The function returns the number of edges incident to the specified vertex, both incoming and outcoming.
-
-GraphVtxIdx
------------
-Returns the index of a graph vertex.
-
-.. ocv:cfunction:: int cvGraphVtxIdx( CvGraph* graph, CvGraphVtx* vtx )
-
- :param graph: Graph
-
- :param vtx: Pointer to the graph vertex
-
-The function returns the index of a graph vertex.
-
-InitTreeNodeIterator
---------------------
-Initializes the tree node iterator.
-
-.. ocv:cfunction:: void cvInitTreeNodeIterator( CvTreeNodeIterator* tree_iterator, const void* first, int max_level )
-
- :param tree_iterator: Tree iterator initialized by the function
-
- :param first: The initial node to start traversing from
-
- :param max_level: The maximal level of the tree ( ``first`` node assumed to be at the first level) to traverse up to. For example, 1 means that only nodes at the same level as ``first`` should be visited, 2 means that the nodes on the same level as ``first`` and their direct children should be visited, and so forth.
-
-The function initializes the tree iterator. The tree is traversed in depth-first order.
-
-InsertNodeIntoTree
-------------------
-Adds a new node to a tree.
-
-.. ocv:cfunction:: void cvInsertNodeIntoTree( void* node, void* parent, void* frame )
-
- :param node: The inserted node
-
- :param parent: The parent node that is already in the tree
-
- :param frame: The top level node. If ``parent`` and ``frame`` are the same, the ``v_prev`` field of ``node`` is set to NULL rather than ``parent`` .
-
-The function adds another node into tree. The function does not allocate any memory, it can only modify links of the tree nodes.
-
-MakeSeqHeaderForArray
----------------------
-Constructs a sequence header for an array.
-
-.. ocv:cfunction:: CvSeq* cvMakeSeqHeaderForArray( int seq_type, int header_size, int elem_size, void* elements, int total, CvSeq* seq, CvSeqBlock* block )
-
- :param seq_type: Type of the created sequence
-
- :param header_size: Size of the header of the sequence. Parameter sequence must point to the structure of that size or greater
-
- :param elem_size: Size of the sequence elements
-
- :param elements: Elements that will form a sequence
-
- :param total: Total number of elements in the sequence. The number of array elements must be equal to the value of this parameter.
-
- :param seq: Pointer to the local variable that is used as the sequence header
-
- :param block: Pointer to the local variable that is the header of the single sequence block
-
-The function initializes a sequence
-header for an array. The sequence header as well as the sequence block are
-allocated by the user (for example, on stack). No data is copied by the
-function. The resultant sequence will consists of a single block and
-have NULL storage pointer; thus, it is possible to read its elements,
-but the attempts to add elements to the sequence will raise an error in
-most cases.
-
-MemStorageAlloc
----------------
-Allocates a memory buffer in a storage block.
-
-.. ocv:cfunction:: void* cvMemStorageAlloc( CvMemStorage* storage, size_t size )
-
- :param storage: Memory storage
-
- :param size: Buffer size
-
-The function allocates a memory buffer in
-a storage block. The buffer size must not exceed the storage block size,
-otherwise a runtime error is raised. The buffer address is aligned by
-``CV_STRUCT_ALIGN=sizeof(double)``
-(for the moment) bytes.
-
-MemStorageAllocString
----------------------
-Allocates a text string in a storage block.
-
-.. ocv:cfunction:: CvString cvMemStorageAllocString(CvMemStorage* storage, const char* ptr, int len=-1)
-
- :param storage: Memory storage
-
- :param ptr: The string
-
- :param len: Length of the string (not counting the ending ``NUL`` ) . If the parameter is negative, the function computes the length.
-
-::
-
- typedef struct CvString
- {
- int len;
- char* ptr;
- }
- CvString;
-
-..
-
-The function creates copy of the string
-in memory storage. It returns the structure that contains user-passed
-or computed length of the string and pointer to the copied string.
-
-NextGraphItem
--------------
-Executes one or more steps of the graph traversal procedure.
-
-.. ocv:cfunction:: int cvNextGraphItem( CvGraphScanner* scanner )
-
- :param scanner: Graph traversal state. It is updated by this function.
-
-The function traverses through the graph
-until an event of interest to the user (that is, an event, specified
-in the
-``mask``
-in the
-:ocv:cfunc:`CreateGraphScanner`
-call) is met or the
-traversal is completed. In the first case, it returns one of the events
-listed in the description of the
-``mask``
-parameter above and with
-the next call it resumes the traversal. In the latter case, it returns
-``CV_GRAPH_OVER``
-(-1). When the event is
-``CV_GRAPH_VERTEX``
-,
-``CV_GRAPH_BACKTRACKING``
-, or
-``CV_GRAPH_NEW_TREE``
-,
-the currently observed vertex is stored in
-``scanner-:math:`>`vtx``
-. And if the
-event is edge-related, the edge itself is stored at
-``scanner-:math:`>`edge``
-,
-the previously visited vertex - at
-``scanner-:math:`>`vtx``
-and the other ending
-vertex of the edge - at
-``scanner-:math:`>`dst``
-.
-
-NextTreeNode
-------------
-Returns the currently observed node and moves the iterator toward the next node.
-
-.. ocv:cfunction:: void* cvNextTreeNode( CvTreeNodeIterator* tree_iterator )
-
- :param tree_iterator: Tree iterator initialized by the function
-
-The function returns the currently observed node and then updates the
-iterator - moving it toward the next node. In other words, the function
-behavior is similar to the
-``*p++``
-expression on a typical C
-pointer or C++ collection iterator. The function returns NULL if there
-are no more nodes.
-
-PrevTreeNode
-------------
-Returns the currently observed node and moves the iterator toward the previous node.
-
-.. ocv:cfunction:: void* cvPrevTreeNode( CvTreeNodeIterator* tree_iterator )
-
- :param tree_iterator: Tree iterator initialized by the function
-
-The function returns the currently observed node and then updates
-the iterator - moving it toward the previous node. In other words,
-the function behavior is similar to the
-``*p--``
-expression on a
-typical C pointer or C++ collection iterator. The function returns NULL
-if there are no more nodes.
-
-ReleaseGraphScanner
--------------------
-Completes the graph traversal procedure.
-
-.. ocv:cfunction:: void cvReleaseGraphScanner( CvGraphScanner** scanner )
-
- :param scanner: Double pointer to graph traverser
-
-The function completes the graph traversal procedure and releases the traverser state.
-
-ReleaseMemStorage
------------------
-Releases memory storage.
-
-.. ocv:cfunction:: void cvReleaseMemStorage( CvMemStorage** storage )
-
- :param storage: Pointer to the released storage
-
-The function deallocates all storage memory
-blocks or returns them to the parent, if any. Then it deallocates the
-storage header and clears the pointer to the storage. All child storage
-associated with a given parent storage block must be released before the
-parent storage block is released.
-
-RestoreMemStoragePos
---------------------
-Restores memory storage position.
-
-.. ocv:cfunction:: void cvRestoreMemStoragePos( CvMemStorage* storage, CvMemStoragePos* pos)
-
- :param storage: Memory storage
-
- :param pos: New storage top position
-
-The function restores the position of the storage top from the parameter
-``pos``
-. This function and the function
-``cvClearMemStorage``
-are the only methods to release memory occupied in memory blocks. Note again that there is no way to free memory in the middle of an occupied portion of a storage block.
-
-SaveMemStoragePos
------------------
-Saves memory storage position.
-
-.. ocv:cfunction:: void cvSaveMemStoragePos( const CvMemStorage* storage, CvMemStoragePos* pos)
-
- :param storage: Memory storage
-
- :param pos: The output position of the storage top
-
-The function saves the current position
-of the storage top to the parameter
-``pos``
-. The function
-``cvRestoreMemStoragePos``
-can further retrieve this position.
-
-SeqElemIdx
-----------
-Returns the index of a specific sequence element.
-
-.. ocv:cfunction:: int cvSeqElemIdx( const CvSeq* seq, const void* element, CvSeqBlock** block=NULL )
-
- :param seq: Sequence
-
- :param element: Pointer to the element within the sequence
-
- :param block: Optional argument. If the pointer is not ``NULL`` , the address of the sequence block that contains the element is stored in this location.
-
-The function returns the index of a sequence element or a negative number if the element is not found.
-
-SeqInsert
----------
-Inserts an element in the middle of a sequence.
-
-.. ocv:cfunction:: schar* cvSeqInsert( CvSeq* seq, int before_index, const void* element=NULL )
-
- :param seq: Sequence
-
- :param before_index: Index before which the element is inserted. Inserting before 0 (the minimal allowed value of the parameter) is equal to :ocv:cfunc:`SeqPushFront` and inserting before ``seq->total`` (the maximal allowed value of the parameter) is equal to :ocv:cfunc:`SeqPush` .
-
- :param element: Inserted element
-
-The function shifts the sequence elements from the inserted position to the nearest end of the sequence and copies the
-``element``
-content there if the pointer is not NULL. The function returns a pointer to the inserted element.
-
-SeqInsertSlice
---------------
-Inserts an array in the middle of a sequence.
-
-.. ocv:cfunction:: void cvSeqInsertSlice( CvSeq* seq, int before_index, const CvArr* from_arr )
-
- :param seq: Sequence
-
- :param before_index: Index before which the array is inserted
-
- :param from_arr: The array to take elements from
-
-The function inserts all
-``fromArr``
-array elements at the specified position of the sequence. The array
-``fromArr``
-can be a matrix or another sequence.
-
-SeqInvert
----------
-Reverses the order of sequence elements.
-
-.. ocv:cfunction:: void cvSeqInvert( CvSeq* seq )
-
- :param seq: Sequence
-
-The function reverses the sequence in-place - the first element becomes the last one, the last element becomes the first one and so forth.
-
-SeqPop
-------
-Removes an element from the end of a sequence.
-
-.. ocv:cfunction:: void cvSeqPop( CvSeq* seq, void* element=NULL )
-
- :param seq: Sequence
-
- :param element: Optional parameter . If the pointer is not zero, the function copies the removed element to this location.
-
-The function removes an element from a sequence. The function reports an error if the sequence is already empty. The function has O(1) complexity.
-
-SeqPopFront
------------
-Removes an element from the beginning of a sequence.
-
-.. ocv:cfunction:: void cvSeqPopFront( CvSeq* seq, void* element=NULL )
-
- :param seq: Sequence
-
- :param element: Optional parameter. If the pointer is not zero, the function copies the removed element to this location.
-
-The function removes an element from the beginning of a sequence. The function reports an error if the sequence is already empty. The function has O(1) complexity.
-
-SeqPopMulti
------------
-Removes several elements from either end of a sequence.
-
-.. ocv:cfunction:: void cvSeqPopMulti( CvSeq* seq, void* elements, int count, int in_front=0 )
-
- :param seq: Sequence
-
- :param elements: Removed elements
-
- :param count: Number of elements to pop
-
- :param in_front: The flags specifying which end of the modified sequence.
-
- * **CV_BACK** the elements are added to the end of the sequence
-
- * **CV_FRONT** the elements are added to the beginning of the sequence
-
-The function removes several elements from either end of the sequence. If the number of the elements to be removed exceeds the total number of elements in the sequence, the function removes as many elements as possible.
-
-SeqPush
--------
-Adds an element to the end of a sequence.
-
-.. ocv:cfunction:: schar* cvSeqPush( CvSeq* seq, const void* element=NULL )
-
- :param seq: Sequence
-
- :param element: Added element
-
-The function adds an element to the end of a sequence and returns a pointer to the allocated element. If the input
-``element``
-is NULL, the function simply allocates a space for one more element.
-
-The following code demonstrates how to create a new sequence using this function:
-
-::
-
- CvMemStorage* storage = cvCreateMemStorage(0);
- CvSeq* seq = cvCreateSeq( CV_32SC1, /* sequence of integer elements */
- sizeof(CvSeq), /* header size - no extra fields */
- sizeof(int), /* element size */
- storage /* the container storage */ );
- int i;
- for( i = 0; i < 100; i++ )
- {
- int* added = (int*)cvSeqPush( seq, &i );
- printf( "
- }
-
- ...
- /* release memory storage in the end */
- cvReleaseMemStorage( &storage );
-
-..
-
-The function has O(1) complexity, but there is a faster method for writing large sequences (see
-:ocv:cfunc:`StartWriteSeq`
-and related functions).
-
-SeqPushFront
-------------
-Adds an element to the beginning of a sequence.
-
-.. ocv:cfunction:: schar* cvSeqPushFront( CvSeq* seq, const void* element=NULL )
-
- :param seq: Sequence
-
- :param element: Added element
-
-The function is similar to
-:ocv:cfunc:`SeqPush`
-but it adds the new element to the beginning of the sequence. The function has O(1) complexity.
-
-SeqPushMulti
-------------
-Pushes several elements to either end of a sequence.
-
-.. ocv:cfunction:: void cvSeqPushMulti( CvSeq* seq, const void* elements, int count, int in_front=0 )
-
- :param seq: Sequence
-
- :param elements: Added elements
-
- :param count: Number of elements to push
-
- :param in_front: The flags specifying which end of the modified sequence.
-
- * **CV_BACK** the elements are added to the end of the sequence
-
- * **CV_FRONT** the elements are added to the beginning of the sequence
-
-The function adds several elements to either
-end of a sequence. The elements are added to the sequence in the same
-order as they are arranged in the input array but they can fall into
-different sequence blocks.
-
-SeqRemove
----------
-Removes an element from the middle of a sequence.
-
-.. ocv:cfunction:: void cvSeqRemove( CvSeq* seq, int index )
-
- :param seq: Sequence
-
- :param index: Index of removed element
-
-The function removes elements with the given
-index. If the index is out of range the function reports an error. An
-attempt to remove an element from an empty sequence is a special
-case of this situation. The function removes an element by shifting
-the sequence elements between the nearest end of the sequence and the
-``index``
--th position, not counting the latter.
-
-SeqRemoveSlice
---------------
-Removes a sequence slice.
-
-.. ocv:cfunction:: void cvSeqRemoveSlice( CvSeq* seq, CvSlice slice )
-
- :param seq: Sequence
-
- :param slice: The part of the sequence to remove
-
-The function removes a slice from the sequence.
-
-SeqSearch
----------
-Searches for an element in a sequence.
-
-.. ocv:cfunction:: schar* cvSeqSearch( CvSeq* seq, const void* elem, CvCmpFunc func, int is_sorted, int* elem_idx, void* userdata=NULL )
-
- :param seq: The sequence
-
- :param elem: The element to look for
-
- :param func: The comparison function that returns negative, zero or positive value depending on the relationships among the elements (see also :ocv:cfunc:`SeqSort` )
-
- :param is_sorted: Whether the sequence is sorted or not
-
- :param elem_idx: Output parameter; index of the found element
-
- :param userdata: The user parameter passed to the comparison function; helps to avoid global variables in some cases
-
-::
-
- /* a < b ? -1 : a > b ? 1 : 0 */
- typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);
-
-..
-
-The function searches for the element in the sequence. If
-the sequence is sorted, a binary O(log(N)) search is used; otherwise, a
-simple linear search is used. If the element is not found, the function
-returns a NULL pointer and the index is set to the number of sequence
-elements if a linear search is used, or to the smallest index
-``i, seq(i)>elem``
-.
-
-SeqSlice
---------
-Makes a separate header for a sequence slice.
-
-.. ocv:cfunction:: CvSeq* cvSeqSlice( const CvSeq* seq, CvSlice slice, CvMemStorage* storage=NULL, int copy_data=0 )
-
- :param seq: Sequence
-
- :param slice: The part of the sequence to be extracted
-
- :param storage: The destination storage block to hold the new sequence header and the copied data, if any. If it is NULL, the function uses the storage block containing the input sequence.
-
- :param copy_data: The flag that indicates whether to copy the elements of the extracted slice ( ``copy_data!=0`` ) or not ( ``copy_data=0`` )
-
-The function creates a sequence that represents the specified slice of the input sequence. The new sequence either shares the elements with the original sequence or has its own copy of the elements. So if one needs to process a part of sequence but the processing function does not have a slice parameter, the required sub-sequence may be extracted using this function.
-
-SeqSort
--------
-Sorts sequence element using the specified comparison function.
-
-.. ocv:cfunction:: void cvSeqSort( CvSeq* seq, CvCmpFunc func, void* userdata=NULL )
-
- :param seq: The sequence to sort
-
- :param func: The comparison function that returns a negative, zero, or positive value depending on the relationships among the elements (see the above declaration and the example below) - a similar function is used by ``qsort`` from C runline except that in the latter, ``userdata`` is not used
-
- :param userdata: The user parameter passed to the comparison function; helps to avoid global variables in some cases
-
-::
-
- /* a < b ? -1 : a > b ? 1 : 0 */
- typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);
-
-..
-
-The function sorts the sequence in-place using the specified criteria. Below is an example of using this function:
-
-::
-
- /* Sort 2d points in top-to-bottom left-to-right order */
- static int cmp_func( const void* _a, const void* _b, void* userdata )
- {
- CvPoint* a = (CvPoint*)_a;
- CvPoint* b = (CvPoint*)_b;
- int y_diff = a->y - b->y;
- int x_diff = a->x - b->x;
- return y_diff ? y_diff : x_diff;
- }
-
- ...
-
- CvMemStorage* storage = cvCreateMemStorage(0);
- CvSeq* seq = cvCreateSeq( CV_32SC2, sizeof(CvSeq), sizeof(CvPoint), storage );
- int i;
-
- for( i = 0; i < 10; i++ )
- {
- CvPoint pt;
- pt.x = rand()
- pt.y = rand()
- cvSeqPush( seq, &pt );
- }
-
- cvSeqSort( seq, cmp_func, 0 /* userdata is not used here */ );
-
- /* print out the sorted sequence */
- for( i = 0; i < seq->total; i++ )
- {
- CvPoint* pt = (CvPoint*)cvSeqElem( seq, i );
- printf( "(
- }
-
- cvReleaseMemStorage( &storage );
-
-..
-
-SetAdd
-------
-Occupies a node in the set.
-
-.. ocv:cfunction:: int cvSetAdd( CvSet* set_header, CvSetElem* elem=NULL, CvSetElem** inserted_elem=NULL )
-
- :param set_header: Set
-
- :param elem: Optional input argument, an inserted element. If not NULL, the function copies the data to the allocated node (the MSB of the first integer field is cleared after copying).
-
- :param inserted_elem: Optional output argument; the pointer to the allocated cell
-
-The function allocates a new node, optionally copies
-input element data to it, and returns the pointer and the index to the
-node. The index value is taken from the lower bits of the
-``flags``
-field of the node. The function has O(1) complexity; however, there exists
-a faster function for allocating set nodes (see
-:ocv:cfunc:`SetNew`
-).
-
-SetNew
-------
-Adds an element to a set (fast variant).
-
-.. ocv:cfunction:: CvSetElem* cvSetNew( CvSet* set_header )
-
- :param set_header: Set
-
-The function is an inline lightweight variant of
-:ocv:cfunc:`SetAdd`
-. It occupies a new node and returns a pointer to it rather than an index.
-
-SetRemove
----------
-Removes an element from a set.
-
-.. ocv:cfunction:: void cvSetRemove( CvSet* set_header, int index )
-
- :param set_header: Set
-
- :param index: Index of the removed element
-
-The function removes an element with a specified
-index from the set. If the node at the specified location is not occupied,
-the function does nothing. The function has O(1) complexity; however,
-:ocv:cfunc:`SetRemoveByPtr`
-provides a quicker way to remove a set element
-if it is located already.
-
-SetRemoveByPtr
---------------
-Removes a set element based on its pointer.
-
-.. ocv:cfunction:: void cvSetRemoveByPtr( CvSet* set_header, void* elem )
-
- :param set_header: Set
-
- :param elem: Removed element
-
-The function is an inline lightweight variant of
-:ocv:cfunc:`SetRemove`
-that requires an element pointer. The function does not check whether the node is occupied or not - the user should take care of that.
-
-SetSeqBlockSize
----------------
-Sets up sequence block size.
-
-.. ocv:cfunction:: void cvSetSeqBlockSize( CvSeq* seq, int delta_elems )
-
- :param seq: Sequence
-
- :param delta_elems: Desirable sequence block size for elements
-
-The function affects memory allocation
-granularity. When the free space in the sequence buffers has run out,
-the function allocates the space for
-``delta_elems``
-sequence
-elements. If this block immediately follows the one previously allocated,
-the two blocks are concatenated; otherwise, a new sequence block is
-created. Therefore, the bigger the parameter is, the lower the possible
-sequence fragmentation, but the more space in the storage block is wasted. When
-the sequence is created, the parameter
-``delta_elems``
-is set to
-the default value of about 1K. The function can be called any time after
-the sequence is created and affects future allocations. The function
-can modify the passed value of the parameter to meet memory storage
-constraints.
-
-SetSeqReaderPos
----------------
-Moves the reader to the specified position.
-
-.. ocv:cfunction:: void cvSetSeqReaderPos( CvSeqReader* reader, int index, int is_relative=0 )
-
- :param reader: Reader state
-
- :param index: The destination position. If the positioning mode is used (see the next parameter), the actual position will be ``index`` mod ``reader->seq->total`` .
-
- :param is_relative: If it is not zero, then ``index`` is a relative to the current position
-
-The function moves the read position to an absolute position or relative to the current position.
-
-StartAppendToSeq
-----------------
-Initializes the process of writing data to a sequence.
-
-.. ocv:cfunction:: void cvStartAppendToSeq( CvSeq* seq, CvSeqWriter* writer )
-
- :param seq: Pointer to the sequence
-
- :param writer: Writer state; initialized by the function
-
-The function initializes the process of
-writing data to a sequence. Written elements are added to the end of the
-sequence by using the
-``CV_WRITE_SEQ_ELEM( written_elem, writer )``
-macro. Note
-that during the writing process, other operations on the sequence may
-yield an incorrect result or even corrupt the sequence (see description of
-:ocv:cfunc:`FlushSeqWriter`
-, which helps to avoid some of these problems).
-
-StartReadSeq
-------------
-Initializes the process of sequential reading from a sequence.
-
-.. ocv:cfunction:: void cvStartReadSeq( const CvSeq* seq, CvSeqReader* reader, int reverse=0 )
-
- :param seq: Sequence
-
- :param reader: Reader state; initialized by the function
-
- :param reverse: Determines the direction of the sequence traversal. If ``reverse`` is 0, the reader is positioned at the first sequence element; otherwise it is positioned at the last element.
-
-The function initializes the reader state. After
-that, all the sequence elements from the first one down to the last one
-can be read by subsequent calls of the macro
-``CV_READ_SEQ_ELEM( read_elem, reader )``
-in the case of forward reading and by using
-``CV_REV_READ_SEQ_ELEM( read_elem, reader )``
-in the case of reverse
-reading. Both macros put the sequence element to
-``read_elem``
-and
-move the reading pointer toward the next element. A circular structure
-of sequence blocks is used for the reading process, that is, after the
-last element has been read by the macro
-``CV_READ_SEQ_ELEM``
-, the
-first element is read when the macro is called again. The same applies to
-``CV_REV_READ_SEQ_ELEM``
-. There is no function to finish the reading
-process, since it neither changes the sequence nor creates any temporary
-buffers. The reader field
-``ptr``
-points to the current element of
-the sequence that is to be read next. The code below demonstrates how
-to use the sequence writer and reader.
-
-::
-
- CvMemStorage* storage = cvCreateMemStorage(0);
- CvSeq* seq = cvCreateSeq( CV_32SC1, sizeof(CvSeq), sizeof(int), storage );
- CvSeqWriter writer;
- CvSeqReader reader;
- int i;
-
- cvStartAppendToSeq( seq, &writer );
- for( i = 0; i < 10; i++ )
- {
- int val = rand()
- CV_WRITE_SEQ_ELEM( val, writer );
- printf("
- }
- cvEndWriteSeq( &writer );
-
- cvStartReadSeq( seq, &reader, 0 );
- for( i = 0; i < seq->total; i++ )
- {
- int val;
- #if 1
- CV_READ_SEQ_ELEM( val, reader );
- printf("
- #else /* alternative way, that is prefferable if sequence elements are large,
- or their size/type is unknown at compile time */
- printf("
- CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
- #endif
- }
- ...
-
- cvReleaseStorage( &storage );
-
-..
-
-StartWriteSeq
--------------
-Creates a new sequence and initializes a writer for it.
-
-.. ocv:cfunction:: void cvStartWriteSeq( int seq_flags, int header_size, int elem_size, CvMemStorage* storage, CvSeqWriter* writer )
-
- :param seq_flags: Flags of the created sequence. If the sequence is not passed to any function working with a specific type of sequences, the sequence value may be equal to 0; otherwise the appropriate type must be selected from the list of predefined sequence types.
-
- :param header_size: Size of the sequence header. The parameter value may not be less than ``sizeof(CvSeq)`` . If a certain type or extension is specified, it must fit within the base type header.
-
- :param elem_size: Size of the sequence elements in bytes; must be consistent with the sequence type. For example, if a sequence of points is created (element type ``CV_SEQ_ELTYPE_POINT`` ), then the parameter ``elem_size`` must be equal to ``sizeof(CvPoint)`` .
-
- :param storage: Sequence location
-
- :param writer: Writer state; initialized by the function
-
-The function is a combination of
-:ocv:cfunc:`CreateSeq`
-and
-:ocv:cfunc:`StartAppendToSeq`
-. The pointer to the
-created sequence is stored at
-``writer->seq``
-and is also returned by the
-:ocv:cfunc:`EndWriteSeq`
-function that should be called at the end.
-
-TreeToNodeSeq
--------------
-Gathers all node pointers to a single sequence.
-
-.. ocv:cfunction:: CvSeq* cvTreeToNodeSeq( const void* first, int header_size, CvMemStorage* storage )
-
- :param first: The initial tree node
-
- :param header_size: Header size of the created sequence (sizeof(CvSeq) is the most frequently used value)
-
- :param storage: Container for the sequence
-
-The function puts pointers of all nodes reachable from ``first`` into a single sequence. The pointers are written sequentially in the depth-first order.
+++ /dev/null
-************
-Introduction
-************
-
-.. highlight:: cpp
-
-OpenCV (Open Source Computer Vision Library: http://opencv.org) is an open-source BSD-licensed library that includes several hundreds of computer vision algorithms. The document describes the so-called OpenCV 2.x API, which is essentially a C++ API, as opposite to the C-based OpenCV 1.x API. The latter is described in opencv1x.pdf.
-
-OpenCV has a modular structure, which means that the package includes several shared or static libraries. The following modules are available:
-
- * **core** - a compact module defining basic data structures, including the dense multi-dimensional array ``Mat`` and basic functions used by all other modules.
- * **imgproc** - an image processing module that includes linear and non-linear image filtering, geometrical image transformations (resize, affine and perspective warping, generic table-based remapping), color space conversion, histograms, and so on.
- * **video** - a video analysis module that includes motion estimation, background subtraction, and object tracking algorithms.
- * **calib3d** - basic multiple-view geometry algorithms, single and stereo camera calibration, object pose estimation, stereo correspondence algorithms, and elements of 3D reconstruction.
- * **features2d** - salient feature detectors, descriptors, and descriptor matchers.
- * **objdetect** - detection of objects and instances of the predefined classes (for example, faces, eyes, mugs, people, cars, and so on).
- * **highgui** - an easy-to-use interface to simple UI capabilities.
- * **videoio** - an easy-to-use interface to video capturing and video codecs.
- * **gpu** - GPU-accelerated algorithms from different OpenCV modules.
- * ... some other helper modules, such as FLANN and Google test wrappers, Python bindings, and others.
-
-The further chapters of the document describe functionality of each module. But first, make sure to get familiar with the common API concepts used thoroughly in the library.
-
-API Concepts
-================
-
-``cv`` Namespace
-------------------
-
-All the OpenCV classes and functions are placed into the ``cv`` namespace. Therefore, to access this functionality from your code, use the ``cv::`` specifier or ``using namespace cv;`` directive:
-
-.. code-block:: c
-
- #include "opencv2/core.hpp"
- ...
- cv::Mat H = cv::findHomography(points1, points2, CV_RANSAC, 5);
- ...
-
-or ::
-
- #include "opencv2/core.hpp"
- using namespace cv;
- ...
- Mat H = findHomography(points1, points2, CV_RANSAC, 5 );
- ...
-
-Some of the current or future OpenCV external names may conflict with STL
-or other libraries. In this case, use explicit namespace specifiers to resolve the name conflicts: ::
-
- Mat a(100, 100, CV_32F);
- randu(a, Scalar::all(1), Scalar::all(std::rand()));
- cv::log(a, a);
- a /= std::log(2.);
-
-Automatic Memory Management
----------------------------
-
-OpenCV handles all the memory automatically.
-
-First of all, ``std::vector``, ``Mat``, and other data structures used by the functions and methods have destructors that deallocate the underlying memory buffers when needed. This means that the destructors do not always deallocate the buffers as in case of ``Mat``. They take into account possible data sharing. A destructor decrements the reference counter associated with the matrix data buffer. The buffer is deallocated if and only if the reference counter reaches zero, that is, when no other structures refer to the same buffer. Similarly, when a ``Mat`` instance is copied, no actual data is really copied. Instead, the reference counter is incremented to memorize that there is another owner of the same data. There is also the ``Mat::clone`` method that creates a full copy of the matrix data. See the example below: ::
-
- // create a big 8Mb matrix
- Mat A(1000, 1000, CV_64F);
-
- // create another header for the same matrix;
- // this is an instant operation, regardless of the matrix size.
- Mat B = A;
- // create another header for the 3-rd row of A; no data is copied either
- Mat C = B.row(3);
- // now create a separate copy of the matrix
- Mat D = B.clone();
- // copy the 5-th row of B to C, that is, copy the 5-th row of A
- // to the 3-rd row of A.
- B.row(5).copyTo(C);
- // now let A and D share the data; after that the modified version
- // of A is still referenced by B and C.
- A = D;
- // now make B an empty matrix (which references no memory buffers),
- // but the modified version of A will still be referenced by C,
- // despite that C is just a single row of the original A
- B.release();
-
- // finally, make a full copy of C. As a result, the big modified
- // matrix will be deallocated, since it is not referenced by anyone
- C = C.clone();
-
-You see that the use of ``Mat`` and other basic structures is simple. But what about high-level classes or even user
-data types created without taking automatic memory management into account? For them, OpenCV offers the :ocv:class:`Ptr`
-template class that is similar to ``std::shared_ptr`` from C++11. So, instead of using plain pointers::
-
- T* ptr = new T(...);
-
-you can use::
-
- Ptr<T> ptr(new T(...));
-
-or::
-
- Ptr<T> ptr = makePtr<T>(...);
-
-``Ptr<T>`` encapsulates a pointer to a ``T`` instance and a reference counter associated with the pointer. See the
-:ocv:class:`Ptr` description for details.
-
-.. _AutomaticAllocation:
-
-Automatic Allocation of the Output Data
----------------------------------------
-
-OpenCV deallocates the memory automatically, as well as automatically allocates the memory for output function parameters most of the time. So, if a function has one or more input arrays (``cv::Mat`` instances) and some output arrays, the output arrays are automatically allocated or reallocated. The size and type of the output arrays are determined from the size and type of input arrays. If needed, the functions take extra parameters that help to figure out the output array properties.
-
-Example: ::
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
-
- using namespace cv;
-
- int main(int, char**)
- {
- VideoCapture cap(0);
- if(!cap.isOpened()) return -1;
-
- Mat frame, edges;
- namedWindow("edges",1);
- for(;;)
- {
- cap >> frame;
- cvtColor(frame, edges, COLOR_BGR2GRAY);
- GaussianBlur(edges, edges, Size(7,7), 1.5, 1.5);
- Canny(edges, edges, 0, 30, 3);
- imshow("edges", edges);
- if(waitKey(30) >= 0) break;
- }
- return 0;
- }
-
-The array ``frame`` is automatically allocated by the ``>>`` operator since the video frame resolution and the bit-depth is known to the video capturing module. The array ``edges`` is automatically allocated by the ``cvtColor`` function. It has the same size and the bit-depth as the input array. The number of channels is 1 because the color conversion code ``COLOR_BGR2GRAY`` is passed, which means a color to grayscale conversion. Note that ``frame`` and ``edges`` are allocated only once during the first execution of the loop body since all the next video frames have the same resolution. If you somehow change the video resolution, the arrays are automatically reallocated.
-
-The key component of this technology is the ``Mat::create`` method. It takes the desired array size and type. If the array already has the specified size and type, the method does nothing. Otherwise, it releases the previously allocated data, if any (this part involves decrementing the reference counter and comparing it with zero), and then allocates a new buffer of the required size. Most functions call the ``Mat::create`` method for each output array, and so the automatic output data allocation is implemented.
-
-Some notable exceptions from this scheme are ``cv::mixChannels``, ``cv::RNG::fill``, and a few other functions and methods. They are not able to allocate the output array, so you have to do this in advance.
-
-Saturation Arithmetics
-----------------------
-
-As a computer vision library, OpenCV deals a lot with image pixels that are often encoded in a compact, 8- or 16-bit per channel, form and thus have a limited value range. Furthermore, certain operations on images, like color space conversions, brightness/contrast adjustments, sharpening, complex interpolation (bi-cubic, Lanczos) can produce values out of the available range. If you just store the lowest 8 (16) bits of the result, this results in visual artifacts and may affect a further image analysis. To solve this problem, the so-called *saturation* arithmetics is used. For example, to store ``r``, the result of an operation, to an 8-bit image, you find the nearest value within the 0..255 range:
-
-.. math::
-
- I(x,y)= \min ( \max (\textrm{round}(r), 0), 255)
-
-Similar rules are applied to 8-bit signed, 16-bit signed and unsigned types. This semantics is used everywhere in the library. In C++ code, it is done using the ``saturate_cast<>`` functions that resemble standard C++ cast operations. See below the implementation of the formula provided above::
-
- I.at<uchar>(y, x) = saturate_cast<uchar>(r);
-
-where ``cv::uchar`` is an OpenCV 8-bit unsigned integer type. In the optimized SIMD code, such SSE2 instructions as ``paddusb``, ``packuswb``, and so on are used. They help achieve exactly the same behavior as in C++ code.
-
-.. note:: Saturation is not applied when the result is 32-bit integer.
-
-Fixed Pixel Types. Limited Use of Templates
--------------------------------------------
-
-Templates is a great feature of C++ that enables implementation of very powerful, efficient and yet safe data structures and algorithms. However, the extensive use of templates may dramatically increase compilation time and code size. Besides, it is difficult to separate an interface and implementation when templates are used exclusively. This could be fine for basic algorithms but not good for computer vision libraries where a single algorithm may span thousands lines of code. Because of this and also to simplify development of bindings for other languages, like Python, Java, Matlab that do not have templates at all or have limited template capabilities, the current OpenCV implementation is based on polymorphism and runtime dispatching over templates. In those places where runtime dispatching would be too slow (like pixel access operators), impossible (generic ``Ptr<>`` implementation), or just very inconvenient (``saturate_cast<>()``) the current implementation introduces small template classes, methods, and functions. Anywhere else in the current OpenCV version the use of templates is limited.
-
-Consequently, there is a limited fixed set of primitive data types the library can operate on. That is, array elements should have one of the following types:
-
- * 8-bit unsigned integer (uchar)
- * 8-bit signed integer (schar)
- * 16-bit unsigned integer (ushort)
- * 16-bit signed integer (short)
- * 32-bit signed integer (int)
- * 32-bit floating-point number (float)
- * 64-bit floating-point number (double)
- * a tuple of several elements where all elements have the same type (one of the above). An array whose elements are such tuples, are called multi-channel arrays, as opposite to the single-channel arrays, whose elements are scalar values. The maximum possible number of channels is defined by the ``CV_CN_MAX`` constant, which is currently set to 512.
-
-For these basic types, the following enumeration is applied::
-
- enum { CV_8U=0, CV_8S=1, CV_16U=2, CV_16S=3, CV_32S=4, CV_32F=5, CV_64F=6 };
-
-Multi-channel (``n``-channel) types can be specified using the following options:
-
-* ``CV_8UC1`` ... ``CV_64FC4`` constants (for a number of channels from 1 to 4)
-* ``CV_8UC(n)`` ... ``CV_64FC(n)`` or ``CV_MAKETYPE(CV_8U, n)`` ... ``CV_MAKETYPE(CV_64F, n)`` macros when the number of channels is more than 4 or unknown at the compilation time.
-
-.. note:: ``CV_32FC1 == CV_32F``, ``CV_32FC2 == CV_32FC(2) == CV_MAKETYPE(CV_32F, 2)``, and ``CV_MAKETYPE(depth, n) == ((x&7)<<3) + (n-1)``. This means that the constant type is formed from the ``depth``, taking the lowest 3 bits, and the number of channels minus 1, taking the next ``log2(CV_CN_MAX)`` bits.
-
-Examples: ::
-
- Mat mtx(3, 3, CV_32F); // make a 3x3 floating-point matrix
- Mat cmtx(10, 1, CV_64FC2); // make a 10x1 2-channel floating-point
- // matrix (10-element complex vector)
- Mat img(Size(1920, 1080), CV_8UC3); // make a 3-channel (color) image
- // of 1920 columns and 1080 rows.
- Mat grayscale(image.size(), CV_MAKETYPE(image.depth(), 1)); // make a 1-channel image of
- // the same size and same
- // channel type as img
-
-Arrays with more complex elements cannot be constructed or processed using OpenCV. Furthermore, each function or method can handle only a subset of all possible array types. Usually, the more complex the algorithm is, the smaller the supported subset of formats is. See below typical examples of such limitations:
-
- * The face detection algorithm only works with 8-bit grayscale or color images.
- * Linear algebra functions and most of the machine learning algorithms work with floating-point arrays only.
- * Basic functions, such as ``cv::add``, support all types.
- * Color space conversion functions support 8-bit unsigned, 16-bit unsigned, and 32-bit floating-point types.
-
-The subset of supported types for each function has been defined from practical needs and could be extended in future based on user requests.
-
-
-InputArray and OutputArray
---------------------------
-
-Many OpenCV functions process dense 2-dimensional or multi-dimensional numerical arrays. Usually, such functions take cpp:class:`Mat` as parameters, but in some cases it's more convenient to use ``std::vector<>`` (for a point set, for example) or ``Matx<>`` (for 3x3 homography matrix and such). To avoid many duplicates in the API, special "proxy" classes have been introduced. The base "proxy" class is ``InputArray``. It is used for passing read-only arrays on a function input. The derived from ``InputArray`` class ``OutputArray`` is used to specify an output array for a function. Normally, you should not care of those intermediate types (and you should not declare variables of those types explicitly) - it will all just work automatically. You can assume that instead of ``InputArray``/``OutputArray`` you can always use ``Mat``, ``std::vector<>``, ``Matx<>``, ``Vec<>`` or ``Scalar``. When a function has an optional input or output array, and you do not have or do not want one, pass ``cv::noArray()``.
-
-Error Handling
---------------
-
-OpenCV uses exceptions to signal critical errors. When the input data has a correct format and belongs to the specified value range, but the algorithm cannot succeed for some reason (for example, the optimization algorithm did not converge), it returns a special error code (typically, just a boolean variable).
-
-The exceptions can be instances of the ``cv::Exception`` class or its derivatives. In its turn, ``cv::Exception`` is a derivative of ``std::exception``. So it can be gracefully handled in the code using other standard C++ library components.
-
-The exception is typically thrown either using the ``CV_Error(errcode, description)`` macro, or its printf-like ``CV_Error_(errcode, printf-spec, (printf-args))`` variant, or using the ``CV_Assert(condition)`` macro that checks the condition and throws an exception when it is not satisfied. For performance-critical code, there is ``CV_DbgAssert(condition)`` that is only retained in the Debug configuration. Due to the automatic memory management, all the intermediate buffers are automatically deallocated in case of a sudden error. You only need to add a try statement to catch exceptions, if needed: ::
-
- try
- {
- ... // call OpenCV
- }
- catch( cv::Exception& e )
- {
- const char* err_msg = e.what();
- std::cout << "exception caught: " << err_msg << std::endl;
- }
-
-Multi-threading and Re-enterability
------------------------------------
-
-The current OpenCV implementation is fully re-enterable. That is, the same function, the same *constant* method of a class instance, or the same *non-constant* method of different class instances can be called from different threads. Also, the same ``cv::Mat`` can be used in different threads because the reference-counting operations use the architecture-specific atomic instructions.
+++ /dev/null
-Intel® IPP Asynchronous C/C++ Converters
-========================================
-
-.. highlight:: cpp
-
-General Information
--------------------
-
-This section describes conversion between OpenCV and `Intel® IPP Asynchronous C/C++ <http://software.intel.com/en-us/intel-ipp-preview>`_ library.
-`Getting Started Guide <http://registrationcenter.intel.com/irc_nas/3727/ipp_async_get_started.htm>`_ help you to install the library, configure header and library build paths.
-
-hpp::getHpp
------------
-Create ``hppiMatrix`` from ``Mat``.
-
-.. ocv:function:: hppiMatrix* hpp::getHpp(const Mat& src, hppAccel accel)
-
- :param src: input matrix.
- :param accel: accelerator instance. Supports type:
-
- * **HPP_ACCEL_TYPE_CPU** - accelerated by optimized CPU instructions.
-
- * **HPP_ACCEL_TYPE_GPU** - accelerated by GPU programmable units or fixed-function accelerators.
-
- * **HPP_ACCEL_TYPE_ANY** - any acceleration or no acceleration available.
-
-This function allocates and initializes the ``hppiMatrix`` that has the same size and type as input matrix, returns the ``hppiMatrix*``.
-
-If you want to use zero-copy for GPU you should to have 4KB aligned matrix data. See details `hppiCreateSharedMatrix <http://software.intel.com/ru-ru/node/501697>`_.
-
-Supports ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32S``, ``CV_32F``, ``CV_64F``.
-
-.. note:: The ``hppiMatrix`` pointer to the image buffer in system memory refers to the ``src.data``. Control the lifetime of the matrix and don't change its data, if there is no special need.
-.. seealso:: :ref:`howToUseIPPAconversion`, :ocv:func:`hpp::getMat`
-
-
-hpp::getMat
------------
-Create ``Mat`` from ``hppiMatrix``.
-
-.. ocv:function:: Mat hpp::getMat(hppiMatrix* src, hppAccel accel, int cn)
-
- :param src: input hppiMatrix.
-
- :param accel: accelerator instance (see :ocv:func:`hpp::getHpp` for the list of acceleration framework types).
-
- :param cn: number of channels.
-
-This function allocates and initializes the ``Mat`` that has the same size and type as input matrix.
-Supports ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32S``, ``CV_32F``, ``CV_64F``.
-
-.. seealso:: :ref:`howToUseIPPAconversion`, :ocv:func:`hpp::copyHppToMat`, :ocv:func:`hpp::getHpp`.
-
-
-hpp::copyHppToMat
------------------
-Convert ``hppiMatrix`` to ``Mat``.
-
-.. ocv:function:: void hpp::copyHppToMat(hppiMatrix* src, Mat& dst, hppAccel accel, int cn)
-
- :param src: input hppiMatrix.
-
- :param dst: output matrix.
-
- :param accel: accelerator instance (see :ocv:func:`hpp::getHpp` for the list of acceleration framework types).
-
- :param cn: number of channels.
-
-This function allocates and initializes new matrix (if needed) that has the same size and type as input matrix.
-Supports ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32S``, ``CV_32F``, ``CV_64F``.
-
-.. seealso:: :ref:`howToUseIPPAconversion`, :ocv:func:`hpp::getMat`, :ocv:func:`hpp::getHpp`.
\ No newline at end of file
+++ /dev/null
-Basic C Structures and Operations
-=================================
-
-.. highlight:: c
-
-The section describes the main data structures, used by the OpenCV 1.x API, and the basic functions to create and process the data structures.
-
-CvPoint
--------
-.. ocv:cfunction:: CvPoint cvPoint( int x, int y )
-
- constructs ``CvPoint`` structure.
-
-.. ocv:cfunction:: CvPoint cvPointFrom32f( CvPoint2D32f point )
-
- converts ``CvPoint2D32f`` to ``CvPoint``.
-
-.. ocv:struct:: CvPoint
-
- 2D point with integer coordinates (usually zero-based).
-
- :param x: x-coordinate of the point.
-
- :param y: y-coordinate of the point.
-
- :param point: the point to convert.
-
-.. seealso:: :ocv:class:`Point\_`
-
-CvPoint2D32f
-------------
-
-.. ocv:cfunction:: CvPoint2D32f cvPoint2D32f( double x, double y )
-
- constructs ``CvPoint2D32f`` structure.
-
-.. ocv:cfunction:: CvPoint2D32f cvPointTo32f( CvPoint point )
-
- converts ``CvPoint`` to ``CvPoint2D32f``.
-
-.. ocv:struct:: CvPoint2D32f
-
- 2D point with floating-point coordinates.
-
- :param x: floating-point x-coordinate of the point.
-
- :param y: floating-point y-coordinate of the point.
-
- :param point: the point to convert.
-
-.. seealso:: :ocv:class:`Point\_`
-
-CvPoint3D32f
-------------
-
-.. ocv:struct:: CvPoint3D32f
-
- 3D point with floating-point coordinates
-
-.. ocv:cfunction:: CvPoint3D32f cvPoint3D32f( double x, double y, double z )
-
- constructs ``CvPoint3D32f`` structure.
-
- :param x: floating-point x-coordinate of the point.
-
- :param y: floating-point y-coordinate of the point.
-
- :param z: floating-point z-coordinate of the point.
-
-.. seealso:: :ocv:class:`Point3\_`
-
-CvPoint2D64f
-------------
-
-.. ocv:struct:: CvPoint2D64f
-
- 2D point with double-precision floating-point coordinates.
-
-.. ocv:cfunction:: CvPoint2D64f cvPoint2D64f( double x, double y )
-
- constructs ``CvPoint2D64f`` structure.
-
- :param x: double-precision floating-point x-coordinate of the point.
-
- :param y: double-precision floating-point y-coordinate of the point.
-
-.. seealso:: :ocv:class:`Point\_`
-
-CvPoint3D64f
-------------
-
-.. ocv:struct:: CvPoint3D64f
-
- 3D point with double-precision floating-point coordinates.
-
-.. ocv:cfunction:: CvPoint3D64f cvPoint3D64f( double x, double y, double z )
-
- constructs ``CvPoint3D64f`` structure.
-
- :param x: double-precision floating-point x-coordinate of the point.
-
- :param y: double-precision floating-point y-coordinate of the point.
-
- :param z: double-precision floating-point z-coordinate of the point.
-
-.. seealso:: :ocv:class:`Point3\_`
-
-CvSize
-------
-
-.. ocv:struct:: CvSize
-
- Size of a rectangle or an image.
-
-.. ocv:cfunction:: CvSize cvSize( int width, int height )
-
- constructs ``CvSize`` structure.
-
- :param width: width of the rectangle.
-
- :param height: height of the rectangle.
-
-.. seealso:: :ocv:class:`Size\_`
-
-CvSize2D32f
------------
-
-.. ocv:struct:: CvSize2D32f
-
- Sub-pixel accurate size of a rectangle.
-
-.. ocv:cfunction:: CvSize2D32f cvSize2D32f( double width, double height )
-
- constructs ``CvSize2D32f`` structure.
-
- :param width: floating-point width of the rectangle.
-
- :param height: floating-point height of the rectangle.
-
-.. seealso:: :ocv:class:`Size\_`
-
-CvRect
-------
-
-.. ocv:struct:: CvRect
-
- Stores coordinates of a rectangle.
-
-.. ocv:cfunction:: CvRect cvRect( int x, int y, int width, int height )
-
- constructs ``CvRect`` structure.
-
- :param x: x-coordinate of the top-left corner.
-
- :param y: y-coordinate of the top-left corner (sometimes bottom-left corner).
-
- :param width: width of the rectangle.
-
- :param height: height of the rectangle.
-
-.. seealso:: :ocv:class:`Rect\_`
-
-
-CvBox2D
--------
-
-.. ocv:struct:: CvBox2D
-
- Stores coordinates of a rotated rectangle.
-
- .. ocv:member:: CvPoint2D32f center
-
- Center of the box
-
- .. ocv:member:: CvSize2D32f size
-
- Box width and height
-
- .. ocv:member:: float angle
-
- Angle between the horizontal axis and the first side (i.e. length) in degrees
-
-.. seealso:: :ocv:class:`RotatedRect`
-
-
-CvScalar
---------
-
-.. ocv:struct:: CvScalar
-
- A container for 1-,2-,3- or 4-tuples of doubles.
-
- .. ocv:member:: double[4] val
-
-.. ocv::cfunction:: CvScalar cvScalar( double val0, double val1=0, double val2=0, double val3=0 )
-
- initializes val[0] with val0, val[1] with val1, val[2] with val2 and val[3] with val3.
-
-.. ocv::cfunction:: CvScalar cvScalarAll( double val0123 )
-
- initializes all of val[0]...val[3] with val0123
-
-.. ocv::cfunction:: CvScalar cvRealScalar( double val0 )
-
- initializes val[0] with val0, val[1], val[2] and val[3] with 0.
-
-.. seealso:: :ocv:class:`Scalar\_`
-
-CvTermCriteria
---------------
-
-.. ocv:struct:: CvTermCriteria
-
- Termination criteria for iterative algorithms.
-
- .. ocv:member:: int type
-
- type of the termination criteria, one of:
-
- * ``CV_TERMCRIT_ITER`` - stop the algorithm after ``max_iter`` iterations at maximum.
-
- * ``CV_TERMCRIT_EPS`` - stop the algorithm after the achieved algorithm-dependent accuracy becomes lower than ``epsilon``.
-
- * ``CV_TERMCRIT_ITER+CV_TERMCRIT_EPS`` - stop the algorithm after ``max_iter`` iterations or when the achieved accuracy is lower than ``epsilon``, whichever comes the earliest.
-
- .. ocv:member:: int max_iter
-
- Maximum number of iterations
-
- .. ocv:member:: double epsilon
-
- Required accuracy
-
-.. seealso:: :ocv:class:`TermCriteria`
-
-CvMat
------
-
-.. ocv:struct:: CvMat
-
- A multi-channel dense matrix.
-
- .. ocv:member:: int type
-
- ``CvMat`` signature (``CV_MAT_MAGIC_VAL``) plus type of the elements. Type of the matrix elements can be retrieved using ``CV_MAT_TYPE`` macro: ::
-
- int type = CV_MAT_TYPE(matrix->type);
-
- For description of possible matrix elements, see :ocv:class:`Mat`.
-
- .. ocv:member:: int step
-
- Full row length in bytes
-
- .. ocv:member:: int* refcount
-
- Underlying data reference counter
-
- .. ocv:member:: union data
-
- Pointers to the actual matrix data:
-
- * ptr - pointer to 8-bit unsigned elements
- * s - pointer to 16-bit signed elements
- * i - pointer to 32-bit signed elements
- * fl - pointer to 32-bit floating-point elements
- * db - pointer to 64-bit floating-point elements
-
- .. ocv:member:: int rows
-
- Number of rows
-
- .. ocv:member:: int cols
-
- Number of columns
-
-Matrix elements are stored row by row. Element (i, j) (i - 0-based row index, j - 0-based column index) of a matrix can be retrieved or modified using ``CV_MAT_ELEM`` macro: ::
-
- uchar pixval = CV_MAT_ELEM(grayimg, uchar, i, j)
- CV_MAT_ELEM(cameraMatrix, float, 0, 2) = image.width*0.5f;
-
-To access multiple-channel matrices, you can use ``CV_MAT_ELEM(matrix, type, i, j*nchannels + channel_idx)``.
-
-``CvMat`` is now obsolete; consider using :ocv:class:`Mat` instead.
-
-CvMatND
--------
-
-.. ocv:struct:: CvMatND
-
- Multi-dimensional dense multi-channel array.
-
- .. ocv:member:: int type
-
- A ``CvMatND`` signature (``CV_MATND_MAGIC_VAL``) plus the type of elements. Type of the matrix elements can be retrieved using ``CV_MAT_TYPE`` macro: ::
-
- int type = CV_MAT_TYPE(ndmatrix->type);
-
- .. ocv:member:: int dims
-
- The number of array dimensions
-
- .. ocv:member:: int* refcount
-
- Underlying data reference counter
-
- .. ocv:member:: union data
-
- Pointers to the actual matrix data
-
- * ptr - pointer to 8-bit unsigned elements
- * s - pointer to 16-bit signed elements
- * i - pointer to 32-bit signed elements
- * fl - pointer to 32-bit floating-point elements
- * db - pointer to 64-bit floating-point elements
-
- .. ocv:member:: array dim
-
- Arrays of pairs (array size along the i-th dimension, distance between neighbor elements along i-th dimension): ::
-
- for(int i = 0; i < ndmatrix->dims; i++)
- printf("size[i] = %d, step[i] = %d\n", ndmatrix->dim[i].size, ndmatrix->dim[i].step);
-
-``CvMatND`` is now obsolete; consider using :ocv:class:`Mat` instead.
-
-CvSparseMat
------------
-
-.. ocv:struct:: CvSparseMat
-
- Multi-dimensional sparse multi-channel array.
-
- .. ocv:member:: int type
-
- A ``CvSparseMat`` signature (CV_SPARSE_MAT_MAGIC_VAL) plus the type of sparse matrix elements. Similarly to ``CvMat`` and ``CvMatND``, use ``CV_MAT_TYPE()`` to retrieve type of the elements.
-
- .. ocv:member:: int dims
-
- Number of dimensions
-
- .. ocv:member:: int* refcount
-
- Underlying reference counter. Not used.
-
- .. ocv:member:: CvSet* heap
-
- A pool of hash table nodes
-
- .. ocv:member:: void** hashtable
-
- The hash table. Each entry is a list of nodes.
-
- .. ocv:member:: int hashsize
-
- Size of the hash table
-
- .. ocv:member:: int[] size
-
- Array of dimension sizes
-
-IplImage
---------
-
-.. ocv:struct:: IplImage
-
- IPL image header
-
- .. ocv:member:: int nSize
-
- ``sizeof(IplImage)``
-
- .. ocv:member:: int ID
-
- Version, always equals 0
-
- .. ocv:member:: int nChannels
-
- Number of channels. Most OpenCV functions support 1-4 channels.
-
- .. ocv:member:: int alphaChannel
-
- Ignored by OpenCV
-
- .. ocv:member:: int depth
-
- Channel depth in bits + the optional sign bit ( ``IPL_DEPTH_SIGN`` ). The supported depths are:
-
- * ``IPL_DEPTH_8U`` - unsigned 8-bit integer. Equivalent to ``CV_8U`` in matrix types.
- * ``IPL_DEPTH_8S`` - signed 8-bit integer. Equivalent to ``CV_8S`` in matrix types.
- * ``IPL_DEPTH_16U`` - unsigned 16-bit integer. Equivalent to ``CV_16U`` in matrix types.
- * ``IPL_DEPTH_16S`` - signed 8-bit integer. Equivalent to ``CV_16S`` in matrix types.
- * ``IPL_DEPTH_32S`` - signed 32-bit integer. Equivalent to ``CV_32S`` in matrix types.
- * ``IPL_DEPTH_32F`` - single-precision floating-point number. Equivalent to ``CV_32F`` in matrix types.
- * ``IPL_DEPTH_64F`` - double-precision floating-point number. Equivalent to ``CV_64F`` in matrix types.
-
- .. ocv:member:: char[] colorModel
-
- Ignored by OpenCV.
-
- .. ocv:member:: char[] channelSeq
-
- Ignored by OpenCV
-
- .. ocv:member:: int dataOrder
-
- 0 = ``IPL_DATA_ORDER_PIXEL`` - interleaved color channels, 1 - separate color channels. :ocv:cfunc:`CreateImage` only creates images with interleaved channels. For example, the usual layout of a color image is: :math:`b_{00} g_{00} r_{00} b_{10} g_{10} r_{10} ...`
-
- .. ocv:member:: int origin
-
- 0 - top-left origin, 1 - bottom-left origin (Windows bitmap style)
-
- .. ocv:member:: int align
-
- Alignment of image rows (4 or 8). OpenCV ignores this and uses widthStep instead.
-
- .. ocv:member:: int width
-
- Image width in pixels
-
- .. ocv:member:: int height
-
- Image height in pixels
-
- .. ocv:member:: IplROI* roi
-
- Region Of Interest (ROI). If not NULL, only this image region will be processed.
-
- .. ocv:member:: IplImage* maskROI
-
- Must be NULL in OpenCV
-
- .. ocv:member:: void* imageId
-
- Must be NULL in OpenCV
-
- .. ocv:member:: void* tileInfo
-
- Must be NULL in OpenCV
-
- .. ocv:member:: int imageSize
-
- Image data size in bytes. For interleaved data, this equals :math:`\texttt{image->height} \cdot \texttt{image->widthStep}`
-
- .. ocv:member:: char* imageData
-
- A pointer to the aligned image data. Do not assign imageData directly. Use :ocv:cfunc:`SetData`.
-
- .. ocv:member:: int widthStep
-
- The size of an aligned image row, in bytes.
-
- .. ocv:member:: int[] BorderMode
-
- Border completion mode, ignored by OpenCV
-
- .. ocv:member:: int[] BorderConst
-
- Constant border value, ignored by OpenCV
-
- .. ocv:member:: char* imageDataOrigin
-
- A pointer to the origin of the image data (not necessarily aligned). This is used for image deallocation.
-
-The ``IplImage`` is taken from the Intel Image Processing Library, in which the format is native. OpenCV only supports a subset of possible ``IplImage`` formats, as outlined in the parameter list above.
-
-In addition to the above restrictions, OpenCV handles ROIs differently. OpenCV functions require that the image size or ROI size of all source and destination images match exactly. On the other hand, the Intel Image Processing Library processes the area of intersection between the source and destination images (or ROIs), allowing them to vary independently.
-
-CvArr
------
-
-.. ocv:struct:: CvArr
-
-This is the "metatype" used *only* as a function parameter. It denotes that the function accepts arrays of multiple types, such as IplImage*, CvMat* or even CvSeq* sometimes. The particular array type is determined at runtime by analyzing the first 4 bytes of the header. In C++ interface the role of ``CvArr`` is played by ``InputArray`` and ``OutputArray``.
-
-ClearND
--------
-Clears a specific array element.
-
-.. ocv:cfunction:: void cvClearND( CvArr* arr, const int* idx )
-
- :param arr: Input array
- :param idx: Array of the element indices
-
-The function clears (sets to zero) a specific element of a dense array or deletes the element of a sparse array. If the sparse array element does not exists, the function does nothing.
-
-CloneImage
-----------
-Makes a full copy of an image, including the header, data, and ROI.
-
-.. ocv:cfunction:: IplImage* cvCloneImage(const IplImage* image)
-
- :param image: The original image
-
-CloneMat
---------
-Creates a full matrix copy.
-
-.. ocv:cfunction:: CvMat* cvCloneMat(const CvMat* mat)
-
- :param mat: Matrix to be copied
-
-Creates a full copy of a matrix and returns a pointer to the copy. Note that the matrix copy is compacted, that is, it will not have gaps between rows.
-
-CloneMatND
-----------
-Creates full copy of a multi-dimensional array and returns a pointer to the copy.
-
-.. ocv:cfunction:: CvMatND* cvCloneMatND(const CvMatND* mat)
-
- :param mat: Input array
-
-CloneSparseMat
---------------
-Creates full copy of sparse array.
-
-.. ocv:cfunction:: CvSparseMat* cvCloneSparseMat(const CvSparseMat* mat)
-
- :param mat: Input array
-
-The function creates a copy of the input array and returns pointer to the copy.
-
-
-ConvertScale
-------------
-Converts one array to another with optional linear transformation.
-
-.. ocv:cfunction:: void cvConvertScale(const CvArr* src, CvArr* dst, double scale=1, double shift=0)
-
- ::
-
- #define cvCvtScale cvConvertScale
- #define cvScale cvConvertScale
- #define cvConvert(src, dst ) cvConvertScale((src), (dst), 1, 0 )
-
- ..
-
- :param src: Source array
-
- :param dst: Destination array
-
- :param scale: Scale factor
-
- :param shift: Value added to the scaled source array elements
-
-The function has several different purposes, and thus has several different names. It copies one array to another with optional scaling, which is performed first, and/or optional type conversion, performed after:
-
-.. math::
-
- \texttt{dst} (I) = \texttt{scale} \texttt{src} (I) + ( \texttt{shift} _0, \texttt{shift} _1,...)
-
-
-All the channels of multi-channel arrays are processed independently.
-
-The type of conversion is done with rounding and saturation, that is if the
-result of scaling + conversion can not be represented exactly by a value
-of the destination array element type, it is set to the nearest representable
-value on the real axis.
-
-
-Copy
-----
-Copies one array to another.
-
-.. ocv:cfunction:: void cvCopy(const CvArr* src, CvArr* dst, const CvArr* mask=NULL)
-
- :param src: The source array
-
- :param dst: The destination array
-
- :param mask: Operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
-
-The function copies selected elements from an input array to an output array:
-
-.. math::
-
- \texttt{dst} (I)= \texttt{src} (I) \quad \text{if} \quad \texttt{mask} (I) \ne 0.
-
-If any of the passed arrays is of ``IplImage`` type, then its ROI and COI fields are used. Both arrays must have the same type, the same number of dimensions, and the same size. The function can also copy sparse arrays (mask is not supported in this case).
-
-
-CreateData
-----------
-Allocates array data
-
-.. ocv:cfunction:: void cvCreateData(CvArr* arr)
-
- :param arr: Array header
-
-The function allocates image, matrix or multi-dimensional dense array data. Note that in the case of matrix types OpenCV allocation functions are used. In the case of IplImage they are used
-unless ``CV_TURN_ON_IPL_COMPATIBILITY()`` has been called before. In the latter case IPL functions are used to allocate the data.
-
-CreateImage
------------
-Creates an image header and allocates the image data.
-
-.. ocv:cfunction:: IplImage* cvCreateImage(CvSize size, int depth, int channels)
-
- :param size: Image width and height
-
- :param depth: Bit depth of image elements. See :ocv:struct:`IplImage` for valid depths.
-
- :param channels: Number of channels per pixel. See :ocv:struct:`IplImage` for details. This function only creates images with interleaved channels.
-
-This function call is equivalent to the following code: ::
-
- header = cvCreateImageHeader(size, depth, channels);
- cvCreateData(header);
-
-CreateImageHeader
------------------
-Creates an image header but does not allocate the image data.
-
-.. ocv:cfunction:: IplImage* cvCreateImageHeader(CvSize size, int depth, int channels)
-
- :param size: Image width and height
-
- :param depth: Image depth (see :ocv:cfunc:`CreateImage` )
-
- :param channels: Number of channels (see :ocv:cfunc:`CreateImage` )
-
-CreateMat
----------
-Creates a matrix header and allocates the matrix data.
-
-.. ocv:cfunction:: CvMat* cvCreateMat( int rows, int cols, int type)
-
- :param rows: Number of rows in the matrix
-
- :param cols: Number of columns in the matrix
-
- :param type: The type of the matrix elements in the form ``CV_<bit depth><S|U|F>C<number of channels>`` , where S=signed, U=unsigned, F=float. For example, CV _ 8UC1 means the elements are 8-bit unsigned and the there is 1 channel, and CV _ 32SC2 means the elements are 32-bit signed and there are 2 channels.
-
-The function call is equivalent to the following code: ::
-
- CvMat* mat = cvCreateMatHeader(rows, cols, type);
- cvCreateData(mat);
-
-CreateMatHeader
----------------
-Creates a matrix header but does not allocate the matrix data.
-
-.. ocv:cfunction:: CvMat* cvCreateMatHeader( int rows, int cols, int type)
-
- :param rows: Number of rows in the matrix
-
- :param cols: Number of columns in the matrix
-
- :param type: Type of the matrix elements, see :ocv:cfunc:`CreateMat`
-
-The function allocates a new matrix header and returns a pointer to it. The matrix data can then be allocated using :ocv:cfunc:`CreateData` or set explicitly to user-allocated data via :ocv:cfunc:`SetData`.
-
-CreateMatND
------------
-Creates the header and allocates the data for a multi-dimensional dense array.
-
-.. ocv:cfunction:: CvMatND* cvCreateMatND( int dims, const int* sizes, int type)
-
- :param dims: Number of array dimensions. This must not exceed CV_MAX_DIM (32 by default, but can be changed at build time).
-
- :param sizes: Array of dimension sizes.
-
- :param type: Type of array elements, see :ocv:cfunc:`CreateMat` .
-
-This function call is equivalent to the following code: ::
-
- CvMatND* mat = cvCreateMatNDHeader(dims, sizes, type);
- cvCreateData(mat);
-
-CreateMatNDHeader
------------------
-Creates a new matrix header but does not allocate the matrix data.
-
-.. ocv:cfunction:: CvMatND* cvCreateMatNDHeader( int dims, const int* sizes, int type)
-
- :param dims: Number of array dimensions
-
- :param sizes: Array of dimension sizes
-
- :param type: Type of array elements, see :ocv:cfunc:`CreateMat`
-
-The function allocates a header for a multi-dimensional dense array. The array data can further be allocated using :ocv:cfunc:`CreateData` or set explicitly to user-allocated data via :ocv:cfunc:`SetData`.
-
-CreateSparseMat
----------------
-Creates sparse array.
-
-.. ocv:cfunction:: CvSparseMat* cvCreateSparseMat(int dims, const int* sizes, int type)
-
- :param dims: Number of array dimensions. In contrast to the dense matrix, the number of dimensions is practically unlimited (up to :math:`2^{16}` ).
-
- :param sizes: Array of dimension sizes
-
- :param type: Type of array elements. The same as for CvMat
-
-The function allocates a multi-dimensional sparse array. Initially the array contain no elements, that is
-:ocv:cfunc:`PtrND` and other related functions will return 0 for every index.
-
-
-CrossProduct
-------------
-Calculates the cross product of two 3D vectors.
-
-.. ocv:cfunction:: void cvCrossProduct(const CvArr* src1, const CvArr* src2, CvArr* dst)
-
- :param src1: The first source vector
-
- :param src2: The second source vector
-
- :param dst: The destination vector
-
-The function calculates the cross product of two 3D vectors:
-
-.. math::
-
- \texttt{dst} = \texttt{src1} \times \texttt{src2}
-
-or:
-
-.. math::
-
- \begin{array}{l} \texttt{dst} _1 = \texttt{src1} _2 \texttt{src2} _3 - \texttt{src1} _3 \texttt{src2} _2 \\ \texttt{dst} _2 = \texttt{src1} _3 \texttt{src2} _1 - \texttt{src1} _1 \texttt{src2} _3 \\ \texttt{dst} _3 = \texttt{src1} _1 \texttt{src2} _2 - \texttt{src1} _2 \texttt{src2} _1 \end{array}
-
-
-DotProduct
-----------
-Calculates the dot product of two arrays in Euclidean metrics.
-
-.. ocv:cfunction:: double cvDotProduct(const CvArr* src1, const CvArr* src2)
-
- :param src1: The first source array
-
- :param src2: The second source array
-
-The function calculates and returns the Euclidean dot product of two arrays.
-
-.. math::
-
- src1 \bullet src2 = \sum _I ( \texttt{src1} (I) \texttt{src2} (I))
-
-In the case of multiple channel arrays, the results for all channels are accumulated. In particular,
-``cvDotProduct(a,a)`` where ``a`` is a complex vector, will return :math:`||\texttt{a}||^2`.
-The function can process multi-dimensional arrays, row by row, layer by layer, and so on.
-
-
-Get?D
------
-
-.. ocv:cfunction:: CvScalar cvGet1D(const CvArr* arr, int idx0)
-.. ocv:cfunction:: CvScalar cvGet2D(const CvArr* arr, int idx0, int idx1)
-.. ocv:cfunction:: CvScalar cvGet3D(const CvArr* arr, int idx0, int idx1, int idx2)
-.. ocv:cfunction:: CvScalar cvGetND( const CvArr* arr, const int* idx )
-
- Return a specific array element.
-
- :param arr: Input array
-
- :param idx0: The first zero-based component of the element index
-
- :param idx1: The second zero-based component of the element index
-
- :param idx2: The third zero-based component of the element index
-
- :param idx: Array of the element indices
-
-The functions return a specific array element. In the case of a sparse array the functions return 0 if the requested node does not exist (no new node is created by the functions).
-
-GetCol(s)
----------
-Returns one of more array columns.
-
-.. ocv:cfunction:: CvMat* cvGetCol(const CvArr* arr, CvMat* submat, int col)
-
-.. ocv:cfunction:: CvMat* cvGetCols( const CvArr* arr, CvMat* submat, int start_col, int end_col )
-
- :param arr: Input array
-
- :param submat: Pointer to the resulting sub-array header
-
- :param col: Zero-based index of the selected column
-
- :param start_col: Zero-based index of the starting column (inclusive) of the span
-
- :param end_col: Zero-based index of the ending column (exclusive) of the span
-
-The functions return the header, corresponding to a specified column span of the input array. That is, no data is copied. Therefore, any modifications of the submatrix will affect the original array. If you need to copy the columns, use :ocv:cfunc:`CloneMat`. ``cvGetCol(arr, submat, col)`` is a shortcut for ``cvGetCols(arr, submat, col, col+1)``.
-
-GetDiag
--------
-Returns one of array diagonals.
-
-.. ocv:cfunction:: CvMat* cvGetDiag(const CvArr* arr, CvMat* submat, int diag=0)
-
- :param arr: Input array
-
- :param submat: Pointer to the resulting sub-array header
-
- :param diag: Index of the array diagonal. Zero value corresponds to the main diagonal, -1 corresponds to the diagonal above the main, 1 corresponds to the diagonal below the main, and so forth.
-
-The function returns the header, corresponding to a specified diagonal of the input array.
-
-GetDims
--------
-Return number of array dimensions
-
-.. ocv:cfunction:: int cvGetDims(const CvArr* arr, int* sizes=NULL)
-
- :param arr: Input array
-
- :param sizes: Optional output vector of the array dimension sizes. For
- 2d arrays the number of rows (height) goes first, number of columns
- (width) next.
-
-The function returns the array dimensionality and the array of dimension sizes. In the case of ``IplImage`` or `CvMat` it always returns 2 regardless of number of image/matrix rows. For example, the following code calculates total number of array elements: ::
-
- int sizes[CV_MAX_DIM];
- int i, total = 1;
- int dims = cvGetDims(arr, size);
- for(i = 0; i < dims; i++ )
- total *= sizes[i];
-
-GetDimSize
-----------
-Returns array size along the specified dimension.
-
-.. ocv:cfunction:: int cvGetDimSize(const CvArr* arr, int index)
-
- :param arr: Input array
-
- :param index: Zero-based dimension index (for matrices 0 means number of rows, 1 means number of columns; for images 0 means height, 1 means width)
-
-GetElemType
------------
-Returns type of array elements.
-
-.. ocv:cfunction:: int cvGetElemType(const CvArr* arr)
-
- :param arr: Input array
-
-The function returns type of the array elements. In the case of ``IplImage`` the type is converted to ``CvMat``-like representation. For example, if the image has been created as: ::
-
- IplImage* img = cvCreateImage(cvSize(640, 480), IPL_DEPTH_8U, 3);
-
-The code ``cvGetElemType(img)`` will return ``CV_8UC3``.
-
-GetImage
---------
-Returns image header for arbitrary array.
-
-.. ocv:cfunction:: IplImage* cvGetImage( const CvArr* arr, IplImage* image_header )
-
- :param arr: Input array
-
- :param image_header: Pointer to ``IplImage`` structure used as a temporary buffer
-
-The function returns the image header for the input array that can be a matrix (:ocv:struct:`CvMat`) or image (:ocv:struct:`IplImage`). In the case of an image the function simply returns the input pointer. In the case of ``CvMat`` it initializes an ``image_header`` structure with the parameters of the input matrix. Note that if we transform ``IplImage`` to ``CvMat`` using :ocv:cfunc:`GetMat` and then transform ``CvMat`` back to IplImage using this function, we will get different headers if the ROI is set in the original image.
-
-GetImageCOI
------------
-Returns the index of the channel of interest.
-
-.. ocv:cfunction:: int cvGetImageCOI(const IplImage* image)
-
- :param image: A pointer to the image header
-
-Returns the channel of interest of in an IplImage. Returned values correspond to the ``coi`` in
-:ocv:cfunc:`SetImageCOI`.
-
-GetImageROI
------------
-Returns the image ROI.
-
-.. ocv:cfunction:: CvRect cvGetImageROI(const IplImage* image)
-
- :param image: A pointer to the image header
-
-If there is no ROI set, ``cvRect(0,0,image->width,image->height)`` is returned.
-
-GetMat
-------
-Returns matrix header for arbitrary array.
-
-.. ocv:cfunction:: CvMat* cvGetMat(const CvArr* arr, CvMat* header, int* coi=NULL, int allowND=0)
-
- :param arr: Input array
-
- :param header: Pointer to :ocv:struct:`CvMat` structure used as a temporary buffer
-
- :param coi: Optional output parameter for storing COI
-
- :param allowND: If non-zero, the function accepts multi-dimensional dense arrays (CvMatND*) and returns 2D matrix (if CvMatND has two dimensions) or 1D matrix (when CvMatND has 1 dimension or more than 2 dimensions). The ``CvMatND`` array must be continuous.
-
-The function returns a matrix header for the input array that can be a matrix - :ocv:struct:`CvMat`, an image - :ocv:struct:`IplImage`, or a multi-dimensional dense array - :ocv:struct:`CvMatND` (the third option is allowed only if ``allowND != 0``) . In the case of matrix the function simply returns the input pointer. In the case of ``IplImage*`` or ``CvMatND`` it initializes the ``header`` structure with parameters of the current image ROI and returns ``&header``. Because COI is not supported by ``CvMat``, it is returned separately.
-
-The function provides an easy way to handle both types of arrays - ``IplImage`` and ``CvMat`` using the same code. Input array must have non-zero data pointer, otherwise the function will report an error.
-
-.. seealso:: :ocv:cfunc:`GetImage`, :ocv:func:`cvarrToMat`.
-
-.. note:: If the input array is ``IplImage`` with planar data layout and COI set, the function returns the pointer to the selected plane and ``COI == 0``. This feature allows user to process ``IplImage`` structures with planar data layout, even though OpenCV does not support such images.
-
-GetNextSparseNode
------------------
-Returns the next sparse matrix element
-
-.. ocv:cfunction:: CvSparseNode* cvGetNextSparseNode( CvSparseMatIterator* mat_iterator )
-
- :param mat_iterator: Sparse array iterator
-
-The function moves iterator to the next sparse matrix element and returns pointer to it. In the current version there is no any particular order of the elements, because they are stored in the hash table. The sample below demonstrates how to iterate through the sparse matrix: ::
-
- // print all the non-zero sparse matrix elements and compute their sum
- double sum = 0;
- int i, dims = cvGetDims(sparsemat);
- CvSparseMatIterator it;
- CvSparseNode* node = cvInitSparseMatIterator(sparsemat, &it);
-
- for(; node != 0; node = cvGetNextSparseNode(&it))
- {
- /* get pointer to the element indices */
- int* idx = CV_NODE_IDX(array, node);
- /* get value of the element (assume that the type is CV_32FC1) */
- float val = *(float*)CV_NODE_VAL(array, node);
- printf("M");
- for(i = 0; i < dims; i++ )
- printf("[%d]", idx[i]);
- printf("=%g\n", val);
-
- sum += val;
- }
-
- printf("nTotal sum = %g\n", sum);
-
-
-GetRawData
-----------
-Retrieves low-level information about the array.
-
-.. ocv:cfunction:: void cvGetRawData( const CvArr* arr, uchar** data, int* step=NULL, CvSize* roi_size=NULL )
-
- :param arr: Array header
-
- :param data: Output pointer to the whole image origin or ROI origin if ROI is set
-
- :param step: Output full row length in bytes
-
- :param roi_size: Output ROI size
-
-The function fills output variables with low-level information about the array data. All output parameters are optional, so some of the pointers may be set to ``NULL``. If the array is ``IplImage`` with ROI set, the parameters of ROI are returned.
-
-The following example shows how to get access to array elements. It computes absolute values of the array elements ::
-
- float* data;
- int step;
- CvSize size;
-
- cvGetRawData(array, (uchar**)&data, &step, &size);
- step /= sizeof(data[0]);
-
- for(int y = 0; y < size.height; y++, data += step )
- for(int x = 0; x < size.width; x++ )
- data[x] = (float)fabs(data[x]);
-
-GetReal?D
----------
-Return a specific element of single-channel 1D, 2D, 3D or nD array.
-
-.. ocv:cfunction:: double cvGetReal1D(const CvArr* arr, int idx0)
-.. ocv:cfunction:: double cvGetReal2D(const CvArr* arr, int idx0, int idx1)
-.. ocv:cfunction:: double cvGetReal3D(const CvArr* arr, int idx0, int idx1, int idx2)
-.. ocv:cfunction:: double cvGetRealND( const CvArr* arr, const int* idx )
-
- :param arr: Input array. Must have a single channel.
-
- :param idx0: The first zero-based component of the element index
-
- :param idx1: The second zero-based component of the element index
-
- :param idx2: The third zero-based component of the element index
-
- :param idx: Array of the element indices
-
-Returns a specific element of a single-channel array. If the array has multiple channels, a runtime error is raised. Note that ``Get?D`` functions can be used safely for both single-channel and multiple-channel arrays though they are a bit slower.
-
-In the case of a sparse array the functions return 0 if the requested node does not exist (no new node is created by the functions).
-
-
-GetRow(s)
----------
-Returns array row or row span.
-
-.. ocv:cfunction:: CvMat* cvGetRow(const CvArr* arr, CvMat* submat, int row)
-
-.. ocv:cfunction:: CvMat* cvGetRows( const CvArr* arr, CvMat* submat, int start_row, int end_row, int delta_row=1 )
-
- :param arr: Input array
-
- :param submat: Pointer to the resulting sub-array header
-
- :param row: Zero-based index of the selected row
-
- :param start_row: Zero-based index of the starting row (inclusive) of the span
-
- :param end_row: Zero-based index of the ending row (exclusive) of the span
-
- :param delta_row: Index step in the row span. That is, the function extracts every ``delta_row`` -th row from ``start_row`` and up to (but not including) ``end_row`` .
-
-The functions return the header, corresponding to a specified row/row span of the input array. ``cvGetRow(arr, submat, row)`` is a shortcut for ``cvGetRows(arr, submat, row, row+1)``.
-
-
-GetSize
--------
-Returns size of matrix or image ROI.
-
-.. ocv:cfunction:: CvSize cvGetSize(const CvArr* arr)
-
- :param arr: array header
-
-The function returns number of rows (CvSize::height) and number of columns (CvSize::width) of the input matrix or image. In the case of image the size of ROI is returned.
-
-GetSubRect
-----------
-Returns matrix header corresponding to the rectangular sub-array of input image or matrix.
-
-.. ocv:cfunction:: CvMat* cvGetSubRect(const CvArr* arr, CvMat* submat, CvRect rect)
-
- :param arr: Input array
-
- :param submat: Pointer to the resultant sub-array header
-
- :param rect: Zero-based coordinates of the rectangle of interest
-
-The function returns header, corresponding to a specified rectangle of the input array. In other words, it allows the user to treat a rectangular part of input array as a stand-alone array. ROI is taken into account by the function so the sub-array of ROI is actually extracted.
-
-DecRefData
-----------
-Decrements an array data reference counter.
-
-.. ocv:cfunction:: void cvDecRefData(CvArr* arr)
-
- :param arr: Pointer to an array header
-
-The function decrements the data reference counter in a :ocv:struct:`CvMat` or :ocv:struct:`CvMatND` if the reference counter pointer is not NULL. If the counter reaches zero, the data is deallocated. In the current implementation the reference counter is not NULL only if the data was allocated using the :ocv:cfunc:`CreateData` function. The counter will be NULL in other cases such as: external data was assigned to the header using :ocv:cfunc:`SetData`, header is part of a larger matrix or image, or the header was converted from an image or n-dimensional matrix header.
-
-
-IncRefData
-----------
-Increments array data reference counter.
-
-.. ocv:cfunction:: int cvIncRefData(CvArr* arr)
-
- :param arr: Array header
-
-The function increments :ocv:struct:`CvMat` or :ocv:struct:`CvMatND` data reference counter and returns the new counter value if the reference counter pointer is not NULL, otherwise it returns zero.
-
-
-InitImageHeader
----------------
-Initializes an image header that was previously allocated.
-
-.. ocv:cfunction:: IplImage* cvInitImageHeader( IplImage* image, CvSize size, int depth, int channels, int origin=0, int align=4)
-
- :param image: Image header to initialize
-
- :param size: Image width and height
-
- :param depth: Image depth (see :ocv:cfunc:`CreateImage` )
-
- :param channels: Number of channels (see :ocv:cfunc:`CreateImage` )
-
- :param origin: Top-left ``IPL_ORIGIN_TL`` or bottom-left ``IPL_ORIGIN_BL``
-
- :param align: Alignment for image rows, typically 4 or 8 bytes
-
-The returned ``IplImage*`` points to the initialized header.
-
-
-InitMatHeader
--------------
-Initializes a pre-allocated matrix header.
-
-.. ocv:cfunction:: CvMat* cvInitMatHeader( CvMat* mat, int rows, int cols, int type, void* data=NULL, int step=CV_AUTOSTEP)
-
- :param mat: A pointer to the matrix header to be initialized
-
- :param rows: Number of rows in the matrix
-
- :param cols: Number of columns in the matrix
-
- :param type: Type of the matrix elements, see :ocv:cfunc:`CreateMat` .
-
- :param data: Optional: data pointer assigned to the matrix header
-
- :param step: Optional: full row width in bytes of the assigned data. By default, the minimal possible step is used which assumes there are no gaps between subsequent rows of the matrix.
-
-This function is often used to process raw data with OpenCV matrix functions. For example, the following code computes the matrix product of two matrices, stored as ordinary arrays: ::
-
- double a[] = { 1, 2, 3, 4,
- 5, 6, 7, 8,
- 9, 10, 11, 12 };
-
- double b[] = { 1, 5, 9,
- 2, 6, 10,
- 3, 7, 11,
- 4, 8, 12 };
-
- double c[9];
- CvMat Ma, Mb, Mc ;
-
- cvInitMatHeader(&Ma, 3, 4, CV_64FC1, a);
- cvInitMatHeader(&Mb, 4, 3, CV_64FC1, b);
- cvInitMatHeader(&Mc, 3, 3, CV_64FC1, c);
-
- cvMatMulAdd(&Ma, &Mb, 0, &Mc);
- // the c array now contains the product of a (3x4) and b (4x3)
-
-
-InitMatNDHeader
----------------
-Initializes a pre-allocated multi-dimensional array header.
-
-.. ocv:cfunction:: CvMatND* cvInitMatNDHeader( CvMatND* mat, int dims, const int* sizes, int type, void* data=NULL)
-
- :param mat: A pointer to the array header to be initialized
-
- :param dims: The number of array dimensions
-
- :param sizes: An array of dimension sizes
-
- :param type: Type of array elements, see :ocv:cfunc:`CreateMat`
-
- :param data: Optional data pointer assigned to the matrix header
-
-
-InitSparseMatIterator
----------------------
-Initializes sparse array elements iterator.
-
-.. ocv:cfunction:: CvSparseNode* cvInitSparseMatIterator( const CvSparseMat* mat, CvSparseMatIterator* mat_iterator )
-
- :param mat: Input array
-
- :param mat_iterator: Initialized iterator
-
-The function initializes iterator of sparse array elements and returns pointer to the first element, or NULL if the array is empty.
-
-
-Mat
----
-Initializes matrix header (lightweight variant).
-
-.. ocv:cfunction:: CvMat cvMat( int rows, int cols, int type, void* data=NULL)
-
- :param rows: Number of rows in the matrix
-
- :param cols: Number of columns in the matrix
-
- :param type: Type of the matrix elements - see :ocv:cfunc:`CreateMat`
-
- :param data: Optional data pointer assigned to the matrix header
-
-Initializes a matrix header and assigns data to it. The matrix is filled *row*-wise (the first ``cols`` elements of data form the first row of the matrix, etc.)
-
-This function is a fast inline substitution for :ocv:cfunc:`InitMatHeader`. Namely, it is equivalent to: ::
-
- CvMat mat;
- cvInitMatHeader(&mat, rows, cols, type, data, CV_AUTOSTEP);
-
-
-Ptr?D
------
-Return pointer to a particular array element.
-
-.. ocv:cfunction:: uchar* cvPtr1D(const CvArr* arr, int idx0, int* type=NULL)
-
-.. ocv:cfunction:: uchar* cvPtr2D(const CvArr* arr, int idx0, int idx1, int* type=NULL)
-
-.. ocv:cfunction:: uchar* cvPtr3D(const CvArr* arr, int idx0, int idx1, int idx2, int* type=NULL)
-
-.. ocv:cfunction:: uchar* cvPtrND( const CvArr* arr, const int* idx, int* type=NULL, int create_node=1, unsigned* precalc_hashval=NULL )
-
- :param arr: Input array
-
- :param idx0: The first zero-based component of the element index
-
- :param idx1: The second zero-based component of the element index
-
- :param idx2: The third zero-based component of the element index
-
- :param idx: Array of the element indices
-
- :param type: Optional output parameter: type of matrix elements
-
- :param create_node: Optional input parameter for sparse matrices. Non-zero value of the parameter means that the requested element is created if it does not exist already.
-
- :param precalc_hashval: Optional input parameter for sparse matrices. If the pointer is not NULL, the function does not recalculate the node hash value, but takes it from the specified location. It is useful for speeding up pair-wise operations (TODO: provide an example)
-
-The functions return a pointer to a specific array element. Number of array dimension should match to the number of indices passed to the function except for ``cvPtr1D`` function that can be used for sequential access to 1D, 2D or nD dense arrays.
-
-The functions can be used for sparse arrays as well - if the requested node does not exist they create it and set it to zero.
-
-All these as well as other functions accessing array elements (
-:ocv:cfunc:`GetND`
-,
-:ocv:cfunc:`GetRealND`
-,
-:ocv:cfunc:`Set`
-,
-:ocv:cfunc:`SetND`
-,
-:ocv:cfunc:`SetRealND`
-) raise an error in case if the element index is out of range.
-
-
-ReleaseData
------------
-Releases array data.
-
-.. ocv:cfunction:: void cvReleaseData(CvArr* arr)
-
- :param arr: Array header
-
-The function releases the array data. In the case of
-:ocv:struct:`CvMat`
-or
-:ocv:struct:`CvMatND`
-it simply calls cvDecRefData(), that is the function can not deallocate external data. See also the note to
-:ocv:cfunc:`CreateData`
-.
-
-
-ReleaseImage
-------------
-Deallocates the image header and the image data.
-
-.. ocv:cfunction:: void cvReleaseImage(IplImage** image)
-
- :param image: Double pointer to the image header
-
-This call is a shortened form of ::
-
- if(*image )
- {
- cvReleaseData(*image);
- cvReleaseImageHeader(image);
- }
-
-..
-
-ReleaseImageHeader
-------------------
-Deallocates an image header.
-
-.. ocv:cfunction:: void cvReleaseImageHeader(IplImage** image)
-
- :param image: Double pointer to the image header
-
-This call is an analogue of ::
-
- if(image )
- {
- iplDeallocate(*image, IPL_IMAGE_HEADER | IPL_IMAGE_ROI);
- *image = 0;
- }
-
-..
-
-but it does not use IPL functions by default (see the ``CV_TURN_ON_IPL_COMPATIBILITY`` macro).
-
-
-ReleaseMat
-----------
-Deallocates a matrix.
-
-.. ocv:cfunction:: void cvReleaseMat(CvMat** mat)
-
- :param mat: Double pointer to the matrix
-
-The function decrements the matrix data reference counter and deallocates matrix header. If the data reference counter is 0, it also deallocates the data. ::
-
- if(*mat )
- cvDecRefData(*mat);
- cvFree((void**)mat);
-
-..
-
-ReleaseMatND
-------------
-Deallocates a multi-dimensional array.
-
-.. ocv:cfunction:: void cvReleaseMatND(CvMatND** mat)
-
- :param mat: Double pointer to the array
-
-The function decrements the array data reference counter and releases the array header. If the reference counter reaches 0, it also deallocates the data. ::
-
- if(*mat )
- cvDecRefData(*mat);
- cvFree((void**)mat);
-
-..
-
-ReleaseSparseMat
-----------------
-Deallocates sparse array.
-
-.. ocv:cfunction:: void cvReleaseSparseMat(CvSparseMat** mat)
-
- :param mat: Double pointer to the array
-
-The function releases the sparse array and clears the array pointer upon exit.
-
-ResetImageROI
--------------
-Resets the image ROI to include the entire image and releases the ROI structure.
-
-.. ocv:cfunction:: void cvResetImageROI(IplImage* image)
-
- :param image: A pointer to the image header
-
-This produces a similar result to the following, but in addition it releases the ROI structure. ::
-
- cvSetImageROI(image, cvRect(0, 0, image->width, image->height ));
- cvSetImageCOI(image, 0);
-
-..
-
-Reshape
--------
-Changes shape of matrix/image without copying data.
-
-.. ocv:cfunction:: CvMat* cvReshape( const CvArr* arr, CvMat* header, int new_cn, int new_rows=0 )
-
- :param arr: Input array
-
- :param header: Output header to be filled
-
- :param new_cn: New number of channels. 'new_cn = 0' means that the number of channels remains unchanged.
-
- :param new_rows: New number of rows. 'new_rows = 0' means that the number of rows remains unchanged unless it needs to be changed according to ``new_cn`` value.
-
-The function initializes the CvMat header so that it points to the same data as the original array but has a different shape - different number of channels, different number of rows, or both.
-
-The following example code creates one image buffer and two image headers, the first is for a 320x240x3 image and the second is for a 960x240x1 image: ::
-
- IplImage* color_img = cvCreateImage(cvSize(320,240), IPL_DEPTH_8U, 3);
- CvMat gray_mat_hdr;
- IplImage gray_img_hdr, *gray_img;
- cvReshape(color_img, &gray_mat_hdr, 1);
- gray_img = cvGetImage(&gray_mat_hdr, &gray_img_hdr);
-
-..
-
-And the next example converts a 3x3 matrix to a single 1x9 vector:
-
-::
-
- CvMat* mat = cvCreateMat(3, 3, CV_32F);
- CvMat row_header, *row;
- row = cvReshape(mat, &row_header, 0, 1);
-
-..
-
-ReshapeMatND
-------------
-Changes the shape of a multi-dimensional array without copying the data.
-
-.. ocv:cfunction:: CvArr* cvReshapeMatND( const CvArr* arr, int sizeof_header, CvArr* header, int new_cn, int new_dims, int* new_sizes )
-
- :param arr: Input array
-
- :param sizeof_header: Size of output header to distinguish between IplImage, CvMat and CvMatND output headers
-
- :param header: Output header to be filled
-
- :param new_cn: New number of channels. ``new_cn = 0`` means that the number of channels remains unchanged.
-
- :param new_dims: New number of dimensions. ``new_dims = 0`` means that the number of dimensions remains the same.
-
- :param new_sizes: Array of new dimension sizes. Only ``new_dims-1`` values are used, because the total number of elements must remain the same. Thus, if ``new_dims = 1``, ``new_sizes`` array is not used.
-
-The function is an advanced version of :ocv:cfunc:`Reshape` that can work with multi-dimensional arrays as well (though it can work with ordinary images and matrices) and change the number of dimensions.
-
-Below are the two samples from the
-:ocv:cfunc:`Reshape`
-description rewritten using
-:ocv:cfunc:`ReshapeMatND`
-: ::
-
- IplImage* color_img = cvCreateImage(cvSize(320,240), IPL_DEPTH_8U, 3);
- IplImage gray_img_hdr, *gray_img;
- gray_img = (IplImage*)cvReshapeMatND(color_img, sizeof(gray_img_hdr), &gray_img_hdr, 1, 0, 0);
-
- ...
-
- /* second example is modified to convert 2x2x2 array to 8x1 vector */
- int size[] = { 2, 2, 2 };
- CvMatND* mat = cvCreateMatND(3, size, CV_32F);
- CvMat row_header, *row;
- row = (CvMat*)cvReshapeMatND(mat, sizeof(row_header), &row_header, 0, 1, 0);
-
-..
-
-In C, the header file for this function includes a convenient macro ``cvReshapeND`` that does away with the ``sizeof_header`` parameter. So, the lines containing the call to ``cvReshapeMatND`` in the examples may be replaced as follow:
-
-::
-
- gray_img = (IplImage*)cvReshapeND(color_img, &gray_img_hdr, 1, 0, 0);
-
- ...
-
- row = (CvMat*)cvReshapeND(mat, &row_header, 0, 1, 0);
-
-..
-
-Set
----
-Sets every element of an array to a given value.
-
-.. ocv:cfunction:: void cvSet(CvArr* arr, CvScalar value, const CvArr* mask=NULL)
-
- :param arr: The destination array
-
- :param value: Fill value
-
- :param mask: Operation mask, 8-bit single channel array; specifies elements of the destination array to be changed
-
-The function copies the scalar ``value`` to every selected element of the destination array:
-
-.. math::
-
- \texttt{arr} (I)= \texttt{value} \quad \text{if} \quad \texttt{mask} (I) \ne 0
-
-If array ``arr`` is of ``IplImage`` type, then is ROI used, but COI must not be set.
-
-Set?D
------
-Change the particular array element.
-
-.. ocv:cfunction:: void cvSet1D(CvArr* arr, int idx0, CvScalar value)
-
-.. ocv:cfunction:: void cvSet2D(CvArr* arr, int idx0, int idx1, CvScalar value)
-
-.. ocv:cfunction:: void cvSet3D(CvArr* arr, int idx0, int idx1, int idx2, CvScalar value)
-
-.. ocv:cfunction:: void cvSetND( CvArr* arr, const int* idx, CvScalar value )
-
- :param arr: Input array
-
- :param idx0: The first zero-based component of the element index
-
- :param idx1: The second zero-based component of the element index
-
- :param idx2: The third zero-based component of the element index
-
- :param idx: Array of the element indices
-
- :param value: The assigned value
-
-The functions assign the new value to a particular array element. In the case of a sparse array the functions create the node if it does not exist yet.
-
-SetData
--------
-Assigns user data to the array header.
-
-.. ocv:cfunction:: void cvSetData(CvArr* arr, void* data, int step)
-
- :param arr: Array header
-
- :param data: User data
-
- :param step: Full row length in bytes
-
-The function assigns user data to the array header. Header should be initialized before using
-:ocv:cfunc:`cvCreateMatHeader`, :ocv:cfunc:`cvCreateImageHeader`, :ocv:cfunc:`cvCreateMatNDHeader`,
-:ocv:cfunc:`cvInitMatHeader`, :ocv:cfunc:`cvInitImageHeader` or :ocv:cfunc:`cvInitMatNDHeader`.
-
-
-
-SetImageCOI
------------
-Sets the channel of interest in an IplImage.
-
-.. ocv:cfunction:: void cvSetImageCOI( IplImage* image, int coi)
-
- :param image: A pointer to the image header
-
- :param coi: The channel of interest. 0 - all channels are selected, 1 - first channel is selected, etc. Note that the channel indices become 1-based.
-
-If the ROI is set to ``NULL`` and the coi is *not* 0, the ROI is allocated. Most OpenCV functions do *not* support the COI setting, so to process an individual image/matrix channel one may copy (via :ocv:cfunc:`Copy` or :ocv:cfunc:`Split`) the channel to a separate image/matrix, process it and then copy the result back (via :ocv:cfunc:`Copy` or :ocv:cfunc:`Merge`) if needed.
-
-
-SetImageROI
------------
-Sets an image Region Of Interest (ROI) for a given rectangle.
-
-.. ocv:cfunction:: void cvSetImageROI( IplImage* image, CvRect rect)
-
- :param image: A pointer to the image header
-
- :param rect: The ROI rectangle
-
-If the original image ROI was ``NULL`` and the ``rect`` is not the whole image, the ROI structure is allocated.
-
-Most OpenCV functions support the use of ROI and treat the image rectangle as a separate image. For example, all of the pixel coordinates are counted from the top-left (or bottom-left) corner of the ROI, not the original image.
-
-
-SetReal?D
----------
-Change a specific array element.
-
-.. ocv:cfunction:: void cvSetReal1D(CvArr* arr, int idx0, double value)
-
-.. ocv:cfunction:: void cvSetReal2D(CvArr* arr, int idx0, int idx1, double value)
-
-.. ocv:cfunction:: void cvSetReal3D(CvArr* arr, int idx0, int idx1, int idx2, double value)
-
-.. ocv:cfunction:: void cvSetRealND( CvArr* arr, const int* idx, double value )
-
- :param arr: Input array
-
- :param idx0: The first zero-based component of the element index
-
- :param idx1: The second zero-based component of the element index
-
- :param idx2: The third zero-based component of the element index
-
- :param idx: Array of the element indices
-
- :param value: The assigned value
-
-The functions assign a new value to a specific element of a single-channel array. If the array has multiple channels, a runtime error is raised. Note that the ``Set*D`` function can be used safely for both single-channel and multiple-channel arrays, though they are a bit slower.
-
-In the case of a sparse array the functions create the node if it does not yet exist.
-
-SetZero
--------
-Clears the array.
-
-.. ocv:cfunction:: void cvSetZero(CvArr* arr)
-
- :param arr: Array to be cleared
-
-The function clears the array. In the case of dense arrays (CvMat, CvMatND or IplImage), cvZero(array) is equivalent to cvSet(array,cvScalarAll(0),0). In the case of sparse arrays all the elements are removed.
-
-mGet
-----
-Returns the particular element of single-channel floating-point matrix.
-
-.. ocv:cfunction:: double cvmGet(const CvMat* mat, int row, int col)
-
- :param mat: Input matrix
-
- :param row: The zero-based index of row
-
- :param col: The zero-based index of column
-
-The function is a fast replacement for :ocv:cfunc:`GetReal2D` in the case of single-channel floating-point matrices. It is faster because it is inline, it does fewer checks for array type and array element type, and it checks for the row and column ranges only in debug mode.
-
-mSet
-----
-Sets a specific element of a single-channel floating-point matrix.
-
-.. ocv:cfunction:: void cvmSet(CvMat* mat, int row, int col, double value)
-
- :param mat: The matrix
-
- :param row: The zero-based index of row
-
- :param col: The zero-based index of column
-
- :param value: The new value of the matrix element
-
-The function is a fast replacement for :ocv:cfunc:`SetReal2D` in the case of single-channel floating-point matrices. It is faster because it is inline, it does fewer checks for array type and array element type, and it checks for the row and column ranges only in debug mode.
-
-
-SetIPLAllocators
-----------------
-Makes OpenCV use IPL functions for allocating IplImage and IplROI structures.
-
-.. ocv:cfunction:: void cvSetIPLAllocators( Cv_iplCreateImageHeader create_header, Cv_iplAllocateImageData allocate_data, Cv_iplDeallocate deallocate, Cv_iplCreateROI create_roi, Cv_iplCloneImage clone_image )
-
- :param create_header: pointer to a function, creating IPL image header.
-
- :param allocate_data: pointer to a function, allocating IPL image data.
-
- :param deallocate: pointer to a function, deallocating IPL image.
-
- :param create_roi: pointer to a function, creating IPL image ROI (i.e. Region of Interest).
-
- :param clone_image: pointer to a function, cloning an IPL image.
-
-Normally, the function is not called directly. Instead, a simple macro ``CV_TURN_ON_IPL_COMPATIBILITY()`` is used that calls ``cvSetIPLAllocators`` and passes there pointers to IPL allocation functions. ::
-
- ...
- CV_TURN_ON_IPL_COMPATIBILITY()
- ...
-
-
-RNG
----
-Initializes a random number generator state.
-
-.. ocv:cfunction:: CvRNG cvRNG(int64 seed=-1)
-
- :param seed: 64-bit value used to initiate a random sequence
-
-The function initializes a random number generator and returns the state. The pointer to the state can be then passed to the :ocv:cfunc:`RandInt`, :ocv:cfunc:`RandReal` and :ocv:cfunc:`RandArr` functions. In the current implementation a multiply-with-carry generator is used.
-
-.. seealso:: the C++ class :ocv:class:`RNG` replaced ``CvRNG``.
-
-
-RandArr
--------
-Fills an array with random numbers and updates the RNG state.
-
-.. ocv:cfunction:: void cvRandArr( CvRNG* rng, CvArr* arr, int dist_type, CvScalar param1, CvScalar param2 )
-
- :param rng: CvRNG state initialized by :ocv:cfunc:`RNG`
-
- :param arr: The destination array
-
- :param dist_type: Distribution type
-
- * **CV_RAND_UNI** uniform distribution
-
- * **CV_RAND_NORMAL** normal or Gaussian distribution
-
- :param param1: The first parameter of the distribution. In the case of a uniform distribution it is the inclusive lower boundary of the random numbers range. In the case of a normal distribution it is the mean value of the random numbers.
-
- :param param2: The second parameter of the distribution. In the case of a uniform distribution it is the exclusive upper boundary of the random numbers range. In the case of a normal distribution it is the standard deviation of the random numbers.
-
-The function fills the destination array with uniformly or normally distributed random numbers.
-
-.. seealso:: :ocv:func:`randu`, :ocv:func:`randn`, :ocv:func:`RNG::fill`.
-
-RandInt
--------
-Returns a 32-bit unsigned integer and updates RNG.
-
-.. ocv:cfunction:: unsigned cvRandInt(CvRNG* rng)
-
- :param rng: CvRNG state initialized by :ocv:cfunc:`RNG`.
-
-The function returns a uniformly-distributed random 32-bit unsigned integer and updates the RNG state. It is similar to the rand() function from the C runtime library, except that OpenCV functions always generates a 32-bit random number, regardless of the platform.
-
-
-RandReal
---------
-Returns a floating-point random number and updates RNG.
-
-.. ocv:cfunction:: double cvRandReal(CvRNG* rng)
-
- :param rng: RNG state initialized by :ocv:cfunc:`RNG`
-
-The function returns a uniformly-distributed random floating-point number between 0 and 1 (1 is not included).
-
-
-fromarray
----------
-Create a CvMat from an object that supports the array interface.
-
- :param object: Any object that supports the array interface
-
- :param allowND: If true, will return a CvMatND
-
-If the object supports the `array interface <http://docs.scipy.org/doc/numpy/reference/arrays.interface.html>`_
-,
-return a :ocv:struct:`CvMat` or :ocv:struct:`CvMatND`, depending on ``allowND`` flag:
-
- * If ``allowND = False``, then the object's array must be either 2D or 3D. If it is 2D, then the returned CvMat has a single channel. If it is 3D, then the returned CvMat will have N channels, where N is the last dimension of the array. In this case, N cannot be greater than OpenCV's channel limit, ``CV_CN_MAX``.
-
- * If``allowND = True``, then ``fromarray`` returns a single-channel :ocv:struct:`CvMatND` with the same shape as the original array.
-
-For example, `NumPy <http://numpy.scipy.org/>`_ arrays support the array interface, so can be converted to OpenCV objects:
-
-.. code-block::python
-
- >>> import cv2.cv as cv, numpy
- >>> a = numpy.ones((480, 640))
- >>> mat = cv.fromarray(a)
- >>> print cv.GetDims(mat), cv.CV_MAT_CN(cv.GetElemType(mat))
- (480, 640) 1
- >>> a = numpy.ones((480, 640, 3))
- >>> mat = cv.fromarray(a)
- >>> print cv.GetDims(mat), cv.CV_MAT_CN(cv.GetElemType(mat))
- (480, 640) 3
- >>> a = numpy.ones((480, 640, 3))
- >>> mat = cv.fromarray(a, allowND = True)
- >>> print cv.GetDims(mat), cv.CV_MAT_CN(cv.GetElemType(mat))
- (480, 640, 3) 1
-
-.. note:: In the new Python wrappers (**cv2** module) the function is not needed, since cv2 can process Numpy arrays (and this is the only supported array type).
+++ /dev/null
-XML/YAML Persistence (C API)
-==============================
-
-The section describes the OpenCV 1.x API for reading and writing data structures to/from XML or YAML files. It is now recommended to use the new C++ interface for reading and writing data.
-
-.. highlight:: c
-
-CvFileStorage
--------------
-
-.. ocv:struct:: CvFileStorage
-
-The structure ``CvFileStorage`` is a "black box" representation of the file storage associated with a file on disk. Several functions that are described below take ``CvFileStorage*`` as inputs and allow the user to save or to load hierarchical collections that consist of scalar values, standard CXCore objects (such as matrices, sequences, graphs), and user-defined objects.
-
-OpenCV can read and write data in XML (http://www.w3c.org/XML) or YAML
-(http://www.yaml.org) formats. Below is an example of 3x3 floating-point identity matrix ``A``, stored in XML and YAML files using CXCore functions:
-
-XML: ::
-
- <?xml version="1.0">
- <opencv_storage>
- <A type_id="opencv-matrix">
- <rows>3</rows>
- <cols>3</cols>
- <dt>f</dt>
- <data>1. 0. 0. 0. 1. 0. 0. 0. 1.</data>
- </A>
- </opencv_storage>
-
-YAML: ::
-
- %YAML:1.0
- A: !!opencv-matrix
- rows: 3
- cols: 3
- dt: f
- data: [ 1., 0., 0., 0., 1., 0., 0., 0., 1.]
-
-As it can be seen from the examples, XML uses nested tags to represent
-hierarchy, while YAML uses indentation for that purpose (similar
-to the Python programming language).
-
-The same functions can read and write data in both formats;
-the particular format is determined by the extension of the opened file, ".xml" for XML files and ".yml" or ".yaml" for YAML.
-
-CvFileNode
-----------
-
-.. ocv:struct:: CvFileNode
-
- File storage node. When XML/YAML file is read, it is first parsed and stored in the memory as a hierarchical collection of nodes. Each node can be a "leaf", that is, contain a single number or a string, or be a collection of other nodes. Collections are also referenced to as "structures" in the data writing functions. There can be named collections (mappings), where each element has a name and is accessed by a name, and ordered collections (sequences), where elements do not have names, but rather accessed by index.
-
- .. ocv:member:: int tag
-
- type of the file node:
-
- * CV_NODE_NONE - empty node
- * CV_NODE_INT - an integer
- * CV_NODE_REAL - a floating-point number
- * CV_NODE_STR - text string
- * CV_NODE_SEQ - a sequence
- * CV_NODE_MAP - a mapping
-
- type of the node can be retrieved using ``CV_NODE_TYPE(node->tag)`` macro.
-
- .. ocv:member:: CvTypeInfo* info
-
- optional pointer to the user type information. If you look at the matrix representation in XML and YAML, shown above, you may notice ``type_id="opencv-matrix"`` or ``!!opencv-matrix`` strings. They are used to specify that the certain element of a file is a representation of a data structure of certain type ("opencv-matrix" corresponds to :ocv:struct:`CvMat`). When a file is parsed, such type identifiers are passed to :ocv:cfunc:`FindType` to find type information and the pointer to it is stored in the file node. See :ocv:struct:`CvTypeInfo` for more details.
-
- .. ocv:member:: union data
-
- the node data, declared as: ::
-
- union
- {
- double f; /* scalar floating-point number */
- int i; /* scalar integer number */
- CvString str; /* text string */
- CvSeq* seq; /* sequence (ordered collection of file nodes) */
- struct CvMap* map; /* map (collection of named file nodes) */
- } data;
-
- ..
-
- Primitive nodes are read using :ocv:cfunc:`ReadInt`, :ocv:cfunc:`ReadReal` and :ocv:cfunc:`ReadString`. Sequences are read by iterating through ``node->data.seq`` (see "Dynamic Data Structures" section). Mappings are read using :ocv:cfunc:`GetFileNodeByName`. Nodes with the specified type (so that ``node->info != NULL``) can be read using :ocv:cfunc:`Read`.
-
-CvAttrList
-----------
-
-.. ocv:struct:: CvAttrList
-
-List of attributes. ::
-
- typedef struct CvAttrList
- {
- const char** attr; /* NULL-terminated array of (attribute_name,attribute_value) pairs */
- struct CvAttrList* next; /* pointer to next chunk of the attributes list */
- }
- CvAttrList;
-
- /* initializes CvAttrList structure */
- inline CvAttrList cvAttrList( const char** attr=NULL, CvAttrList* next=NULL );
-
- /* returns attribute value or 0 (NULL) if there is no such attribute */
- const char* cvAttrValue( const CvAttrList* attr, const char* attr_name );
-
-..
-
-In the current implementation, attributes are used to pass extra parameters when writing user objects (see
-:ocv:cfunc:`Write`). XML attributes inside tags are not supported, aside from the object type specification (``type_id`` attribute).
-
-CvTypeInfo
-----------
-
-.. ocv:struct:: CvTypeInfo
-
-Type information. ::
-
- typedef int (CV_CDECL *CvIsInstanceFunc)( const void* structPtr );
- typedef void (CV_CDECL *CvReleaseFunc)( void** structDblPtr );
- typedef void* (CV_CDECL *CvReadFunc)( CvFileStorage* storage, CvFileNode* node );
- typedef void (CV_CDECL *CvWriteFunc)( CvFileStorage* storage,
- const char* name,
- const void* structPtr,
- CvAttrList attributes );
- typedef void* (CV_CDECL *CvCloneFunc)( const void* structPtr );
-
- typedef struct CvTypeInfo
- {
- int flags; /* not used */
- int header_size; /* sizeof(CvTypeInfo) */
- struct CvTypeInfo* prev; /* previous registered type in the list */
- struct CvTypeInfo* next; /* next registered type in the list */
- const char* type_name; /* type name, written to file storage */
-
- /* methods */
- CvIsInstanceFunc is_instance; /* checks if the passed object belongs to the type */
- CvReleaseFunc release; /* releases object (memory etc.) */
- CvReadFunc read; /* reads object from file storage */
- CvWriteFunc write; /* writes object to file storage */
- CvCloneFunc clone; /* creates a copy of the object */
- }
- CvTypeInfo;
-
-..
-
-The structure contains information about one of the standard or user-defined types. Instances of the type may or may not contain a pointer to the corresponding :ocv:struct:`CvTypeInfo` structure. In any case, there is a way to find the type info structure for a given object using the :ocv:cfunc:`TypeOf` function. Alternatively, type info can be found by type name using :ocv:cfunc:`FindType`, which is used when an object is read from file storage. The user can register a new type with :ocv:cfunc:`RegisterType`
-that adds the type information structure into the beginning of the type list. Thus, it is possible to create specialized types from generic standard types and override the basic methods.
-
-Clone
------
-Makes a clone of an object.
-
-.. ocv:cfunction:: void* cvClone( const void* struct_ptr )
-
- :param struct_ptr: The object to clone
-
-The function finds the type of a given object and calls ``clone`` with the passed object. Of course, if you know the object type, for example, ``struct_ptr`` is ``CvMat*``, it is faster to call the specific function, like :ocv:cfunc:`CloneMat`.
-
-EndWriteStruct
---------------
-Finishes writing to a file node collection.
-
-.. ocv:cfunction:: void cvEndWriteStruct(CvFileStorage* fs)
-
- :param fs: File storage
-
-.. seealso:: :ocv:cfunc:`StartWriteStruct`.
-
-FindType
---------
-Finds a type by its name.
-
-.. ocv:cfunction:: CvTypeInfo* cvFindType( const char* type_name )
-
- :param type_name: Type name
-
-The function finds a registered type by its name. It returns NULL if there is no type with the specified name.
-
-FirstType
----------
-Returns the beginning of a type list.
-
-.. ocv:cfunction:: CvTypeInfo* cvFirstType(void)
-
-The function returns the first type in the list of registered types. Navigation through the list can be done via the ``prev`` and ``next`` fields of the :ocv:struct:`CvTypeInfo` structure.
-
-GetFileNode
------------
-Finds a node in a map or file storage.
-
-.. ocv:cfunction:: CvFileNode* cvGetFileNode( CvFileStorage* fs, CvFileNode* map, const CvStringHashNode* key, int create_missing=0 )
-
- :param fs: File storage
-
- :param map: The parent map. If it is NULL, the function searches a top-level node. If both ``map`` and ``key`` are NULLs, the function returns the root file node - a map that contains top-level nodes.
-
- :param key: Unique pointer to the node name, retrieved with :ocv:cfunc:`GetHashedKey`
-
- :param create_missing: Flag that specifies whether an absent node should be added to the map
-
-The function finds a file node. It is a faster version of :ocv:cfunc:`GetFileNodeByName`
-(see :ocv:cfunc:`GetHashedKey` discussion). Also, the function can insert a new node, if it is not in the map yet.
-
-GetFileNodeByName
------------------
-Finds a node in a map or file storage.
-
-.. ocv:cfunction:: CvFileNode* cvGetFileNodeByName( const CvFileStorage* fs, const CvFileNode* map, const char* name)
-
- :param fs: File storage
-
- :param map: The parent map. If it is NULL, the function searches in all the top-level nodes (streams), starting with the first one.
-
- :param name: The file node name
-
-The function finds a file node by ``name``. The node is searched either in ``map`` or, if the pointer is NULL, among the top-level file storage nodes. Using this function for maps and :ocv:cfunc:`GetSeqElem`
-(or sequence reader) for sequences, it is possible to navigate through the file storage. To speed up multiple queries for a certain key (e.g., in the case of an array of structures) one may use a combination of :ocv:cfunc:`GetHashedKey` and :ocv:cfunc:`GetFileNode`.
-
-GetFileNodeName
----------------
-Returns the name of a file node.
-
-.. ocv:cfunction:: const char* cvGetFileNodeName( const CvFileNode* node )
-
- :param node: File node
-
-The function returns the name of a file node or NULL, if the file node does not have a name or if ``node`` is ``NULL``.
-
-GetHashedKey
-------------
-Returns a unique pointer for a given name.
-
-.. ocv:cfunction:: CvStringHashNode* cvGetHashedKey( CvFileStorage* fs, const char* name, int len=-1, int create_missing=0 )
-
- :param fs: File storage
-
- :param name: Literal node name
-
- :param len: Length of the name (if it is known apriori), or -1 if it needs to be calculated
-
- :param create_missing: Flag that specifies, whether an absent key should be added into the hash table
-
-The function returns a unique pointer for each particular file node name. This pointer can be then passed to the :ocv:cfunc:`GetFileNode` function that is faster than :ocv:cfunc:`GetFileNodeByName`
-because it compares text strings by comparing pointers rather than the strings' content.
-
-Consider the following example where an array of points is encoded as a sequence of 2-entry maps: ::
-
- points:
- - { x: 10, y: 10 }
- - { x: 20, y: 20 }
- - { x: 30, y: 30 }
- # ...
-
-..
-
-Then, it is possible to get hashed "x" and "y" pointers to speed up decoding of the points. ::
-
- #include "cxcore.h"
-
- int main( int argc, char** argv )
- {
- CvFileStorage* fs = cvOpenFileStorage( "points.yml", 0, CV_STORAGE_READ );
- CvStringHashNode* x_key = cvGetHashedNode( fs, "x", -1, 1 );
- CvStringHashNode* y_key = cvGetHashedNode( fs, "y", -1, 1 );
- CvFileNode* points = cvGetFileNodeByName( fs, 0, "points" );
-
- if( CV_NODE_IS_SEQ(points->tag) )
- {
- CvSeq* seq = points->data.seq;
- int i, total = seq->total;
- CvSeqReader reader;
- cvStartReadSeq( seq, &reader, 0 );
- for( i = 0; i < total; i++ )
- {
- CvFileNode* pt = (CvFileNode*)reader.ptr;
- #if 1 /* faster variant */
- CvFileNode* xnode = cvGetFileNode( fs, pt, x_key, 0 );
- CvFileNode* ynode = cvGetFileNode( fs, pt, y_key, 0 );
- assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
- ynode && CV_NODE_IS_INT(ynode->tag));
- int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
- int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
- #elif 1 /* slower variant; does not use x_key & y_key */
- CvFileNode* xnode = cvGetFileNodeByName( fs, pt, "x" );
- CvFileNode* ynode = cvGetFileNodeByName( fs, pt, "y" );
- assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
- ynode && CV_NODE_IS_INT(ynode->tag));
- int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
- int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
- #else /* the slowest yet the easiest to use variant */
- int x = cvReadIntByName( fs, pt, "x", 0 /* default value */ );
- int y = cvReadIntByName( fs, pt, "y", 0 /* default value */ );
- #endif
- CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
- printf("
- }
- }
- cvReleaseFileStorage( &fs );
- return 0;
- }
-
-..
-
-Please note that whatever method of accessing a map you are using, it is
-still much slower than using plain sequences; for example, in the above
-example, it is more efficient to encode the points as pairs of integers
-in a single numeric sequence.
-
-GetRootFileNode
----------------
-Retrieves one of the top-level nodes of the file storage.
-
-.. ocv:cfunction:: CvFileNode* cvGetRootFileNode( const CvFileStorage* fs, int stream_index=0 )
-
- :param fs: File storage
-
- :param stream_index: Zero-based index of the stream. See :ocv:cfunc:`StartNextStream` . In most cases, there is only one stream in the file; however, there can be several.
-
-The function returns one of the top-level file nodes. The top-level nodes do not have a name, they correspond to the streams that are stored one after another in the file storage. If the index is out of range, the function returns a NULL pointer, so all the top-level nodes can be iterated by subsequent calls to the function with ``stream_index=0,1,...``, until the NULL pointer is returned. This function
-can be used as a base for recursive traversal of the file storage.
-
-
-Load
-----
-Loads an object from a file.
-
-.. ocv:cfunction:: void* cvLoad( const char* filename, CvMemStorage* memstorage=NULL, const char* name=NULL, const char** real_name=NULL )
-
- :param filename: File name
-
- :param memstorage: Memory storage for dynamic structures, such as :ocv:struct:`CvSeq` or :ocv:struct:`CvGraph` . It is not used for matrices or images.
-
- :param name: Optional object name. If it is NULL, the first top-level object in the storage will be loaded.
-
- :param real_name: Optional output parameter that will contain the name of the loaded object (useful if ``name=NULL`` )
-
-The function loads an object from a file. It basically reads the specified file, find the first top-level node and calls :ocv:cfunc:`Read` for that node. If the file node does not have type information or the type information can not be found by the type name, the function returns NULL. After the object is loaded, the file storage is closed and all the temporary buffers are deleted. Thus, to load a dynamic structure, such as a sequence, contour, or graph, one should pass a valid memory storage destination to the function.
-
-OpenFileStorage
----------------
-Opens file storage for reading or writing data.
-
-.. ocv:cfunction:: CvFileStorage* cvOpenFileStorage( const char* filename, CvMemStorage* memstorage, int flags, const char* encoding=NULL )
-
- :param filename: Name of the file associated with the storage
-
- :param memstorage: Memory storage used for temporary data and for
- storing dynamic structures, such as :ocv:struct:`CvSeq` or :ocv:struct:`CvGraph` .
- If it is NULL, a temporary memory storage is created and used.
-
- :param flags: Can be one of the following:
-
- * **CV_STORAGE_READ** the storage is open for reading
-
- * **CV_STORAGE_WRITE** the storage is open for writing
-
-The function opens file storage for reading or writing data. In the latter case, a new file is created or an existing file is rewritten. The type of the read or written file is determined by the filename extension: ``.xml`` for ``XML`` and ``.yml`` or ``.yaml`` for ``YAML``. The function returns a pointer to the :ocv:struct:`CvFileStorage` structure. If the file cannot be opened then the function returns ``NULL``.
-
-Read
-----
-Decodes an object and returns a pointer to it.
-
-.. ocv:cfunction:: void* cvRead( CvFileStorage* fs, CvFileNode* node, CvAttrList* attributes=NULL )
-
- :param fs: File storage
-
- :param node: The root object node
-
- :param attributes: Unused parameter
-
-The function decodes a user object (creates an object in a native representation from the file storage subtree) and returns it. The object to be decoded must be an instance of a registered type that supports the ``read`` method (see :ocv:struct:`CvTypeInfo`). The type of the object is determined by the type name that is encoded in the file. If the object is a dynamic structure, it is created either in memory storage and passed to :ocv:cfunc:`OpenFileStorage` or, if a NULL pointer was passed, in temporary
-memory storage, which is released when :ocv:cfunc:`ReleaseFileStorage` is called. Otherwise, if the object is not a dynamic structure, it is created in a heap and should be released with a specialized function or by using the generic :ocv:cfunc:`Release`.
-
-ReadByName
-----------
-Finds an object by name and decodes it.
-
-.. ocv:cfunction:: void* cvReadByName( CvFileStorage* fs, const CvFileNode* map, const char* name, CvAttrList* attributes=NULL )
-
- :param fs: File storage
-
- :param map: The parent map. If it is NULL, the function searches a top-level node.
-
- :param name: The node name
-
- :param attributes: Unused parameter
-
-The function is a simple superposition of :ocv:cfunc:`GetFileNodeByName` and :ocv:cfunc:`Read`.
-
-ReadInt
--------
-Retrieves an integer value from a file node.
-
-.. ocv:cfunction:: int cvReadInt( const CvFileNode* node, int default_value=0 )
-
- :param node: File node
-
- :param default_value: The value that is returned if ``node`` is NULL
-
-The function returns an integer that is represented by the file node. If the file node is NULL, the
-``default_value`` is returned (thus, it is convenient to call the function right after :ocv:cfunc:`GetFileNode` without checking for a NULL pointer). If the file node has type ``CV_NODE_INT``, then ``node->data.i`` is returned. If the file node has type ``CV_NODE_REAL``, then ``node->data.f``
-is converted to an integer and returned. Otherwise the error is reported.
-
-ReadIntByName
--------------
-Finds a file node and returns its value.
-
-.. ocv:cfunction:: int cvReadIntByName( const CvFileStorage* fs, const CvFileNode* map, const char* name, int default_value=0 )
-
- :param fs: File storage
-
- :param map: The parent map. If it is NULL, the function searches a top-level node.
-
- :param name: The node name
-
- :param default_value: The value that is returned if the file node is not found
-
-The function is a simple superposition of :ocv:cfunc:`GetFileNodeByName` and :ocv:cfunc:`ReadInt`.
-
-ReadRawData
------------
-Reads multiple numbers.
-
-.. ocv:cfunction:: void cvReadRawData( const CvFileStorage* fs, const CvFileNode* src, void* dst, const char* dt)
-
- :param fs: File storage
-
- :param src: The file node (a sequence) to read numbers from
-
- :param dst: Pointer to the destination array
-
- :param dt: Specification of each array element. It has the same format as in :ocv:cfunc:`WriteRawData` .
-
-The function reads elements from a file node that represents a sequence of scalars.
-
-
-ReadRawDataSlice
-----------------
-Initializes file node sequence reader.
-
-.. ocv:cfunction:: void cvReadRawDataSlice( const CvFileStorage* fs, CvSeqReader* reader, int count, void* dst, const char* dt )
-
- :param fs: File storage
-
- :param reader: The sequence reader. Initialize it with :ocv:cfunc:`StartReadRawData` .
-
- :param count: The number of elements to read
-
- :param dst: Pointer to the destination array
-
- :param dt: Specification of each array element. It has the same format as in :ocv:cfunc:`WriteRawData` .
-
-The function reads one or more elements from the file node, representing a sequence, to a user-specified array. The total number of read sequence elements is a product of ``total``
-and the number of components in each array element. For example, if ``dt=2if``, the function will read ``total*3`` sequence elements. As with any sequence, some parts of the file node sequence can be skipped or read repeatedly by repositioning the reader using :ocv:cfunc:`SetSeqReaderPos`.
-
-ReadReal
---------
-Retrieves a floating-point value from a file node.
-
-.. ocv:cfunction:: double cvReadReal( const CvFileNode* node, double default_value=0. )
-
- :param node: File node
-
- :param default_value: The value that is returned if ``node`` is NULL
-
-The function returns a floating-point value
-that is represented by the file node. If the file node is NULL, the
-``default_value``
-is returned (thus, it is convenient to call
-the function right after
-:ocv:cfunc:`GetFileNode`
-without checking for a NULL
-pointer). If the file node has type
-``CV_NODE_REAL``
-,
-then
-``node->data.f``
-is returned. If the file node has type
-``CV_NODE_INT``
-, then
-``node-:math:`>`data.f``
-is converted to floating-point
-and returned. Otherwise the result is not determined.
-
-
-ReadRealByName
---------------
-Finds a file node and returns its value.
-
-.. ocv:cfunction:: double cvReadRealByName( const CvFileStorage* fs, const CvFileNode* map, const char* name, double default_value=0. )
-
- :param fs: File storage
-
- :param map: The parent map. If it is NULL, the function searches a top-level node.
-
- :param name: The node name
-
- :param default_value: The value that is returned if the file node is not found
-
-The function is a simple superposition of
-:ocv:cfunc:`GetFileNodeByName`
-and
-:ocv:cfunc:`ReadReal`
-.
-
-
-ReadString
-----------
-Retrieves a text string from a file node.
-
-.. ocv:cfunction:: const char* cvReadString( const CvFileNode* node, const char* default_value=NULL )
-
- :param node: File node
-
- :param default_value: The value that is returned if ``node`` is NULL
-
-The function returns a text string that is represented
-by the file node. If the file node is NULL, the
-``default_value``
-is returned (thus, it is convenient to call the function right after
-:ocv:cfunc:`GetFileNode`
-without checking for a NULL pointer). If
-the file node has type
-``CV_NODE_STR``
-, then
-``node-:math:`>`data.str.ptr``
-is returned. Otherwise the result is not determined.
-
-
-ReadStringByName
-----------------
-Finds a file node by its name and returns its value.
-
-.. ocv:cfunction:: const char* cvReadStringByName( const CvFileStorage* fs, const CvFileNode* map, const char* name, const char* default_value=NULL )
-
- :param fs: File storage
-
- :param map: The parent map. If it is NULL, the function searches a top-level node.
-
- :param name: The node name
-
- :param default_value: The value that is returned if the file node is not found
-
-The function is a simple superposition of
-:ocv:cfunc:`GetFileNodeByName`
-and
-:ocv:cfunc:`ReadString`
-.
-
-
-RegisterType
-------------
-Registers a new type.
-
-.. ocv:cfunction:: void cvRegisterType(const CvTypeInfo* info)
-
- :param info: Type info structure
-
-The function registers a new type, which is
-described by
-``info``
-. The function creates a copy of the structure,
-so the user should delete it after calling the function.
-
-
-Release
--------
-Releases an object.
-
-.. ocv:cfunction:: void cvRelease( void** struct_ptr )
-
- :param struct_ptr: Double pointer to the object
-
-The function finds the type of a given object and calls
-``release``
-with the double pointer.
-
-
-ReleaseFileStorage
-------------------
-Releases file storage.
-
-.. ocv:cfunction:: void cvReleaseFileStorage(CvFileStorage** fs)
-
- :param fs: Double pointer to the released file storage
-
-The function closes the file associated with the storage and releases all the temporary structures. It must be called after all I/O operations with the storage are finished.
-
-
-Save
-----
-Saves an object to a file.
-
-.. ocv:cfunction:: void cvSave( const char* filename, const void* struct_ptr, const char* name=NULL, const char* comment=NULL, CvAttrList attributes=cvAttrList() )
-
- :param filename: File name
-
- :param struct_ptr: Object to save
-
- :param name: Optional object name. If it is NULL, the name will be formed from ``filename`` .
-
- :param comment: Optional comment to put in the beginning of the file
-
- :param attributes: Optional attributes passed to :ocv:cfunc:`Write`
-
-The function saves an object to a file. It provides a simple interface to
-:ocv:cfunc:`Write`
-.
-
-
-StartNextStream
----------------
-Starts the next stream.
-
-.. ocv:cfunction:: void cvStartNextStream(CvFileStorage* fs)
-
- :param fs: File storage
-
-The function finishes the currently written stream and starts the next stream. In the case of XML the file with multiple streams looks like this: ::
-
- <opencv_storage>
- <!-- stream #1 data -->
- </opencv_storage>
- <opencv_storage>
- <!-- stream #2 data -->
- </opencv_storage>
- ...
-
-The YAML file will look like this: ::
-
- %YAML:1.0
- # stream #1 data
- ...
- ---
- # stream #2 data
-
-This is useful for concatenating files or for resuming the writing process.
-
-
-StartReadRawData
-----------------
-Initializes the file node sequence reader.
-
-.. ocv:cfunction:: void cvStartReadRawData( const CvFileStorage* fs, const CvFileNode* src, CvSeqReader* reader)
-
- :param fs: File storage
-
- :param src: The file node (a sequence) to read numbers from
-
- :param reader: Pointer to the sequence reader
-
-The function initializes the sequence reader to read data from a file node. The initialized reader can be then passed to :ocv:cfunc:`ReadRawDataSlice`.
-
-
-StartWriteStruct
-----------------
-Starts writing a new structure.
-
-.. ocv:cfunction:: void cvStartWriteStruct( CvFileStorage* fs, const char* name, int struct_flags, const char* type_name=NULL, CvAttrList attributes=cvAttrList() )
-
- :param fs: File storage
-
- :param name: Name of the written structure. The structure can be accessed by this name when the storage is read.
-
- :param struct_flags: A combination one of the following values:
-
- * **CV_NODE_SEQ** the written structure is a sequence (see discussion of :ocv:struct:`CvFileStorage` ), that is, its elements do not have a name.
-
- * **CV_NODE_MAP** the written structure is a map (see discussion of :ocv:struct:`CvFileStorage` ), that is, all its elements have names.
-
- One and only one of the two above flags must be specified
-
- * **CV_NODE_FLOW** the optional flag that makes sense only for YAML streams. It means that the structure is written as a flow (not as a block), which is more compact. It is recommended to use this flag for structures or arrays whose elements are all scalars.
-
- :param type_name: Optional parameter - the object type name. In
- case of XML it is written as a ``type_id`` attribute of the
- structure opening tag. In the case of YAML it is written after a colon
- following the structure name (see the example in :ocv:struct:`CvFileStorage`
- description). Mainly it is used with user objects. When the storage
- is read, the encoded type name is used to determine the object type
- (see :ocv:struct:`CvTypeInfo` and :ocv:cfunc:`FindType` ).
-
- :param attributes: This parameter is not used in the current implementation
-
-The function starts writing a compound structure (collection) that can be a sequence or a map. After all the structure fields, which can be scalars or structures, are written, :ocv:cfunc:`EndWriteStruct` should be called. The function can be used to group some objects or to implement the ``write`` function for a some user object (see :ocv:struct:`CvTypeInfo`).
-
-
-TypeOf
-------
-Returns the type of an object.
-
-.. ocv:cfunction:: CvTypeInfo* cvTypeOf( const void* struct_ptr )
-
- :param struct_ptr: The object pointer
-
-The function finds the type of a given object. It iterates through the list of registered types and calls the ``is_instance`` function/method for every type info structure with that object until one of them returns non-zero or until the whole list has been traversed. In the latter case, the function returns NULL.
-
-
-UnregisterType
---------------
-Unregisters the type.
-
-.. ocv:cfunction:: void cvUnregisterType( const char* type_name )
-
- :param type_name: Name of an unregistered type
-
-The function unregisters a type with a specified name. If the name is unknown, it is possible to locate the type info by an instance of the type using :ocv:cfunc:`TypeOf` or by iterating the type list, starting from :ocv:cfunc:`FirstType`, and then calling ``cvUnregisterType(info->typeName)``.
-
-
-Write
------
-Writes an object to file storage.
-
-.. ocv:cfunction:: void cvWrite( CvFileStorage* fs, const char* name, const void* ptr, CvAttrList attributes=cvAttrList() )
-
- :param fs: File storage
-
- :param name: Name of the written object. Should be NULL if and only if the parent structure is a sequence.
-
- :param ptr: Pointer to the object
-
- :param attributes: The attributes of the object. They are specific for each particular type (see the discussion below).
-
-The function writes an object to file storage. First, the appropriate type info is found using :ocv:cfunc:`TypeOf`. Then, the ``write`` method associated with the type info is called.
-
-Attributes are used to customize the writing procedure. The standard types support the following attributes (all the ``dt`` attributes have the same format as in :ocv:cfunc:`WriteRawData`):
-
-#.
- CvSeq
-
- * **header_dt** description of user fields of the sequence header that follow CvSeq, or CvChain (if the sequence is a Freeman chain) or CvContour (if the sequence is a contour or point sequence)
-
- * **dt** description of the sequence elements.
-
- * **recursive** if the attribute is present and is not equal to "0" or "false", the whole tree of sequences (contours) is stored.
-
-#.
- CvGraph
-
- * **header_dt** description of user fields of the graph header that follows CvGraph;
-
- * **vertex_dt** description of user fields of graph vertices
-
- * **edge_dt** description of user fields of graph edges (note that the edge weight is always written, so there is no need to specify it explicitly)
-
-Below is the code that creates the YAML file shown in the
-``CvFileStorage``
-description:
-
-::
-
- #include "cxcore.h"
-
- int main( int argc, char** argv )
- {
- CvMat* mat = cvCreateMat( 3, 3, CV_32F );
- CvFileStorage* fs = cvOpenFileStorage( "example.yml", 0, CV_STORAGE_WRITE );
-
- cvSetIdentity( mat );
- cvWrite( fs, "A", mat, cvAttrList(0,0) );
-
- cvReleaseFileStorage( &fs );
- cvReleaseMat( &mat );
- return 0;
- }
-
-..
-
-
-WriteComment
-------------
-Writes a comment.
-
-.. ocv:cfunction:: void cvWriteComment( CvFileStorage* fs, const char* comment, int eol_comment )
-
- :param fs: File storage
-
- :param comment: The written comment, single-line or multi-line
-
- :param eol_comment: If non-zero, the function tries to put the comment at the end of current line. If the flag is zero, if the comment is multi-line, or if it does not fit at the end of the current line, the comment starts a new line.
-
-The function writes a comment into file storage. The comments are skipped when the storage is read.
-
-WriteFileNode
--------------
-Writes a file node to another file storage.
-
-.. ocv:cfunction:: void cvWriteFileNode( CvFileStorage* fs, const char* new_node_name, const CvFileNode* node, int embed )
-
- :param fs: Destination file storage
-
- :param new_node_name: New name of the file node in the destination file storage. To keep the existing name, use :ocv:cfunc:`cvGetFileNodeName`
-
- :param node: The written node
-
- :param embed: If the written node is a collection and this parameter is not zero, no extra level of hierarchy is created. Instead, all the elements of ``node`` are written into the currently written structure. Of course, map elements can only be embedded into another map, and sequence elements can only be embedded into another sequence.
-
-The function writes a copy of a file node to file storage. Possible applications of the function are merging several file storages into one and conversion between XML and YAML formats.
-
-WriteInt
---------
-Writes an integer value.
-
-.. ocv:cfunction:: void cvWriteInt( CvFileStorage* fs, const char* name, int value)
-
- :param fs: File storage
-
- :param name: Name of the written value. Should be NULL if and only if the parent structure is a sequence.
-
- :param value: The written value
-
-The function writes a single integer value (with or without a name) to the file storage.
-
-
-WriteRawData
-------------
-Writes multiple numbers.
-
-.. ocv:cfunction:: void cvWriteRawData( CvFileStorage* fs, const void* src, int len, const char* dt )
-
- :param fs: File storage
-
- :param src: Pointer to the written array
-
- :param len: Number of the array elements to write
-
- :param dt: Specification of each array element that has the following format ``([count]{'u'|'c'|'w'|'s'|'i'|'f'|'d'})...``
- where the characters correspond to fundamental C types:
-
- * **u** 8-bit unsigned number
-
- * **c** 8-bit signed number
-
- * **w** 16-bit unsigned number
-
- * **s** 16-bit signed number
-
- * **i** 32-bit signed number
-
- * **f** single precision floating-point number
-
- * **d** double precision floating-point number
-
- * **r** pointer, 32 lower bits of which are written as a signed integer. The type can be used to store structures with links between the elements. ``count`` is the optional counter of values of a given type. For
- example, ``2if`` means that each array element is a structure
- of 2 integers, followed by a single-precision floating-point number. The
- equivalent notations of the above specification are ' ``iif`` ',
- ' ``2i1f`` ' and so forth. Other examples: ``u`` means that the
- array consists of bytes, and ``2d`` means the array consists of pairs
- of doubles.
-
-The function writes an array, whose elements consist
-of single or multiple numbers. The function call can be replaced with
-a loop containing a few
-:ocv:cfunc:`WriteInt`
-and
-:ocv:cfunc:`WriteReal`
-calls, but
-a single call is more efficient. Note that because none of the elements
-have a name, they should be written to a sequence rather than a map.
-
-
-WriteReal
----------
-Writes a floating-point value.
-
-.. ocv:cfunction:: void cvWriteReal( CvFileStorage* fs, const char* name, double value )
-
- :param fs: File storage
-
- :param name: Name of the written value. Should be NULL if and only if the parent structure is a sequence.
-
- :param value: The written value
-
-The function writes a single floating-point value (with or without a name) to file storage. Special values are encoded as follows: NaN (Not A Number) as .NaN, infinity as +.Inf or -.Inf.
-
-The following example shows how to use the low-level writing functions to store custom structures, such as termination criteria, without registering a new type. ::
-
- void write_termcriteria( CvFileStorage* fs, const char* struct_name,
- CvTermCriteria* termcrit )
- {
- cvStartWriteStruct( fs, struct_name, CV_NODE_MAP, NULL, cvAttrList(0,0));
- cvWriteComment( fs, "termination criteria", 1 ); // just a description
- if( termcrit->type & CV_TERMCRIT_ITER )
- cvWriteInteger( fs, "max_iterations", termcrit->max_iter );
- if( termcrit->type & CV_TERMCRIT_EPS )
- cvWriteReal( fs, "accuracy", termcrit->epsilon );
- cvEndWriteStruct( fs );
- }
-
-..
-
-
-WriteString
------------
-Writes a text string.
-
-.. ocv:cfunction:: void cvWriteString( CvFileStorage* fs, const char* name, const char* str, int quote=0 )
-
- :param fs: File storage
-
- :param name: Name of the written string . Should be NULL if and only if the parent structure is a sequence.
-
- :param str: The written text string
-
- :param quote: If non-zero, the written string is put in quotes, regardless of whether they are required. Otherwise, if the flag is zero, quotes are used only when they are required (e.g. when the string starts with a digit or contains spaces).
-
-The function writes a text string to file storage.
+++ /dev/null
-OpenGL interoperability
-=======================
-
-.. highlight:: cpp
-
-
-
-General Information
--------------------
-This section describes OpenGL interoperability.
-
-To enable OpenGL support, configure OpenCV using ``CMake`` with ``WITH_OPENGL=ON`` .
-Currently OpenGL is supported only with WIN32, GTK and Qt backends on Windows and Linux (MacOS and Android are not supported).
-For GTK backend ``gtkglext-1.0`` library is required.
-
-To use OpenGL functionality you should first create OpenGL context (window or frame buffer).
-You can do this with :ocv:func:`namedWindow` function or with other OpenGL toolkit (GLUT, for example).
-
-
-
-ogl::Buffer
------------
-Smart pointer for OpenGL buffer object with reference counting.
-
-.. ocv:class:: ogl::Buffer
-
-Buffer Objects are OpenGL objects that store an array of unformatted memory allocated by the OpenGL context.
-These can be used to store vertex data, pixel data retrieved from images or the framebuffer, and a variety of other things.
-
-``ogl::Buffer`` has interface similar with :ocv:class:`Mat` interface and represents 2D array memory.
-
-``ogl::Buffer`` supports memory transfers between host and device and also can be mapped to CUDA memory.
-
-
-
-ogl::Buffer::Target
--------------------
-The target defines how you intend to use the buffer object.
-
-.. ocv:enum:: ogl::Buffer::Target
-
- .. ocv:emember:: ARRAY_BUFFER
-
- The buffer will be used as a source for vertex data.
-
- .. ocv:emember:: ELEMENT_ARRAY_BUFFER
-
- The buffer will be used for indices (in ``glDrawElements`` or :ocv:func:`ogl::render`, for example).
-
- .. ocv:emember:: PIXEL_PACK_BUFFER
-
- The buffer will be used for reading from OpenGL textures.
-
- .. ocv:emember:: PIXEL_UNPACK_BUFFER
-
- The buffer will be used for writing to OpenGL textures.
-
-
-
-ogl::Buffer::Buffer
--------------------
-The constructors.
-
-.. ocv:function:: ogl::Buffer::Buffer()
-
-.. ocv:function:: ogl::Buffer::Buffer(int arows, int acols, int atype, unsigned int abufId, bool autoRelease = false)
-
-.. ocv:function:: ogl::Buffer::Buffer(Size asize, int atype, unsigned int abufId, bool autoRelease = false)
-
-.. ocv:function:: ogl::Buffer::Buffer(int arows, int acols, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
-
-.. ocv:function:: ogl::Buffer::Buffer(Size asize, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
-
-.. ocv:function:: ogl::Buffer::Buffer(InputArray arr, Target target = ARRAY_BUFFER, bool autoRelease = false)
-
- :param arows: Number of rows in a 2D array.
-
- :param acols: Number of columns in a 2D array.
-
- :param asize: 2D array size.
-
- :param atype: Array type ( ``CV_8UC1, ..., CV_64FC4`` ). See :ocv:class:`Mat` for details.
-
- :param abufId: Buffer object name.
-
- :param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` or ``std::vector`` ).
-
- :param target: Buffer usage. See :ocv:enum:`ogl::Buffer::Target` .
-
- :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
-
-Creates empty ``ogl::Buffer`` object, creates ``ogl::Buffer`` object from existed buffer ( ``abufId`` parameter),
-allocates memory for ``ogl::Buffer`` object or copies from host/device memory.
-
-
-
-ogl::Buffer::create
--------------------
-Allocates memory for ``ogl::Buffer`` object.
-
-.. ocv:function:: void ogl::Buffer::create(int arows, int acols, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
-
-.. ocv:function:: void ogl::Buffer::create(Size asize, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
-
- :param arows: Number of rows in a 2D array.
-
- :param acols: Number of columns in a 2D array.
-
- :param asize: 2D array size.
-
- :param atype: Array type ( ``CV_8UC1, ..., CV_64FC4`` ). See :ocv:class:`Mat` for details.
-
- :param target: Buffer usage. See :ocv:enum:`ogl::Buffer::Target` .
-
- :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
-
-
-
-ogl::Buffer::release
---------------------
-Decrements the reference counter and destroys the buffer object if needed.
-
-.. ocv:function:: void ogl::Buffer::release()
-
-The function will call `setAutoRelease(true)` .
-
-
-
-ogl::Buffer::setAutoRelease
----------------------------
-Sets auto release mode.
-
-.. ocv:function:: void ogl::Buffer::setAutoRelease(bool flag)
-
- :param flag: Auto release mode (if true, release will be called in object's destructor).
-
-The lifetime of the OpenGL object is tied to the lifetime of the context.
-If OpenGL context was bound to a window it could be released at any time (user can close a window).
-If object's destructor is called after destruction of the context it will cause an error.
-Thus ``ogl::Buffer`` doesn't destroy OpenGL object in destructor by default (all OpenGL resources will be released with OpenGL context).
-This function can force ``ogl::Buffer`` destructor to destroy OpenGL object.
-
-
-
-ogl::Buffer::copyFrom
----------------------
-Copies from host/device memory to OpenGL buffer.
-
-.. ocv:function:: void ogl::Buffer::copyFrom(InputArray arr, Target target = ARRAY_BUFFER, bool autoRelease = false)
-
- :param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` or ``std::vector`` ).
-
- :param target: Buffer usage. See :ocv:enum:`ogl::Buffer::Target` .
-
- :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
-
-
-
-ogl::Buffer::copyTo
--------------------
-Copies from OpenGL buffer to host/device memory or another OpenGL buffer object.
-
-.. ocv:function:: void ogl::Buffer::copyTo(OutputArray arr) const
-
- :param arr: Destination array (host or device memory, can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` , ``std::vector`` or ``ogl::Buffer`` ).
-
-
-
-ogl::Buffer::clone
-------------------
-Creates a full copy of the buffer object and the underlying data.
-
-.. ocv:function:: Buffer ogl::Buffer::clone(Target target = ARRAY_BUFFER, bool autoRelease = false) const
-
- :param target: Buffer usage for destination buffer.
-
- :param autoRelease: Auto release mode for destination buffer.
-
-
-
-ogl::Buffer::bind
------------------
-Binds OpenGL buffer to the specified buffer binding point.
-
-.. ocv:function:: void ogl::Buffer::bind(Target target) const
-
- :param target: Binding point. See :ocv:enum:`ogl::Buffer::Target` .
-
-
-
-ogl::Buffer::unbind
--------------------
-Unbind any buffers from the specified binding point.
-
-.. ocv:function:: static void ogl::Buffer::unbind(Target target)
-
- :param target: Binding point. See :ocv:enum:`ogl::Buffer::Target` .
-
-
-
-ogl::Buffer::mapHost
---------------------
-Maps OpenGL buffer to host memory.
-
-.. ocv:function:: Mat ogl::Buffer::mapHost(Access access)
-
- :param access: Access policy, indicating whether it will be possible to read from, write to, or both read from and write to the buffer object's mapped data store. The symbolic constant must be ``ogl::Buffer::READ_ONLY`` , ``ogl::Buffer::WRITE_ONLY`` or ``ogl::Buffer::READ_WRITE`` .
-
-``mapHost`` maps to the client's address space the entire data store of the buffer object.
-The data can then be directly read and/or written relative to the returned pointer, depending on the specified ``access`` policy.
-
-A mapped data store must be unmapped with :ocv:func:`ogl::Buffer::unmapHost` before its buffer object is used.
-
-This operation can lead to memory transfers between host and device.
-
-Only one buffer object can be mapped at a time.
-
-
-
-ogl::Buffer::unmapHost
-----------------------
-Unmaps OpenGL buffer.
-
-.. ocv:function:: void ogl::Buffer::unmapHost()
-
-
-
-ogl::Buffer::mapDevice
-----------------------
-Maps OpenGL buffer to CUDA device memory.
-
-.. ocv:function:: cuda::GpuMat ogl::Buffer::mapDevice()
-
-This operatation doesn't copy data.
-Several buffer objects can be mapped to CUDA memory at a time.
-
-A mapped data store must be unmapped with :ocv:func:`ogl::Buffer::unmapDevice` before its buffer object is used.
-
-
-
-ogl::Buffer::unmapDevice
-------------------------
-Unmaps OpenGL buffer.
-
-.. ocv:function:: void ogl::Buffer::unmapDevice()
-
-
-
-ogl::Texture2D
---------------
-Smart pointer for OpenGL 2D texture memory with reference counting.
-
-.. ocv:class:: ogl::Texture2D
-
-
-
-ogl::Texture2D::Format
-----------------------
-An Image Format describes the way that the images in Textures store their data.
-
-.. ocv:enum:: ogl::Texture2D::Format
-
- .. ocv:emember:: NONE
- .. ocv:emember:: DEPTH_COMPONENT
- .. ocv:emember:: RGB
- .. ocv:emember:: RGBA
-
-
-
-ogl::Texture2D::Texture2D
--------------------------
-The constructors.
-
-.. ocv:function:: ogl::Texture2D::Texture2D()
-
-.. ocv:function:: ogl::Texture2D::Texture2D(int arows, int acols, Format aformat, unsigned int atexId, bool autoRelease = false)
-
-.. ocv:function:: ogl::Texture2D::Texture2D(Size asize, Format aformat, unsigned int atexId, bool autoRelease = false)
-
-.. ocv:function:: ogl::Texture2D::Texture2D(int arows, int acols, Format aformat, bool autoRelease = false)
-
-.. ocv:function:: ogl::Texture2D::Texture2D(Size asize, Format aformat, bool autoRelease = false)
-
-.. ocv:function:: ogl::Texture2D::Texture2D(InputArray arr, bool autoRelease = false)
-
- :param arows: Number of rows.
-
- :param acols: Number of columns.
-
- :param asize: 2D array size.
-
- :param aformat: Image format. See :ocv:enum:`ogl::Texture2D::Format` .
-
- :param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` or :ocv:class:`ogl::Buffer` ).
-
- :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
-
-Creates empty ``ogl::Texture2D`` object, allocates memory for ``ogl::Texture2D`` object or copies from host/device memory.
-
-
-
-ogl::Texture2D::create
-----------------------
-Allocates memory for ``ogl::Texture2D`` object.
-
-.. ocv:function:: void ogl::Texture2D::create(int arows, int acols, Format aformat, bool autoRelease = false)
-
-.. ocv:function:: void ogl::Texture2D::create(Size asize, Format aformat, bool autoRelease = false)
-
- :param arows: Number of rows.
-
- :param acols: Number of columns.
-
- :param asize: 2D array size.
-
- :param aformat: Image format. See :ocv:enum:`ogl::Texture2D::Format` .
-
- :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
-
-
-
-ogl::Texture2D::release
------------------------
-Decrements the reference counter and destroys the texture object if needed.
-
-.. ocv:function:: void ogl::Texture2D::release()
-
-The function will call `setAutoRelease(true)` .
-
-
-
-ogl::Texture2D::setAutoRelease
-------------------------------
-Sets auto release mode.
-
-.. ocv:function:: void ogl::Texture2D::setAutoRelease(bool flag)
-
- :param flag: Auto release mode (if true, release will be called in object's destructor).
-
-The lifetime of the OpenGL object is tied to the lifetime of the context.
-If OpenGL context was bound to a window it could be released at any time (user can close a window).
-If object's destructor is called after destruction of the context it will cause an error.
-Thus ``ogl::Texture2D`` doesn't destroy OpenGL object in destructor by default (all OpenGL resources will be released with OpenGL context).
-This function can force ``ogl::Texture2D`` destructor to destroy OpenGL object.
-
-
-
-ogl::Texture2D::copyFrom
-------------------------
-Copies from host/device memory to OpenGL texture.
-
-.. ocv:function:: void ogl::Texture2D::copyFrom(InputArray arr, bool autoRelease = false)
-
- :param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` or :ocv:class:`ogl::Buffer` ).
-
- :param autoRelease: Auto release mode (if true, release will be called in object's destructor).
-
-
-
-ogl::Texture2D::copyTo
-----------------------
-Copies from OpenGL texture to host/device memory or another OpenGL texture object.
-
-.. ocv:function:: void ogl::Texture2D::copyTo(OutputArray arr, int ddepth = CV_32F, bool autoRelease = false) const
-
- :param arr: Destination array (host or device memory, can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` , :ocv:class:`ogl::Buffer` or ``ogl::Texture2D`` ).
-
- :param ddepth: Destination depth.
-
- :param autoRelease: Auto release mode for destination buffer (if ``arr`` is OpenGL buffer or texture).
-
-
-
-ogl::Texture2D::bind
---------------------
-Binds texture to current active texture unit for ``GL_TEXTURE_2D`` target.
-
-.. ocv:function:: void ogl::Texture2D::bind() const
-
-
-
-ogl::Arrays
------------
-Wrapper for OpenGL Client-Side Vertex arrays.
-
-.. ocv:class:: ogl::Arrays
-
-``ogl::Arrays`` stores vertex data in :ocv:class:`ogl::Buffer` objects.
-
-
-
-ogl::Arrays::setVertexArray
----------------------------
-Sets an array of vertex coordinates.
-
-.. ocv:function:: void ogl::Arrays::setVertexArray(InputArray vertex)
-
- :param vertex: array with vertex coordinates, can be both host and device memory.
-
-
-
-ogl::Arrays::resetVertexArray
------------------------------
-Resets vertex coordinates.
-
-.. ocv:function:: void ogl::Arrays::resetVertexArray()
-
-
-
-ogl::Arrays::setColorArray
---------------------------
-Sets an array of vertex colors.
-
-.. ocv:function:: void ogl::Arrays::setColorArray(InputArray color)
-
- :param color: array with vertex colors, can be both host and device memory.
-
-
-
-ogl::Arrays::resetColorArray
-----------------------------
-Resets vertex colors.
-
-.. ocv:function:: void ogl::Arrays::resetColorArray()
-
-
-
-ogl::Arrays::setNormalArray
----------------------------
-Sets an array of vertex normals.
-
-.. ocv:function:: void ogl::Arrays::setNormalArray(InputArray normal)
-
- :param normal: array with vertex normals, can be both host and device memory.
-
-
-
-ogl::Arrays::resetNormalArray
------------------------------
-Resets vertex normals.
-
-.. ocv:function:: void ogl::Arrays::resetNormalArray()
-
-
-
-ogl::Arrays::setTexCoordArray
------------------------------
-Sets an array of vertex texture coordinates.
-
-.. ocv:function:: void ogl::Arrays::setTexCoordArray(InputArray texCoord)
-
- :param texCoord: array with vertex texture coordinates, can be both host and device memory.
-
-
-
-ogl::Arrays::resetTexCoordArray
--------------------------------
-Resets vertex texture coordinates.
-
-.. ocv:function:: void ogl::Arrays::resetTexCoordArray()
-
-
-
-ogl::Arrays::release
---------------------
-Releases all inner buffers.
-
-.. ocv:function:: void ogl::Arrays::release()
-
-
-
-ogl::Arrays::setAutoRelease
----------------------------
-Sets auto release mode all inner buffers.
-
-.. ocv:function:: void ogl::Arrays::setAutoRelease(bool flag)
-
- :param flag: Auto release mode.
-
-
-
-ogl::Arrays::bind
------------------
-Binds all vertex arrays.
-
-.. ocv:function:: void ogl::Arrays::bind() const
-
-
-
-ogl::Arrays::size
------------------
-Returns the vertex count.
-
-.. ocv:function:: int ogl::Arrays::size() const
-
-
-
-ogl::render
------------
-Render OpenGL texture or primitives.
-
-.. ocv:function:: void ogl::render(const Texture2D& tex, Rect_<double> wndRect = Rect_<double>(0.0, 0.0, 1.0, 1.0), Rect_<double> texRect = Rect_<double>(0.0, 0.0, 1.0, 1.0))
-
-.. ocv:function:: void ogl::render(const Arrays& arr, int mode = POINTS, Scalar color = Scalar::all(255))
-
-.. ocv:function:: void ogl::render(const Arrays& arr, InputArray indices, int mode = POINTS, Scalar color = Scalar::all(255))
-
- :param tex: Texture to draw.
-
- :param wndRect: Region of window, where to draw a texture (normalized coordinates).
-
- :param texRect: Region of texture to draw (normalized coordinates).
-
- :param arr: Array of privitives vertices.
-
- :param indices: Array of vertices indices (host or device memory).
-
- :param mode: Render mode. Available options:
-
- * **POINTS**
- * **LINES**
- * **LINE_LOOP**
- * **LINE_STRIP**
- * **TRIANGLES**
- * **TRIANGLE_STRIP**
- * **TRIANGLE_FAN**
- * **QUADS**
- * **QUAD_STRIP**
- * **POLYGON**
-
- :param color: Color for all vertices. Will be used if ``arr`` doesn't contain color array.
-
-
-
-cuda::setGlDevice
------------------
-Sets a CUDA device and initializes it for the current thread with OpenGL interoperability.
-
-.. ocv:function:: void cuda::setGlDevice( int device = 0 )
-
- :param device: System index of a CUDA device starting with 0.
-
-This function should be explicitly called after OpenGL context creation and before any CUDA calls.
+++ /dev/null
-Operations on Arrays
-====================
-
-.. highlight:: cpp
-
-abs
----
-Calculates an absolute value of each matrix element.
-
-.. ocv:function:: MatExpr abs( const Mat& m )
-.. ocv:function:: MatExpr abs( const MatExpr& e )
-
- :param m: matrix.
- :param e: matrix expression.
-
-``abs`` is a meta-function that is expanded to one of :ocv:func:`absdiff` or :ocv:func:`convertScaleAbs` forms:
-
- * ``C = abs(A-B)`` is equivalent to ``absdiff(A, B, C)``
-
- * ``C = abs(A)`` is equivalent to ``absdiff(A, Scalar::all(0), C)``
-
- * ``C = Mat_<Vec<uchar,n> >(abs(A*alpha + beta))`` is equivalent to ``convertScaleAbs(A, C, alpha, beta)``
-
-The output matrix has the same size and the same type as the input one except for the last case, where ``C`` is ``depth=CV_8U`` .
-
- .. seealso:: :ref:`MatrixExpressions`, :ocv:func:`absdiff`, :ocv:func:`convertScaleAbs`
-
-
-absdiff
--------
-Calculates the per-element absolute difference between two arrays or between an array and a scalar.
-
-.. ocv:function:: void absdiff(InputArray src1, InputArray src2, OutputArray dst)
-
-.. ocv:pyfunction:: cv2.absdiff(src1, src2[, dst]) -> dst
-
-.. ocv:cfunction:: void cvAbsDiff(const CvArr* src1, const CvArr* src2, CvArr* dst)
-.. ocv:cfunction:: void cvAbsDiffS(const CvArr* src, CvArr* dst, CvScalar value)
-
- :param src1: first input array or a scalar.
-
- :param src2: second input array or a scalar.
-
- :param src: single input array.
-
- :param value: scalar value.
-
- :param dst: output array that has the same size and type as input arrays.
-
-The function ``absdiff`` calculates:
-
- *
- Absolute difference between two arrays when they have the same size and type:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2}(I)|)
-
- *
- Absolute difference between an array and a scalar when the second array is constructed from ``Scalar`` or has as many elements as the number of channels in ``src1``:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2} |)
-
- *
- Absolute difference between a scalar and an array when the first array is constructed from ``Scalar`` or has as many elements as the number of channels in ``src2``:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} (| \texttt{src1} - \texttt{src2}(I) |)
-
- where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
-
-.. note:: Saturation is not applied when the arrays have the depth ``CV_32S``. You may even get a negative value in the case of overflow.
-
-.. seealso:: :ocv:func:`abs`
-
-
-add
----
-
-Calculates the per-element sum of two arrays or an array and a scalar.
-
-.. ocv:function:: void add(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray(), int dtype=-1)
-
-.. ocv:pyfunction:: cv2.add(src1, src2[, dst[, mask[, dtype]]]) -> dst
-
-.. ocv:cfunction:: void cvAdd(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
-.. ocv:cfunction:: void cvAddS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL)
-
- :param src1: first input array or a scalar.
-
- :param src2: second input array or a scalar.
-
- :param src: single input array.
-
- :param value: scalar value.
-
- :param dst: output array that has the same size and number of channels as the input array(s); the depth is defined by ``dtype`` or ``src1``/``src2``.
-
- :param mask: optional operation mask - 8-bit single channel array, that specifies elements of the output array to be changed.
-
- :param dtype: optional depth of the output array (see the discussion below).
-
-The function ``add`` calculates:
-
- *
- Sum of two arrays when both input arrays have the same size and the same number of channels:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0
-
- *
- Sum of an array and a scalar when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2} ) \quad \texttt{if mask}(I) \ne0
-
- *
- Sum of a scalar and an array when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} + \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0
-
- where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
-
-The first function in the list above can be replaced with matrix expressions: ::
-
- dst = src1 + src2;
- dst += src1; // equivalent to add(dst, src1, dst);
-
-The input arrays and the output array can all have the same or different depths. For example, you can add a 16-bit unsigned array to a 8-bit signed array and store the sum as a 32-bit floating-point array. Depth of the output array is determined by the ``dtype`` parameter. In the second and third cases above, as well as in the first case, when ``src1.depth() == src2.depth()``, ``dtype`` can be set to the default ``-1``. In this case, the output array will have the same depth as the input array, be it ``src1``, ``src2`` or both.
-
-.. note:: Saturation is not applied when the output array has the depth ``CV_32S``. You may even get result of an incorrect sign in the case of overflow.
-
-.. seealso::
-
- :ocv:func:`subtract`,
- :ocv:func:`addWeighted`,
- :ocv:func:`scaleAdd`,
- :ocv:func:`Mat::convertTo`,
- :ref:`MatrixExpressions`
-
-
-
-addWeighted
------------
-Calculates the weighted sum of two arrays.
-
-.. ocv:function:: void addWeighted(InputArray src1, double alpha, InputArray src2, double beta, double gamma, OutputArray dst, int dtype=-1)
-
-.. ocv:pyfunction:: cv2.addWeighted(src1, alpha, src2, beta, gamma[, dst[, dtype]]) -> dst
-
-.. ocv:cfunction:: void cvAddWeighted(const CvArr* src1, double alpha, const CvArr* src2, double beta, double gamma, CvArr* dst)
-
- :param src1: first input array.
-
- :param alpha: weight of the first array elements.
-
- :param src2: second input array of the same size and channel number as ``src1``.
-
- :param beta: weight of the second array elements.
-
- :param dst: output array that has the same size and number of channels as the input arrays.
-
- :param gamma: scalar added to each sum.
-
- :param dtype: optional depth of the output array; when both input arrays have the same depth, ``dtype`` can be set to ``-1``, which will be equivalent to ``src1.depth()``.
-
-The function ``addWeighted`` calculates the weighted sum of two arrays as follows:
-
-.. math::
-
- \texttt{dst} (I)= \texttt{saturate} ( \texttt{src1} (I)* \texttt{alpha} + \texttt{src2} (I)* \texttt{beta} + \texttt{gamma} )
-
-where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
-
-The function can be replaced with a matrix expression: ::
-
- dst = src1*alpha + src2*beta + gamma;
-
-.. note:: Saturation is not applied when the output array has the depth ``CV_32S``. You may even get result of an incorrect sign in the case of overflow.
-
-.. seealso::
-
- :ocv:func:`add`,
- :ocv:func:`subtract`,
- :ocv:func:`scaleAdd`,
- :ocv:func:`Mat::convertTo`,
- :ref:`MatrixExpressions`
-
-
-
-bitwise_and
------------
-Calculates the per-element bit-wise conjunction of two arrays or an array and a scalar.
-
-.. ocv:function:: void bitwise_and(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray())
-
-.. ocv:pyfunction:: cv2.bitwise_and(src1, src2[, dst[, mask]]) -> dst
-
-.. ocv:cfunction:: void cvAnd(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
-.. ocv:cfunction:: void cvAndS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL)
-
- :param src1: first input array or a scalar.
-
- :param src2: second input array or a scalar.
-
- :param src: single input array.
-
- :param value: scalar value.
-
- :param dst: output array that has the same size and type as the input arrays.
-
- :param mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.
-
-The function calculates the per-element bit-wise logical conjunction for:
-
- *
- Two arrays when ``src1`` and ``src2`` have the same size:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
-
- *
- An array and a scalar when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} \quad \texttt{if mask} (I) \ne0
-
- *
- A scalar and an array when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
-
-
-In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the second and third cases above, the scalar is first converted to the array type.
-
-
-
-bitwise_not
------------
-Inverts every bit of an array.
-
-.. ocv:function:: void bitwise_not(InputArray src, OutputArray dst, InputArray mask=noArray())
-
-.. ocv:pyfunction:: cv2.bitwise_not(src[, dst[, mask]]) -> dst
-
-.. ocv:cfunction:: void cvNot(const CvArr* src, CvArr* dst)
-
- :param src: input array.
-
- :param dst: output array that has the same size and type as the input array.
-
- :param mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.
-
-The function calculates per-element bit-wise inversion of the input array:
-
-.. math::
-
- \texttt{dst} (I) = \neg \texttt{src} (I)
-
-In case of a floating-point input array, its machine-specific bit representation (usually IEEE754-compliant) is used for the operation. In case of multi-channel arrays, each channel is processed independently.
-
-
-
-bitwise_or
-----------
-Calculates the per-element bit-wise disjunction of two arrays or an array and a scalar.
-
-.. ocv:function:: void bitwise_or(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray())
-
-.. ocv:pyfunction:: cv2.bitwise_or(src1, src2[, dst[, mask]]) -> dst
-
-.. ocv:cfunction:: void cvOr(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
-.. ocv:cfunction:: void cvOrS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL)
-
- :param src1: first input array or a scalar.
-
- :param src2: second input array or a scalar.
-
- :param src: single input array.
-
- :param value: scalar value.
-
- :param dst: output array that has the same size and type as the input arrays.
-
- :param mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.
-
-The function calculates the per-element bit-wise logical disjunction for:
-
- *
- Two arrays when ``src1`` and ``src2`` have the same size:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
-
- *
- An array and a scalar when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} \quad \texttt{if mask} (I) \ne0
-
- *
- A scalar and an array when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
-
-
-In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the second and third cases above, the scalar is first converted to the array type.
-
-
-bitwise_xor
------------
-Calculates the per-element bit-wise "exclusive or" operation on two arrays or an array and a scalar.
-
-.. ocv:function:: void bitwise_xor(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray())
-
-.. ocv:pyfunction:: cv2.bitwise_xor(src1, src2[, dst[, mask]]) -> dst
-
-.. ocv:cfunction:: void cvXor(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
-.. ocv:cfunction:: void cvXorS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL)
-
- :param src1: first input array or a scalar.
-
- :param src2: second input array or a scalar.
-
- :param src: single input array.
-
- :param value: scalar value.
-
- :param dst: output array that has the same size and type as the input arrays.
-
- :param mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.
-
-The function calculates the per-element bit-wise logical "exclusive-or" operation for:
-
- *
- Two arrays when ``src1`` and ``src2`` have the same size:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
-
- *
- An array and a scalar when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} \quad \texttt{if mask} (I) \ne0
-
- *
- A scalar and an array when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
-
-
-In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the 2nd and 3rd cases above, the scalar is first converted to the array type.
-
-
-calcCovarMatrix
----------------
-Calculates the covariance matrix of a set of vectors.
-
-.. ocv:function:: void calcCovarMatrix( const Mat* samples, int nsamples, Mat& covar, Mat& mean, int flags, int ctype=CV_64F)
-
-.. ocv:function:: void calcCovarMatrix( InputArray samples, OutputArray covar, InputOutputArray mean, int flags, int ctype=CV_64F)
-
-.. ocv:pyfunction:: cv2.calcCovarMatrix(samples, flags[, covar[, mean[, ctype]]]) -> covar, mean
-
-.. ocv:cfunction:: void cvCalcCovarMatrix( const CvArr** vects, int count, CvArr* cov_mat, CvArr* avg, int flags )
-
- :param samples: samples stored either as separate matrices or as rows/columns of a single matrix.
-
- :param nsamples: number of samples when they are stored separately.
-
- :param covar: output covariance matrix of the type ``ctype`` and square size.
-
- :param ctype: type of the matrixl; it equals 'CV_64F' by default.
-
- :param mean: input or output (depending on the flags) array as the average value of the input vectors.
-
- :param vects: a set of vectors.
-
- :param flags: operation flags as a combination of the following values:
-
- * **CV_COVAR_SCRAMBLED** The output covariance matrix is calculated as:
-
- .. math::
-
- \texttt{scale} \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...]^T \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...],
-
- The covariance matrix will be ``nsamples x nsamples``. Such an unusual covariance matrix is used for fast PCA of a set of very large vectors (see, for example, the EigenFaces technique for face recognition). Eigenvalues of this "scrambled" matrix match the eigenvalues of the true covariance matrix. The "true" eigenvectors can be easily calculated from the eigenvectors of the "scrambled" covariance matrix.
-
- * **CV_COVAR_NORMAL** The output covariance matrix is calculated as:
-
- .. math::
-
- \texttt{scale} \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...] \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...]^T,
-
- ``covar`` will be a square matrix of the same size as the total number of elements in each input vector. One and only one of ``CV_COVAR_SCRAMBLED`` and ``CV_COVAR_NORMAL`` must be specified.
-
- * **CV_COVAR_USE_AVG** If the flag is specified, the function does not calculate ``mean`` from the input vectors but, instead, uses the passed ``mean`` vector. This is useful if ``mean`` has been pre-calculated or known in advance, or if the covariance matrix is calculated by parts. In this case, ``mean`` is not a mean vector of the input sub-set of vectors but rather the mean vector of the whole set.
-
- * **CV_COVAR_SCALE** If the flag is specified, the covariance matrix is scaled. In the "normal" mode, ``scale`` is ``1./nsamples`` . In the "scrambled" mode, ``scale`` is the reciprocal of the total number of elements in each input vector. By default (if the flag is not specified), the covariance matrix is not scaled ( ``scale=1`` ).
-
- * **CV_COVAR_ROWS** [Only useful in the second variant of the function] If the flag is specified, all the input vectors are stored as rows of the ``samples`` matrix. ``mean`` should be a single-row vector in this case.
-
- * **CV_COVAR_COLS** [Only useful in the second variant of the function] If the flag is specified, all the input vectors are stored as columns of the ``samples`` matrix. ``mean`` should be a single-column vector in this case.
-
-The functions ``calcCovarMatrix`` calculate the covariance matrix and, optionally, the mean vector of the set of input vectors.
-
-.. seealso::
-
- :ocv:class:`PCA`,
- :ocv:func:`mulTransposed`,
- :ocv:func:`Mahalanobis`
-
-
-
-cartToPolar
------------
-Calculates the magnitude and angle of 2D vectors.
-
-.. ocv:function:: void cartToPolar(InputArray x, InputArray y, OutputArray magnitude, OutputArray angle, bool angleInDegrees=false)
-
-.. ocv:pyfunction:: cv2.cartToPolar(x, y[, magnitude[, angle[, angleInDegrees]]]) -> magnitude, angle
-
-.. ocv:cfunction:: void cvCartToPolar( const CvArr* x, const CvArr* y, CvArr* magnitude, CvArr* angle=NULL, int angle_in_degrees=0 )
-
- :param x: array of x-coordinates; this must be a single-precision or double-precision floating-point array.
-
- :param y: array of y-coordinates, that must have the same size and same type as ``x``.
-
- :param magnitude: output array of magnitudes of the same size and type as ``x``.
-
- :param angle: output array of angles that has the same size and type as ``x``; the angles are measured in radians (from 0 to 2*Pi) or in degrees (0 to 360 degrees).
-
- :param angleInDegrees: a flag, indicating whether the angles are measured in radians (which is by default), or in degrees.
-
- :param angle_in_degrees: a flag, indicating whether the angles are measured in radians, or in degrees (specific to C syntax).
-
-The function ``cartToPolar`` calculates either the magnitude, angle, or both for every 2D vector (x(I),y(I)):
-
-.. math::
-
- \begin{array}{l} \texttt{magnitude} (I)= \sqrt{\texttt{x}(I)^2+\texttt{y}(I)^2} , \\ \texttt{angle} (I)= \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))[ \cdot180 / \pi ] \end{array}
-
-The angles are calculated with accuracy about 0.3 degrees. For the point (0,0), the angle is set to 0.
-
-.. seealso::
-
- :ocv:func:`Sobel`,
- :ocv:func:`Scharr`
-
-checkRange
-----------
-Checks every element of an input array for invalid values.
-
-.. ocv:function:: bool checkRange( InputArray a, bool quiet=true, Point* pos=0, double minVal=-DBL_MAX, double maxVal=DBL_MAX )
-
-.. ocv:pyfunction:: cv2.checkRange(a[, quiet[, minVal[, maxVal]]]) -> retval, pos
-
- :param a: input array.
-
- :param quiet: a flag, indicating whether the functions quietly return false when the array elements are out of range or they throw an exception.
-
- :param pos: optional output parameter, where the position of the first outlier is stored; in the second function ``pos``, when not NULL, must be a pointer to array of ``src.dims`` elements.
-
- :param minVal: inclusive lower boundary of valid values range.
-
- :param maxVal: exclusive upper boundary of valid values range.
-
-The functions ``checkRange`` check that every array element is neither NaN nor
-infinite. When ``minVal < -DBL_MAX`` and ``maxVal < DBL_MAX``, the functions also check that each value is between ``minVal`` and ``maxVal``. In case of multi-channel arrays, each channel is processed independently.
-If some values are out of range, position of the first outlier is stored in ``pos`` (when
-``pos != NULL``). Then, the functions either return false (when ``quiet=true``) or throw an exception.
-
-
-
-compare
--------
-Performs the per-element comparison of two arrays or an array and scalar value.
-
-.. ocv:function:: void compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop)
-
-.. ocv:pyfunction:: cv2.compare(src1, src2, cmpop[, dst]) -> dst
-
-.. ocv:cfunction:: void cvCmp( const CvArr* src1, const CvArr* src2, CvArr* dst, int cmp_op )
-
-.. ocv:cfunction:: void cvCmpS( const CvArr* src, double value, CvArr* dst, int cmp_op )
-
- :param src1: first input array or a scalar (in the case of ``cvCmp``, ``cv.Cmp``, ``cvCmpS``, ``cv.CmpS`` it is always an array); when it is an array, it must have a single channel.
-
- :param src2: second input array or a scalar (in the case of ``cvCmp`` and ``cv.Cmp`` it is always an array; in the case of ``cvCmpS``, ``cv.CmpS`` it is always a scalar); when it is an array, it must have a single channel.
-
- :param src: single input array.
-
- :param value: scalar value.
-
- :param dst: output array that has the same size and type as the input arrays.
-
- :param cmpop: a flag, that specifies correspondence between the arrays:
-
- * **CMP_EQ** ``src1`` is equal to ``src2``.
- * **CMP_GT** ``src1`` is greater than ``src2``.
- * **CMP_GE** ``src1`` is greater than or equal to ``src2``.
- * **CMP_LT** ``src1`` is less than ``src2``.
- * **CMP_LE** ``src1`` is less than or equal to ``src2``.
- * **CMP_NE** ``src1`` is unequal to ``src2``.
-
-The function compares:
-
-
- *
- Elements of two arrays when ``src1`` and ``src2`` have the same size:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} (I) \,\texttt{cmpop}\, \texttt{src2} (I)
-
- *
- Elements of ``src1`` with a scalar ``src2`` when ``src2`` is constructed from ``Scalar`` or has a single element:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1}(I) \,\texttt{cmpop}\, \texttt{src2}
-
- *
- ``src1`` with elements of ``src2`` when ``src1`` is constructed from ``Scalar`` or has a single element:
-
- .. math::
-
- \texttt{dst} (I) = \texttt{src1} \,\texttt{cmpop}\, \texttt{src2} (I)
-
-
-When the comparison result is true, the corresponding element of output array is set to 255.
-The comparison operations can be replaced with the equivalent matrix expressions: ::
-
- Mat dst1 = src1 >= src2;
- Mat dst2 = src1 < 8;
- ...
-
-
-.. seealso::
-
- :ocv:func:`checkRange`,
- :ocv:func:`min`,
- :ocv:func:`max`,
- :ocv:func:`threshold`,
- :ref:`MatrixExpressions`
-
-
-
-completeSymm
-------------
-Copies the lower or the upper half of a square matrix to another half.
-
-.. ocv:function:: void completeSymm(InputOutputArray mtx, bool lowerToUpper=false)
-
-.. ocv:pyfunction:: cv2.completeSymm(mtx[, lowerToUpper]) -> mtx
-
- :param mtx: input-output floating-point square matrix.
-
- :param lowerToUpper: operation flag; if true, the lower half is copied to the upper half. Otherwise, the upper half is copied to the lower half.
-
-The function ``completeSymm`` copies the lower half of a square matrix to its another half. The matrix diagonal remains unchanged:
-
- *
- :math:`\texttt{mtx}_{ij}=\texttt{mtx}_{ji}` for
- :math:`i > j` if ``lowerToUpper=false``
-
- *
- :math:`\texttt{mtx}_{ij}=\texttt{mtx}_{ji}` for
- :math:`i < j` if ``lowerToUpper=true``
-
-.. seealso::
-
- :ocv:func:`flip`,
- :ocv:func:`transpose`
-
-
-
-convertScaleAbs
----------------
-Scales, calculates absolute values, and converts the result to 8-bit.
-
-.. ocv:function:: void convertScaleAbs(InputArray src, OutputArray dst, double alpha=1, double beta=0)
-
-.. ocv:pyfunction:: cv2.convertScaleAbs(src[, dst[, alpha[, beta]]]) -> dst
-
-.. ocv:cfunction:: void cvConvertScaleAbs(const CvArr* src, CvArr* dst, double scale=1, double shift=0)
-
- :param src: input array.
-
- :param dst: output array.
-
- :param alpha: optional scale factor.
-
- :param beta: optional delta added to the scaled values.
-
-On each element of the input array, the function ``convertScaleAbs`` performs three operations sequentially: scaling, taking an absolute value, conversion to an unsigned 8-bit type:
-
-
-.. math::
-
- \texttt{dst} (I)= \texttt{saturate\_cast<uchar>} (| \texttt{src} (I)* \texttt{alpha} + \texttt{beta} |)
-
-In case of multi-channel arrays, the function processes each channel independently. When the output is not 8-bit, the operation can be emulated by calling the ``Mat::convertTo`` method (or by using matrix expressions) and then by calculating an absolute value of the result. For example: ::
-
- Mat_<float> A(30,30);
- randu(A, Scalar(-100), Scalar(100));
- Mat_<float> B = A*5 + 3;
- B = abs(B);
- // Mat_<float> B = abs(A*5+3) will also do the job,
- // but it will allocate a temporary matrix
-
-
-.. seealso::
-
- :ocv:func:`Mat::convertTo`,
- :ocv:func:`abs`
-
-
-
-countNonZero
-------------
-Counts non-zero array elements.
-
-.. ocv:function:: int countNonZero( InputArray src )
-
-.. ocv:pyfunction:: cv2.countNonZero(src) -> retval
-
-.. ocv:cfunction:: int cvCountNonZero(const CvArr* arr)
-
- :param src: single-channel array.
-
-The function returns the number of non-zero elements in ``src`` :
-
-.. math::
-
- \sum _{I: \; \texttt{src} (I) \ne0 } 1
-
-.. seealso::
-
- :ocv:func:`mean`,
- :ocv:func:`meanStdDev`,
- :ocv:func:`norm`,
- :ocv:func:`minMaxLoc`,
- :ocv:func:`calcCovarMatrix`
-
-
-
-cvarrToMat
-----------
-Converts ``CvMat``, ``IplImage`` , or ``CvMatND`` to ``Mat``.
-
-.. ocv:function:: Mat cvarrToMat( const CvArr* arr, bool copyData=false, bool allowND=true, int coiMode=0, AutoBuffer<double>* buf=0 )
-
- :param arr: input ``CvMat``, ``IplImage`` , or ``CvMatND``.
-
- :param copyData: when false (default value), no data is copied and only the new header is created, in this case, the original array should not be deallocated while the new matrix header is used; if the parameter is true, all the data is copied and you may deallocate the original array right after the conversion.
-
- :param allowND: when true (default value), ``CvMatND`` is converted to 2-dimensional ``Mat``, if it is possible (see the discussion below); if it is not possible, or when the parameter is false, the function will report an error.
-
- :param coiMode: parameter specifying how the IplImage COI (when set) is handled.
-
- * If ``coiMode=0`` and COI is set, the function reports an error.
-
- * If ``coiMode=1`` , the function never reports an error. Instead, it returns the header to the whole original image and you will have to check and process COI manually. See :ocv:func:`extractImageCOI` .
-
-The function ``cvarrToMat`` converts ``CvMat``, ``IplImage`` , or ``CvMatND`` header to
-:ocv:class:`Mat` header, and optionally duplicates the underlying data. The constructed header is returned by the function.
-
-When ``copyData=false`` , the conversion is done really fast (in O(1) time) and the newly created matrix header will have ``refcount=0`` , which means that no reference counting is done for the matrix data. In this case, you have to preserve the data until the new header is destructed. Otherwise, when ``copyData=true`` , the new buffer is allocated and managed as if you created a new matrix from scratch and copied the data there. That is, ``cvarrToMat(arr, true)`` is equivalent to ``cvarrToMat(arr, false).clone()`` (assuming that COI is not set). The function provides a uniform way of supporting
-``CvArr`` paradigm in the code that is migrated to use new-style data structures internally. The reverse transformation, from
-``Mat`` to
-``CvMat`` or
-``IplImage`` can be done by a simple assignment: ::
-
- CvMat* A = cvCreateMat(10, 10, CV_32F);
- cvSetIdentity(A);
- IplImage A1; cvGetImage(A, &A1);
- Mat B = cvarrToMat(A);
- Mat B1 = cvarrToMat(&A1);
- IplImage C = B;
- CvMat C1 = B1;
- // now A, A1, B, B1, C and C1 are different headers
- // for the same 10x10 floating-point array.
- // note that you will need to use "&"
- // to pass C & C1 to OpenCV functions, for example:
- printf("%g\n", cvNorm(&C1, 0, CV_L2));
-
-Normally, the function is used to convert an old-style 2D array (
-``CvMat`` or
-``IplImage`` ) to ``Mat`` . However, the function can also take
-``CvMatND`` as an input and create
-:ocv:func:`Mat` for it, if it is possible. And, for ``CvMatND A`` , it is possible if and only if ``A.dim[i].size*A.dim.step[i] == A.dim.step[i-1]`` for all or for all but one ``i, 0 < i < A.dims`` . That is, the matrix data should be continuous or it should be representable as a sequence of continuous matrices. By using this function in this way, you can process
-``CvMatND`` using an arbitrary element-wise function.
-
-The last parameter, ``coiMode`` , specifies how to deal with an image with COI set. By default, it is 0 and the function reports an error when an image with COI comes in. And ``coiMode=1`` means that no error is signalled. You have to check COI presence and handle it manually. The modern structures, such as
-:ocv:class:`Mat` and
-``MatND`` do not support COI natively. To process an individual channel of a new-style array, you need either to organize a loop over the array (for example, using matrix iterators) where the channel of interest will be processed, or extract the COI using
-:ocv:func:`mixChannels` (for new-style arrays) or
-:ocv:func:`extractImageCOI` (for old-style arrays), process this individual channel, and insert it back to the output array if needed (using
-:ocv:func:`mixChannels` or
-:ocv:func:`insertImageCOI` , respectively).
-
-.. seealso::
-
- :ocv:cfunc:`cvGetImage`,
- :ocv:cfunc:`cvGetMat`,
- :ocv:func:`extractImageCOI`,
- :ocv:func:`insertImageCOI`,
- :ocv:func:`mixChannels`
-
-dct
----
-Performs a forward or inverse discrete Cosine transform of 1D or 2D array.
-
-.. ocv:function:: void dct(InputArray src, OutputArray dst, int flags=0)
-
-.. ocv:pyfunction:: cv2.dct(src[, dst[, flags]]) -> dst
-
-.. ocv:cfunction:: void cvDCT(const CvArr* src, CvArr* dst, int flags)
-
- :param src: input floating-point array.
-
- :param dst: output array of the same size and type as ``src`` .
-
- :param flags: transformation flags as a combination of the following values:
-
- * **DCT_INVERSE** performs an inverse 1D or 2D transform instead of the default forward transform.
-
- * **DCT_ROWS** performs a forward or inverse transform of every individual row of the input matrix. This flag enables you to transform multiple vectors simultaneously and can be used to decrease the overhead (which is sometimes several times larger than the processing itself) to perform 3D and higher-dimensional transforms and so forth.
-
-The function ``dct`` performs a forward or inverse discrete Cosine transform (DCT) of a 1D or 2D floating-point array:
-
-*
- Forward Cosine transform of a 1D vector of ``N`` elements:
-
- .. math::
-
- Y = C^{(N)} \cdot X
-
- where
-
- .. math::
-
- C^{(N)}_{jk}= \sqrt{\alpha_j/N} \cos \left ( \frac{\pi(2k+1)j}{2N} \right )
-
- and
-
- :math:`\alpha_0=1`, :math:`\alpha_j=2` for *j > 0*.
-
-*
- Inverse Cosine transform of a 1D vector of ``N`` elements:
-
- .. math::
-
- X = \left (C^{(N)} \right )^{-1} \cdot Y = \left (C^{(N)} \right )^T \cdot Y
-
- (since
- :math:`C^{(N)}` is an orthogonal matrix,
- :math:`C^{(N)} \cdot \left(C^{(N)}\right)^T = I` )
-
-*
- Forward 2D Cosine transform of ``M x N`` matrix:
-
- .. math::
-
- Y = C^{(N)} \cdot X \cdot \left (C^{(N)} \right )^T
-
-*
- Inverse 2D Cosine transform of ``M x N`` matrix:
-
- .. math::
-
- X = \left (C^{(N)} \right )^T \cdot X \cdot C^{(N)}
-
-
-The function chooses the mode of operation by looking at the flags and size of the input array:
-
-*
- If ``(flags & DCT_INVERSE) == 0`` , the function does a forward 1D or 2D transform. Otherwise, it is an inverse 1D or 2D transform.
-
-*
- If ``(flags & DCT_ROWS) != 0`` , the function performs a 1D transform of each row.
-
-*
- If the array is a single column or a single row, the function performs a 1D transform.
-
-*
- If none of the above is true, the function performs a 2D transform.
-
-.. note::
-
- Currently ``dct`` supports even-size arrays (2, 4, 6 ...). For data analysis and approximation, you can pad the array when necessary.
-
- Also, the function performance depends very much, and not monotonically, on the array size (see
- :ocv:func:`getOptimalDFTSize` ). In the current implementation DCT of a vector of size ``N`` is calculated via DFT of a vector of size ``N/2`` . Thus, the optimal DCT size ``N1 >= N`` can be calculated as: ::
-
- size_t getOptimalDCTSize(size_t N) { return 2*getOptimalDFTSize((N+1)/2); }
- N1 = getOptimalDCTSize(N);
-
-.. seealso:: :ocv:func:`dft` , :ocv:func:`getOptimalDFTSize` , :ocv:func:`idct`
-
-
-
-dft
----
-Performs a forward or inverse Discrete Fourier transform of a 1D or 2D floating-point array.
-
-.. ocv:function:: void dft(InputArray src, OutputArray dst, int flags=0, int nonzeroRows=0)
-
-.. ocv:pyfunction:: cv2.dft(src[, dst[, flags[, nonzeroRows]]]) -> dst
-
-.. ocv:cfunction:: void cvDFT( const CvArr* src, CvArr* dst, int flags, int nonzero_rows=0 )
-
- :param src: input array that could be real or complex.
-
- :param dst: output array whose size and type depends on the ``flags`` .
-
- :param flags: transformation flags, representing a combination of the following values:
-
- * **DFT_INVERSE** performs an inverse 1D or 2D transform instead of the default forward transform.
-
- * **DFT_SCALE** scales the result: divide it by the number of array elements. Normally, it is combined with ``DFT_INVERSE``.
- * **DFT_ROWS** performs a forward or inverse transform of every individual row of the input matrix; this flag enables you to transform multiple vectors simultaneously and can be used to decrease the overhead (which is sometimes several times larger than the processing itself) to perform 3D and higher-dimensional transformations and so forth.
-
- * **DFT_COMPLEX_OUTPUT** performs a forward transformation of 1D or 2D real array; the result, though being a complex array, has complex-conjugate symmetry (*CCS*, see the function description below for details), and such an array can be packed into a real array of the same size as input, which is the fastest option and which is what the function does by default; however, you may wish to get a full complex array (for simpler spectrum analysis, and so on) - pass the flag to enable the function to produce a full-size complex output array.
-
- * **DFT_REAL_OUTPUT** performs an inverse transformation of a 1D or 2D complex array; the result is normally a complex array of the same size, however, if the input array has conjugate-complex symmetry (for example, it is a result of forward transformation with ``DFT_COMPLEX_OUTPUT`` flag), the output is a real array; while the function itself does not check whether the input is symmetrical or not, you can pass the flag and then the function will assume the symmetry and produce the real output array (note that when the input is packed into a real array and inverse transformation is executed, the function treats the input as a packed complex-conjugate symmetrical array, and the output will also be a real array).
-
- :param nonzeroRows: when the parameter is not zero, the function assumes that only the first ``nonzeroRows`` rows of the input array (``DFT_INVERSE`` is not set) or only the first ``nonzeroRows`` of the output array (``DFT_INVERSE`` is set) contain non-zeros, thus, the function can handle the rest of the rows more efficiently and save some time; this technique is very useful for calculating array cross-correlation or convolution using DFT.
-
-
-The function performs one of the following:
-
-*
- Forward the Fourier transform of a 1D vector of ``N`` elements:
-
- .. math::
-
- Y = F^{(N)} \cdot X,
-
- where
- :math:`F^{(N)}_{jk}=\exp(-2\pi i j k/N)` and
- :math:`i=\sqrt{-1}`
-
-*
- Inverse the Fourier transform of a 1D vector of ``N`` elements:
-
- .. math::
-
- \begin{array}{l} X'= \left (F^{(N)} \right )^{-1} \cdot Y = \left (F^{(N)} \right )^* \cdot y \\ X = (1/N) \cdot X, \end{array}
-
- where
- :math:`F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T`
-
-*
- Forward the 2D Fourier transform of a ``M x N`` matrix:
-
- .. math::
-
- Y = F^{(M)} \cdot X \cdot F^{(N)}
-
-*
- Inverse the 2D Fourier transform of a ``M x N`` matrix:
-
- .. math::
-
- \begin{array}{l} X'= \left (F^{(M)} \right )^* \cdot Y \cdot \left (F^{(N)} \right )^* \\ X = \frac{1}{M \cdot N} \cdot X' \end{array}
-
-
-In case of real (single-channel) data, the output spectrum of the forward Fourier transform or input spectrum of the inverse Fourier transform can be represented in a packed format called *CCS* (complex-conjugate-symmetrical). It was borrowed from IPL (Intel* Image Processing Library). Here is how 2D *CCS* spectrum looks:
-
-.. math::
-
- \begin{bmatrix} Re Y_{0,0} & Re Y_{0,1} & Im Y_{0,1} & Re Y_{0,2} & Im Y_{0,2} & \cdots & Re Y_{0,N/2-1} & Im Y_{0,N/2-1} & Re Y_{0,N/2} \\ Re Y_{1,0} & Re Y_{1,1} & Im Y_{1,1} & Re Y_{1,2} & Im Y_{1,2} & \cdots & Re Y_{1,N/2-1} & Im Y_{1,N/2-1} & Re Y_{1,N/2} \\ Im Y_{1,0} & Re Y_{2,1} & Im Y_{2,1} & Re Y_{2,2} & Im Y_{2,2} & \cdots & Re Y_{2,N/2-1} & Im Y_{2,N/2-1} & Im Y_{1,N/2} \\ \hdotsfor{9} \\ Re Y_{M/2-1,0} & Re Y_{M-3,1} & Im Y_{M-3,1} & \hdotsfor{3} & Re Y_{M-3,N/2-1} & Im Y_{M-3,N/2-1}& Re Y_{M/2-1,N/2} \\ Im Y_{M/2-1,0} & Re Y_{M-2,1} & Im Y_{M-2,1} & \hdotsfor{3} & Re Y_{M-2,N/2-1} & Im Y_{M-2,N/2-1}& Im Y_{M/2-1,N/2} \\ Re Y_{M/2,0} & Re Y_{M-1,1} & Im Y_{M-1,1} & \hdotsfor{3} & Re Y_{M-1,N/2-1} & Im Y_{M-1,N/2-1}& Re Y_{M/2,N/2} \end{bmatrix}
-
-In case of 1D transform of a real vector, the output looks like the first row of the matrix above.
-
-So, the function chooses an operation mode depending on the flags and size of the input array:
-
- * If ``DFT_ROWS`` is set or the input array has a single row or single column, the function performs a 1D forward or inverse transform of each row of a matrix when ``DFT_ROWS`` is set. Otherwise, it performs a 2D transform.
-
- * If the input array is real and ``DFT_INVERSE`` is not set, the function performs a forward 1D or 2D transform:
-
- * When ``DFT_COMPLEX_OUTPUT`` is set, the output is a complex matrix of the same size as input.
-
- * When ``DFT_COMPLEX_OUTPUT`` is not set, the output is a real matrix of the same size as input. In case of 2D transform, it uses the packed format as shown above. In case of a single 1D transform, it looks like the first row of the matrix above. In case of multiple 1D transforms (when using the ``DFT_ROWS`` flag), each row of the output matrix looks like the first row of the matrix above.
-
- * If the input array is complex and either ``DFT_INVERSE`` or ``DFT_REAL_OUTPUT`` are not set, the output is a complex array of the same size as input. The function performs a forward or inverse 1D or 2D transform of the whole input array or each row of the input array independently, depending on the flags ``DFT_INVERSE`` and ``DFT_ROWS``.
-
- * When ``DFT_INVERSE`` is set and the input array is real, or it is complex but ``DFT_REAL_OUTPUT`` is set, the output is a real array of the same size as input. The function performs a 1D or 2D inverse transformation of the whole input array or each individual row, depending on the flags ``DFT_INVERSE`` and ``DFT_ROWS``.
-
-If ``DFT_SCALE`` is set, the scaling is done after the transformation.
-
-Unlike :ocv:func:`dct` , the function supports arrays of arbitrary size. But only those arrays are processed efficiently, whose sizes can be factorized in a product of small prime numbers (2, 3, and 5 in the current implementation). Such an efficient DFT size can be calculated using the :ocv:func:`getOptimalDFTSize` method.
-
-The sample below illustrates how to calculate a DFT-based convolution of two 2D real arrays: ::
-
- void convolveDFT(InputArray A, InputArray B, OutputArray C)
- {
- // reallocate the output array if needed
- C.create(abs(A.rows - B.rows)+1, abs(A.cols - B.cols)+1, A.type());
- Size dftSize;
- // calculate the size of DFT transform
- dftSize.width = getOptimalDFTSize(A.cols + B.cols - 1);
- dftSize.height = getOptimalDFTSize(A.rows + B.rows - 1);
-
- // allocate temporary buffers and initialize them with 0's
- Mat tempA(dftSize, A.type(), Scalar::all(0));
- Mat tempB(dftSize, B.type(), Scalar::all(0));
-
- // copy A and B to the top-left corners of tempA and tempB, respectively
- Mat roiA(tempA, Rect(0,0,A.cols,A.rows));
- A.copyTo(roiA);
- Mat roiB(tempB, Rect(0,0,B.cols,B.rows));
- B.copyTo(roiB);
-
- // now transform the padded A & B in-place;
- // use "nonzeroRows" hint for faster processing
- dft(tempA, tempA, 0, A.rows);
- dft(tempB, tempB, 0, B.rows);
-
- // multiply the spectrums;
- // the function handles packed spectrum representations well
- mulSpectrums(tempA, tempB, tempA);
-
- // transform the product back from the frequency domain.
- // Even though all the result rows will be non-zero,
- // you need only the first C.rows of them, and thus you
- // pass nonzeroRows == C.rows
- dft(tempA, tempA, DFT_INVERSE + DFT_SCALE, C.rows);
-
- // now copy the result back to C.
- tempA(Rect(0, 0, C.cols, C.rows)).copyTo(C);
-
- // all the temporary buffers will be deallocated automatically
- }
-
-
-To optimize this sample, consider the following approaches:
-
-*
- Since ``nonzeroRows != 0`` is passed to the forward transform calls and since ``A`` and ``B`` are copied to the top-left corners of ``tempA`` and ``tempB``, respectively, it is not necessary to clear the whole ``tempA`` and ``tempB``. It is only necessary to clear the ``tempA.cols - A.cols`` ( ``tempB.cols - B.cols``) rightmost columns of the matrices.
-
-*
- This DFT-based convolution does not have to be applied to the whole big arrays, especially if ``B`` is significantly smaller than ``A`` or vice versa. Instead, you can calculate convolution by parts. To do this, you need to split the output array ``C`` into multiple tiles. For each tile, estimate which parts of ``A`` and ``B`` are required to calculate convolution in this tile. If the tiles in ``C`` are too small, the speed will decrease a lot because of repeated work. In the ultimate case, when each tile in ``C`` is a single pixel, the algorithm becomes equivalent to the naive convolution algorithm. If the tiles are too big, the temporary arrays ``tempA`` and ``tempB`` become too big and there is also a slowdown because of bad cache locality. So, there is an optimal tile size somewhere in the middle.
-
-*
- If different tiles in ``C`` can be calculated in parallel and, thus, the convolution is done by parts, the loop can be threaded.
-
-All of the above improvements have been implemented in :ocv:func:`matchTemplate` and :ocv:func:`filter2D` . Therefore, by using them, you can get the performance even better than with the above theoretically optimal implementation. Though, those two functions actually calculate cross-correlation, not convolution, so you need to "flip" the second convolution operand ``B`` vertically and horizontally using :ocv:func:`flip` .
-
-.. seealso:: :ocv:func:`dct` , :ocv:func:`getOptimalDFTSize` , :ocv:func:`mulSpectrums`, :ocv:func:`filter2D` , :ocv:func:`matchTemplate` , :ocv:func:`flip` , :ocv:func:`cartToPolar` , :ocv:func:`magnitude` , :ocv:func:`phase`
-
-.. note::
-
- * An example using the discrete fourier transform can be found at opencv_source_code/samples/cpp/dft.cpp
-
- * (Python) An example using the dft functionality to perform Wiener deconvolution can be found at opencv_source/samples/python2/deconvolution.py
- * (Python) An example rearranging the quadrants of a Fourier image can be found at opencv_source/samples/python2/dft.py
-
-
-divide
-------
-Performs per-element division of two arrays or a scalar by an array.
-
-.. ocv:function:: void divide(InputArray src1, InputArray src2, OutputArray dst, double scale=1, int dtype=-1)
-
-.. ocv:function:: void divide(double scale, InputArray src2, OutputArray dst, int dtype=-1)
-
-.. ocv:pyfunction:: cv2.divide(src1, src2[, dst[, scale[, dtype]]]) -> dst
-.. ocv:pyfunction:: cv2.divide(scale, src2[, dst[, dtype]]) -> dst
-
-.. ocv:cfunction:: void cvDiv(const CvArr* src1, const CvArr* src2, CvArr* dst, double scale=1)
-
- :param src1: first input array.
-
- :param src2: second input array of the same size and type as ``src1``.
-
- :param scale: scalar factor.
-
- :param dst: output array of the same size and type as ``src2``.
-
- :param dtype: optional depth of the output array; if ``-1``, ``dst`` will have depth ``src2.depth()``, but in case of an array-by-array division, you can only pass ``-1`` when ``src1.depth()==src2.depth()``.
-
-The functions ``divide`` divide one array by another:
-
-.. math::
-
- \texttt{dst(I) = saturate(src1(I)*scale/src2(I))}
-
-or a scalar by an array when there is no ``src1`` :
-
-.. math::
-
- \texttt{dst(I) = saturate(scale/src2(I))}
-
-When ``src2(I)`` is zero, ``dst(I)`` will also be zero. Different channels of multi-channel arrays are processed independently.
-
-.. note:: Saturation is not applied when the output array has the depth ``CV_32S``. You may even get result of an incorrect sign in the case of overflow.
-
-.. seealso::
-
- :ocv:func:`multiply`,
- :ocv:func:`add`,
- :ocv:func:`subtract`,
- :ref:`MatrixExpressions`
-
-
-
-determinant
------------
-Returns the determinant of a square floating-point matrix.
-
-.. ocv:function:: double determinant(InputArray mtx)
-
-.. ocv:pyfunction:: cv2.determinant(mtx) -> retval
-
-.. ocv:cfunction:: double cvDet( const CvArr* mat )
-
- :param mtx: input matrix that must have ``CV_32FC1`` or ``CV_64FC1`` type and square size.
-
- :param mat: input matrix that must have ``CV_32FC1`` or ``CV_64FC1`` type and square size.
-
-The function ``determinant`` calculates and returns the determinant of the specified matrix. For small matrices ( ``mtx.cols=mtx.rows<=3`` ),
-the direct method is used. For larger matrices, the function uses LU factorization with partial pivoting.
-
-For symmetric positively-determined matrices, it is also possible to use :ocv:func:`eigen` decomposition to calculate the determinant.
-
-.. seealso::
-
- :ocv:func:`trace`,
- :ocv:func:`invert`,
- :ocv:func:`solve`,
- :ocv:func:`eigen`,
- :ref:`MatrixExpressions`
-
-
-
-eigen
------
-Calculates eigenvalues and eigenvectors of a symmetric matrix.
-
-.. ocv:function:: bool eigen( InputArray src, OutputArray eigenvalues, OutputArray eigenvectors=noArray() )
-
-.. ocv:pyfunction:: cv2.eigen(src[, eigenvalues[, eigenvectors]]) -> retval, eigenvalues, eigenvectors
-
-.. ocv:cfunction:: void cvEigenVV( CvArr* mat, CvArr* evects, CvArr* evals, double eps=0, int lowindex=-1, int highindex=-1 )
-
- :param src: input matrix that must have ``CV_32FC1`` or ``CV_64FC1`` type, square size and be symmetrical (``src`` :sup:`T` == ``src``).
-
- :param eigenvalues: output vector of eigenvalues of the same type as ``src``; the eigenvalues are stored in the descending order.
-
- :param eigenvectors: output matrix of eigenvectors; it has the same size and type as ``src``; the eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding eigenvalues.
-
- :param lowindex: optional index of largest eigenvalue/-vector to calculate; the parameter is ignored in the current implementation.
-
- :param highindex: optional index of smallest eigenvalue/-vector to calculate; the parameter is ignored in the current implementation.
-
-The functions ``eigen`` calculate just eigenvalues, or eigenvalues and eigenvectors of the symmetric matrix ``src`` : ::
-
- src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()
-
-.. note:: in the new and the old interfaces different ordering of eigenvalues and eigenvectors parameters is used.
-
-.. seealso:: :ocv:func:`completeSymm` , :ocv:class:`PCA`
-
-
-
-exp
----
-Calculates the exponent of every array element.
-
-.. ocv:function:: void exp(InputArray src, OutputArray dst)
-
-.. ocv:pyfunction:: cv2.exp(src[, dst]) -> dst
-
-.. ocv:cfunction:: void cvExp(const CvArr* src, CvArr* dst)
-
- :param src: input array.
-
- :param dst: output array of the same size and type as ``src``.
-
-The function ``exp`` calculates the exponent of every element of the input array:
-
-.. math::
-
- \texttt{dst} [I] = e^{ src(I) }
-
-The maximum relative error is about ``7e-6`` for single-precision input and less than ``1e-10`` for double-precision input. Currently, the function converts denormalized values to zeros on output. Special values (NaN, Inf) are not handled.
-
-.. seealso:: :ocv:func:`log` , :ocv:func:`cartToPolar` , :ocv:func:`polarToCart` , :ocv:func:`phase` , :ocv:func:`pow` , :ocv:func:`sqrt` , :ocv:func:`magnitude`
-
-
-
-extractImageCOI
----------------
-Extracts the selected image channel.
-
-.. ocv:function:: void extractImageCOI( const CvArr* arr, OutputArray coiimg, int coi=-1 )
-
- :param arr: input array; it should be a pointer to ``CvMat`` or ``IplImage``.
-
- :param coiimg: output array with a single channel and the same size and depth as ``arr``.
-
- :param coi: if the parameter is ``>=0``, it specifies the channel to extract, if it is ``<0`` and ``arr`` is a pointer to ``IplImage`` with a valid COI set, the selected COI is extracted.
-
-The function ``extractImageCOI`` is used to extract an image COI from an old-style array and put the result to the new-style C++ matrix. As usual, the output matrix is reallocated using ``Mat::create`` if needed.
-
-To extract a channel from a new-style matrix, use
-:ocv:func:`mixChannels` or
-:ocv:func:`split` .
-
-.. seealso:: :ocv:func:`mixChannels` , :ocv:func:`split` , :ocv:func:`merge` , :ocv:func:`cvarrToMat` , :ocv:cfunc:`cvSetImageCOI` , :ocv:cfunc:`cvGetImageCOI`
-
-
-insertImageCOI
---------------
-Copies the selected image channel from a new-style C++ matrix to the old-style C array.
-
-.. ocv:function:: void insertImageCOI( InputArray coiimg, CvArr* arr, int coi=-1 )
-
- :param coiimg: input array with a single channel and the same size and depth as ``arr``.
-
- :param arr: output array, it should be a pointer to ``CvMat`` or ``IplImage``.
-
- :param coi: if the parameter is ``>=0``, it specifies the channel to insert, if it is ``<0`` and ``arr`` is a pointer to ``IplImage`` with a valid COI set, the selected COI is extracted.
-
-The function ``insertImageCOI`` is used to extract an image COI from a new-style C++ matrix and put the result to the old-style array.
-
-The sample below illustrates how to use the function:
-::
-
- Mat temp(240, 320, CV_8UC1, Scalar(255));
- IplImage* img = cvCreateImage(cvSize(320,240), IPL_DEPTH_8U, 3);
- insertImageCOI(temp, img, 1); //insert to the first channel
- cvNamedWindow("window",1);
- cvShowImage("window", img); //you should see green image, because channel number 1 is green (BGR)
- cvWaitKey(0);
- cvDestroyAllWindows();
- cvReleaseImage(&img);
-
-To insert a channel to a new-style matrix, use
-:ocv:func:`merge` .
-
-.. seealso:: :ocv:func:`mixChannels` , :ocv:func:`split` , :ocv:func:`merge` , :ocv:func:`cvarrToMat` , :ocv:cfunc:`cvSetImageCOI` , :ocv:cfunc:`cvGetImageCOI`
-
-
-flip
-----
-Flips a 2D array around vertical, horizontal, or both axes.
-
-.. ocv:function:: void flip(InputArray src, OutputArray dst, int flipCode)
-
-.. ocv:pyfunction:: cv2.flip(src, flipCode[, dst]) -> dst
-
-.. ocv:cfunction:: void cvFlip( const CvArr* src, CvArr* dst=NULL, int flip_mode=0 )
-
- :param src: input array.
-
- :param dst: output array of the same size and type as ``src``.
-
- :param flipCode: a flag to specify how to flip the array; 0 means flipping around the x-axis and positive value (for example, 1) means flipping around y-axis. Negative value (for example, -1) means flipping around both axes (see the discussion below for the formulas).
-
-The function ``flip`` flips the array in one of three different ways (row and column indices are 0-based):
-
-.. math::
-
- \texttt{dst} _{ij} =
- \left\{
- \begin{array}{l l}
- \texttt{src} _{\texttt{src.rows}-i-1,j} & if\; \texttt{flipCode} = 0 \\
- \texttt{src} _{i, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} > 0 \\
- \texttt{src} _{ \texttt{src.rows} -i-1, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} < 0 \\
- \end{array}
- \right.
-
-The example scenarios of using the function are the following:
-
- *
- Vertical flipping of the image (``flipCode == 0``) to switch between top-left and bottom-left image origin. This is a typical operation in video processing on Microsoft Windows* OS.
-
- *
- Horizontal flipping of the image with the subsequent horizontal shift and absolute difference calculation to check for a vertical-axis symmetry (``flipCode > 0``).
-
- *
- Simultaneous horizontal and vertical flipping of the image with the subsequent shift and absolute difference calculation to check for a central symmetry (``flipCode < 0``).
-
- *
- Reversing the order of point arrays (``flipCode > 0`` or ``flipCode == 0``).
-
-.. seealso:: :ocv:func:`transpose` , :ocv:func:`repeat` , :ocv:func:`completeSymm`
-
-
-
-gemm
-----
-Performs generalized matrix multiplication.
-
-.. ocv:function:: void gemm( InputArray src1, InputArray src2, double alpha, InputArray src3, double beta, OutputArray dst, int flags=0 )
-
-.. ocv:pyfunction:: cv2.gemm(src1, src2, alpha, src3, beta[, dst[, flags]]) -> dst
-
-.. ocv:cfunction:: void cvGEMM( const CvArr* src1, const CvArr* src2, double alpha, const CvArr* src3, double beta, CvArr* dst, int tABC=0)
-
- :param src1: first multiplied input matrix that could be real(``CV_32FC1``, ``CV_64FC1``) or complex(``CV_32FC2``, ``CV_64FC2``).
-
- :param src2: second multiplied input matrix of the same type as ``src1``.
-
- :param alpha: weight of the matrix product.
-
- :param src3: third optional delta matrix added to the matrix product; it should have the same type as ``src1`` and ``src2``.
-
- :param beta: weight of ``src3``.
-
- :param dst: output matrix; it has the proper size and the same type as input matrices.
-
- :param flags: operation flags:
-
- * **GEMM_1_T** transposes ``src1``.
- * **GEMM_2_T** transposes ``src2``.
- * **GEMM_3_T** transposes ``src3``.
-
-The function performs generalized matrix multiplication similar to the ``gemm`` functions in BLAS level 3. For example, ``gemm(src1, src2, alpha, src3, beta, dst, GEMM_1_T + GEMM_3_T)`` corresponds to
-
-.. math::
-
- \texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T
-
-In case of complex (two-channel) data, performed a complex matrix multiplication.
-
-The function can be replaced with a matrix expression. For example, the above call can be replaced with: ::
-
- dst = alpha*src1.t()*src2 + beta*src3.t();
-
-
-.. seealso:: :ocv:func:`mulTransposed` , :ocv:func:`transform` , :ref:`MatrixExpressions`
-
-
-
-getOptimalDFTSize
------------------
-Returns the optimal DFT size for a given vector size.
-
-.. ocv:function:: int getOptimalDFTSize(int vecsize)
-
-.. ocv:pyfunction:: cv2.getOptimalDFTSize(vecsize) -> retval
-
-.. ocv:cfunction:: int cvGetOptimalDFTSize(int size0)
-
- :param vecsize: vector size.
-
-DFT performance is not a monotonic function of a vector size. Therefore, when you calculate convolution of two arrays or perform the spectral analysis of an array, it usually makes sense to pad the input data with zeros to get a bit larger array that can be transformed much faster than the original one.
-Arrays whose size is a power-of-two (2, 4, 8, 16, 32, ...) are the fastest to process. Though, the arrays whose size is a product of 2's, 3's, and 5's (for example, 300 = 5*5*3*2*2) are also processed quite efficiently.
-
-The function ``getOptimalDFTSize`` returns the minimum number ``N`` that is greater than or equal to ``vecsize`` so that the DFT of a vector of size ``N`` can be processed efficiently. In the current implementation ``N`` = 2 :sup:`p` * 3 :sup:`q` * 5 :sup:`r` for some integer ``p``, ``q``, ``r``.
-
-The function returns a negative number if ``vecsize`` is too large (very close to ``INT_MAX`` ).
-
-While the function cannot be used directly to estimate the optimal vector size for DCT transform (since the current DCT implementation supports only even-size vectors), it can be easily processed as ``getOptimalDFTSize((vecsize+1)/2)*2``.
-
-.. seealso:: :ocv:func:`dft` , :ocv:func:`dct` , :ocv:func:`idft` , :ocv:func:`idct` , :ocv:func:`mulSpectrums`
-
-
-
-idct
-----
-Calculates the inverse Discrete Cosine Transform of a 1D or 2D array.
-
-.. ocv:function:: void idct(InputArray src, OutputArray dst, int flags=0)
-
-.. ocv:pyfunction:: cv2.idct(src[, dst[, flags]]) -> dst
-
- :param src: input floating-point single-channel array.
-
- :param dst: output array of the same size and type as ``src``.
-
- :param flags: operation flags.
-
-``idct(src, dst, flags)`` is equivalent to ``dct(src, dst, flags | DCT_INVERSE)``.
-
-.. seealso::
-
- :ocv:func:`dct`,
- :ocv:func:`dft`,
- :ocv:func:`idft`,
- :ocv:func:`getOptimalDFTSize`
-
-
-
-idft
-----
-Calculates the inverse Discrete Fourier Transform of a 1D or 2D array.
-
-.. ocv:function:: void idft(InputArray src, OutputArray dst, int flags=0, int nonzeroRows=0)
-
-.. ocv:pyfunction:: cv2.idft(src[, dst[, flags[, nonzeroRows]]]) -> dst
-
- :param src: input floating-point real or complex array.
-
- :param dst: output array whose size and type depend on the ``flags``.
-
- :param flags: operation flags (see :ocv:func:`dft`).
-
- :param nonzeroRows: number of ``dst`` rows to process; the rest of the rows have undefined content (see the convolution sample in :ocv:func:`dft` description.
-
-``idft(src, dst, flags)`` is equivalent to ``dft(src, dst, flags | DFT_INVERSE)`` .
-
-See :ocv:func:`dft` for details.
-
-.. note:: None of ``dft`` and ``idft`` scales the result by default. So, you should pass ``DFT_SCALE`` to one of ``dft`` or ``idft`` explicitly to make these transforms mutually inverse.
-
-.. seealso::
-
- :ocv:func:`dft`,
- :ocv:func:`dct`,
- :ocv:func:`idct`,
- :ocv:func:`mulSpectrums`,
- :ocv:func:`getOptimalDFTSize`
-
-
-
-inRange
--------
-Checks if array elements lie between the elements of two other arrays.
-
-.. ocv:function:: void inRange(InputArray src, InputArray lowerb, InputArray upperb, OutputArray dst)
-
-.. ocv:pyfunction:: cv2.inRange(src, lowerb, upperb[, dst]) -> dst
-
-.. ocv:cfunction:: void cvInRange(const CvArr* src, const CvArr* lower, const CvArr* upper, CvArr* dst)
-.. ocv:cfunction:: void cvInRangeS(const CvArr* src, CvScalar lower, CvScalar upper, CvArr* dst)
-
- :param src: first input array.
-
- :param lowerb: inclusive lower boundary array or a scalar.
-
- :param upperb: inclusive upper boundary array or a scalar.
-
- :param dst: output array of the same size as ``src`` and ``CV_8U`` type.
-
-The function checks the range as follows:
-
- * For every element of a single-channel input array:
-
- .. math::
-
- \texttt{dst} (I)= \texttt{lowerb} (I)_0 \leq \texttt{src} (I)_0 \leq \texttt{upperb} (I)_0
-
- * For two-channel arrays:
-
- .. math::
-
- \texttt{dst} (I)= \texttt{lowerb} (I)_0 \leq \texttt{src} (I)_0 \leq \texttt{upperb} (I)_0 \land \texttt{lowerb} (I)_1 \leq \texttt{src} (I)_1 \leq \texttt{upperb} (I)_1
-
- * and so forth.
-
-That is, ``dst`` (I) is set to 255 (all ``1`` -bits) if ``src`` (I) is within the specified 1D, 2D, 3D, ... box and 0 otherwise.
-
-When the lower and/or upper boundary parameters are scalars, the indexes ``(I)`` at ``lowerb`` and ``upperb`` in the above formulas should be omitted.
-
-
-invert
-------
-Finds the inverse or pseudo-inverse of a matrix.
-
-.. ocv:function:: double invert(InputArray src, OutputArray dst, int flags=DECOMP_LU)
-
-.. ocv:pyfunction:: cv2.invert(src[, dst[, flags]]) -> retval, dst
-
-.. ocv:cfunction:: double cvInvert( const CvArr* src, CvArr* dst, int method=CV_LU )
-
- :param src: input floating-point ``M x N`` matrix.
-
- :param dst: output matrix of ``N x M`` size and the same type as ``src``.
-
- :param flags: inversion method :
-
- * **DECOMP_LU** Gaussian elimination with the optimal pivot element chosen.
-
- * **DECOMP_SVD** singular value decomposition (SVD) method.
-
- * **DECOMP_CHOLESKY** Cholesky decomposition; the matrix must be symmetrical and positively defined.
-
-The function ``invert`` inverts the matrix ``src`` and stores the result in ``dst`` .
-When the matrix ``src`` is singular or non-square, the function calculates the pseudo-inverse matrix (the ``dst`` matrix) so that ``norm(src*dst - I)`` is minimal, where I is an identity matrix.
-
-In case of the ``DECOMP_LU`` method, the function returns non-zero value if the inverse has been successfully calculated and 0 if ``src`` is singular.
-
-In case of the ``DECOMP_SVD`` method, the function returns the inverse condition number of ``src`` (the ratio of the smallest singular value to the largest singular value) and 0 if ``src`` is singular. The SVD method calculates a pseudo-inverse matrix if ``src`` is singular.
-
-Similarly to ``DECOMP_LU`` , the method ``DECOMP_CHOLESKY`` works only with non-singular square matrices that should also be symmetrical and positively defined. In this case, the function stores the inverted matrix in ``dst`` and returns non-zero. Otherwise, it returns 0.
-
-.. seealso::
-
- :ocv:func:`solve`,
- :ocv:class:`SVD`
-
-
-
-log
----
-Calculates the natural logarithm of every array element.
-
-.. ocv:function:: void log(InputArray src, OutputArray dst)
-
-.. ocv:pyfunction:: cv2.log(src[, dst]) -> dst
-
-.. ocv:cfunction:: void cvLog(const CvArr* src, CvArr* dst)
-
- :param src: input array.
-
- :param dst: output array of the same size and type as ``src`` .
-
-The function ``log`` calculates the natural logarithm of the absolute value of every element of the input array:
-
-.. math::
-
- \texttt{dst} (I) = \fork{\log |\texttt{src}(I)|}{if $\texttt{src}(I) \ne 0$ }{\texttt{C}}{otherwise}
-
-where ``C`` is a large negative number (about -700 in the current implementation).
-The maximum relative error is about ``7e-6`` for single-precision input and less than ``1e-10`` for double-precision input. Special values (NaN, Inf) are not handled.
-
-.. seealso::
-
- :ocv:func:`exp`,
- :ocv:func:`cartToPolar`,
- :ocv:func:`polarToCart`,
- :ocv:func:`phase`,
- :ocv:func:`pow`,
- :ocv:func:`sqrt`,
- :ocv:func:`magnitude`
-
-
-
-LUT
----
-Performs a look-up table transform of an array.
-
-.. ocv:function:: void LUT( InputArray src, InputArray lut, OutputArray dst )
-
-.. ocv:pyfunction:: cv2.LUT(src, lut[, dst]) -> dst
-
-.. ocv:cfunction:: void cvLUT(const CvArr* src, CvArr* dst, const CvArr* lut)
-
- :param src: input array of 8-bit elements.
-
- :param lut: look-up table of 256 elements; in case of multi-channel input array, the table should either have a single channel (in this case the same table is used for all channels) or the same number of channels as in the input array.
-
- :param dst: output array of the same size and number of channels as ``src``, and the same depth as ``lut``.
-
-The function ``LUT`` fills the output array with values from the look-up table. Indices of the entries are taken from the input array. That is, the function processes each element of ``src`` as follows:
-
-.. math::
-
- \texttt{dst} (I) \leftarrow \texttt{lut(src(I) + d)}
-
-where
-
-.. math::
-
- d = \fork{0}{if \texttt{src} has depth \texttt{CV\_8U}}{128}{if \texttt{src} has depth \texttt{CV\_8S}}
-
-.. seealso::
-
- :ocv:func:`convertScaleAbs`,
- :ocv:func:`Mat::convertTo`
-
-
-
-magnitude
----------
-Calculates the magnitude of 2D vectors.
-
-.. ocv:function:: void magnitude(InputArray x, InputArray y, OutputArray magnitude)
-
-.. ocv:pyfunction:: cv2.magnitude(x, y[, magnitude]) -> magnitude
-
- :param x: floating-point array of x-coordinates of the vectors.
-
- :param y: floating-point array of y-coordinates of the vectors; it must have the same size as ``x``.
-
- :param magnitude: output array of the same size and type as ``x``.
-
-The function ``magnitude`` calculates the magnitude of 2D vectors formed from the corresponding elements of ``x`` and ``y`` arrays:
-
-.. math::
-
- \texttt{dst} (I) = \sqrt{\texttt{x}(I)^2 + \texttt{y}(I)^2}
-
-.. seealso::
-
- :ocv:func:`cartToPolar`,
- :ocv:func:`polarToCart`,
- :ocv:func:`phase`,
- :ocv:func:`sqrt`
-
-
-
-Mahalanobis
------------
-Calculates the Mahalanobis distance between two vectors.
-
-.. ocv:function:: double Mahalanobis( InputArray v1, InputArray v2, InputArray icovar )
-
-.. ocv:pyfunction:: cv2.Mahalanobis(v1, v2, icovar) -> retval
-
-.. ocv:cfunction:: double cvMahalanobis( const CvArr* vec1, const CvArr* vec2, const CvArr* mat )
-
- :param vec1: first 1D input vector.
-
- :param vec2: second 1D input vector.
-
- :param icovar: inverse covariance matrix.
-
-The function ``Mahalanobis`` calculates and returns the weighted distance between two vectors:
-
-.. math::
-
- d( \texttt{vec1} , \texttt{vec2} )= \sqrt{\sum_{i,j}{\texttt{icovar(i,j)}\cdot(\texttt{vec1}(I)-\texttt{vec2}(I))\cdot(\texttt{vec1(j)}-\texttt{vec2(j)})} }
-
-The covariance matrix may be calculated using the
-:ocv:func:`calcCovarMatrix` function and then inverted using the
-:ocv:func:`invert` function (preferably using the ``DECOMP_SVD`` method, as the most accurate).
-
-
-
-max
----
-Calculates per-element maximum of two arrays or an array and a scalar.
-
-.. ocv:function:: MatExpr max( const Mat& a, const Mat& b )
-
-.. ocv:function:: MatExpr max( const Mat& a, double s )
-
-.. ocv:function:: MatExpr max( double s, const Mat& a )
-
-.. ocv:function:: void max(InputArray src1, InputArray src2, OutputArray dst)
-
-.. ocv:function:: void max(const Mat& src1, const Mat& src2, Mat& dst)
-
-.. ocv:pyfunction:: cv2.max(src1, src2[, dst]) -> dst
-
-.. ocv:cfunction:: void cvMax(const CvArr* src1, const CvArr* src2, CvArr* dst)
-.. ocv:cfunction:: void cvMaxS(const CvArr* src, double value, CvArr* dst)
-
- :param src1: first input array.
-
- :param src2: second input array of the same size and type as ``src1`` .
-
- :param value: real scalar value.
-
- :param dst: output array of the same size and type as ``src1``.
-
-The functions ``max`` calculate the per-element maximum of two arrays:
-
-.. math::
-
- \texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{src2} (I))
-
-or array and a scalar:
-
-.. math::
-
- \texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{value} )
-
-In the second variant, when the input array is multi-channel, each channel is compared with ``value`` independently.
-
-The first 3 variants of the function listed above are actually a part of
-:ref:`MatrixExpressions` . They return an expression object that can be further either transformed/ assigned to a matrix, or passed to a function, and so on.
-
-.. seealso::
-
- :ocv:func:`min`,
- :ocv:func:`compare`,
- :ocv:func:`inRange`,
- :ocv:func:`minMaxLoc`,
- :ref:`MatrixExpressions`
-
-
-mean
-----
-Calculates an average (mean) of array elements.
-
-.. ocv:function:: Scalar mean(InputArray src, InputArray mask=noArray())
-
-.. ocv:pyfunction:: cv2.mean(src[, mask]) -> retval
-
-.. ocv:cfunction:: CvScalar cvAvg( const CvArr* arr, const CvArr* mask=NULL )
-
- :param src: input array that should have from 1 to 4 channels so that the result can be stored in :ocv:class:`Scalar_` .
-
- :param mask: optional operation mask.
-
-The function ``mean`` calculates the mean value ``M`` of array elements, independently for each channel, and return it:
-
-.. math::
-
- \begin{array}{l} N = \sum _{I: \; \texttt{mask} (I) \ne 0} 1 \\ M_c = \left ( \sum _{I: \; \texttt{mask} (I) \ne 0}{ \texttt{mtx} (I)_c} \right )/N \end{array}
-
-When all the mask elements are 0's, the functions return ``Scalar::all(0)`` .
-
-.. seealso::
-
- :ocv:func:`countNonZero`,
- :ocv:func:`meanStdDev`,
- :ocv:func:`norm`,
- :ocv:func:`minMaxLoc`
-
-
-
-meanStdDev
-----------
-Calculates a mean and standard deviation of array elements.
-
-.. ocv:function:: void meanStdDev(InputArray src, OutputArray mean, OutputArray stddev, InputArray mask=noArray())
-
-.. ocv:pyfunction:: cv2.meanStdDev(src[, mean[, stddev[, mask]]]) -> mean, stddev
-
-.. ocv:cfunction:: void cvAvgSdv( const CvArr* arr, CvScalar* mean, CvScalar* std_dev, const CvArr* mask=NULL )
-
- :param src: input array that should have from 1 to 4 channels so that the results can be stored in :ocv:class:`Scalar_` 's.
-
- :param mean: output parameter: calculated mean value.
-
- :param stddev: output parameter: calculateded standard deviation.
-
- :param mask: optional operation mask.
-
-The function ``meanStdDev`` calculates the mean and the standard deviation ``M`` of array elements independently for each channel and returns it via the output parameters:
-
-.. math::
-
- \begin{array}{l} N = \sum _{I, \texttt{mask} (I) \ne 0} 1 \\ \texttt{mean} _c = \frac{\sum_{ I: \; \texttt{mask}(I) \ne 0} \texttt{src} (I)_c}{N} \\ \texttt{stddev} _c = \sqrt{\frac{\sum_{ I: \; \texttt{mask}(I) \ne 0} \left ( \texttt{src} (I)_c - \texttt{mean} _c \right )^2}{N}} \end{array}
-
-When all the mask elements are 0's, the functions return ``mean=stddev=Scalar::all(0)`` .
-
-.. note:: The calculated standard deviation is only the diagonal of the complete normalized covariance matrix. If the full matrix is needed, you can reshape the multi-channel array ``M x N`` to the single-channel array ``M*N x mtx.channels()`` (only possible when the matrix is continuous) and then pass the matrix to :ocv:func:`calcCovarMatrix` .
-
-.. seealso::
-
- :ocv:func:`countNonZero`,
- :ocv:func:`mean`,
- :ocv:func:`norm`,
- :ocv:func:`minMaxLoc`,
- :ocv:func:`calcCovarMatrix`
-
-
-
-merge
------
-Creates one multichannel array out of several single-channel ones.
-
-.. ocv:function:: void merge(const Mat* mv, size_t count, OutputArray dst)
-
-.. ocv:function:: void merge( InputArrayOfArrays mv, OutputArray dst )
-
-.. ocv:pyfunction:: cv2.merge(mv[, dst]) -> dst
-
-.. ocv:cfunction:: void cvMerge(const CvArr* src0, const CvArr* src1, const CvArr* src2, const CvArr* src3, CvArr* dst)
-
- :param mv: input array or vector of matrices to be merged; all the matrices in ``mv`` must have the same size and the same depth.
-
- :param count: number of input matrices when ``mv`` is a plain C array; it must be greater than zero.
-
- :param dst: output array of the same size and the same depth as ``mv[0]``; The number of channels will be the total number of channels in the matrix array.
-
-The functions ``merge`` merge several arrays to make a single multi-channel array. That is, each element of the output array will be a concatenation of the elements of the input arrays, where elements of i-th input array are treated as ``mv[i].channels()``-element vectors.
-
-The function
-:ocv:func:`split` does the reverse operation. If you need to shuffle channels in some other advanced way, use
-:ocv:func:`mixChannels` .
-
-.. seealso::
-
- :ocv:func:`mixChannels`,
- :ocv:func:`split`,
- :ocv:func:`Mat::reshape`
-
-
-
-min
----
-Calculates per-element minimum of two arrays or an array and a scalar.
-
-.. ocv:function:: MatExpr min( const Mat& a, const Mat& b )
-
-.. ocv:function:: MatExpr min( const Mat& a, double s )
-
-.. ocv:function:: MatExpr min( double s, const Mat& a )
-
-.. ocv:function:: void min(InputArray src1, InputArray src2, OutputArray dst)
-
-.. ocv:function:: void min(const Mat& src1, const Mat& src2, Mat& dst)
-
-.. ocv:pyfunction:: cv2.min(src1, src2[, dst]) -> dst
-
-.. ocv:cfunction:: void cvMin(const CvArr* src1, const CvArr* src2, CvArr* dst)
-.. ocv:cfunction:: void cvMinS(const CvArr* src, double value, CvArr* dst)
-
- :param src1: first input array.
-
- :param src2: second input array of the same size and type as ``src1``.
-
- :param value: real scalar value.
-
- :param dst: output array of the same size and type as ``src1``.
-
-The functions ``min`` calculate the per-element minimum of two arrays:
-
-.. math::
-
- \texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{src2} (I))
-
-or array and a scalar:
-
-.. math::
-
- \texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{value} )
-
-In the second variant, when the input array is multi-channel, each channel is compared with ``value`` independently.
-
-The first three variants of the function listed above are actually a part of
-:ref:`MatrixExpressions` . They return the expression object that can be further either transformed/assigned to a matrix, or passed to a function, and so on.
-
-.. seealso::
-
- :ocv:func:`max`,
- :ocv:func:`compare`,
- :ocv:func:`inRange`,
- :ocv:func:`minMaxLoc`,
- :ref:`MatrixExpressions`
-
-
-minMaxIdx
----------
-Finds the global minimum and maximum in an array
-
-.. ocv:function:: void minMaxIdx(InputArray src, double* minVal, double* maxVal = 0, int* minIdx=0, int* maxIdx=0, InputArray mask=noArray())
-
- :param src: input single-channel array.
-
- :param minVal: pointer to the returned minimum value; ``NULL`` is used if not required.
-
- :param maxVal: pointer to the returned maximum value; ``NULL`` is used if not required.
-
- :param minIdx: pointer to the returned minimum location (in nD case); ``NULL`` is used if not required; Otherwise, it must point to an array of ``src.dims`` elements, the coordinates of the minimum element in each dimension are stored there sequentially.
-
- .. note::
-
- When ``minIdx`` is not NULL, it must have at least 2 elements (as well as ``maxIdx``), even if ``src`` is a single-row or single-column matrix. In OpenCV (following MATLAB) each array has at least 2 dimensions, i.e. single-column matrix is ``Mx1`` matrix (and therefore ``minIdx``/``maxIdx`` will be ``(i1,0)``/``(i2,0)``) and single-row matrix is ``1xN`` matrix (and therefore ``minIdx``/``maxIdx`` will be ``(0,j1)``/``(0,j2)``).
-
- :param maxIdx: pointer to the returned maximum location (in nD case). ``NULL`` is used if not required.
-
- The function ``minMaxIdx`` finds the minimum and maximum element values and their positions. The extremums are searched across the whole array or, if ``mask`` is not an empty array, in the specified array region.
-
- The function does not work with multi-channel arrays. If you need to find minimum or maximum elements across all the channels, use
- :ocv:func:`Mat::reshape` first to reinterpret the array as single-channel. Or you may extract the particular channel using either
- :ocv:func:`extractImageCOI` , or
- :ocv:func:`mixChannels` , or
- :ocv:func:`split` .
-
- In case of a sparse matrix, the minimum is found among non-zero elements only.
-
-
-
-minMaxLoc
----------
-Finds the global minimum and maximum in an array.
-
-.. ocv:function:: void minMaxLoc(InputArray src, double* minVal, double* maxVal=0, Point* minLoc=0, Point* maxLoc=0, InputArray mask=noArray())
-
-.. ocv:function:: void minMaxLoc( const SparseMat& a, double* minVal, double* maxVal, int* minIdx=0, int* maxIdx=0 )
-
-.. ocv:pyfunction:: cv2.minMaxLoc(src[, mask]) -> minVal, maxVal, minLoc, maxLoc
-
-.. ocv:cfunction:: void cvMinMaxLoc( const CvArr* arr, double* min_val, double* max_val, CvPoint* min_loc=NULL, CvPoint* max_loc=NULL, const CvArr* mask=NULL )
-
- :param src: input single-channel array.
-
- :param minVal: pointer to the returned minimum value; ``NULL`` is used if not required.
-
- :param maxVal: pointer to the returned maximum value; ``NULL`` is used if not required.
-
- :param minLoc: pointer to the returned minimum location (in 2D case); ``NULL`` is used if not required.
-
- :param maxLoc: pointer to the returned maximum location (in 2D case); ``NULL`` is used if not required.
-
- :param mask: optional mask used to select a sub-array.
-
-The functions ``minMaxLoc`` find the minimum and maximum element values and their positions. The extremums are searched across the whole array or,
-if ``mask`` is not an empty array, in the specified array region.
-
-The functions do not work with multi-channel arrays. If you need to find minimum or maximum elements across all the channels, use
-:ocv:func:`Mat::reshape` first to reinterpret the array as single-channel. Or you may extract the particular channel using either
-:ocv:func:`extractImageCOI` , or
-:ocv:func:`mixChannels` , or
-:ocv:func:`split` .
-
-.. seealso::
-
- :ocv:func:`max`,
- :ocv:func:`min`,
- :ocv:func:`compare`,
- :ocv:func:`inRange`,
- :ocv:func:`extractImageCOI`,
- :ocv:func:`mixChannels`,
- :ocv:func:`split`,
- :ocv:func:`Mat::reshape`
-
-
-
-mixChannels
------------
-Copies specified channels from input arrays to the specified channels of output arrays.
-
-.. ocv:function:: void mixChannels( const Mat* src, size_t nsrcs, Mat* dst, size_t ndsts, const int* fromTo, size_t npairs )
-
-.. ocv:function:: void mixChannels( InputArrayOfArrays src, InputOutputArrayOfArrays dst, const int* fromTo, size_t npairs )
-
-.. ocv:function:: void mixChannels( InputArrayOfArrays src, InputOutputArrayOfArrays dst, const std::vector<int>& fromTo )
-
-.. ocv:pyfunction:: cv2.mixChannels(src, dst, fromTo) -> dst
-
-.. ocv:cfunction:: void cvMixChannels( const CvArr** src, int src_count, CvArr** dst, int dst_count, const int* from_to, int pair_count )
-
- :param src: input array or vector of matricesl; all of the matrices must have the same size and the same depth.
-
- :param nsrcs: number of matrices in ``src``.
-
- :param dst: output array or vector of matrices; all the matrices *must be allocated*; their size and depth must be the same as in ``src[0]``.
-
- :param ndsts: number of matrices in ``dst``.
-
- :param fromTo: array of index pairs specifying which channels are copied and where; ``fromTo[k*2]`` is a 0-based index of the input channel in ``src``, ``fromTo[k*2+1]`` is an index of the output channel in ``dst``; the continuous channel numbering is used: the first input image channels are indexed from ``0`` to ``src[0].channels()-1``, the second input image channels are indexed from ``src[0].channels()`` to ``src[0].channels() + src[1].channels()-1``, and so on, the same scheme is used for the output image channels; as a special case, when ``fromTo[k*2]`` is negative, the corresponding output channel is filled with zero .
-
- :param npairs: number of index pairs in ``fromTo``.
-
-The functions ``mixChannels`` provide an advanced mechanism for shuffling image channels.
-
-:ocv:func:`split` and
-:ocv:func:`merge` and some forms of
-:ocv:func:`cvtColor` are partial cases of ``mixChannels`` .
-
-In the example below, the code splits a 4-channel RGBA image into a 3-channel BGR (with R and B channels swapped) and a separate alpha-channel image: ::
-
- Mat rgba( 100, 100, CV_8UC4, Scalar(1,2,3,4) );
- Mat bgr( rgba.rows, rgba.cols, CV_8UC3 );
- Mat alpha( rgba.rows, rgba.cols, CV_8UC1 );
-
- // forming an array of matrices is a quite efficient operation,
- // because the matrix data is not copied, only the headers
- Mat out[] = { bgr, alpha };
- // rgba[0] -> bgr[2], rgba[1] -> bgr[1],
- // rgba[2] -> bgr[0], rgba[3] -> alpha[0]
- int from_to[] = { 0,2, 1,1, 2,0, 3,3 };
- mixChannels( &rgba, 1, out, 2, from_to, 4 );
-
-
-.. note:: Unlike many other new-style C++ functions in OpenCV (see the introduction section and :ocv:func:`Mat::create` ), ``mixChannels`` requires the output arrays to be pre-allocated before calling the function.
-
-.. seealso::
-
- :ocv:func:`split`,
- :ocv:func:`merge`,
- :ocv:func:`cvtColor`
-
-
-
-mulSpectrums
-------------
-Performs the per-element multiplication of two Fourier spectrums.
-
-.. ocv:function:: void mulSpectrums( InputArray a, InputArray b, OutputArray c, int flags, bool conjB=false )
-
-.. ocv:pyfunction:: cv2.mulSpectrums(a, b, flags[, c[, conjB]]) -> c
-
-.. ocv:cfunction:: void cvMulSpectrums( const CvArr* src1, const CvArr* src2, CvArr* dst, int flags)
-
- :param src1: first input array.
-
- :param src2: second input array of the same size and type as ``src1`` .
-
- :param dst: output array of the same size and type as ``src1`` .
-
- :param flags: operation flags; currently, the only supported flag is ``DFT_ROWS``, which indicates that each row of ``src1`` and ``src2`` is an independent 1D Fourier spectrum. If you do not want to use this flag, then simply add a `0` as value.
-
- :param conjB: optional flag that conjugates the second input array before the multiplication (true) or not (false).
-
-The function ``mulSpectrums`` performs the per-element multiplication of the two CCS-packed or complex matrices that are results of a real or complex Fourier transform.
-
-The function, together with
-:ocv:func:`dft` and
-:ocv:func:`idft` , may be used to calculate convolution (pass ``conjB=false`` ) or correlation (pass ``conjB=true`` ) of two arrays rapidly. When the arrays are complex, they are simply multiplied (per element) with an optional conjugation of the second-array elements. When the arrays are real, they are assumed to be CCS-packed (see
-:ocv:func:`dft` for details).
-
-
-
-multiply
---------
-Calculates the per-element scaled product of two arrays.
-
-.. ocv:function:: void multiply( InputArray src1, InputArray src2, OutputArray dst, double scale=1, int dtype=-1 )
-
-.. ocv:pyfunction:: cv2.multiply(src1, src2[, dst[, scale[, dtype]]]) -> dst
-
-.. ocv:cfunction:: void cvMul(const CvArr* src1, const CvArr* src2, CvArr* dst, double scale=1)
-
- :param src1: first input array.
-
- :param src2: second input array of the same size and the same type as ``src1``.
-
- :param dst: output array of the same size and type as ``src1``.
-
- :param scale: optional scale factor.
-
-The function ``multiply`` calculates the per-element product of two arrays:
-
-.. math::
-
- \texttt{dst} (I)= \texttt{saturate} ( \texttt{scale} \cdot \texttt{src1} (I) \cdot \texttt{src2} (I))
-
-There is also a
-:ref:`MatrixExpressions` -friendly variant of the first function. See
-:ocv:func:`Mat::mul` .
-
-For a not-per-element matrix product, see
-:ocv:func:`gemm` .
-
-.. note:: Saturation is not applied when the output array has the depth ``CV_32S``. You may even get result of an incorrect sign in the case of overflow.
-
-.. seealso::
-
- :ocv:func:`add`,
- :ocv:func:`subtract`,
- :ocv:func:`divide`,
- :ref:`MatrixExpressions`,
- :ocv:func:`scaleAdd`,
- :ocv:func:`addWeighted`,
- :ocv:func:`accumulate`,
- :ocv:func:`accumulateProduct`,
- :ocv:func:`accumulateSquare`,
- :ocv:func:`Mat::convertTo`
-
-
-
-mulTransposed
--------------
-Calculates the product of a matrix and its transposition.
-
-.. ocv:function:: void mulTransposed( InputArray src, OutputArray dst, bool aTa, InputArray delta=noArray(), double scale=1, int dtype=-1 )
-
-.. ocv:pyfunction:: cv2.mulTransposed(src, aTa[, dst[, delta[, scale[, dtype]]]]) -> dst
-
-.. ocv:cfunction:: void cvMulTransposed( const CvArr* src, CvArr* dst, int order, const CvArr* delta=NULL, double scale=1. )
-
- :param src: input single-channel matrix. Note that unlike :ocv:func:`gemm`, the function can multiply not only floating-point matrices.
-
- :param dst: output square matrix.
-
- :param aTa: Flag specifying the multiplication ordering. See the description below.
-
- :param delta: Optional delta matrix subtracted from ``src`` before the multiplication. When the matrix is empty ( ``delta=noArray()`` ), it is assumed to be zero, that is, nothing is subtracted. If it has the same size as ``src`` , it is simply subtracted. Otherwise, it is "repeated" (see :ocv:func:`repeat` ) to cover the full ``src`` and then subtracted. Type of the delta matrix, when it is not empty, must be the same as the type of created output matrix. See the ``dtype`` parameter description below.
-
- :param scale: Optional scale factor for the matrix product.
-
- :param dtype: Optional type of the output matrix. When it is negative, the output matrix will have the same type as ``src`` . Otherwise, it will be ``type=CV_MAT_DEPTH(dtype)`` that should be either ``CV_32F`` or ``CV_64F`` .
-
-The function ``mulTransposed`` calculates the product of ``src`` and its transposition:
-
-.. math::
-
- \texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} )^T ( \texttt{src} - \texttt{delta} )
-
-if ``aTa=true`` , and
-
-.. math::
-
- \texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} ) ( \texttt{src} - \texttt{delta} )^T
-
-otherwise. The function is used to calculate the covariance matrix. With zero delta, it can be used as a faster substitute for general matrix product ``A*B`` when ``B=A'``
-
-.. seealso::
-
- :ocv:func:`calcCovarMatrix`,
- :ocv:func:`gemm`,
- :ocv:func:`repeat`,
- :ocv:func:`reduce`
-
-
-
-norm
-----
-Calculates an absolute array norm, an absolute difference norm, or a relative difference norm.
-
-.. ocv:function:: double norm(InputArray src1, int normType=NORM_L2, InputArray mask=noArray())
-
-.. ocv:function:: double norm( InputArray src1, InputArray src2, int normType=NORM_L2, InputArray mask=noArray() )
-
-.. ocv:function:: double norm( const SparseMat& src, int normType )
-
-.. ocv:pyfunction:: cv2.norm(src1[, normType[, mask]]) -> retval
-.. ocv:pyfunction:: cv2.norm(src1, src2[, normType[, mask]]) -> retval
-
-.. ocv:cfunction:: double cvNorm( const CvArr* arr1, const CvArr* arr2=NULL, int norm_type=CV_L2, const CvArr* mask=NULL )
-
- :param src1: first input array.
-
- :param src2: second input array of the same size and the same type as ``src1``.
-
- :param normType: type of the norm (see the details below).
-
- :param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
-
-The functions ``norm`` calculate an absolute norm of ``src1`` (when there is no ``src2`` ):
-
-.. math::
-
- norm = \forkthree{\|\texttt{src1}\|_{L_{\infty}} = \max _I | \texttt{src1} (I)|}{if $\texttt{normType} = \texttt{NORM\_INF}$ }
- { \| \texttt{src1} \| _{L_1} = \sum _I | \texttt{src1} (I)|}{if $\texttt{normType} = \texttt{NORM\_L1}$ }
- { \| \texttt{src1} \| _{L_2} = \sqrt{\sum_I \texttt{src1}(I)^2} }{if $\texttt{normType} = \texttt{NORM\_L2}$ }
-
-or an absolute or relative difference norm if ``src2`` is there:
-
-.. math::
-
- norm = \forkthree{\|\texttt{src1}-\texttt{src2}\|_{L_{\infty}} = \max _I | \texttt{src1} (I) - \texttt{src2} (I)|}{if $\texttt{normType} = \texttt{NORM\_INF}$ }
- { \| \texttt{src1} - \texttt{src2} \| _{L_1} = \sum _I | \texttt{src1} (I) - \texttt{src2} (I)|}{if $\texttt{normType} = \texttt{NORM\_L1}$ }
- { \| \texttt{src1} - \texttt{src2} \| _{L_2} = \sqrt{\sum_I (\texttt{src1}(I) - \texttt{src2}(I))^2} }{if $\texttt{normType} = \texttt{NORM\_L2}$ }
-
-or
-
-.. math::
-
- norm = \forkthree{\frac{\|\texttt{src1}-\texttt{src2}\|_{L_{\infty}} }{\|\texttt{src2}\|_{L_{\infty}} }}{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_INF}$ }
- { \frac{\|\texttt{src1}-\texttt{src2}\|_{L_1} }{\|\texttt{src2}\|_{L_1}} }{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_L1}$ }
- { \frac{\|\texttt{src1}-\texttt{src2}\|_{L_2} }{\|\texttt{src2}\|_{L_2}} }{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_L2}$ }
-
-The functions ``norm`` return the calculated norm.
-
-When the ``mask`` parameter is specified and it is not empty, the norm is calculated only over the region specified by the mask.
-
-A multi-channel input arrays are treated as a single-channel, that is, the results for all channels are combined.
-
-
-
-normalize
----------
-Normalizes the norm or value range of an array.
-
-.. ocv:function:: void normalize( InputArray src, InputOutputArray dst, double alpha=1, double beta=0, int norm_type=NORM_L2, int dtype=-1, InputArray mask=noArray() )
-
-.. ocv:function:: void normalize(const SparseMat& src, SparseMat& dst, double alpha, int normType)
-
-.. ocv:pyfunction:: cv2.normalize(src[, dst[, alpha[, beta[, norm_type[, dtype[, mask]]]]]]) -> dst
-
- :param src: input array.
-
- :param dst: output array of the same size as ``src`` .
-
- :param alpha: norm value to normalize to or the lower range boundary in case of the range normalization.
-
- :param beta: upper range boundary in case of the range normalization; it is not used for the norm normalization.
-
- :param normType: normalization type (see the details below).
-
- :param dtype: when negative, the output array has the same type as ``src``; otherwise, it has the same number of channels as ``src`` and the depth ``=CV_MAT_DEPTH(dtype)``.
-
- :param mask: optional operation mask.
-
-
-The functions ``normalize`` scale and shift the input array elements so that
-
-.. math::
-
- \| \texttt{dst} \| _{L_p}= \texttt{alpha}
-
-(where p=Inf, 1 or 2) when ``normType=NORM_INF``, ``NORM_L1``, or ``NORM_L2``, respectively; or so that
-
-.. math::
-
- \min _I \texttt{dst} (I)= \texttt{alpha} , \, \, \max _I \texttt{dst} (I)= \texttt{beta}
-
-when ``normType=NORM_MINMAX`` (for dense arrays only).
-The optional mask specifies a sub-array to be normalized. This means that the norm or min-n-max are calculated over the sub-array, and then this sub-array is modified to be normalized. If you want to only use the mask to calculate the norm or min-max but modify the whole array, you can use
-:ocv:func:`norm` and
-:ocv:func:`Mat::convertTo`.
-
-In case of sparse matrices, only the non-zero values are analyzed and transformed. Because of this, the range transformation for sparse matrices is not allowed since it can shift the zero level.
-
-.. seealso::
-
- :ocv:func:`norm`,
- :ocv:func:`Mat::convertTo`,
- :ocv:func:`SparseMat::convertTo`
-
-
-
-PCA
----
-.. ocv:class:: PCA
-
-Principal Component Analysis class.
-
-The class is used to calculate a special basis for a set of vectors. The basis will consist of eigenvectors of the covariance matrix calculated from the input set of vectors. The class ``PCA`` can also transform vectors to/from the new coordinate space defined by the basis. Usually, in this new coordinate system, each vector from the original set (and any linear combination of such vectors) can be quite accurately approximated by taking its first few components, corresponding to the eigenvectors of the largest eigenvalues of the covariance matrix. Geometrically it means that you calculate a projection of the vector to a subspace formed by a few eigenvectors corresponding to the dominant eigenvalues of the covariance matrix. And usually such a projection is very close to the original vector. So, you can represent the original vector from a high-dimensional space with a much shorter vector consisting of the projected vector's coordinates in the subspace. Such a transformation is also known as Karhunen-Loeve Transform, or KLT. See
-http://en.wikipedia.org/wiki/Principal\_component\_analysis .
-
-The sample below is the function that takes two matrices. The first function stores a set of vectors (a row per vector) that is used to calculate PCA. The second function stores another "test" set of vectors (a row per vector). First, these vectors are compressed with PCA, then reconstructed back, and then the reconstruction error norm is computed and printed for each vector. ::
-
- PCA compressPCA(InputArray pcaset, int maxComponents,
- const Mat& testset, OutputArray compressed)
- {
- PCA pca(pcaset, // pass the data
- Mat(), // there is no pre-computed mean vector,
- // so let the PCA engine to compute it
- CV_PCA_DATA_AS_ROW, // indicate that the vectors
- // are stored as matrix rows
- // (use CV_PCA_DATA_AS_COL if the vectors are
- // the matrix columns)
- maxComponents // specify how many principal components to retain
- );
- // if there is no test data, just return the computed basis, ready-to-use
- if( !testset.data )
- return pca;
- CV_Assert( testset.cols == pcaset.cols );
-
- compressed.create(testset.rows, maxComponents, testset.type());
-
- Mat reconstructed;
- for( int i = 0; i < testset.rows; i++ )
- {
- Mat vec = testset.row(i), coeffs = compressed.row(i);
- // compress the vector, the result will be stored
- // in the i-th row of the output matrix
- pca.project(vec, coeffs);
- // and then reconstruct it
- pca.backProject(coeffs, reconstructed);
- // and measure the error
- printf("%d. diff = %g\n", i, norm(vec, reconstructed, NORM_L2));
- }
- return pca;
- }
-
-
-.. seealso::
-
- :ocv:func:`calcCovarMatrix`,
- :ocv:func:`mulTransposed`,
- :ocv:class:`SVD`,
- :ocv:func:`dft`,
- :ocv:func:`dct`
-
-.. note::
-
- * An example using PCA for dimensionality reduction while maintaining an amount of variance can be found at opencv_source_code/samples/cpp/pca.cpp
-
-PCA::PCA
---------
-PCA constructors
-
-.. ocv:function:: PCA::PCA()
-
-.. ocv:function:: PCA::PCA(InputArray data, InputArray mean, int flags, int maxComponents=0)
-
-.. ocv:function:: PCA::PCA(InputArray data, InputArray mean, int flags, double retainedVariance)
-
- :param data: input samples stored as matrix rows or matrix columns.
-
- :param mean: optional mean value; if the matrix is empty (``noArray()``), the mean is computed from the data.
-
- :param flags: operation flags; currently the parameter is only used to specify the data layout:
-
- * **CV_PCA_DATA_AS_ROW** indicates that the input samples are stored as matrix rows.
-
- * **CV_PCA_DATA_AS_COL** indicates that the input samples are stored as matrix columns.
-
- :param maxComponents: maximum number of components that PCA should retain; by default, all the components are retained.
-
- :param retainedVariance: Percentage of variance that PCA should retain. Using this parameter will let the PCA decided how many components to retain but it will always keep at least 2.
-
-The default constructor initializes an empty PCA structure. The other constructors initialize the structure and call
-:ocv:funcx:`PCA::operator()` .
-
-
-
-PCA::operator ()
-----------------
-Performs Principal Component Analysis of the supplied dataset.
-
-.. ocv:function:: PCA& PCA::operator()(InputArray data, InputArray mean, int flags, int maxComponents=0)
-
-.. ocv:function:: PCA& PCA::operator()(InputArray data, InputArray mean, int flags, double retainedVariance)
-
-.. ocv:pyfunction:: cv2.PCACompute(data, mean[, eigenvectors[, maxComponents]]) -> mean, eigenvectors
-
-.. ocv:pyfunction:: cv2.PCACompute(data, mean, retainedVariance[, eigenvectors]) -> mean, eigenvectors
-
- :param data: input samples stored as the matrix rows or as the matrix columns.
-
- :param mean: optional mean value; if the matrix is empty (``noArray()``), the mean is computed from the data.
-
- :param flags: operation flags; currently the parameter is only used to specify the data layout.
-
- * **CV_PCA_DATA_AS_ROW** indicates that the input samples are stored as matrix rows.
-
- * **CV_PCA_DATA_AS_COL** indicates that the input samples are stored as matrix columns.
-
- :param maxComponents: maximum number of components that PCA should retain; by default, all the components are retained.
-
- :param retainedVariance: Percentage of variance that PCA should retain. Using this parameter will let the PCA decided how many components to retain but it will always keep at least 2.
-
-The operator performs PCA of the supplied dataset. It is safe to reuse the same PCA structure for multiple datasets. That is, if the structure has been previously used with another dataset, the existing internal data is reclaimed and the new ``eigenvalues``, ``eigenvectors`` , and ``mean`` are allocated and computed.
-
-The computed eigenvalues are sorted from the largest to the smallest and the corresponding eigenvectors are stored as ``PCA::eigenvectors`` rows.
-
-
-
-PCA::project
-------------
-Projects vector(s) to the principal component subspace.
-
-.. ocv:function:: Mat PCA::project(InputArray vec) const
-
-.. ocv:function:: void PCA::project(InputArray vec, OutputArray result) const
-
-.. ocv:pyfunction:: cv2.PCAProject(data, mean, eigenvectors[, result]) -> result
-
- :param vec: input vector(s); must have the same dimensionality and the same layout as the input data used at PCA phase, that is, if ``CV_PCA_DATA_AS_ROW`` are specified, then ``vec.cols==data.cols`` (vector dimensionality) and ``vec.rows`` is the number of vectors to project, and the same is true for the ``CV_PCA_DATA_AS_COL`` case.
-
- :param result: output vectors; in case of ``CV_PCA_DATA_AS_COL``, the output matrix has as many columns as the number of input vectors, this means that ``result.cols==vec.cols`` and the number of rows match the number of principal components (for example, ``maxComponents`` parameter passed to the constructor).
-
-The methods project one or more vectors to the principal component subspace, where each vector projection is represented by coefficients in the principal component basis. The first form of the method returns the matrix that the second form writes to the result. So the first form can be used as a part of expression while the second form can be more efficient in a processing loop.
-
-
-
-PCA::backProject
-----------------
-Reconstructs vectors from their PC projections.
-
-.. ocv:function:: Mat PCA::backProject(InputArray vec) const
-
-.. ocv:function:: void PCA::backProject(InputArray vec, OutputArray result) const
-
-.. ocv:pyfunction:: cv2.PCABackProject(data, mean, eigenvectors[, result]) -> result
-
- :param vec: coordinates of the vectors in the principal component subspace, the layout and size are the same as of ``PCA::project`` output vectors.
-
- :param result: reconstructed vectors; the layout and size are the same as of ``PCA::project`` input vectors.
-
-The methods are inverse operations to
-:ocv:func:`PCA::project`. They take PC coordinates of projected vectors and reconstruct the original vectors. Unless all the principal components have been retained, the reconstructed vectors are different from the originals. But typically, the difference is small if the number of components is large enough (but still much smaller than the original vector dimensionality). As a result, PCA is used.
-
-
-
-perspectiveTransform
---------------------
-Performs the perspective matrix transformation of vectors.
-
-.. ocv:function:: void perspectiveTransform( InputArray src, OutputArray dst, InputArray m )
-
-.. ocv:pyfunction:: cv2.perspectiveTransform(src, m[, dst]) -> dst
-
-.. ocv:cfunction:: void cvPerspectiveTransform(const CvArr* src, CvArr* dst, const CvMat* mat)
-
- :param src: input two-channel or three-channel floating-point array; each element is a 2D/3D vector to be transformed.
-
- :param dst: output array of the same size and type as ``src``.
-
- :param m: ``3x3`` or ``4x4`` floating-point transformation matrix.
-
-The function ``perspectiveTransform`` transforms every element of ``src`` by treating it as a 2D or 3D vector, in the following way:
-
-.. math::
-
- (x, y, z) \rightarrow (x'/w, y'/w, z'/w)
-
-where
-
-.. math::
-
- (x', y', z', w') = \texttt{mat} \cdot \begin{bmatrix} x & y & z & 1 \end{bmatrix}
-
-and
-
-.. math::
-
- w = \fork{w'}{if $w' \ne 0$}{\infty}{otherwise}
-
-Here a 3D vector transformation is shown. In case of a 2D vector transformation, the ``z`` component is omitted.
-
-.. note:: The function transforms a sparse set of 2D or 3D vectors. If you want to transform an image using perspective transformation, use :ocv:func:`warpPerspective` . If you have an inverse problem, that is, you want to compute the most probable perspective transformation out of several pairs of corresponding points, you can use :ocv:func:`getPerspectiveTransform` or :ocv:func:`findHomography` .
-
-.. seealso::
-
- :ocv:func:`transform`,
- :ocv:func:`warpPerspective`,
- :ocv:func:`getPerspectiveTransform`,
- :ocv:func:`findHomography`
-
-
-
-phase
------
-Calculates the rotation angle of 2D vectors.
-
-.. ocv:function:: void phase(InputArray x, InputArray y, OutputArray angle, bool angleInDegrees=false)
-
-.. ocv:pyfunction:: cv2.phase(x, y[, angle[, angleInDegrees]]) -> angle
-
- :param x: input floating-point array of x-coordinates of 2D vectors.
-
- :param y: input array of y-coordinates of 2D vectors; it must have the same size and the same type as ``x``.
-
- :param angle: output array of vector angles; it has the same size and same type as ``x`` .
-
- :param angleInDegrees: when true, the function calculates the angle in degrees, otherwise, they are measured in radians.
-
-The function ``phase`` calculates the rotation angle of each 2D vector that is formed from the corresponding elements of ``x`` and ``y`` :
-
-.. math::
-
- \texttt{angle} (I) = \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))
-
-The angle estimation accuracy is about 0.3 degrees. When ``x(I)=y(I)=0`` , the corresponding ``angle(I)`` is set to 0.
-
-
-polarToCart
------------
-Calculates x and y coordinates of 2D vectors from their magnitude and angle.
-
-.. ocv:function:: void polarToCart(InputArray magnitude, InputArray angle, OutputArray x, OutputArray y, bool angleInDegrees=false)
-
-.. ocv:pyfunction:: cv2.polarToCart(magnitude, angle[, x[, y[, angleInDegrees]]]) -> x, y
-
-.. ocv:cfunction:: void cvPolarToCart( const CvArr* magnitude, const CvArr* angle, CvArr* x, CvArr* y, int angle_in_degrees=0 )
-
- :param magnitude: input floating-point array of magnitudes of 2D vectors; it can be an empty matrix (``=Mat()``), in this case, the function assumes that all the magnitudes are =1; if it is not empty, it must have the same size and type as ``angle``.
-
- :param angle: input floating-point array of angles of 2D vectors.
-
- :param x: output array of x-coordinates of 2D vectors; it has the same size and type as ``angle``.
-
- :param y: output array of y-coordinates of 2D vectors; it has the same size and type as ``angle``.
-
- :param angleInDegrees: when true, the input angles are measured in degrees, otherwise, they are measured in radians.
-
-The function ``polarToCart`` calculates the Cartesian coordinates of each 2D vector represented by the corresponding elements of ``magnitude`` and ``angle`` :
-
-.. math::
-
- \begin{array}{l} \texttt{x} (I) = \texttt{magnitude} (I) \cos ( \texttt{angle} (I)) \\ \texttt{y} (I) = \texttt{magnitude} (I) \sin ( \texttt{angle} (I)) \\ \end{array}
-
-The relative accuracy of the estimated coordinates is about ``1e-6``.
-
-.. seealso::
-
- :ocv:func:`cartToPolar`,
- :ocv:func:`magnitude`,
- :ocv:func:`phase`,
- :ocv:func:`exp`,
- :ocv:func:`log`,
- :ocv:func:`pow`,
- :ocv:func:`sqrt`
-
-
-
-pow
----
-Raises every array element to a power.
-
-.. ocv:function:: void pow( InputArray src, double power, OutputArray dst )
-
-.. ocv:pyfunction:: cv2.pow(src, power[, dst]) -> dst
-
-.. ocv:cfunction:: void cvPow( const CvArr* src, CvArr* dst, double power)
-
- :param src: input array.
-
- :param power: exponent of power.
-
- :param dst: output array of the same size and type as ``src``.
-
-The function ``pow`` raises every element of the input array to ``power`` :
-
-.. math::
-
- \texttt{dst} (I) = \fork{\texttt{src}(I)^power}{if \texttt{power} is integer}{|\texttt{src}(I)|^power}{otherwise}
-
-So, for a non-integer power exponent, the absolute values of input array elements are used. However, it is possible to get true values for negative values using some extra operations. In the example below, computing the 5th root of array ``src`` shows: ::
-
- Mat mask = src < 0;
- pow(src, 1./5, dst);
- subtract(Scalar::all(0), dst, dst, mask);
-
-
-For some values of ``power`` , such as integer values, 0.5 and -0.5, specialized faster algorithms are used.
-
-Special values (NaN, Inf) are not handled.
-
-.. seealso::
-
- :ocv:func:`sqrt`,
- :ocv:func:`exp`,
- :ocv:func:`log`,
- :ocv:func:`cartToPolar`,
- :ocv:func:`polarToCart`
-
-
-
-RNG
----
-
-.. ocv:class:: RNG
-
-Random number generator. It encapsulates the state (currently, a 64-bit integer) and has methods to return scalar random values and to fill arrays with random values. Currently it supports uniform and Gaussian (normal) distributions. The generator uses Multiply-With-Carry algorithm, introduced by G. Marsaglia (
-http://en.wikipedia.org/wiki/Multiply-with-carry
-). Gaussian-distribution random numbers are generated using the Ziggurat algorithm (
-http://en.wikipedia.org/wiki/Ziggurat_algorithm
-), introduced by G. Marsaglia and W. W. Tsang.
-
-
-
-RNG::RNG
---------
-The constructors
-
-.. ocv:function:: RNG::RNG()
-
-.. ocv:function:: RNG::RNG(uint64 state)
-
- :param state: 64-bit value used to initialize the RNG.
-
-These are the RNG constructors. The first form sets the state to some pre-defined value, equal to ``2**32-1`` in the current implementation. The second form sets the state to the specified value. If you passed ``state=0`` , the constructor uses the above default value instead to avoid the singular random number sequence, consisting of all zeros.
-
-
-
-RNG::next
----------
-Returns the next random number.
-
-.. ocv:function:: unsigned RNG::next()
-
-The method updates the state using the MWC algorithm and returns the next 32-bit random number.
-
-
-
-RNG::operator T
----------------
-Returns the next random number of the specified type.
-
-.. ocv:function:: RNG::operator uchar()
-
-.. ocv:function:: RNG::operator schar()
-
-.. ocv:function:: RNG::operator ushort()
-
-.. ocv:function:: RNG::operator short()
-
-.. ocv:function:: RNG::operator int()
-
-.. ocv:function:: RNG::operator unsigned()
-
-.. ocv:function:: RNG::operator float()
-
-.. ocv:function:: RNG::operator double()
-
-Each of the methods updates the state using the MWC algorithm and returns the next random number of the specified type. In case of integer types, the returned number is from the available value range for the specified type. In case of floating-point types, the returned value is from ``[0,1)`` range.
-
-
-
-RNG::operator ()
-----------------
-Returns the next random number.
-
-.. ocv:function:: unsigned RNG::operator ()()
-
-.. ocv:function:: unsigned RNG::operator ()(unsigned N)
-
- :param N: upper non-inclusive boundary of the returned random number.
-
-The methods transform the state using the MWC algorithm and return the next random number. The first form is equivalent to
-:ocv:func:`RNG::next` . The second form returns the random number modulo ``N`` , which means that the result is in the range ``[0, N)`` .
-
-
-
-RNG::uniform
-------------
-Returns the next random number sampled from the uniform distribution.
-
-.. ocv:function:: int RNG::uniform(int a, int b)
-
-.. ocv:function:: float RNG::uniform(float a, float b)
-
-.. ocv:function:: double RNG::uniform(double a, double b)
-
- :param a: lower inclusive boundary of the returned random numbers.
-
- :param b: upper non-inclusive boundary of the returned random numbers.
-
-The methods transform the state using the MWC algorithm and return the next uniformly-distributed random number of the specified type, deduced from the input parameter type, from the range ``[a, b)`` . There is a nuance illustrated by the following sample: ::
-
- RNG rng;
-
- // always produces 0
- double a = rng.uniform(0, 1);
-
- // produces double from [0, 1)
- double a1 = rng.uniform((double)0, (double)1);
-
- // produces float from [0, 1)
- double b = rng.uniform(0.f, 1.f);
-
- // produces double from [0, 1)
- double c = rng.uniform(0., 1.);
-
- // may cause compiler error because of ambiguity:
- // RNG::uniform(0, (int)0.999999)? or RNG::uniform((double)0, 0.99999)?
- double d = rng.uniform(0, 0.999999);
-
-
-The compiler does not take into account the type of the variable to which you assign the result of ``RNG::uniform`` . The only thing that matters to the compiler is the type of ``a`` and ``b`` parameters. So, if you want a floating-point random number, but the range boundaries are integer numbers, either put dots in the end, if they are constants, or use explicit type cast operators, as in the ``a1`` initialization above.
-
-
-
-RNG::gaussian
--------------
-Returns the next random number sampled from the Gaussian distribution.
-
-.. ocv:function:: double RNG::gaussian(double sigma)
-
- :param sigma: standard deviation of the distribution.
-
-The method transforms the state using the MWC algorithm and returns the next random number from the Gaussian distribution ``N(0,sigma)`` . That is, the mean value of the returned random numbers is zero and the standard deviation is the specified ``sigma`` .
-
-
-
-RNG::fill
----------
-Fills arrays with random numbers.
-
-.. ocv:function:: void RNG::fill( InputOutputArray mat, int distType, InputArray a, InputArray b, bool saturateRange=false )
-
- :param mat: 2D or N-dimensional matrix; currently matrices with more than 4 channels are not supported by the methods, use :ocv:func:`Mat::reshape` as a possible workaround.
-
- :param distType: distribution type, ``RNG::UNIFORM`` or ``RNG::NORMAL``.
-
- :param a: first distribution parameter; in case of the uniform distribution, this is an inclusive lower boundary, in case of the normal distribution, this is a mean value.
-
- :param b: second distribution parameter; in case of the uniform distribution, this is a non-inclusive upper boundary, in case of the normal distribution, this is a standard deviation (diagonal of the standard deviation matrix or the full standard deviation matrix).
-
- :param saturateRange: pre-saturation flag; for uniform distribution only; if true, the method will first convert a and b to the acceptable value range (according to the mat datatype) and then will generate uniformly distributed random numbers within the range ``[saturate(a), saturate(b))``, if ``saturateRange=false``, the method will generate uniformly distributed random numbers in the original range ``[a, b)`` and then will saturate them, it means, for example, that ``theRNG().fill(mat_8u, RNG::UNIFORM, -DBL_MAX, DBL_MAX)`` will likely produce array mostly filled with 0's and 255's, since the range ``(0, 255)`` is significantly smaller than ``[-DBL_MAX, DBL_MAX)``.
-
-Each of the methods fills the matrix with the random values from the specified distribution. As the new numbers are generated, the RNG state is updated accordingly. In case of multiple-channel images, every channel is filled independently, which means that RNG cannot generate samples from the multi-dimensional Gaussian distribution with non-diagonal covariance matrix directly. To do that, the method generates samples from multi-dimensional standard Gaussian distribution with zero mean and identity covariation matrix, and then transforms them using :ocv:func:`transform` to get samples from the specified Gaussian distribution.
-
-randu
------
-Generates a single uniformly-distributed random number or an array of random numbers.
-
-.. ocv:function:: template<typename _Tp> _Tp randu()
-
-.. ocv:function:: void randu( InputOutputArray dst, InputArray low, InputArray high )
-
-.. ocv:pyfunction:: cv2.randu(dst, low, high) -> dst
-
- :param dst: output array of random numbers; the array must be pre-allocated.
-
- :param low: inclusive lower boundary of the generated random numbers.
-
- :param high: exclusive upper boundary of the generated random numbers.
-
-The template functions ``randu`` generate and return the next uniformly-distributed random value of the specified type. ``randu<int>()`` is an equivalent to ``(int)theRNG();`` , and so on. See
-:ocv:class:`RNG` description.
-
-The second non-template variant of the function fills the matrix ``dst`` with uniformly-distributed random numbers from the specified range:
-
-.. math::
-
- \texttt{low} _c \leq \texttt{dst} (I)_c < \texttt{high} _c
-
-.. seealso::
-
- :ocv:class:`RNG`,
- :ocv:func:`randn`,
- :ocv:func:`theRNG`
-
-
-
-randn
------
-Fills the array with normally distributed random numbers.
-
-.. ocv:function:: void randn( InputOutputArray dst, InputArray mean, InputArray stddev )
-
-.. ocv:pyfunction:: cv2.randn(dst, mean, stddev) -> dst
-
- :param dst: output array of random numbers; the array must be pre-allocated and have 1 to 4 channels.
-
- :param mean: mean value (expectation) of the generated random numbers.
-
- :param stddev: standard deviation of the generated random numbers; it can be either a vector (in which case a diagonal standard deviation matrix is assumed) or a square matrix.
-
-The function ``randn`` fills the matrix ``dst`` with normally distributed random numbers with the specified mean vector and the standard deviation matrix. The generated random numbers are clipped to fit the value range of the output array data type.
-
-.. seealso::
-
- :ocv:class:`RNG`,
- :ocv:func:`randu`
-
-
-
-randShuffle
------------
-Shuffles the array elements randomly.
-
-.. ocv:function:: void randShuffle( InputOutputArray dst, double iterFactor=1., RNG* rng=0 )
-
-.. ocv:pyfunction:: cv2.randShuffle(dst[, iterFactor]) -> dst
-
- :param dst: input/output numerical 1D array.
-
- :param iterFactor: scale factor that determines the number of random swap operations (see the details below).
-
- :param rng: optional random number generator used for shuffling; if it is zero, :ocv:func:`theRNG` () is used instead.
-
-The function ``randShuffle`` shuffles the specified 1D array by randomly choosing pairs of elements and swapping them. The number of such swap operations will be ``dst.rows*dst.cols*iterFactor`` .
-
-.. seealso::
-
- :ocv:class:`RNG`,
- :ocv:func:`sort`
-
-
-
-reduce
-------
-Reduces a matrix to a vector.
-
-.. ocv:function:: void reduce( InputArray src, OutputArray dst, int dim, int rtype, int dtype=-1 )
-
-.. ocv:pyfunction:: cv2.reduce(src, dim, rtype[, dst[, dtype]]) -> dst
-
-.. ocv:cfunction:: void cvReduce(const CvArr* src, CvArr* dst, int dim=-1, int op=CV_REDUCE_SUM)
-
- :param src: input 2D matrix.
-
- :param dst: output vector. Its size and type is defined by ``dim`` and ``dtype`` parameters.
-
- :param dim: dimension index along which the matrix is reduced. 0 means that the matrix is reduced to a single row. 1 means that the matrix is reduced to a single column.
-
- :param rtype: reduction operation that could be one of the following:
-
- * **CV_REDUCE_SUM**: the output is the sum of all rows/columns of the matrix.
-
- * **CV_REDUCE_AVG**: the output is the mean vector of all rows/columns of the matrix.
-
- * **CV_REDUCE_MAX**: the output is the maximum (column/row-wise) of all rows/columns of the matrix.
-
- * **CV_REDUCE_MIN**: the output is the minimum (column/row-wise) of all rows/columns of the matrix.
-
- :param dtype: when negative, the output vector will have the same type as the input matrix, otherwise, its type will be ``CV_MAKE_TYPE(CV_MAT_DEPTH(dtype), src.channels())``.
-
-The function ``reduce`` reduces the matrix to a vector by treating the matrix rows/columns as a set of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained. For example, the function can be used to compute horizontal and vertical projections of a raster image. In case of ``CV_REDUCE_SUM`` and ``CV_REDUCE_AVG`` , the output may have a larger element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes.
-
-.. seealso:: :ocv:func:`repeat`
-
-
-
-repeat
-------
-Fills the output array with repeated copies of the input array.
-
-.. ocv:function:: void repeat(InputArray src, int ny, int nx, OutputArray dst)
-
-.. ocv:function:: Mat repeat( const Mat& src, int ny, int nx )
-
-.. ocv:pyfunction:: cv2.repeat(src, ny, nx[, dst]) -> dst
-
-.. ocv:cfunction:: void cvRepeat(const CvArr* src, CvArr* dst)
-
- :param src: input array to replicate.
-
- :param dst: output array of the same type as ``src``.
-
- :param ny: Flag to specify how many times the ``src`` is repeated along the vertical axis.
-
- :param nx: Flag to specify how many times the ``src`` is repeated along the horizontal axis.
-
-The functions
-:ocv:func:`repeat` duplicate the input array one or more times along each of the two axes:
-
-.. math::
-
- \texttt{dst} _{ij}= \texttt{src} _{i\mod src.rows, \; j\mod src.cols }
-
-The second variant of the function is more convenient to use with
-:ref:`MatrixExpressions` .
-
-.. seealso::
-
- :ocv:func:`reduce`,
- :ref:`MatrixExpressions`
-
-
-
-scaleAdd
---------
-Calculates the sum of a scaled array and another array.
-
-.. ocv:function:: void scaleAdd( InputArray src1, double alpha, InputArray src2, OutputArray dst )
-
-.. ocv:pyfunction:: cv2.scaleAdd(src1, alpha, src2[, dst]) -> dst
-
-.. ocv:cfunction:: void cvScaleAdd(const CvArr* src1, CvScalar scale, const CvArr* src2, CvArr* dst)
-
- :param src1: first input array.
-
- :param scale: scale factor for the first array.
-
- :param src2: second input array of the same size and type as ``src1``.
-
- :param dst: output array of the same size and type as ``src1``.
-
-The function ``scaleAdd`` is one of the classical primitive linear algebra operations, known as ``DAXPY`` or ``SAXPY`` in `BLAS <http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms>`_. It calculates the sum of a scaled array and another array:
-
-.. math::
-
- \texttt{dst} (I)= \texttt{scale} \cdot \texttt{src1} (I) + \texttt{src2} (I)
-
-The function can also be emulated with a matrix expression, for example: ::
-
- Mat A(3, 3, CV_64F);
- ...
- A.row(0) = A.row(1)*2 + A.row(2);
-
-
-.. seealso::
-
- :ocv:func:`add`,
- :ocv:func:`addWeighted`,
- :ocv:func:`subtract`,
- :ocv:func:`Mat::dot`,
- :ocv:func:`Mat::convertTo`,
- :ref:`MatrixExpressions`
-
-
-
-setIdentity
------------
-Initializes a scaled identity matrix.
-
-.. ocv:function:: void setIdentity( InputOutputArray mtx, const Scalar& s=Scalar(1) )
-
-.. ocv:pyfunction:: cv2.setIdentity(mtx[, s]) -> mtx
-
-.. ocv:cfunction:: void cvSetIdentity(CvArr* mat, CvScalar value=cvRealScalar(1))
-
- :param mtx: matrix to initialize (not necessarily square).
-
- :param value: value to assign to diagonal elements.
-
-The function
-:ocv:func:`setIdentity` initializes a scaled identity matrix:
-
-.. math::
-
- \texttt{mtx} (i,j)= \fork{\texttt{value}}{ if $i=j$}{0}{otherwise}
-
-The function can also be emulated using the matrix initializers and the matrix expressions: ::
-
- Mat A = Mat::eye(4, 3, CV_32F)*5;
- // A will be set to [[5, 0, 0], [0, 5, 0], [0, 0, 5], [0, 0, 0]]
-
-
-.. seealso::
-
- :ocv:func:`Mat::zeros`,
- :ocv:func:`Mat::ones`,
- :ref:`MatrixExpressions`,
- :ocv:func:`Mat::setTo`,
- :ocv:func:`Mat::operator=`
-
-
-
-solve
------
-Solves one or more linear systems or least-squares problems.
-
-.. ocv:function:: bool solve(InputArray src1, InputArray src2, OutputArray dst, int flags=DECOMP_LU)
-
-.. ocv:pyfunction:: cv2.solve(src1, src2[, dst[, flags]]) -> retval, dst
-
-.. ocv:cfunction:: int cvSolve(const CvArr* src1, const CvArr* src2, CvArr* dst, int method=CV_LU)
-
- :param src1: input matrix on the left-hand side of the system.
-
- :param src2: input matrix on the right-hand side of the system.
-
- :param dst: output solution.
-
- :param flags: solution (matrix inversion) method.
-
- * **DECOMP_LU** Gaussian elimination with optimal pivot element chosen.
-
- * **DECOMP_CHOLESKY** Cholesky :math:`LL^T` factorization; the matrix ``src1`` must be symmetrical and positively defined.
-
- * **DECOMP_EIG** eigenvalue decomposition; the matrix ``src1`` must be symmetrical.
-
- * **DECOMP_SVD** singular value decomposition (SVD) method; the system can be over-defined and/or the matrix ``src1`` can be singular.
-
- * **DECOMP_QR** QR factorization; the system can be over-defined and/or the matrix ``src1`` can be singular.
-
- * **DECOMP_NORMAL** while all the previous flags are mutually exclusive, this flag can be used together with any of the previous; it means that the normal equations :math:`\texttt{src1}^T\cdot\texttt{src1}\cdot\texttt{dst}=\texttt{src1}^T\texttt{src2}` are solved instead of the original system :math:`\texttt{src1}\cdot\texttt{dst}=\texttt{src2}` .
-
-The function ``solve`` solves a linear system or least-squares problem (the latter is possible with SVD or QR methods, or by specifying the flag ``DECOMP_NORMAL`` ):
-
-.. math::
-
- \texttt{dst} = \arg \min _X \| \texttt{src1} \cdot \texttt{X} - \texttt{src2} \|
-
-If ``DECOMP_LU`` or ``DECOMP_CHOLESKY`` method is used, the function returns 1 if ``src1`` (or
-:math:`\texttt{src1}^T\texttt{src1}` ) is non-singular. Otherwise, it returns 0. In the latter case, ``dst`` is not valid. Other methods find a pseudo-solution in case of a singular left-hand side part.
-
-.. note:: If you want to find a unity-norm solution of an under-defined singular system :math:`\texttt{src1}\cdot\texttt{dst}=0` , the function ``solve`` will not do the work. Use :ocv:func:`SVD::solveZ` instead.
-
-.. seealso::
-
- :ocv:func:`invert`,
- :ocv:class:`SVD`,
- :ocv:func:`eigen`
-
-
-
-solveCubic
-----------
-Finds the real roots of a cubic equation.
-
-.. ocv:function:: int solveCubic( InputArray coeffs, OutputArray roots )
-
-.. ocv:pyfunction:: cv2.solveCubic(coeffs[, roots]) -> retval, roots
-
-.. ocv:cfunction:: int cvSolveCubic( const CvMat* coeffs, CvMat* roots )
-
- :param coeffs: equation coefficients, an array of 3 or 4 elements.
-
- :param roots: output array of real roots that has 1 or 3 elements.
-
-The function ``solveCubic`` finds the real roots of a cubic equation:
-
-* if ``coeffs`` is a 4-element vector:
-
-.. math::
-
- \texttt{coeffs} [0] x^3 + \texttt{coeffs} [1] x^2 + \texttt{coeffs} [2] x + \texttt{coeffs} [3] = 0
-
-* if ``coeffs`` is a 3-element vector:
-
-.. math::
-
- x^3 + \texttt{coeffs} [0] x^2 + \texttt{coeffs} [1] x + \texttt{coeffs} [2] = 0
-
-The roots are stored in the ``roots`` array.
-
-
-
-solvePoly
----------
-Finds the real or complex roots of a polynomial equation.
-
-.. ocv:function:: double solvePoly( InputArray coeffs, OutputArray roots, int maxIters=300 )
-
-.. ocv:pyfunction:: cv2.solvePoly(coeffs[, roots[, maxIters]]) -> retval, roots
-
- :param coeffs: array of polynomial coefficients.
-
- :param roots: output (complex) array of roots.
-
- :param maxIters: maximum number of iterations the algorithm does.
-
-The function ``solvePoly`` finds real and complex roots of a polynomial equation:
-
-.. math::
-
- \texttt{coeffs} [n] x^{n} + \texttt{coeffs} [n-1] x^{n-1} + ... + \texttt{coeffs} [1] x + \texttt{coeffs} [0] = 0
-
-
-
-sort
-----
-Sorts each row or each column of a matrix.
-
-.. ocv:function:: void sort(InputArray src, OutputArray dst, int flags)
-
-.. ocv:pyfunction:: cv2.sort(src, flags[, dst]) -> dst
-
- :param src: input single-channel array.
-
- :param dst: output array of the same size and type as ``src``.
-
- :param flags: operation flags, a combination of the following values:
-
- * **CV_SORT_EVERY_ROW** each matrix row is sorted independently.
-
- * **CV_SORT_EVERY_COLUMN** each matrix column is sorted independently; this flag and the previous one are mutually exclusive.
-
- * **CV_SORT_ASCENDING** each matrix row is sorted in the ascending order.
-
- * **CV_SORT_DESCENDING** each matrix row is sorted in the descending order; this flag and the previous one are also mutually exclusive.
-
-The function ``sort`` sorts each matrix row or each matrix column in ascending or descending order. So you should pass two operation flags to get desired behaviour. If you want to sort matrix rows or columns lexicographically, you can use STL ``std::sort`` generic function with the proper comparison predicate.
-
-.. seealso::
-
- :ocv:func:`sortIdx`,
- :ocv:func:`randShuffle`
-
-
-
-sortIdx
--------
-Sorts each row or each column of a matrix.
-
-.. ocv:function:: void sortIdx(InputArray src, OutputArray dst, int flags)
-
-.. ocv:pyfunction:: cv2.sortIdx(src, flags[, dst]) -> dst
-
- :param src: input single-channel array.
-
- :param dst: output integer array of the same size as ``src``.
-
- :param flags: operation flags that could be a combination of the following values:
-
- * **CV_SORT_EVERY_ROW** each matrix row is sorted independently.
-
- * **CV_SORT_EVERY_COLUMN** each matrix column is sorted independently; this flag and the previous one are mutually exclusive.
-
- * **CV_SORT_ASCENDING** each matrix row is sorted in the ascending order.
-
- * **CV_SORT_DESCENDING** each matrix row is sorted in the descending order; his flag and the previous one are also mutually exclusive.
-
-The function ``sortIdx`` sorts each matrix row or each matrix column in the ascending or descending order. So you should pass two operation flags to get desired behaviour. Instead of reordering the elements themselves, it stores the indices of sorted elements in the output array. For example: ::
-
- Mat A = Mat::eye(3,3,CV_32F), B;
- sortIdx(A, B, CV_SORT_EVERY_ROW + CV_SORT_ASCENDING);
- // B will probably contain
- // (because of equal elements in A some permutations are possible):
- // [[1, 2, 0], [0, 2, 1], [0, 1, 2]]
-
-
-.. seealso::
-
- :ocv:func:`sort`,
- :ocv:func:`randShuffle`
-
-
-
-split
------
-Divides a multi-channel array into several single-channel arrays.
-
-.. ocv:function:: void split( const Mat& src, Mat* mvbegin )
-
-.. ocv:function:: void split( InputArray m, OutputArrayOfArrays mv )
-
-.. ocv:pyfunction:: cv2.split(m[, mv]) -> mv
-
-.. ocv:cfunction:: void cvSplit(const CvArr* src, CvArr* dst0, CvArr* dst1, CvArr* dst2, CvArr* dst3)
-
- :param src: input multi-channel array.
-
- :param mv: output array or vector of arrays; in the first variant of the function the number of arrays must match ``src.channels()``; the arrays themselves are reallocated, if needed.
-
-The functions ``split`` split a multi-channel array into separate single-channel arrays:
-
-.. math::
-
- \texttt{mv} [c](I) = \texttt{src} (I)_c
-
-If you need to extract a single channel or do some other sophisticated channel permutation, use
-:ocv:func:`mixChannels` .
-
-.. seealso::
-
- :ocv:func:`merge`,
- :ocv:func:`mixChannels`,
- :ocv:func:`cvtColor`
-
-
-
-sqrt
-----
-Calculates a square root of array elements.
-
-.. ocv:function:: void sqrt(InputArray src, OutputArray dst)
-
-.. ocv:pyfunction:: cv2.sqrt(src[, dst]) -> dst
-
-.. ocv:cfunction:: float cvSqrt(float value)
-
- :param src: input floating-point array.
-
- :param dst: output array of the same size and type as ``src``.
-
-The functions ``sqrt`` calculate a square root of each input array element. In case of multi-channel arrays, each channel is processed independently. The accuracy is approximately the same as of the built-in ``std::sqrt`` .
-
-.. seealso::
-
- :ocv:func:`pow`,
- :ocv:func:`magnitude`
-
-
-
-subtract
---------
-Calculates the per-element difference between two arrays or array and a scalar.
-
-.. ocv:function:: void subtract(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray(), int dtype=-1)
-
-.. ocv:pyfunction:: cv2.subtract(src1, src2[, dst[, mask[, dtype]]]) -> dst
-
-.. ocv:cfunction:: void cvSub(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
-.. ocv:cfunction:: void cvSubRS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL )
-.. ocv:cfunction:: void cvSubS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL )
-
- :param src1: first input array or a scalar.
-
- :param src2: second input array or a scalar.
-
- :param dst: output array of the same size and the same number of channels as the input array.
-
- :param mask: optional operation mask; this is an 8-bit single channel array that specifies elements of the output array to be changed.
-
- :param dtype: optional depth of the output array (see the details below).
-
-The function ``subtract`` calculates:
-
- *
- Difference between two arrays, when both input arrays have the same size and the same number of channels:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0
-
- *
- Difference between an array and a scalar, when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2} ) \quad \texttt{if mask}(I) \ne0
-
- *
- Difference between a scalar and an array, when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} - \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0
-
- *
- The reverse difference between a scalar and an array in the case of ``SubRS``:
-
- .. math::
-
- \texttt{dst}(I) = \texttt{saturate} ( \texttt{src2} - \texttt{src1}(I) ) \quad \texttt{if mask}(I) \ne0
-
-where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
-
-The first function in the list above can be replaced with matrix expressions: ::
-
- dst = src1 - src2;
- dst -= src1; // equivalent to subtract(dst, src1, dst);
-
-The input arrays and the output array can all have the same or different depths. For example, you can subtract to 8-bit unsigned arrays and store the difference in a 16-bit signed array. Depth of the output array is determined by ``dtype`` parameter. In the second and third cases above, as well as in the first case, when ``src1.depth() == src2.depth()``, ``dtype`` can be set to the default ``-1``. In this case the output array will have the same depth as the input array, be it ``src1``, ``src2`` or both.
-
-.. note:: Saturation is not applied when the output array has the depth ``CV_32S``. You may even get result of an incorrect sign in the case of overflow.
-
-.. seealso::
-
- :ocv:func:`add`,
- :ocv:func:`addWeighted`,
- :ocv:func:`scaleAdd`,
- :ocv:func:`Mat::convertTo`,
- :ref:`MatrixExpressions`
-
-
-
-SVD
----
-.. ocv:class:: SVD
-
-Class for computing Singular Value Decomposition of a floating-point matrix. The Singular Value Decomposition is used to solve least-square problems, under-determined linear systems, invert matrices, compute condition numbers, and so on.
-
-For a faster operation, you can pass ``flags=SVD::MODIFY_A|...`` to modify the decomposed matrix when it is not necessary to preserve it. If you want to compute a condition number of a matrix or an absolute value of its determinant, you do not need ``u`` and ``vt`` . You can pass ``flags=SVD::NO_UV|...`` . Another flag ``FULL_UV`` indicates that full-size ``u`` and ``vt`` must be computed, which is not necessary most of the time.
-
-.. seealso::
-
- :ocv:func:`invert`,
- :ocv:func:`solve`,
- :ocv:func:`eigen`,
- :ocv:func:`determinant`
-
-
-
-SVD::SVD
---------
-The constructors.
-
-.. ocv:function:: SVD::SVD()
-
-.. ocv:function:: SVD::SVD( InputArray src, int flags=0 )
-
- :param src: decomposed matrix.
-
- :param flags: operation flags.
-
- * **SVD::MODIFY_A** use the algorithm to modify the decomposed matrix; it can save space and speed up processing.
-
- * **SVD::NO_UV** indicates that only a vector of singular values ``w`` is to be processed, while ``u`` and ``vt`` will be set to empty matrices.
-
- * **SVD::FULL_UV** when the matrix is not square, by default the algorithm produces ``u`` and ``vt`` matrices of sufficiently large size for the further ``A`` reconstruction; if, however, ``FULL_UV`` flag is specified, ``u`` and ``vt`` will be full-size square orthogonal matrices.
-
-The first constructor initializes an empty ``SVD`` structure. The second constructor initializes an empty ``SVD`` structure and then calls
-:ocv:funcx:`SVD::operator()` .
-
-
-SVD::operator ()
-----------------
-Performs SVD of a matrix.
-
-.. ocv:function:: SVD& SVD::operator()( InputArray src, int flags=0 )
-
- :param src: decomposed matrix.
-
- :param flags: operation flags.
-
- * **SVD::MODIFY_A** use the algorithm to modify the decomposed matrix; it can save space and speed up processing.
-
- * **SVD::NO_UV** use only singular values; the algorithm does not compute ``u`` and ``vt`` matrices.
-
- * **SVD::FULL_UV** when the matrix is not square, by default the algorithm produces ``u`` and ``vt`` matrices of sufficiently large size for the further ``A`` reconstruction; if, however, the ``FULL_UV`` flag is specified, ``u`` and ``vt`` are full-size square orthogonal matrices.
-
-The operator performs the singular value decomposition of the supplied matrix. The ``u``,``vt`` , and the vector of singular values ``w`` are stored in the structure. The same ``SVD`` structure can be reused many times with different matrices. Each time, if needed, the previous ``u``,``vt`` , and ``w`` are reclaimed and the new matrices are created, which is all handled by
-:ocv:func:`Mat::create` .
-
-
-SVD::compute
-------------
-Performs SVD of a matrix
-
-.. ocv:function:: static void SVD::compute( InputArray src, OutputArray w, OutputArray u, OutputArray vt, int flags=0 )
-
-.. ocv:function:: static void SVD::compute( InputArray src, OutputArray w, int flags=0 )
-
-.. ocv:pyfunction:: cv2.SVDecomp(src[, w[, u[, vt[, flags]]]]) -> w, u, vt
-
-.. ocv:cfunction:: void cvSVD( CvArr* A, CvArr* W, CvArr* U=NULL, CvArr* V=NULL, int flags=0 )
-
- :param src: decomposed matrix
-
- :param w: calculated singular values
-
- :param u: calculated left singular vectors
-
- :param V: calculated right singular vectors
-
- :param vt: transposed matrix of right singular values
-
- :param flags: operation flags - see :ocv:func:`SVD::SVD`.
-
-The methods/functions perform SVD of matrix. Unlike ``SVD::SVD`` constructor and ``SVD::operator()``, they store the results to the user-provided matrices. ::
-
- Mat A, w, u, vt;
- SVD::compute(A, w, u, vt);
-
-
-SVD::solveZ
------------
-Solves an under-determined singular linear system.
-
-.. ocv:function:: static void SVD::solveZ( InputArray src, OutputArray dst )
-
- :param src: left-hand-side matrix.
-
- :param dst: found solution.
-
-The method finds a unit-length solution ``x`` of a singular linear system
-``A*x = 0``. Depending on the rank of ``A``, there can be no solutions, a single solution or an infinite number of solutions. In general, the algorithm solves the following problem:
-
-.. math::
-
- dst = \arg \min _{x: \| x \| =1} \| src \cdot x \|
-
-
-SVD::backSubst
---------------
-Performs a singular value back substitution.
-
-.. ocv:function:: void SVD::backSubst( InputArray rhs, OutputArray dst ) const
-
-.. ocv:function:: static void SVD::backSubst( InputArray w, InputArray u, InputArray vt, InputArray rhs, OutputArray dst )
-
-.. ocv:pyfunction:: cv2.SVBackSubst(w, u, vt, rhs[, dst]) -> dst
-
-.. ocv:cfunction:: void cvSVBkSb( const CvArr* W, const CvArr* U, const CvArr* V, const CvArr* B, CvArr* X, int flags )
-
- :param w: singular values
-
- :param u: left singular vectors
-
- :param V: right singular vectors
-
- :param vt: transposed matrix of right singular vectors.
-
- :param rhs: right-hand side of a linear system ``(u*w*v')*dst = rhs`` to be solved, where ``A`` has been previously decomposed.
-
- :param dst: found solution of the system.
-
-The method calculates a back substitution for the specified right-hand side:
-
-.. math::
-
- \texttt{x} = \texttt{vt} ^T \cdot diag( \texttt{w} )^{-1} \cdot \texttt{u} ^T \cdot \texttt{rhs} \sim \texttt{A} ^{-1} \cdot \texttt{rhs}
-
-Using this technique you can either get a very accurate solution of the convenient linear system, or the best (in the least-squares terms) pseudo-solution of an overdetermined linear system.
-
-.. note:: Explicit SVD with the further back substitution only makes sense if you need to solve many linear systems with the same left-hand side (for example, ``src`` ). If all you need is to solve a single system (possibly with multiple ``rhs`` immediately available), simply call :ocv:func:`solve` add pass ``DECOMP_SVD`` there. It does absolutely the same thing.
-
-
-
-sum
----
-Calculates the sum of array elements.
-
-.. ocv:function:: Scalar sum( InputArray src )
-
-.. ocv:pyfunction:: cv2.sumElems(src) -> retval
-
-.. ocv:cfunction:: CvScalar cvSum(const CvArr* arr)
-
- :param arr: input array that must have from 1 to 4 channels.
-
-The functions ``sum`` calculate and return the sum of array elements, independently for each channel.
-
-.. seealso::
-
- :ocv:func:`countNonZero`,
- :ocv:func:`mean`,
- :ocv:func:`meanStdDev`,
- :ocv:func:`norm`,
- :ocv:func:`minMaxLoc`,
- :ocv:func:`reduce`
-
-
-
-theRNG
-------
-Returns the default random number generator.
-
-.. ocv:function:: RNG& theRNG()
-
-The function ``theRNG`` returns the default random number generator. For each thread, there is a separate random number generator, so you can use the function safely in multi-thread environments. If you just need to get a single random number using this generator or initialize an array, you can use
-:ocv:func:`randu` or
-:ocv:func:`randn` instead. But if you are going to generate many random numbers inside a loop, it is much faster to use this function to retrieve the generator and then use ``RNG::operator _Tp()`` .
-
-.. seealso::
-
- :ocv:class:`RNG`,
- :ocv:func:`randu`,
- :ocv:func:`randn`
-
-
-
-trace
------
-Returns the trace of a matrix.
-
-.. ocv:function:: Scalar trace( InputArray mtx )
-
-.. ocv:pyfunction:: cv2.trace(mtx) -> retval
-
-.. ocv:cfunction:: CvScalar cvTrace(const CvArr* mat)
-
- :param mat: input matrix.
-
-The function ``trace`` returns the sum of the diagonal elements of the matrix ``mtx`` .
-
-.. math::
-
- \mathrm{tr} ( \texttt{mtx} ) = \sum _i \texttt{mtx} (i,i)
-
-
-
-transform
----------
-Performs the matrix transformation of every array element.
-
-.. ocv:function:: void transform( InputArray src, OutputArray dst, InputArray m )
-
-.. ocv:pyfunction:: cv2.transform(src, m[, dst]) -> dst
-
-.. ocv:cfunction:: void cvTransform( const CvArr* src, CvArr* dst, const CvMat* transmat, const CvMat* shiftvec=NULL )
-
- :param src: input array that must have as many channels (1 to 4) as ``m.cols`` or ``m.cols-1``.
-
- :param dst: output array of the same size and depth as ``src``; it has as many channels as ``m.rows``.
-
- :param m: transformation ``2x2`` or ``2x3`` floating-point matrix.
-
- :param shiftvec: optional translation vector (when ``m`` is ``2x2``)
-
-The function ``transform`` performs the matrix transformation of every element of the array ``src`` and stores the results in ``dst`` :
-
-.. math::
-
- \texttt{dst} (I) = \texttt{m} \cdot \texttt{src} (I)
-
-(when ``m.cols=src.channels()`` ), or
-
-.. math::
-
- \texttt{dst} (I) = \texttt{m} \cdot [ \texttt{src} (I); 1]
-
-(when ``m.cols=src.channels()+1`` )
-
-Every element of the ``N`` -channel array ``src`` is interpreted as ``N`` -element vector that is transformed using
-the ``M x N`` or ``M x (N+1)`` matrix ``m``
-to ``M``-element vector - the corresponding element of the output array ``dst`` .
-
-The function may be used for geometrical transformation of
-``N`` -dimensional
-points, arbitrary linear color space transformation (such as various kinds of RGB to YUV transforms), shuffling the image channels, and so forth.
-
-.. seealso::
-
- :ocv:func:`perspectiveTransform`,
- :ocv:func:`getAffineTransform`,
- :ocv:func:`estimateRigidTransform`,
- :ocv:func:`warpAffine`,
- :ocv:func:`warpPerspective`
-
-
-
-transpose
----------
-Transposes a matrix.
-
-.. ocv:function:: void transpose(InputArray src, OutputArray dst)
-
-.. ocv:pyfunction:: cv2.transpose(src[, dst]) -> dst
-
-.. ocv:cfunction:: void cvTranspose(const CvArr* src, CvArr* dst)
-
- :param src: input array.
-
- :param dst: output array of the same type as ``src``.
-
-The function :ocv:func:`transpose` transposes the matrix ``src`` :
-
-.. math::
-
- \texttt{dst} (i,j) = \texttt{src} (j,i)
-
-.. note:: No complex conjugation is done in case of a complex matrix. It it should be done separately if needed.
-
-
-borderInterpolate
------------------
-Computes the source location of an extrapolated pixel.
-
-.. ocv:function:: int borderInterpolate( int p, int len, int borderType )
-
-.. ocv:pyfunction:: cv2.borderInterpolate(p, len, borderType) -> retval
-
- :param p: 0-based coordinate of the extrapolated pixel along one of the axes,
- likely <0 or >= ``len`` .
-
- :param len: Length of the array along the corresponding axis.
-
- :param borderType: Border type, one of the ``BORDER_*`` , except for ``BORDER_TRANSPARENT``
- and ``BORDER_ISOLATED`` . When ``borderType==BORDER_CONSTANT`` , the
- function always returns -1, regardless of ``p`` and ``len`` .
-
-The function computes and returns the coordinate of a donor pixel corresponding to the specified
-extrapolated pixel when using the specified extrapolation border mode. For example, if you use
-``BORDER_WRAP`` mode in the horizontal direction, ``BORDER_REFLECT_101`` in the vertical direction
-and want to compute value of the "virtual" pixel ``Point(-5, 100)`` in a floating-point image
-``img`` , it looks like: ::
-
- float val = img.at<float>(borderInterpolate(100, img.rows, BORDER_REFLECT_101),
- borderInterpolate(-5, img.cols, BORDER_WRAP));
-
-
-Normally, the function is not called directly. It is used inside filtering functions
-and also in :ocv:func:`copyMakeBorder`.
-
-.. seealso::
-
- :ocv:func:`copyMakeBorder`
-
-
-copyMakeBorder
---------------
-Forms a border around an image.
-
-.. ocv:function:: void copyMakeBorder( InputArray src, OutputArray dst, int top, int bottom, int left, int right, int borderType, const Scalar& value=Scalar() )
-
-.. ocv:pyfunction:: cv2.copyMakeBorder(src, top, bottom, left, right, borderType[, dst[, value]]) -> dst
-
- :param src: Source image.
-
- :param dst: Destination image of the same type as ``src`` and the
- size ``Size(src.cols+left+right, src.rows+top+bottom)`` .
-
- :param top:
-
- :param bottom:
-
- :param left:
-
- :param right: Parameter specifying how many pixels in each direction from the source image
- rectangle to extrapolate. For example, ``top=1, bottom=1, left=1, right=1``
- mean that 1 pixel-wide border needs to be built.
-
- :param borderType: Border type. See :ocv:func:`borderInterpolate` for details.
-
- :param value: Border value if ``borderType==BORDER_CONSTANT`` .
-
-The function copies the source image into the middle of the destination image. The areas to the
-left, to the right, above and below the copied source image will be filled with extrapolated pixels.
-This is not what filtering functions based on it do (they extrapolate
-pixels on-fly), but what other more complex functions, including your own, may do to simplify image
-boundary handling.
-
-The function supports the mode when ``src`` is already in the middle of ``dst`` . In this case, the
-function does not copy ``src`` itself but simply constructs the border, for example: ::
-
- // let border be the same in all directions
- int border=2;
- // constructs a larger image to fit both the image and the border
- Mat gray_buf(rgb.rows + border*2, rgb.cols + border*2, rgb.depth());
- // select the middle part of it w/o copying data
- Mat gray(gray_canvas, Rect(border, border, rgb.cols, rgb.rows));
- // convert image from RGB to grayscale
- cvtColor(rgb, gray, COLOR_RGB2GRAY);
- // form a border in-place
- copyMakeBorder(gray, gray_buf, border, border,
- border, border, BORDER_REPLICATE);
- // now do some custom filtering ...
- ...
-
-
-.. note::
-
- When the source image is a part (ROI) of a bigger image, the function will try to use the pixels
- outside of the ROI to form a border. To disable this feature and always do extrapolation, as if
- ``src`` was not a ROI, use ``borderType | BORDER_ISOLATED``.
-
-.. seealso::
-
- :ocv:func:`borderInterpolate`
+++ /dev/null
-Optimization Algorithms
-=======================
-
-.. highlight:: cpp
-
-The algorithms in this section minimize or maximize function value within specified constraints or without any constraints.
-
-solveLP
---------------------
-Solve given (non-integer) linear programming problem using the Simplex Algorithm (Simplex Method).
-What we mean here by "linear programming problem" (or LP problem, for short) can be
-formulated as:
-
-.. math::
- \mbox{Maximize } c\cdot x\\
- \mbox{Subject to:}\\
- Ax\leq b\\
- x\geq 0
-
-Where :math:`c` is fixed *1*-by-*n* row-vector, :math:`A` is fixed *m*-by-*n* matrix, :math:`b` is fixed *m*-by-*1* column vector and
-:math:`x` is an arbitrary *n*-by-*1* column vector, which satisfies the constraints.
-
-Simplex algorithm is one of many algorithms that are designed to handle this sort of problems efficiently. Although it is not optimal in theoretical
-sense (there exist algorithms that can solve any problem written as above in polynomial type, while simplex method degenerates to exponential time
-for some special cases), it is well-studied, easy to implement and is shown to work well for real-life purposes.
-
-The particular implementation is taken almost verbatim from **Introduction to Algorithms, third edition**
-by T. H. Cormen, C. E. Leiserson, R. L. Rivest and Clifford Stein. In particular, the Bland's rule
-(`http://en.wikipedia.org/wiki/Bland%27s\_rule <http://en.wikipedia.org/wiki/Bland%27s_rule>`_) is used to prevent cycling.
-
-.. ocv:function:: int solveLP(const Mat& Func, const Mat& Constr, Mat& z)
-
- :param Func: This row-vector corresponds to :math:`c` in the LP problem formulation (see above). It should contain 32- or 64-bit floating point numbers. As a convenience, column-vector may be also submitted, in the latter case it is understood to correspond to :math:`c^T`.
-
- :param Constr: *m*-by-*n\+1* matrix, whose rightmost column corresponds to :math:`b` in formulation above and the remaining to :math:`A`. It should containt 32- or 64-bit floating point numbers.
-
- :param z: The solution will be returned here as a column-vector - it corresponds to :math:`c` in the formulation above. It will contain 64-bit floating point numbers.
-
- :return: One of the return codes:
-
-::
-
- //!the return codes for solveLP() function
- enum
- {
- SOLVELP_UNBOUNDED = -2, //problem is unbounded (target function can achieve arbitrary high values)
- SOLVELP_UNFEASIBLE = -1, //problem is unfeasible (there are no points that satisfy all the constraints imposed)
- SOLVELP_SINGLE = 0, //there is only one maximum for target function
- SOLVELP_MULTI = 1 //there are multiple maxima for target function - the arbitrary one is returned
- };
-
-DownhillSolver
----------------------------------
-
-.. ocv:class:: DownhillSolver
-
-This class is used to perform the non-linear non-constrained *minimization* of a function, defined on an *n*-dimensional Euclidean space,
-using the **Nelder-Mead method**, also known as **downhill simplex method**. The basic idea about the method can be obtained from
-(`http://en.wikipedia.org/wiki/Nelder-Mead\_method <http://en.wikipedia.org/wiki/Nelder-Mead_method>`_). It should be noted, that
-this method, although deterministic, is rather a heuristic and therefore may converge to a local minima, not necessary a global one.
-It is iterative optimization technique, which at each step uses an information about the values of a function evaluated only at
-*n+1* points, arranged as a *simplex* in *n*-dimensional space (hence the second name of the method). At each step new point is
-chosen to evaluate function at, obtained value is compared with previous ones and based on this information simplex changes it's shape
-, slowly moving to the local minimum. Thus this method is using *only* function values to make decision, on contrary to, say, Nonlinear
-Conjugate Gradient method (which is also implemented in ``optim``).
-
-Algorithm stops when the number of function evaluations done exceeds ``termcrit.maxCount``, when the function values at the
-vertices of simplex are within ``termcrit.epsilon`` range or simplex becomes so small that it
-can enclosed in a box with ``termcrit.epsilon`` sides, whatever comes first, for some defined by user
-positive integer ``termcrit.maxCount`` and positive non-integer ``termcrit.epsilon``.
-
-::
-
- class CV_EXPORTS Solver : public Algorithm
- {
- public:
- class CV_EXPORTS Function
- {
- public:
- virtual ~Function() {}
- virtual double calc(const double* x) const = 0;
- virtual void getGradient(const double* /*x*/,double* /*grad*/) {}
- };
-
- virtual Ptr<Function> getFunction() const = 0;
- virtual void setFunction(const Ptr<Function>& f) = 0;
-
- virtual TermCriteria getTermCriteria() const = 0;
- virtual void setTermCriteria(const TermCriteria& termcrit) = 0;
-
- // x contain the initial point before the call and the minima position (if algorithm converged) after. x is assumed to be (something that
- // after getMat() will return) row-vector or column-vector. *It's size and should
- // be consisted with previous dimensionality data given, if any (otherwise, it determines dimensionality)*
- virtual double minimize(InputOutputArray x) = 0;
- };
-
- class CV_EXPORTS DownhillSolver : public Solver
- {
- public:
- //! returns row-vector, even if the column-vector was given
- virtual void getInitStep(OutputArray step) const=0;
- //!This should be called at least once before the first call to minimize() and step is assumed to be (something that
- //! after getMat() will return) row-vector or column-vector. *It's dimensionality determines the dimensionality of a problem.*
- virtual void setInitStep(InputArray step)=0;
- };
-
-It should be noted, that ``DownhillSolver`` is a derivative of the abstract interface ``Solver``, which in
-turn is derived from the ``Algorithm`` interface and is used to encapsulate the functionality, common to all non-linear optimization
-algorithms in the ``optim`` module.
-
-DownhillSolver::getFunction
---------------------------------------------
-
-Getter for the optimized function. The optimized function is represented by ``Solver::Function`` interface, which requires
-derivatives to implement the sole method ``calc(double*)`` to evaluate the function.
-
-.. ocv:function:: Ptr<Solver::Function> DownhillSolver::getFunction()
-
- :return: Smart-pointer to an object that implements ``Solver::Function`` interface - it represents the function that is being optimized. It can be empty, if no function was given so far.
-
-DownhillSolver::setFunction
------------------------------------------------
-
-Setter for the optimized function. *It should be called at least once before the call to* ``DownhillSolver::minimize()``, as
-default value is not usable.
-
-.. ocv:function:: void DownhillSolver::setFunction(const Ptr<Solver::Function>& f)
-
- :param f: The new function to optimize.
-
-DownhillSolver::getTermCriteria
-----------------------------------------------------
-
-Getter for the previously set terminal criteria for this algorithm.
-
-.. ocv:function:: TermCriteria DownhillSolver::getTermCriteria()
-
- :return: Deep copy of the terminal criteria used at the moment.
-
-DownhillSolver::setTermCriteria
-------------------------------------------
-
-Set terminal criteria for downhill simplex method. Two things should be noted. First, this method *is not necessary* to be called
-before the first call to ``DownhillSolver::minimize()``, as the default value is sensible. Second, the method will raise an error
-if ``termcrit.type!=(TermCriteria::MAX_ITER+TermCriteria::EPS)``, ``termcrit.epsilon<=0`` or ``termcrit.maxCount<=0``. That is,
-both ``epsilon`` and ``maxCount`` should be set to positive values (non-integer and integer respectively) and they represent
-tolerance and maximal number of function evaluations that is allowed.
-
-Algorithm stops when the number of function evaluations done exceeds ``termcrit.maxCount``, when the function values at the
-vertices of simplex are within ``termcrit.epsilon`` range or simplex becomes so small that it
-can enclosed in a box with ``termcrit.epsilon`` sides, whatever comes first.
-
-.. ocv:function:: void DownhillSolver::setTermCriteria(const TermCriteria& termcrit)
-
- :param termcrit: Terminal criteria to be used, represented as ``TermCriteria`` structure (defined elsewhere in openCV). Mind you, that it should meet ``(termcrit.type==(TermCriteria::MAX_ITER+TermCriteria::EPS) && termcrit.epsilon>0 && termcrit.maxCount>0)``, otherwise the error will be raised.
-
-DownhillSolver::getInitStep
------------------------------------
-
-Returns the initial step that will be used in downhill simplex algorithm. See the description
-of corresponding setter (follows next) for the meaning of this parameter.
-
-.. ocv:function:: void getInitStep(OutputArray step)
-
- :param step: Initial step that will be used in algorithm. Note, that although corresponding setter accepts column-vectors as well as row-vectors, this method will return a row-vector.
-
-DownhillSolver::setInitStep
-----------------------------------
-
-Sets the initial step that will be used in downhill simplex algorithm. Step, together with initial point (givin in ``DownhillSolver::minimize``)
-are two *n*-dimensional vectors that are used to determine the shape of initial simplex. Roughly said, initial point determines the position
-of a simplex (it will become simplex's centroid), while step determines the spread (size in each dimension) of a simplex. To be more precise,
-if :math:`s,x_0\in\mathbb{R}^n` are the initial step and initial point respectively, the vertices of a simplex will be: :math:`v_0:=x_0-\frac{1}{2}
-s` and :math:`v_i:=x_0+s_i` for :math:`i=1,2,\dots,n` where :math:`s_i` denotes projections of the initial step of *n*-th coordinate (the result
-of projection is treated to be vector given by :math:`s_i:=e_i\cdot\left<e_i\cdot s\right>`, where :math:`e_i` form canonical basis)
-
-.. ocv:function:: void setInitStep(InputArray step)
-
- :param step: Initial step that will be used in algorithm. Roughly said, it determines the spread (size in each dimension) of an initial simplex.
-
-DownhillSolver::minimize
------------------------------------
-
-The main method of the ``DownhillSolver``. It actually runs the algorithm and performs the minimization. The sole input parameter determines the
-centroid of the starting simplex (roughly, it tells where to start), all the others (terminal criteria, initial step, function to be minimized)
-are supposed to be set via the setters before the call to this method or the default values (not always sensible) will be used.
-
-.. ocv:function:: double DownhillSolver::minimize(InputOutputArray x)
-
- :param x: The initial point, that will become a centroid of an initial simplex. After the algorithm will terminate, it will be setted to the point where the algorithm stops, the point of possible minimum.
-
- :return: The value of a function at the point found.
-
-createDownhillSolver
-------------------------------------
-
-This function returns the reference to the ready-to-use ``DownhillSolver`` object. All the parameters are optional, so this procedure can be called
-even without parameters at all. In this case, the default values will be used. As default value for terminal criteria are the only sensible ones,
-``DownhillSolver::setFunction()`` and ``DownhillSolver::setInitStep()`` should be called upon the obtained object, if the respective parameters
-were not given to ``createDownhillSolver()``. Otherwise, the two ways (give parameters to ``createDownhillSolver()`` or miss them out and call the
-``DownhillSolver::setFunction()`` and ``DownhillSolver::setInitStep()``) are absolutely equivalent (and will drop the same errors in the same way,
-should invalid input be detected).
-
-.. ocv:function:: Ptr<DownhillSolver> createDownhillSolver(const Ptr<Solver::Function>& f,InputArray initStep, TermCriteria termcrit)
-
- :param f: Pointer to the function that will be minimized, similarly to the one you submit via ``DownhillSolver::setFunction``.
- :param step: Initial step, that will be used to construct the initial simplex, similarly to the one you submit via ``DownhillSolver::setInitStep``.
- :param termcrit: Terminal criteria to the algorithm, similarly to the one you submit via ``DownhillSolver::setTermCriteria``.
-
-
-ConjGradSolver
----------------------------------
-
-.. ocv:class:: ConjGradSolver
-
-This class is used to perform the non-linear non-constrained *minimization* of a function with *known gradient*
-, defined on an *n*-dimensional Euclidean space,
-using the **Nonlinear Conjugate Gradient method**. The implementation was done based on the beautifully clear explanatory article `An Introduction to the Conjugate Gradient Method Without the Agonizing Pain <http://www.cs.cmu.edu/~quake-papers/painless-conjugate-gradient.pdf>`_
-by Jonathan Richard Shewchuk. The method can be seen as an adaptation of a standard Conjugate Gradient method (see, for example
-`http://en.wikipedia.org/wiki/Conjugate_gradient_method <http://en.wikipedia.org/wiki/Conjugate_gradient_method>`_) for numerically solving the
-systems of linear equations.
-
-It should be noted, that
-this method, although deterministic, is rather a heuristic method and therefore may converge to a local minima, not necessary a global one. What
-is even more disastrous, most of its behaviour is ruled by gradient, therefore it essentially cannot distinguish between local minima and maxima.
-Therefore, if it starts sufficiently near to the local maximum, it may converge to it. Another obvious restriction is that it should be possible
-to compute the gradient of a function at any point, thus it is preferable to have analytic expression for gradient and computational burden
-should be born by the user.
-
-The latter responsibility is accompilished via the ``getGradient(const double* x,double* grad)`` method of a
-``Solver::Function`` interface (which represents function that is being optimized). This method takes point a point in *n*-dimensional space
-(first argument represents the array of coordinates of that point) and comput its gradient (it should be stored in the second argument as an array).
-
- ::
-
- class CV_EXPORTS Solver : public Algorithm
- {
- public:
- class CV_EXPORTS Function
- {
- public:
- virtual ~Function() {}
- virtual double calc(const double* x) const = 0;
- virtual void getGradient(const double* /*x*/,double* /*grad*/) {}
- };
-
- virtual Ptr<Function> getFunction() const = 0;
- virtual void setFunction(const Ptr<Function>& f) = 0;
-
- virtual TermCriteria getTermCriteria() const = 0;
- virtual void setTermCriteria(const TermCriteria& termcrit) = 0;
-
- // x contain the initial point before the call and the minima position (if algorithm converged) after. x is assumed to be (something that
- // after getMat() will return) row-vector or column-vector. *It's size and should
- // be consisted with previous dimensionality data given, if any (otherwise, it determines dimensionality)*
- virtual double minimize(InputOutputArray x) = 0;
- };
-
- class CV_EXPORTS ConjGradSolver : public Solver{
- };
-
- Note, that class ``ConjGradSolver`` thus does not add any new methods to the basic ``Solver`` interface.
-
-ConjGradSolver::getFunction
---------------------------------------------
-
-Getter for the optimized function. The optimized function is represented by ``Solver::Function`` interface, which requires
-derivatives to implement the method ``calc(double*)`` to evaluate the function. It should be emphasized once more, that since Nonlinear
-Conjugate Gradient method requires gradient to be computable in addition to the function values,
-``getGradient(const double* x,double* grad)`` method of a ``Solver::Function`` interface should be also implemented meaningfully.
-
-.. ocv:function:: Ptr<Solver::Function> ConjGradSolver::getFunction()
-
- :return: Smart-pointer to an object that implements ``Solver::Function`` interface - it represents the function that is being optimized. It can be empty, if no function was given so far.
-
-ConjGradSolver::setFunction
------------------------------------------------
-
-Setter for the optimized function. *It should be called at least once before the call to* ``ConjGradSolver::minimize()``, as
-default value is not usable.
-
-.. ocv:function:: void ConjGradSolver::setFunction(const Ptr<Solver::Function>& f)
-
- :param f: The new function to optimize.
-
-ConjGradSolver::getTermCriteria
-----------------------------------------------------
-
-Getter for the previously set terminal criteria for this algorithm.
-
-.. ocv:function:: TermCriteria ConjGradSolver::getTermCriteria()
-
- :return: Deep copy of the terminal criteria used at the moment.
-
-ConjGradSolver::setTermCriteria
-------------------------------------------
-
-Set terminal criteria for downhill simplex method. Two things should be noted. First, this method *is not necessary* to be called
-before the first call to ``ConjGradSolver::minimize()``, as the default value is sensible. Second, the method will raise an error
-if ``termcrit.type!=(TermCriteria::MAX_ITER+TermCriteria::EPS)`` and ``termcrit.type!=TermCriteria::MAX_ITER``. This means that termination criteria
-has to restrict maximum number of iterations to be done and may optionally allow algorithm to stop earlier if certain tolerance
-is achieved (what we mean by "tolerance is achieved" will be clarified below). If ``termcrit`` restricts both tolerance and maximum iteration
-number, both ``termcrit.epsilon`` and ``termcrit.maxCount`` should be positive. In case, if ``termcrit.type==TermCriteria::MAX_ITER``,
-only member ``termcrit.maxCount`` is required to be positive and in this case algorithm will just work for required number of iterations.
-
-In current implementation, "tolerance is achieved" means that we have arrived at the point where the :math:`L_2`-norm of the gradient is less
-than the tolerance value.
-
-.. ocv:function:: void ConjGradSolver::setTermCriteria(const TermCriteria& termcrit)
-
- :param termcrit: Terminal criteria to be used, represented as ``TermCriteria`` structure (defined elsewhere in openCV). Mind you, that it should meet ``termcrit.type==(TermCriteria::MAX_ITER+TermCriteria::EPS) && termcrit.epsilon>0 && termcrit.maxCount>0`` or ``termcrit.type==TermCriteria::MAX_ITER) && termcrit.maxCount>0``, otherwise the error will be raised.
-
-ConjGradSolver::minimize
------------------------------------
-
-The main method of the ``ConjGradSolver``. It actually runs the algorithm and performs the minimization. The sole input parameter determines the
-centroid of the starting simplex (roughly, it tells where to start), all the others (terminal criteria and function to be minimized)
-are supposed to be set via the setters before the call to this method or the default values (not always sensible) will be used. Sometimes it may
-throw an error, if these default values cannot be used (say, you forgot to set the function to minimize and default value, that is, empty function,
-cannot be used).
-
-.. ocv:function:: double ConjGradSolver::minimize(InputOutputArray x)
-
- :param x: The initial point. It is hard to overemphasize how important the choise of initial point is when you are using the heuristic algorithm like this one. Badly chosen initial point can make algorithm converge to (local) maximum instead of minimum, do not converge at all, converge to local minimum instead of global one.
-
- :return: The value of a function at the point found.
-
-createConjGradSolver
-------------------------------------
-
-This function returns the reference to the ready-to-use ``ConjGradSolver`` object. All the parameters are optional, so this procedure can be called
-even without parameters at all. In this case, the default values will be used. As default value for terminal criteria are the only sensible ones,
-``ConjGradSolver::setFunction()`` should be called upon the obtained object, if the function
-was not given to ``createConjGradSolver()``. Otherwise, the two ways (submit it to ``createConjGradSolver()`` or miss it out and call the
-``ConjGradSolver::setFunction()``) are absolutely equivalent (and will drop the same errors in the same way,
-should invalid input be detected).
-
-.. ocv:function:: Ptr<ConjGradSolver> createConjGradSolver(const Ptr<Solver::Function>& f, TermCriteria termcrit)
-
- :param f: Pointer to the function that will be minimized, similarly to the one you submit via ``ConjGradSolver::setFunction``.
- :param termcrit: Terminal criteria to the algorithm, similarly to the one you submit via ``ConjGradSolver::setTermCriteria``.
+++ /dev/null
-Utility and System Functions and Macros
-=======================================
-
-.. highlight:: cpp
-
-alignPtr
-------------
-Aligns a pointer to the specified number of bytes.
-
-.. ocv:function:: template<typename _Tp> _Tp* alignPtr(_Tp* ptr, int n=sizeof(_Tp))
-
- :param ptr: Aligned pointer.
-
- :param n: Alignment size that must be a power of two.
-
-The function returns the aligned pointer of the same type as the input pointer:
-
-.. math::
-
- \texttt{(\_Tp*)(((size\_t)ptr + n-1) \& -n)}
-
-
-
-alignSize
--------------
-Aligns a buffer size to the specified number of bytes.
-
-.. ocv:function:: size_t alignSize(size_t sz, int n)
-
- :param sz: Buffer size to align.
-
- :param n: Alignment size that must be a power of two.
-
-The function returns the minimum number that is greater or equal to ``sz`` and is divisible by ``n`` :
-
-.. math::
-
- \texttt{(sz + n-1) \& -n}
-
-
-
-allocate
-------------
-Allocates an array of elements.
-
-.. ocv:function:: template<typename _Tp> _Tp* allocate(size_t n)
-
- :param n: Number of elements to allocate.
-
-The generic function ``allocate`` allocates a buffer for the specified number of elements. For each element, the default constructor is called.
-
-
-
-deallocate
---------------
-Deallocates an array of elements.
-
-.. ocv:function:: template<typename _Tp> void deallocate(_Tp* ptr, size_t n)
-
- :param ptr: Pointer to the deallocated buffer.
-
- :param n: Number of elements in the buffer.
-
-The generic function ``deallocate`` deallocates the buffer allocated with
-:ocv:func:`allocate` . The number of elements must match the number passed to
-:ocv:func:`allocate` .
-
-
-
-fastAtan2
----------
-Calculates the angle of a 2D vector in degrees.
-
-.. ocv:function:: float fastAtan2(float y, float x)
-
-.. ocv:pyfunction:: cv2.fastAtan2(y, x) -> retval
-
-.. ocv:cfunction:: float cvFastArctan(float y, float x)
-
- :param x: x-coordinate of the vector.
-
- :param y: y-coordinate of the vector.
-
-The function ``fastAtan2`` calculates the full-range angle of an input 2D vector. The angle is measured in degrees and varies from 0 to 360 degrees. The accuracy is about 0.3 degrees.
-
-
-cubeRoot
---------
-Computes the cube root of an argument.
-
-.. ocv:function:: float cubeRoot(float val)
-
-.. ocv:pyfunction:: cv2.cubeRoot(val) -> retval
-
-.. ocv:cfunction:: float cvCbrt( float value )
-
- :param val: A function argument.
-
-The function ``cubeRoot`` computes :math:`\sqrt[3]{\texttt{val}}`. Negative arguments are handled correctly. NaN and Inf are not handled. The accuracy approaches the maximum possible accuracy for single-precision data.
-
-
-Ceil
------
-Rounds floating-point number to the nearest integer not smaller than the original.
-
-.. ocv:cfunction:: int cvCeil(double value)
-
- :param value: floating-point number. If the value is outside of ``INT_MIN`` ... ``INT_MAX`` range, the result is not defined.
-
-The function computes an integer ``i`` such that:
-
-.. math::
-
- i-1 < \texttt{value} \le i
-
-
-Floor
------
-Rounds floating-point number to the nearest integer not larger than the original.
-
-.. ocv:cfunction:: int cvFloor(double value)
-
- :param value: floating-point number. If the value is outside of ``INT_MIN`` ... ``INT_MAX`` range, the result is not defined.
-
-The function computes an integer ``i`` such that:
-
-.. math::
-
- i \le \texttt{value} < i+1
-
-
-Round
------
-Rounds floating-point number to the nearest integer
-
-.. ocv:cfunction:: int cvRound(double value)
-
- :param value: floating-point number. If the value is outside of ``INT_MIN`` ... ``INT_MAX`` range, the result is not defined.
-
-
-IsInf
------
-Determines if the argument is Infinity.
-
-.. ocv:cfunction:: int cvIsInf(double value)
-
- :param value: The input floating-point value
-
-The function returns 1 if the argument is a plus or minus infinity (as defined by IEEE754 standard) and 0 otherwise.
-
-IsNaN
------
-Determines if the argument is Not A Number.
-
-.. ocv:cfunction:: int cvIsNaN(double value)
-
- :param value: The input floating-point value
-
-The function returns 1 if the argument is Not A Number (as defined by IEEE754 standard), 0 otherwise.
-
-
-CV_Assert
----------
-Checks a condition at runtime and throws exception if it fails
-
-.. ocv:function:: CV_Assert(expr)
-
- :param expr: Expression for check.
-
-The macros ``CV_Assert`` (and ``CV_DbgAssert``) evaluate the specified expression. If it is 0, the macros raise an error (see :ocv:func:`error` ). The macro ``CV_Assert`` checks the condition in both Debug and Release configurations while ``CV_DbgAssert`` is only retained in the Debug configuration.
-
-
-error
------
-Signals an error and raises an exception.
-
-.. ocv:function:: void error( const Exception& exc )
-
-.. ocv:cfunction:: void cvError( int status, const char* func_name, const char* err_msg, const char* file_name, int line )
-
- :param exc: Exception to throw.
-
- :param status: Error code. Normally, it is a negative value. The list of pre-defined error codes can be found in ``cxerror.h`` .
-
- :param func_name: The function name where error occurs.
-
- :param err_msg: Text of the error message.
-
- :param file_name: The file name where error occurs.
-
- :param line: The line number where error occurs.
-
- :param args: ``printf`` -like formatted error message in parentheses.
-
-The function and the helper macros ``CV_Error`` and ``CV_Error_``: ::
-
- #define CV_Error( code, msg ) error(...)
- #define CV_Error_( code, args ) error(...)
-
-call the error handler. Currently, the error handler prints the error code ( ``exc.code`` ), the context ( ``exc.file``,``exc.line`` ), and the error message ``exc.err`` to the standard error stream ``stderr`` . In the Debug configuration, it then provokes memory access violation, so that the execution stack and all the parameters can be analyzed by the debugger. In the Release configuration, the exception ``exc`` is thrown.
-
-The macro ``CV_Error_`` can be used to construct an error message on-fly to include some dynamic information, for example: ::
-
- // note the extra parentheses around the formatted text message
- CV_Error_(CV_StsOutOfRange,
- ("the matrix element (
- i, j, mtx.at<float>(i,j)))
-
-
-Exception
----------
-.. ocv:class:: Exception : public std::exception
-
-Exception class passed to an error. ::
-
- class Exception
- {
- public:
- // various constructors and the copy operation
- Exception() { code = 0; line = 0; }
- Exception(int _code, const String& _err,
- const String& _func, const String& _file, int _line);
- Exception(const Exception& exc);
- Exception& operator = (const Exception& exc);
-
- // the error code
- int code;
- // the error text message
- String err;
- // function name where the error happened
- String func;
- // the source file name where the error happened
- String file;
- // the source file line where the error happened
- int line;
- };
-
-The class ``Exception`` encapsulates all or almost all necessary information about the error happened in the program. The exception is usually constructed and thrown implicitly via ``CV_Error`` and ``CV_Error_`` macros. See
-:ocv:func:`error` .
-
-
-
-fastMalloc
---------------
-Allocates an aligned memory buffer.
-
-.. ocv:function:: void* fastMalloc( size_t bufSize )
-
-.. ocv:cfunction:: void* cvAlloc( size_t size )
-
- :param size: Allocated buffer size.
- :param bufSize: Allocated buffer size.
-
-The function allocates the buffer of the specified size and returns it. When the buffer size is 16 bytes or more, the returned buffer is aligned to 16 bytes.
-
-
-
-fastFree
---------
-Deallocates a memory buffer.
-
-.. ocv:function:: void fastFree(void* ptr)
-.. ocv:cfunction:: void cvFree( void** pptr )
-
- :param ptr: Pointer to the allocated buffer.
-
- :param pptr: Double pointer to the allocated buffer
-
-The function deallocates the buffer allocated with :ocv:func:`fastMalloc` . If NULL pointer is passed, the function does nothing. C version of the function clears the pointer ``*pptr`` to avoid problems with double memory deallocation.
-
-
-format
-------
-Returns a text string formatted using the ``printf``\ -like expression.
-
-.. ocv:function:: String format( const char* fmt, ... )
-
- :param fmt: ``printf`` -compatible formatting specifiers.
-
-The function acts like ``sprintf`` but forms and returns an STL string. It can be used to form an error message in the
-:ocv:class:`Exception` constructor.
-
-
-getBuildInformation
--------------------
-Returns full configuration time cmake output.
-
-.. ocv:function:: const String& getBuildInformation()
-
-Returned value is raw cmake output including version control system revision, compiler version, compiler flags, enabled modules and third party libraries, etc. Output format depends on target architecture.
-
-
-checkHardwareSupport
---------------------
-Returns true if the specified feature is supported by the host hardware.
-
-.. ocv:function:: bool checkHardwareSupport(int feature)
-.. ocv:cfunction:: int cvCheckHardwareSupport(int feature)
-.. ocv:pyfunction:: cv2.checkHardwareSupport(feature) -> retval
-
- :param feature: The feature of interest, one of:
-
- * ``CV_CPU_MMX`` - MMX
- * ``CV_CPU_SSE`` - SSE
- * ``CV_CPU_SSE2`` - SSE 2
- * ``CV_CPU_SSE3`` - SSE 3
- * ``CV_CPU_SSSE3`` - SSSE 3
- * ``CV_CPU_SSE4_1`` - SSE 4.1
- * ``CV_CPU_SSE4_2`` - SSE 4.2
- * ``CV_CPU_POPCNT`` - POPCOUNT
- * ``CV_CPU_AVX`` - AVX
-
-The function returns true if the host hardware supports the specified feature. When user calls ``setUseOptimized(false)``, the subsequent calls to ``checkHardwareSupport()`` will return false until ``setUseOptimized(true)`` is called. This way user can dynamically switch on and off the optimized code in OpenCV.
-
-
-
-getNumberOfCPUs
------------------
-Returns the number of logical CPUs available for the process.
-
-.. ocv:function:: int getNumberOfCPUs()
-
-
-
-getNumThreads
------------------
-Returns the number of threads used by OpenCV for parallel regions.
-Always returns 1 if OpenCV is built without threading support.
-
-.. ocv:function:: int getNumThreads()
-
-The exact meaning of return value depends on the threading framework used by OpenCV library:
-
- * **TBB** – The number of threads, that OpenCV will try to use for parallel regions.
- If there is any ``tbb::thread_scheduler_init`` in user code conflicting with OpenCV, then
- function returns default number of threads used by TBB library.
- * **OpenMP** – An upper bound on the number of threads that could be used to form a new team.
- * **Concurrency** – The number of threads, that OpenCV will try to use for parallel regions.
- * **GCD** – Unsupported; returns the GCD thread pool limit (512) for compatibility.
- * **C=** – The number of threads, that OpenCV will try to use for parallel regions,
- if before called ``setNumThreads`` with ``threads > 0``,
- otherwise returns the number of logical CPUs, available for the process.
-
-.. seealso::
- :ocv:func:`setNumThreads`,
- :ocv:func:`getThreadNum`
-
-
-
-getThreadNum
-----------------
-Returns the index of the currently executed thread within the current parallel region.
-Always returns 0 if called outside of parallel region.
-
-.. ocv:function:: int getThreadNum()
-
-The exact meaning of return value depends on the threading framework used by OpenCV library:
-
- * **TBB** – Unsupported with current 4.1 TBB release. May be will be supported in future.
- * **OpenMP** – The thread number, within the current team, of the calling thread.
- * **Concurrency** – An ID for the virtual processor that the current context is executing
- on (0 for master thread and unique number for others, but not necessary 1,2,3,...).
- * **GCD** – System calling thread's ID. Never returns 0 inside parallel region.
- * **C=** – The index of the current parallel task.
-
-.. seealso::
- :ocv:func:`setNumThreads`,
- :ocv:func:`getNumThreads`
-
-
-
-getTickCount
-------------
-Returns the number of ticks.
-
-.. ocv:function:: int64 getTickCount()
-
-.. ocv:pyfunction:: cv2.getTickCount() -> retval
-
-The function returns the number of ticks after the certain event (for example, when the machine was turned on).
-It can be used to initialize
-:ocv:func:`RNG` or to measure a function execution time by reading the tick count before and after the function call. See also the tick frequency.
-
-
-
-getTickFrequency
-----------------
-Returns the number of ticks per second.
-
-.. ocv:function:: double getTickFrequency()
-
-.. ocv:pyfunction:: cv2.getTickFrequency() -> retval
-
-The function returns the number of ticks per second.
-That is, the following code computes the execution time in seconds: ::
-
- double t = (double)getTickCount();
- // do something ...
- t = ((double)getTickCount() - t)/getTickFrequency();
-
-
-
-getCPUTickCount
----------------
-Returns the number of CPU ticks.
-
-.. ocv:function:: int64 getCPUTickCount()
-
-.. ocv:pyfunction:: cv2.getCPUTickCount() -> retval
-
-The function returns the current number of CPU ticks on some architectures (such as x86, x64, PowerPC). On other platforms the function is equivalent to ``getTickCount``. It can also be used for very accurate time measurements, as well as for RNG initialization. Note that in case of multi-CPU systems a thread, from which ``getCPUTickCount`` is called, can be suspended and resumed at another CPU with its own counter. So, theoretically (and practically) the subsequent calls to the function do not necessary return the monotonously increasing values. Also, since a modern CPU varies the CPU frequency depending on the load, the number of CPU clocks spent in some code cannot be directly converted to time units. Therefore, ``getTickCount`` is generally a preferable solution for measuring execution time.
-
-
-saturate_cast
--------------
-Template function for accurate conversion from one primitive type to another.
-
-.. ocv:function:: template<...> _Tp saturate_cast(_Tp2 v)
-
- :param v: Function parameter.
-
-The functions ``saturate_cast`` resemble the standard C++ cast operations, such as ``static_cast<T>()`` and others. They perform an efficient and accurate conversion from one primitive type to another (see the introduction chapter). ``saturate`` in the name means that when the input value ``v`` is out of the range of the target type, the result is not formed just by taking low bits of the input, but instead the value is clipped. For example: ::
-
- uchar a = saturate_cast<uchar>(-100); // a = 0 (UCHAR_MIN)
- short b = saturate_cast<short>(33333.33333); // b = 32767 (SHRT_MAX)
-
-Such clipping is done when the target type is ``unsigned char`` , ``signed char`` , ``unsigned short`` or ``signed short`` . For 32-bit integers, no clipping is done.
-
-When the parameter is a floating-point value and the target type is an integer (8-, 16- or 32-bit), the floating-point value is first rounded to the nearest integer and then clipped if needed (when the target type is 8- or 16-bit).
-
-This operation is used in the simplest or most complex image processing functions in OpenCV.
-
-.. seealso::
-
- :ocv:func:`add`,
- :ocv:func:`subtract`,
- :ocv:func:`multiply`,
- :ocv:func:`divide`,
- :ocv:func:`Mat::convertTo`
-
-setNumThreads
------------------
-OpenCV will try to set the number of threads for the next parallel region.
-If ``threads == 0``, OpenCV will disable threading optimizations and run all it's
-functions sequentially. Passing ``threads < 0`` will reset threads number to system default.
-This function must be called outside of parallel region.
-
-.. ocv:function:: void setNumThreads(int nthreads)
-
- :param nthreads: Number of threads used by OpenCV.
-
-OpenCV will try to run it's functions with specified threads number, but
-some behaviour differs from framework:
-
- * **TBB** – User-defined parallel constructions will run with the same threads number,
- if another does not specified. If late on user creates own scheduler, OpenCV will be use it.
- * **OpenMP** – No special defined behaviour.
- * **Concurrency** – If ``threads == 1``, OpenCV will disable threading optimizations
- and run it's functions sequentially.
- * **GCD** – Supports only values <= 0.
- * **C=** – No special defined behaviour.
-
-.. seealso::
- :ocv:func:`getNumThreads`,
- :ocv:func:`getThreadNum`
-
-
-
-setUseOptimized
----------------
-Enables or disables the optimized code.
-
-.. ocv:function:: int cvUseOptimized( int on_off )
-
-.. ocv:pyfunction:: cv2.setUseOptimized(onoff) -> None
-
-.. ocv:cfunction:: int cvUseOptimized( int on_off )
-
- :param on_off: The boolean flag specifying whether the optimized code should be used (``on_off=true``) or not (``on_off=false``).
-
-The function can be used to dynamically turn on and off optimized code (code that uses SSE2, AVX, and other instructions on the platforms that support it). It sets a global flag that is further checked by OpenCV functions. Since the flag is not checked in the inner OpenCV loops, it is only safe to call the function on the very top level in your application where you can be sure that no other OpenCV function is currently executed.
-
-By default, the optimized code is enabled unless you disable it in CMake. The current status can be retrieved using ``useOptimized``.
-
-useOptimized
-------------
-Returns the status of optimized code usage.
-
-.. ocv:function:: bool useOptimized()
-
-.. ocv:pyfunction:: cv2.useOptimized() -> retval
-
-The function returns ``true`` if the optimized code is enabled. Otherwise, it returns ``false``.
+++ /dev/null
-XML/YAML Persistence
-====================
-
-.. highlight:: cpp
-
-XML/YAML file storages. Writing to a file storage.
---------------------------------------------------
-
-You can store and then restore various OpenCV data structures to/from XML (http://www.w3c.org/XML) or YAML
-(http://www.yaml.org) formats. Also, it is possible store and load arbitrarily complex data structures, which include OpenCV data structures, as well as primitive data types (integer and floating-point numbers and text strings) as their elements.
-
-Use the following procedure to write something to XML or YAML:
- #. Create new :ocv:class:`FileStorage` and open it for writing. It can be done with a single call to :ocv:func:`FileStorage::FileStorage` constructor that takes a filename, or you can use the default constructor and then call :ocv:func:`FileStorage::open`. Format of the file (XML or YAML) is determined from the filename extension (".xml" and ".yml"/".yaml", respectively)
- #. Write all the data you want using the streaming operator ``<<``, just like in the case of STL streams.
- #. Close the file using :ocv:func:`FileStorage::release`. ``FileStorage`` destructor also closes the file.
-
-Here is an example: ::
-
- #include "opencv2/opencv.hpp"
- #include <time.h>
-
- using namespace cv;
-
- int main(int, char** argv)
- {
- FileStorage fs("test.yml", FileStorage::WRITE);
-
- fs << "frameCount" << 5;
- time_t rawtime; time(&rawtime);
- fs << "calibrationDate" << asctime(localtime(&rawtime));
- Mat cameraMatrix = (Mat_<double>(3,3) << 1000, 0, 320, 0, 1000, 240, 0, 0, 1);
- Mat distCoeffs = (Mat_<double>(5,1) << 0.1, 0.01, -0.001, 0, 0);
- fs << "cameraMatrix" << cameraMatrix << "distCoeffs" << distCoeffs;
- fs << "features" << "[";
- for( int i = 0; i < 3; i++ )
- {
- int x = rand() % 640;
- int y = rand() % 480;
- uchar lbp = rand() % 256;
-
- fs << "{:" << "x" << x << "y" << y << "lbp" << "[:";
- for( int j = 0; j < 8; j++ )
- fs << ((lbp >> j) & 1);
- fs << "]" << "}";
- }
- fs << "]";
- fs.release();
- return 0;
- }
-
-The sample above stores to XML and integer, text string (calibration date), 2 matrices, and a custom structure "feature", which includes feature coordinates and LBP (local binary pattern) value. Here is output of the sample:
-
-.. code-block:: yaml
-
- %YAML:1.0
- frameCount: 5
- calibrationDate: "Fri Jun 17 14:09:29 2011\n"
- cameraMatrix: !!opencv-matrix
- rows: 3
- cols: 3
- dt: d
- data: [ 1000., 0., 320., 0., 1000., 240., 0., 0., 1. ]
- distCoeffs: !!opencv-matrix
- rows: 5
- cols: 1
- dt: d
- data: [ 1.0000000000000001e-01, 1.0000000000000000e-02,
- -1.0000000000000000e-03, 0., 0. ]
- features:
- - { x:167, y:49, lbp:[ 1, 0, 0, 1, 1, 0, 1, 1 ] }
- - { x:298, y:130, lbp:[ 0, 0, 0, 1, 0, 0, 1, 1 ] }
- - { x:344, y:158, lbp:[ 1, 1, 0, 0, 0, 0, 1, 0 ] }
-
-As an exercise, you can replace ".yml" with ".xml" in the sample above and see, how the corresponding XML file will look like.
-
-Several things can be noted by looking at the sample code and the output:
- *
- The produced YAML (and XML) consists of heterogeneous collections that can be nested. There are 2 types of collections: named collections (mappings) and unnamed collections (sequences). In mappings each element has a name and is accessed by name. This is similar to structures and ``std::map`` in C/C++ and dictionaries in Python. In sequences elements do not have names, they are accessed by indices. This is similar to arrays and ``std::vector`` in C/C++ and lists, tuples in Python. "Heterogeneous" means that elements of each single collection can have different types.
-
- Top-level collection in YAML/XML is a mapping. Each matrix is stored as a mapping, and the matrix elements are stored as a sequence. Then, there is a sequence of features, where each feature is represented a mapping, and lbp value in a nested sequence.
-
- *
- When you write to a mapping (a structure), you write element name followed by its value. When you write to a sequence, you simply write the elements one by one. OpenCV data structures (such as cv::Mat) are written in absolutely the same way as simple C data structures - using **``<<``** operator.
-
- *
- To write a mapping, you first write the special string **"{"** to the storage, then write the elements as pairs (``fs << <element_name> << <element_value>``) and then write the closing **"}"**.
-
- *
- To write a sequence, you first write the special string **"["**, then write the elements, then write the closing **"]"**.
-
- *
- In YAML (but not XML), mappings and sequences can be written in a compact Python-like inline form. In the sample above matrix elements, as well as each feature, including its lbp value, is stored in such inline form. To store a mapping/sequence in a compact form, put ":" after the opening character, e.g. use **"{:"** instead of **"{"** and **"[:"** instead of **"["**. When the data is written to XML, those extra ":" are ignored.
-
-.. note::
-
- * A complete example using the FileStorage interface can be found at opencv_source_code/samples/cpp/filestorage.cpp
-
-
-Reading data from a file storage.
----------------------------------
-
-To read the previously written XML or YAML file, do the following:
-
- #.
- Open the file storage using :ocv:func:`FileStorage::FileStorage` constructor or :ocv:func:`FileStorage::open` method. In the current implementation the whole file is parsed and the whole representation of file storage is built in memory as a hierarchy of file nodes (see :ocv:class:`FileNode`)
-
- #.
- Read the data you are interested in. Use :ocv:func:`FileStorage::operator []`, :ocv:func:`FileNode::operator []` and/or :ocv:class:`FileNodeIterator`.
-
- #.
- Close the storage using :ocv:func:`FileStorage::release`.
-
-Here is how to read the file created by the code sample above: ::
-
- FileStorage fs2("test.yml", FileStorage::READ);
-
- // first method: use (type) operator on FileNode.
- int frameCount = (int)fs2["frameCount"];
-
- String date;
- // second method: use FileNode::operator >>
- fs2["calibrationDate"] >> date;
-
- Mat cameraMatrix2, distCoeffs2;
- fs2["cameraMatrix"] >> cameraMatrix2;
- fs2["distCoeffs"] >> distCoeffs2;
-
- cout << "frameCount: " << frameCount << endl
- << "calibration date: " << date << endl
- << "camera matrix: " << cameraMatrix2 << endl
- << "distortion coeffs: " << distCoeffs2 << endl;
-
- FileNode features = fs2["features"];
- FileNodeIterator it = features.begin(), it_end = features.end();
- int idx = 0;
- std::vector<uchar> lbpval;
-
- // iterate through a sequence using FileNodeIterator
- for( ; it != it_end; ++it, idx++ )
- {
- cout << "feature #" << idx << ": ";
- cout << "x=" << (int)(*it)["x"] << ", y=" << (int)(*it)["y"] << ", lbp: (";
- // you can also easily read numerical arrays using FileNode >> std::vector operator.
- (*it)["lbp"] >> lbpval;
- for( int i = 0; i < (int)lbpval.size(); i++ )
- cout << " " << (int)lbpval[i];
- cout << ")" << endl;
- }
- fs.release();
-
-FileStorage
------------
-.. ocv:class:: FileStorage
-
-XML/YAML file storage class that encapsulates all the information necessary for writing or reading data to/from a file.
-
-FileStorage::FileStorage
-------------------------
-The constructors.
-
-.. ocv:function:: FileStorage::FileStorage()
-
-.. ocv:function:: FileStorage::FileStorage(const String& source, int flags, const String& encoding=String())
-
- :param source: Name of the file to open or the text string to read the data from. Extension of the file (``.xml`` or ``.yml``/``.yaml``) determines its format (XML or YAML respectively). Also you can append ``.gz`` to work with compressed files, for example ``myHugeMatrix.xml.gz``. If both ``FileStorage::WRITE`` and ``FileStorage::MEMORY`` flags are specified, ``source`` is used just to specify the output file format (e.g. ``mydata.xml``, ``.yml`` etc.).
-
- :param flags: Mode of operation. Possible values are:
-
- * **FileStorage::READ** Open the file for reading.
-
- * **FileStorage::WRITE** Open the file for writing.
-
- * **FileStorage::APPEND** Open the file for appending.
-
- * **FileStorage::MEMORY** Read data from ``source`` or write data to the internal buffer (which is returned by ``FileStorage::release``)
-
- :param encoding: Encoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.
-
-The full constructor opens the file. Alternatively you can use the default constructor and then call :ocv:func:`FileStorage::open`.
-
-
-FileStorage::open
------------------
-Opens a file.
-
-.. ocv:function:: bool FileStorage::open(const String& filename, int flags, const String& encoding=String())
-
- :param filename: Name of the file to open or the text string to read the data from.
- Extension of the file (``.xml`` or ``.yml``/``.yaml``) determines its format (XML or YAML respectively).
- Also you can append ``.gz`` to work with compressed files, for example ``myHugeMatrix.xml.gz``.
- If both ``FileStorage::WRITE`` and ``FileStorage::MEMORY`` flags are specified, ``source``
- is used just to specify the output file format (e.g. ``mydata.xml``, ``.yml`` etc.).
-
- :param flags: Mode of operation. See FileStorage constructor for more details.
-
- :param encoding: Encoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.
-
-
-See description of parameters in :ocv:func:`FileStorage::FileStorage`. The method calls :ocv:func:`FileStorage::release` before opening the file.
-
-
-FileStorage::isOpened
----------------------
-Checks whether the file is opened.
-
-.. ocv:function:: bool FileStorage::isOpened() const
-
- :returns: ``true`` if the object is associated with the current file and ``false`` otherwise.
-
-It is a good practice to call this method after you tried to open a file.
-
-
-FileStorage::release
---------------------
-Closes the file and releases all the memory buffers.
-
-.. ocv:function:: void FileStorage::release()
-
-Call this method after all I/O operations with the storage are finished.
-
-
-FileStorage::releaseAndGetString
---------------------------------
-Closes the file and releases all the memory buffers.
-
-.. ocv:function:: String FileStorage::releaseAndGetString()
-
-Call this method after all I/O operations with the storage are finished. If the storage was opened for writing data and ``FileStorage::WRITE`` was specified
-
-
-FileStorage::getFirstTopLevelNode
----------------------------------
-Returns the first element of the top-level mapping.
-
-.. ocv:function:: FileNode FileStorage::getFirstTopLevelNode() const
-
- :returns: The first element of the top-level mapping.
-
-
-FileStorage::root
------------------
-Returns the top-level mapping
-
-.. ocv:function:: FileNode FileStorage::root(int streamidx=0) const
-
- :param streamidx: Zero-based index of the stream. In most cases there is only one stream in the file. However, YAML supports multiple streams and so there can be several.
-
- :returns: The top-level mapping.
-
-
-FileStorage::operator[]
------------------------
-Returns the specified element of the top-level mapping.
-
-.. ocv:function:: FileNode FileStorage::operator[](const String& nodename) const
-
-.. ocv:function:: FileNode FileStorage::operator[](const char* nodename) const
-
- :param nodename: Name of the file node.
-
- :returns: Node with the given name.
-
-
-FileStorage::operator*
-----------------------
-Returns the obsolete C FileStorage structure.
-
-.. ocv:function:: CvFileStorage* FileStorage::operator *()
-
-.. ocv:function:: const CvFileStorage* FileStorage::operator *() const
-
- :returns: Pointer to the underlying C FileStorage structure
-
-
-FileStorage::writeRaw
----------------------
-Writes multiple numbers.
-
-.. ocv:function:: void FileStorage::writeRaw( const String& fmt, const uchar* vec, size_t len )
-
- :param fmt: Specification of each array element that has the following format ``([count]{'u'|'c'|'w'|'s'|'i'|'f'|'d'})...`` where the characters correspond to fundamental C++ types:
-
- * **u** 8-bit unsigned number
-
- * **c** 8-bit signed number
-
- * **w** 16-bit unsigned number
-
- * **s** 16-bit signed number
-
- * **i** 32-bit signed number
-
- * **f** single precision floating-point number
-
- * **d** double precision floating-point number
-
- * **r** pointer, 32 lower bits of which are written as a signed integer. The type can be used to store structures with links between the elements.
-
- ``count`` is the optional counter of values of a given type. For example, ``2if`` means that each array element is a structure of 2 integers, followed by a single-precision floating-point number. The equivalent notations of the above specification are ' ``iif`` ', ' ``2i1f`` ' and so forth. Other examples: ``u`` means that the array consists of bytes, and ``2d`` means the array consists of pairs of doubles.
-
- :param vec: Pointer to the written array.
-
- :param len: Number of the ``uchar`` elements to write.
-
-Writes one or more numbers of the specified format to the currently written structure. Usually it is more convenient to use :ocv:func:`operator <<` instead of this method.
-
-FileStorage::writeObj
----------------------
-Writes the registered C structure (CvMat, CvMatND, CvSeq).
-
-.. ocv:function:: void FileStorage::writeObj( const String& name, const void* obj )
-
- :param name: Name of the written object.
-
- :param obj: Pointer to the object.
-
-See :ocv:cfunc:`Write` for details.
-
-
-FileStorage::getDefaultObjectName
----------------------------------
-Returns the normalized object name for the specified name of a file.
-
-.. ocv:function:: static String FileStorage::getDefaultObjectName(const String& filename)
-
- :param filename: Name of a file
-
- :returns: The normalized object name.
-
-
-operator <<
------------
-Writes data to a file storage.
-
-.. ocv:function:: template<typename _Tp> FileStorage& operator << (FileStorage& fs, const _Tp& value)
-
-.. ocv:function:: template<typename _Tp> FileStorage& operator << ( FileStorage& fs, const vector<_Tp>& vec )
-
- :param fs: Opened file storage to write data.
-
- :param value: Value to be written to the file storage.
-
- :param vec: Vector of values to be written to the file storage.
-
-It is the main function to write data to a file storage. See an example of its usage at the beginning of the section.
-
-
-operator >>
------------
-Reads data from a file storage.
-
-.. ocv:function:: template<typename _Tp> void operator >> (const FileNode& n, _Tp& value)
-
-.. ocv:function:: template<typename _Tp> void operator >> (const FileNode& n, vector<_Tp>& vec)
-
-.. ocv:function:: template<typename _Tp> FileNodeIterator& operator >> (FileNodeIterator& it, _Tp& value)
-
-.. ocv:function:: template<typename _Tp> FileNodeIterator& operator >> (FileNodeIterator& it, vector<_Tp>& vec)
-
- :param n: Node from which data will be read.
-
- :param it: Iterator from which data will be read.
-
- :param value: Value to be read from the file storage.
-
- :param vec: Vector of values to be read from the file storage.
-
-It is the main function to read data from a file storage. See an example of its usage at the beginning of the section.
-
-
-FileNode
---------
-.. ocv:class:: FileNode
-
-File Storage Node class. The node is used to store each and every element of the file storage opened for reading. When XML/YAML file is read, it is first parsed and stored in the memory as a hierarchical collection of nodes. Each node can be a “leaf” that is contain a single number or a string, or be a collection of other nodes. There can be named collections (mappings) where each element has a name and it is accessed by a name, and ordered collections (sequences) where elements do not have names but rather accessed by index. Type of the file node can be determined using :ocv:func:`FileNode::type` method.
-
-Note that file nodes are only used for navigating file storages opened for reading. When a file storage is opened for writing, no data is stored in memory after it is written.
-
-
-FileNode::FileNode
-------------------
-The constructors.
-
-.. ocv:function:: FileNode::FileNode()
-
-.. ocv:function:: FileNode::FileNode(const CvFileStorage* fs, const CvFileNode* node)
-
-.. ocv:function:: FileNode::FileNode(const FileNode& node)
-
- :param fs: Pointer to the obsolete file storage structure.
-
- :param node: File node to be used as initialization for the created file node.
-
-These constructors are used to create a default file node, construct it from obsolete structures or from the another file node.
-
-
-FileNode::operator[]
---------------------
-Returns element of a mapping node or a sequence node.
-
-.. ocv:function:: FileNode FileNode::operator[](const String& nodename) const
-
-.. ocv:function:: FileNode FileNode::operator[](const char* nodename) const
-
-.. ocv:function:: FileNode FileNode::operator[](int i) const
-
- :param nodename: Name of an element in the mapping node.
-
- :param i: Index of an element in the sequence node.
-
- :returns: Returns the element with the given identifier.
-
-
-FileNode::type
---------------
-Returns type of the node.
-
-.. ocv:function:: int FileNode::type() const
-
- :returns: Type of the node. Possible values are:
-
- * **FileNode::NONE** Empty node.
-
- * **FileNode::INT** Integer.
-
- * **FileNode::REAL** Floating-point number.
-
- * **FileNode::FLOAT** Synonym or ``REAL``.
-
- * **FileNode::STR** Text string in UTF-8 encoding.
-
- * **FileNode::STRING** Synonym for ``STR``.
-
- * **FileNode::REF** Integer of type ``size_t``. Typically used for storing complex dynamic structures where some elements reference the others.
-
- * **FileNode::SEQ** Sequence.
-
- * **FileNode::MAP** Mapping.
-
- * **FileNode::FLOW** Compact representation of a sequence or mapping. Used only by the YAML writer.
-
- * **FileNode::USER** Registered object (e.g. a matrix).
-
- * **FileNode::EMPTY** Empty structure (sequence or mapping).
-
- * **FileNode::NAMED** The node has a name (i.e. it is an element of a mapping).
-
-
-FileNode::empty
----------------
-Checks whether the node is empty.
-
-.. ocv:function:: bool FileNode::empty() const
-
- :returns: ``true`` if the node is empty.
-
-
-FileNode::isNone
-----------------
-Checks whether the node is a "none" object
-
-.. ocv:function:: bool FileNode::isNone() const
-
- :returns: ``true`` if the node is a "none" object.
-
-
-FileNode::isSeq
----------------
-Checks whether the node is a sequence.
-
-.. ocv:function:: bool FileNode::isSeq() const
-
- :returns: ``true`` if the node is a sequence.
-
-
-FileNode::isMap
----------------
-Checks whether the node is a mapping.
-
-.. ocv:function:: bool FileNode::isMap() const
-
- :returns: ``true`` if the node is a mapping.
-
-
-FileNode::isInt
----------------
-Checks whether the node is an integer.
-
-.. ocv:function:: bool FileNode::isInt() const
-
- :returns: ``true`` if the node is an integer.
-
-
-FileNode::isReal
-----------------
-Checks whether the node is a floating-point number.
-
-.. ocv:function:: bool FileNode::isReal() const
-
- :returns: ``true`` if the node is a floating-point number.
-
-
-FileNode::isString
-------------------
-Checks whether the node is a text string.
-
-.. ocv:function:: bool FileNode::isString() const
-
- :returns: ``true`` if the node is a text string.
-
-
-FileNode::isNamed
------------------
-Checks whether the node has a name.
-
-.. ocv:function:: bool FileNode::isNamed() const
-
- :returns: ``true`` if the node has a name.
-
-
-FileNode::name
---------------
-Returns the node name.
-
-.. ocv:function:: String FileNode::name() const
-
- :returns: The node name or an empty string if the node is nameless.
-
-
-FileNode::size
---------------
-Returns the number of elements in the node.
-
-.. ocv:function:: size_t FileNode::size() const
-
- :returns: The number of elements in the node, if it is a sequence or mapping, or 1 otherwise.
-
-
-FileNode::operator int
-----------------------
-Returns the node content as an integer.
-
-.. ocv:function:: FileNode::operator int() const
-
- :returns: The node content as an integer. If the node stores a floating-point number, it is rounded.
-
-
-FileNode::operator float
-------------------------
-Returns the node content as float.
-
-.. ocv:function:: FileNode::operator float() const
-
- :returns: The node content as float.
-
-
-FileNode::operator double
--------------------------
-Returns the node content as double.
-
-.. ocv:function:: FileNode::operator double() const
-
- :returns: The node content as double.
-
-
-FileNode::operator String
-------------------------------
-Returns the node content as text string.
-
-.. ocv:function:: FileNode::operator String() const
-
- :returns: The node content as a text string.
-
-
-FileNode::operator*
--------------------
-Returns pointer to the underlying obsolete file node structure.
-
-.. ocv:function:: CvFileNode* FileNode::operator *()
-
- :returns: Pointer to the underlying obsolete file node structure.
-
-
-FileNode::begin
----------------
-Returns the iterator pointing to the first node element.
-
-.. ocv:function:: FileNodeIterator FileNode::begin() const
-
- :returns: Iterator pointing to the first node element.
-
-
-FileNode::end
--------------
-Returns the iterator pointing to the element following the last node element.
-
-.. ocv:function:: FileNodeIterator FileNode::end() const
-
- :returns: Iterator pointing to the element following the last node element.
-
-
-FileNode::readRaw
------------------
-Reads node elements to the buffer with the specified format.
-
-.. ocv:function:: void FileNode::readRaw( const String& fmt, uchar* vec, size_t len ) const
-
- :param fmt: Specification of each array element. It has the same format as in :ocv:func:`FileStorage::writeRaw`.
-
- :param vec: Pointer to the destination array.
-
- :param len: Number of elements to read. If it is greater than number of remaining elements then all of them will be read.
-
-Usually it is more convenient to use :ocv:func:`operator >>` instead of this method.
-
-FileNode::readObj
------------------
-Reads the registered object.
-
-.. ocv:function:: void* FileNode::readObj() const
-
- :returns: Pointer to the read object.
-
-See :ocv:cfunc:`Read` for details.
-
-FileNodeIterator
-----------------
-.. ocv:class:: FileNodeIterator
-
-The class ``FileNodeIterator`` is used to iterate through sequences and mappings. A standard STL notation, with ``node.begin()``, ``node.end()`` denoting the beginning and the end of a sequence, stored in ``node``. See the data reading sample in the beginning of the section.
-
-
-FileNodeIterator::FileNodeIterator
-----------------------------------
-The constructors.
-
-.. ocv:function:: FileNodeIterator::FileNodeIterator()
-
-.. ocv:function:: FileNodeIterator::FileNodeIterator(const CvFileStorage* fs, const CvFileNode* node, size_t ofs=0)
-
-.. ocv:function:: FileNodeIterator::FileNodeIterator(const FileNodeIterator& it)
-
- :param fs: File storage for the iterator.
-
- :param node: File node for the iterator.
-
- :param ofs: Index of the element in the node. The created iterator will point to this element.
-
- :param it: Iterator to be used as initialization for the created iterator.
-
-These constructors are used to create a default iterator, set it to specific element in a file node or construct it from another iterator.
-
-
-FileNodeIterator::operator*
----------------------------
-Returns the currently observed element.
-
-.. ocv:function:: FileNode FileNodeIterator::operator *() const
-
- :returns: Currently observed element.
-
-
-FileNodeIterator::operator->
-----------------------------
-Accesses methods of the currently observed element.
-
-.. ocv:function:: FileNode FileNodeIterator::operator ->() const
-
-
-FileNodeIterator::operator ++
------------------------------
-Moves iterator to the next node.
-
-.. ocv:function:: FileNodeIterator& FileNodeIterator::operator ++ ()
-
-.. ocv:function:: FileNodeIterator FileNodeIterator::operator ++ (int)
-
-
-FileNodeIterator::operator --
------------------------------
-Moves iterator to the previous node.
-
-.. ocv:function:: FileNodeIterator& FileNodeIterator::operator -- ()
-
-.. ocv:function:: FileNodeIterator FileNodeIterator::operator -- (int)
-
-
-FileNodeIterator::operator +=
------------------------------
-Moves iterator forward by the specified offset.
-
-.. ocv:function:: FileNodeIterator& FileNodeIterator::operator +=( int ofs )
-
- :param ofs: Offset (possibly negative) to move the iterator.
-
-
-FileNodeIterator::operator -=
------------------------------
-Moves iterator backward by the specified offset (possibly negative).
-
-.. ocv:function:: FileNodeIterator& FileNodeIterator::operator -=( int ofs )
-
- :param ofs: Offset (possibly negative) to move the iterator.
-
-
-FileNodeIterator::readRaw
--------------------------
-Reads node elements to the buffer with the specified format.
-
-.. ocv:function:: FileNodeIterator& FileNodeIterator::readRaw( const String& fmt, uchar* vec, size_t maxCount=(size_t)INT_MAX )
-
- :param fmt: Specification of each array element. It has the same format as in :ocv:func:`FileStorage::writeRaw`.
-
- :param vec: Pointer to the destination array.
-
- :param maxCount: Number of elements to read. If it is greater than number of remaining elements then all of them will be read.
-
-Usually it is more convenient to use :ocv:func:`operator >>` instead of this method.
+++ /dev/null
-Camera Calibration and 3D Reconstruction
-========================================
-
-.. highlight:: cpp
-
-
-
-cuda::solvePnPRansac
---------------------
-Finds the object pose from 3D-2D point correspondences.
-
-.. ocv:function:: void cuda::solvePnPRansac(const Mat& object, const Mat& image, const Mat& camera_mat, const Mat& dist_coef, Mat& rvec, Mat& tvec, bool use_extrinsic_guess=false, int num_iters=100, float max_dist=8.0, int min_inlier_count=100, vector<int>* inliers=NULL)
-
- :param object: Single-row matrix of object points.
-
- :param image: Single-row matrix of image points.
-
- :param camera_mat: 3x3 matrix of intrinsic camera parameters.
-
- :param dist_coef: Distortion coefficients. See :ocv:func:`undistortPoints` for details.
-
- :param rvec: Output 3D rotation vector.
-
- :param tvec: Output 3D translation vector.
-
- :param use_extrinsic_guess: Flag to indicate that the function must use ``rvec`` and ``tvec`` as an initial transformation guess. It is not supported for now.
-
- :param num_iters: Maximum number of RANSAC iterations.
-
- :param max_dist: Euclidean distance threshold to detect whether point is inlier or not.
-
- :param min_inlier_count: Flag to indicate that the function must stop if greater or equal number of inliers is achieved. It is not supported for now.
-
- :param inliers: Output vector of inlier indices.
-
-.. seealso:: :ocv:func:`solvePnPRansac`
+++ /dev/null
-**************************************
-cuda. CUDA-accelerated Computer Vision
-**************************************
-
-.. toctree::
- :maxdepth: 1
-
- introduction
- initalization_and_information
- data_structures
- object_detection
- calib3d
+++ /dev/null
-Data Structures
-===============
-
-.. highlight:: cpp
-
-
-
-cuda::PtrStepSz
----------------
-.. ocv:class:: cuda::PtrStepSz
-
-Lightweight class encapsulating pitched memory on a GPU and passed to nvcc-compiled code (CUDA kernels). Typically, it is used internally by OpenCV and by users who write device code. You can call its members from both host and device code. ::
-
- template <typename T> struct PtrStepSz : public PtrStep<T>
- {
- __CV_GPU_HOST_DEVICE__ PtrStepSz() : cols(0), rows(0) {}
- __CV_GPU_HOST_DEVICE__ PtrStepSz(int rows_, int cols_, T* data_, size_t step_)
- : PtrStep<T>(data_, step_), cols(cols_), rows(rows_) {}
-
- template <typename U>
- explicit PtrStepSz(const PtrStepSz<U>& d) : PtrStep<T>((T*)d.data, d.step), cols(d.cols), rows(d.rows){}
-
- int cols;
- int rows;
- };
-
- typedef PtrStepSz<unsigned char> PtrStepSzb;
- typedef PtrStepSz<float> PtrStepSzf;
- typedef PtrStepSz<int> PtrStepSzi;
-
-
-
-cuda::PtrStep
--------------
-.. ocv:class:: cuda::PtrStep
-
-Structure similar to :ocv:class:`cuda::PtrStepSz` but containing only a pointer and row step. Width and height fields are excluded due to performance reasons. The structure is intended for internal use or for users who write device code. ::
-
- template <typename T> struct PtrStep : public DevPtr<T>
- {
- __CV_GPU_HOST_DEVICE__ PtrStep() : step(0) {}
- __CV_GPU_HOST_DEVICE__ PtrStep(T* data_, size_t step_) : DevPtr<T>(data_), step(step_) {}
-
- //! stride between two consecutive rows in bytes. Step is stored always and everywhere in bytes!!!
- size_t step;
-
- __CV_GPU_HOST_DEVICE__ T* ptr(int y = 0) { return ( T*)( ( char*)DevPtr<T>::data + y * step); }
- __CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const { return (const T*)( (const char*)DevPtr<T>::data + y * step); }
-
- __CV_GPU_HOST_DEVICE__ T& operator ()(int y, int x) { return ptr(y)[x]; }
- __CV_GPU_HOST_DEVICE__ const T& operator ()(int y, int x) const { return ptr(y)[x]; }
- };
-
- typedef PtrStep<unsigned char> PtrStepb;
- typedef PtrStep<float> PtrStepf;
- typedef PtrStep<int> PtrStepi;
-
-
-
-cuda::GpuMat
-------------
-.. ocv:class:: cuda::GpuMat
-
-Base storage class for GPU memory with reference counting. Its interface matches the :ocv:class:`Mat` interface with the following limitations:
-
-* no arbitrary dimensions support (only 2D)
-* no functions that return references to their data (because references on GPU are not valid for CPU)
-* no expression templates technique support
-
-Beware that the latter limitation may lead to overloaded matrix operators that cause memory allocations. The ``GpuMat`` class is convertible to :ocv:class:`cuda::PtrStepSz` and :ocv:class:`cuda::PtrStep` so it can be passed directly to the kernel.
-
-.. note:: In contrast with :ocv:class:`Mat`, in most cases ``GpuMat::isContinuous() == false`` . This means that rows are aligned to a size depending on the hardware. Single-row ``GpuMat`` is always a continuous matrix.
-
-::
-
- class CV_EXPORTS GpuMat
- {
- public:
- //! default constructor
- GpuMat();
-
- //! constructs GpuMat of the specified size and type
- GpuMat(int rows, int cols, int type);
- GpuMat(Size size, int type);
-
- .....
-
- //! builds GpuMat from host memory (Blocking call)
- explicit GpuMat(InputArray arr);
-
- //! returns lightweight PtrStepSz structure for passing
- //to nvcc-compiled code. Contains size, data ptr and step.
- template <class T> operator PtrStepSz<T>() const;
- template <class T> operator PtrStep<T>() const;
-
- //! pefroms upload data to GpuMat (Blocking call)
- void upload(InputArray arr);
-
- //! pefroms upload data to GpuMat (Non-Blocking call)
- void upload(InputArray arr, Stream& stream);
-
- //! pefroms download data from device to host memory (Blocking call)
- void download(OutputArray dst) const;
-
- //! pefroms download data from device to host memory (Non-Blocking call)
- void download(OutputArray dst, Stream& stream) const;
- };
-
-
-.. note:: You are not recommended to leave static or global ``GpuMat`` variables allocated, that is, to rely on its destructor. The destruction order of such variables and CUDA context is undefined. GPU memory release function returns error if the CUDA context has been destroyed before.
-
-.. seealso:: :ocv:class:`Mat`
-
-
-
-cuda::createContinuous
-----------------------
-Creates a continuous matrix.
-
-.. ocv:function:: void cuda::createContinuous(int rows, int cols, int type, OutputArray arr)
-
- :param rows: Row count.
-
- :param cols: Column count.
-
- :param type: Type of the matrix.
-
- :param arr: Destination matrix. This parameter changes only if it has a proper type and area ( :math:`\texttt{rows} \times \texttt{cols}` ).
-
-Matrix is called continuous if its elements are stored continuously, that is, without gaps at the end of each row.
-
-
-
-cuda::ensureSizeIsEnough
-------------------------
-Ensures that the size of a matrix is big enough and the matrix has a proper type.
-
-.. ocv:function:: void cuda::ensureSizeIsEnough(int rows, int cols, int type, OutputArray arr)
-
- :param rows: Minimum desired number of rows.
-
- :param cols: Minimum desired number of columns.
-
- :param type: Desired matrix type.
-
- :param arr: Destination matrix.
-
-The function does not reallocate memory if the matrix has proper attributes already.
-
-
-
-cuda::CudaMem
--------------
-.. ocv:class:: cuda::CudaMem
-
-Class with reference counting wrapping special memory type allocation functions from CUDA. Its interface is also :ocv:func:`Mat`-like but with additional memory type parameters.
-
-* **PAGE_LOCKED** sets a page locked memory type used commonly for fast and asynchronous uploading/downloading data from/to GPU.
-* **SHARED** specifies a zero copy memory allocation that enables mapping the host memory to GPU address space, if supported.
-* **WRITE_COMBINED** sets the write combined buffer that is not cached by CPU. Such buffers are used to supply GPU with data when GPU only reads it. The advantage is a better CPU cache utilization.
-
-.. note:: Allocation size of such memory types is usually limited. For more details, see *CUDA 2.2 Pinned Memory APIs* document or *CUDA C Programming Guide*.
-
-::
-
- class CV_EXPORTS CudaMem
- {
- public:
- enum AllocType { PAGE_LOCKED = 1, SHARED = 2, WRITE_COMBINED = 4 };
-
- explicit CudaMem(AllocType alloc_type = PAGE_LOCKED);
-
- CudaMem(int rows, int cols, int type, AllocType alloc_type = PAGE_LOCKED);
- CudaMem(Size size, int type, AllocType alloc_type = PAGE_LOCKED);
-
- //! creates from host memory with coping data
- explicit CudaMem(InputArray arr, AllocType alloc_type = PAGE_LOCKED);
-
- ......
-
- //! returns matrix header with disabled reference counting for CudaMem data.
- Mat createMatHeader() const;
-
- //! maps host memory into device address space and returns GpuMat header for it. Throws exception if not supported by hardware.
- GpuMat createGpuMatHeader() const;
-
- ......
-
- AllocType alloc_type;
- };
-
-
-
-cuda::CudaMem::createMatHeader
-------------------------------
-Creates a header without reference counting to :ocv:class:`cuda::CudaMem` data.
-
-.. ocv:function:: Mat cuda::CudaMem::createMatHeader() const
-
-
-
-cuda::CudaMem::createGpuMatHeader
----------------------------------
-Maps CPU memory to GPU address space and creates the :ocv:class:`cuda::GpuMat` header without reference counting for it.
-
-.. ocv:function:: GpuMat cuda::CudaMem::createGpuMatHeader() const
-
-This can be done only if memory was allocated with the ``SHARED`` flag and if it is supported by the hardware. Laptops often share video and CPU memory, so address spaces can be mapped, which eliminates an extra copy.
-
-
-
-cuda::registerPageLocked
-------------------------
-Page-locks the memory of matrix and maps it for the device(s).
-
-.. ocv:function:: void cuda::registerPageLocked(Mat& m)
-
- :param m: Input matrix.
-
-
-
-cuda::unregisterPageLocked
---------------------------
-Unmaps the memory of matrix and makes it pageable again.
-
-.. ocv:function:: void cuda::unregisterPageLocked(Mat& m)
-
- :param m: Input matrix.
-
-
-
-cuda::Stream
-------------
-.. ocv:class:: cuda::Stream
-
-This class encapsulates a queue of asynchronous calls.
-
-.. note:: Currently, you may face problems if an operation is enqueued twice with different data. Some functions use the constant GPU memory, and next call may update the memory before the previous one has been finished. But calling different operations asynchronously is safe because each operation has its own constant buffer. Memory copy/upload/download/set operations to the buffers you hold are also safe.
-
-::
-
- class CV_EXPORTS Stream
- {
- public:
- Stream();
-
- //! queries an asynchronous stream for completion status
- bool queryIfComplete() const;
-
- //! waits for stream tasks to complete
- void waitForCompletion();
-
- //! makes a compute stream wait on an event
- void waitEvent(const Event& event);
-
- //! adds a callback to be called on the host after all currently enqueued items in the stream have completed
- void enqueueHostCallback(StreamCallback callback, void* userData);
-
- //! return Stream object for default CUDA stream
- static Stream& Null();
-
- //! returns true if stream object is not default (!= 0)
- operator bool_type() const;
- };
-
-
-
-cuda::Stream::queryIfComplete
------------------------------
-Returns ``true`` if the current stream queue is finished. Otherwise, it returns false.
-
-.. ocv:function:: bool cuda::Stream::queryIfComplete()
-
-
-
-cuda::Stream::waitForCompletion
--------------------------------
-Blocks the current CPU thread until all operations in the stream are complete.
-
-.. ocv:function:: void cuda::Stream::waitForCompletion()
-
-
-
-cuda::Stream::waitEvent
------------------------
-Makes a compute stream wait on an event.
-
-.. ocv:function:: void cuda::Stream::waitEvent(const Event& event)
-
-
-
-cuda::Stream::enqueueHostCallback
----------------------------------
-Adds a callback to be called on the host after all currently enqueued items in the stream have completed.
-
-.. ocv:function:: void cuda::Stream::enqueueHostCallback(StreamCallback callback, void* userData)
-
-.. note:: Callbacks must not make any CUDA API calls. Callbacks must not perform any synchronization that may depend on outstanding device work or other callbacks that are not mandated to run earlier. Callbacks without a mandated order (in independent streams) execute in undefined order and may be serialized.
-
-
-
-cuda::StreamAccessor
---------------------
-.. ocv:struct:: cuda::StreamAccessor
-
-Class that enables getting ``cudaStream_t`` from :ocv:class:`cuda::Stream` and is declared in ``stream_accessor.hpp`` because it is the only public header that depends on the CUDA Runtime API. Including it brings a dependency to your code. ::
-
- struct StreamAccessor
- {
- CV_EXPORTS static cudaStream_t getStream(const Stream& stream);
- };
+++ /dev/null
-Initalization and Information
-=============================
-
-.. highlight:: cpp
-
-
-
-cuda::getCudaEnabledDeviceCount
--------------------------------
-Returns the number of installed CUDA-enabled devices.
-
-.. ocv:function:: int cuda::getCudaEnabledDeviceCount()
-
-Use this function before any other CUDA functions calls. If OpenCV is compiled without CUDA support, this function returns 0.
-
-
-
-cuda::setDevice
----------------
-Sets a device and initializes it for the current thread.
-
-.. ocv:function:: void cuda::setDevice(int device)
-
- :param device: System index of a CUDA device starting with 0.
-
-If the call of this function is omitted, a default device is initialized at the fist CUDA usage.
-
-
-
-cuda::getDevice
----------------
-Returns the current device index set by :ocv:func:`cuda::setDevice` or initialized by default.
-
-.. ocv:function:: int cuda::getDevice()
-
-
-
-cuda::resetDevice
------------------
-Explicitly destroys and cleans up all resources associated with the current device in the current process.
-
-.. ocv:function:: void cuda::resetDevice()
-
-Any subsequent API call to this device will reinitialize the device.
-
-
-
-cuda::FeatureSet
-----------------
-Enumeration providing CUDA computing features.
-
-.. ocv:enum:: cuda::FeatureSet
-
- .. ocv:emember:: FEATURE_SET_COMPUTE_10
- .. ocv:emember:: FEATURE_SET_COMPUTE_11
- .. ocv:emember:: FEATURE_SET_COMPUTE_12
- .. ocv:emember:: FEATURE_SET_COMPUTE_13
- .. ocv:emember:: FEATURE_SET_COMPUTE_20
- .. ocv:emember:: FEATURE_SET_COMPUTE_21
- .. ocv:emember:: GLOBAL_ATOMICS
- .. ocv:emember:: SHARED_ATOMICS
- .. ocv:emember:: NATIVE_DOUBLE
-
-
-
-cuda::TargetArchs
------------------
-.. ocv:class:: cuda::TargetArchs
-
-Class providing a set of static methods to check what NVIDIA* card architecture the CUDA module was built for.
-
-The following method checks whether the module was built with the support of the given feature:
-
- .. ocv:function:: static bool cuda::TargetArchs::builtWith( FeatureSet feature_set )
-
- :param feature_set: Features to be checked. See :ocv:enum:`cuda::FeatureSet`.
-
-There is a set of methods to check whether the module contains intermediate (PTX) or binary CUDA code for the given architecture(s):
-
- .. ocv:function:: static bool cuda::TargetArchs::has(int major, int minor)
-
- .. ocv:function:: static bool cuda::TargetArchs::hasPtx(int major, int minor)
-
- .. ocv:function:: static bool cuda::TargetArchs::hasBin(int major, int minor)
-
- .. ocv:function:: static bool cuda::TargetArchs::hasEqualOrLessPtx(int major, int minor)
-
- .. ocv:function:: static bool cuda::TargetArchs::hasEqualOrGreater(int major, int minor)
-
- .. ocv:function:: static bool cuda::TargetArchs::hasEqualOrGreaterPtx(int major, int minor)
-
- .. ocv:function:: static bool cuda::TargetArchs::hasEqualOrGreaterBin(int major, int minor)
-
- :param major: Major compute capability version.
-
- :param minor: Minor compute capability version.
-
-According to the CUDA C Programming Guide Version 3.2: "PTX code produced for some specific compute capability can always be compiled to binary code of greater or equal compute capability".
-
-
-
-cuda::DeviceInfo
-----------------
-.. ocv:class:: cuda::DeviceInfo
-
-Class providing functionality for querying the specified GPU properties. ::
-
- class CV_EXPORTS DeviceInfo
- {
- public:
- //! creates DeviceInfo object for the current GPU
- DeviceInfo();
-
- //! creates DeviceInfo object for the given GPU
- DeviceInfo(int device_id);
-
- //! ASCII string identifying device
- const char* name() const;
-
- //! global memory available on device in bytes
- size_t totalGlobalMem() const;
-
- //! shared memory available per block in bytes
- size_t sharedMemPerBlock() const;
-
- //! 32-bit registers available per block
- int regsPerBlock() const;
-
- //! warp size in threads
- int warpSize() const;
-
- //! maximum pitch in bytes allowed by memory copies
- size_t memPitch() const;
-
- //! maximum number of threads per block
- int maxThreadsPerBlock() const;
-
- //! maximum size of each dimension of a block
- Vec3i maxThreadsDim() const;
-
- //! maximum size of each dimension of a grid
- Vec3i maxGridSize() const;
-
- //! clock frequency in kilohertz
- int clockRate() const;
-
- //! constant memory available on device in bytes
- size_t totalConstMem() const;
-
- //! major compute capability
- int majorVersion() const;
-
- //! minor compute capability
- int minorVersion() const;
-
- //! alignment requirement for textures
- size_t textureAlignment() const;
-
- //! pitch alignment requirement for texture references bound to pitched memory
- size_t texturePitchAlignment() const;
-
- //! number of multiprocessors on device
- int multiProcessorCount() const;
-
- //! specified whether there is a run time limit on kernels
- bool kernelExecTimeoutEnabled() const;
-
- //! device is integrated as opposed to discrete
- bool integrated() const;
-
- //! device can map host memory with cudaHostAlloc/cudaHostGetDevicePointer
- bool canMapHostMemory() const;
-
- enum ComputeMode
- {
- ComputeModeDefault, /**< default compute mode (Multiple threads can use ::cudaSetDevice() with this device) */
- ComputeModeExclusive, /**< compute-exclusive-thread mode (Only one thread in one process will be able to use ::cudaSetDevice() with this device) */
- ComputeModeProhibited, /**< compute-prohibited mode (No threads can use ::cudaSetDevice() with this device) */
- ComputeModeExclusiveProcess /**< compute-exclusive-process mode (Many threads in one process will be able to use ::cudaSetDevice() with this device) */
- };
-
- //! compute mode
- ComputeMode computeMode() const;
-
- //! maximum 1D texture size
- int maxTexture1D() const;
-
- //! maximum 1D mipmapped texture size
- int maxTexture1DMipmap() const;
-
- //! maximum size for 1D textures bound to linear memory
- int maxTexture1DLinear() const;
-
- //! maximum 2D texture dimensions
- Vec2i maxTexture2D() const;
-
- //! maximum 2D mipmapped texture dimensions
- Vec2i maxTexture2DMipmap() const;
-
- //! maximum dimensions (width, height, pitch) for 2D textures bound to pitched memory
- Vec3i maxTexture2DLinear() const;
-
- //! maximum 2D texture dimensions if texture gather operations have to be performed
- Vec2i maxTexture2DGather() const;
-
- //! maximum 3D texture dimensions
- Vec3i maxTexture3D() const;
-
- //! maximum Cubemap texture dimensions
- int maxTextureCubemap() const;
-
- //! maximum 1D layered texture dimensions
- Vec2i maxTexture1DLayered() const;
-
- //! maximum 2D layered texture dimensions
- Vec3i maxTexture2DLayered() const;
-
- //! maximum Cubemap layered texture dimensions
- Vec2i maxTextureCubemapLayered() const;
-
- //! maximum 1D surface size
- int maxSurface1D() const;
-
- //! maximum 2D surface dimensions
- Vec2i maxSurface2D() const;
-
- //! maximum 3D surface dimensions
- Vec3i maxSurface3D() const;
-
- //! maximum 1D layered surface dimensions
- Vec2i maxSurface1DLayered() const;
-
- //! maximum 2D layered surface dimensions
- Vec3i maxSurface2DLayered() const;
-
- //! maximum Cubemap surface dimensions
- int maxSurfaceCubemap() const;
-
- //! maximum Cubemap layered surface dimensions
- Vec2i maxSurfaceCubemapLayered() const;
-
- //! alignment requirements for surfaces
- size_t surfaceAlignment() const;
-
- //! device can possibly execute multiple kernels concurrently
- bool concurrentKernels() const;
-
- //! device has ECC support enabled
- bool ECCEnabled() const;
-
- //! PCI bus ID of the device
- int pciBusID() const;
-
- //! PCI device ID of the device
- int pciDeviceID() const;
-
- //! PCI domain ID of the device
- int pciDomainID() const;
-
- //! true if device is a Tesla device using TCC driver, false otherwise
- bool tccDriver() const;
-
- //! number of asynchronous engines
- int asyncEngineCount() const;
-
- //! device shares a unified address space with the host
- bool unifiedAddressing() const;
-
- //! peak memory clock frequency in kilohertz
- int memoryClockRate() const;
-
- //! global memory bus width in bits
- int memoryBusWidth() const;
-
- //! size of L2 cache in bytes
- int l2CacheSize() const;
-
- //! maximum resident threads per multiprocessor
- int maxThreadsPerMultiProcessor() const;
-
- //! gets free and total device memory
- void queryMemory(size_t& totalMemory, size_t& freeMemory) const;
- size_t freeMemory() const;
- size_t totalMemory() const;
-
- //! checks whether device supports the given feature
- bool supports(FeatureSet feature_set) const;
-
- //! checks whether the CUDA module can be run on the given device
- bool isCompatible() const;
- };
-
-
-
-cuda::DeviceInfo::DeviceInfo
-----------------------------
-The constructors.
-
-.. ocv:function:: cuda::DeviceInfo::DeviceInfo()
-
-.. ocv:function:: cuda::DeviceInfo::DeviceInfo(int device_id)
-
- :param device_id: System index of the CUDA device starting with 0.
-
-Constructs the ``DeviceInfo`` object for the specified device. If ``device_id`` parameter is missed, it constructs an object for the current device.
-
-
-
-cuda::DeviceInfo::name
-----------------------
-Returns the device name.
-
-.. ocv:function:: const char* cuda::DeviceInfo::name() const
-
-
-
-cuda::DeviceInfo::majorVersion
-------------------------------
-Returns the major compute capability version.
-
-.. ocv:function:: int cuda::DeviceInfo::majorVersion()
-
-
-
-cuda::DeviceInfo::minorVersion
-------------------------------
-Returns the minor compute capability version.
-
-.. ocv:function:: int cuda::DeviceInfo::minorVersion()
-
-
-
-cuda::DeviceInfo::freeMemory
-----------------------------
-Returns the amount of free memory in bytes.
-
-.. ocv:function:: size_t cuda::DeviceInfo::freeMemory()
-
-
-
-cuda::DeviceInfo::totalMemory
------------------------------
-Returns the amount of total memory in bytes.
-
-.. ocv:function:: size_t cuda::DeviceInfo::totalMemory()
-
-
-
-cuda::DeviceInfo::supports
---------------------------
-Provides information on CUDA feature support.
-
-.. ocv:function:: bool cuda::DeviceInfo::supports(FeatureSet feature_set) const
-
- :param feature_set: Features to be checked. See :ocv:enum:`cuda::FeatureSet`.
-
-This function returns ``true`` if the device has the specified CUDA feature. Otherwise, it returns ``false`` .
-
-
-
-cuda::DeviceInfo::isCompatible
-------------------------------
-Checks the CUDA module and device compatibility.
-
-.. ocv:function:: bool cuda::DeviceInfo::isCompatible()
-
-This function returns ``true`` if the CUDA module can be run on the specified device. Otherwise, it returns ``false`` .
-
-
-
-cuda::DeviceInfo::deviceID
---------------------------
-Returns system index of the CUDA device starting with 0.
-
-.. ocv:function:: int cuda::DeviceInfo::deviceID()
+++ /dev/null
-CUDA Module Introduction
-========================
-
-.. highlight:: cpp
-
-
-
-General Information
--------------------
-
-The OpenCV CUDA module is a set of classes and functions to utilize CUDA computational capabilities. It is implemented using NVIDIA* CUDA* Runtime API and supports only NVIDIA GPUs. The OpenCV CUDA module includes utility functions, low-level vision primitives, and high-level algorithms. The utility functions and low-level primitives provide a powerful infrastructure for developing fast vision algorithms taking advantage of CUDA whereas the high-level functionality includes some state-of-the-art algorithms (such as stereo correspondence, face and people detectors, and others) ready to be used by the application developers.
-
-The CUDA module is designed as a host-level API. This means that if you have pre-compiled OpenCV CUDA binaries, you are not required to have the CUDA Toolkit installed or write any extra code to make use of the CUDA.
-
-The OpenCV CUDA module is designed for ease of use and does not require any knowledge of CUDA. Though, such a knowledge will certainly be useful to handle non-trivial cases or achieve the highest performance. It is helpful to understand the cost of various operations, what the GPU does, what the preferred data formats are, and so on. The CUDA module is an effective instrument for quick implementation of CUDA-accelerated computer vision algorithms. However, if your algorithm involves many simple operations, then, for the best possible performance, you may still need to write your own kernels to avoid extra write and read operations on the intermediate results.
-
-To enable CUDA support, configure OpenCV using ``CMake`` with ``WITH_CUDA=ON`` . When the flag is set and if CUDA is installed, the full-featured OpenCV CUDA module is built. Otherwise, the module is still built but at runtime all functions from the module throw
-:ocv:class:`Exception` with ``CV_GpuNotSupported`` error code, except for
-:ocv:func:`cuda::getCudaEnabledDeviceCount()`. The latter function returns zero GPU count in this case. Building OpenCV without CUDA support does not perform device code compilation, so it does not require the CUDA Toolkit installed. Therefore, using the
-:ocv:func:`cuda::getCudaEnabledDeviceCount()` function, you can implement a high-level algorithm that will detect GPU presence at runtime and choose an appropriate implementation (CPU or GPU) accordingly.
-
-Compilation for Different NVIDIA* Platforms
--------------------------------------------
-
-NVIDIA* compiler enables generating binary code (cubin and fatbin) and intermediate code (PTX). Binary code often implies a specific GPU architecture and generation, so the compatibility with other GPUs is not guaranteed. PTX is targeted for a virtual platform that is defined entirely by the set of capabilities or features. Depending on the selected virtual platform, some of the instructions are emulated or disabled, even if the real hardware supports all the features.
-
-At the first call, the PTX code is compiled to binary code for the particular GPU using a JIT compiler. When the target GPU has a compute capability (CC) lower than the PTX code, JIT fails.
-By default, the OpenCV CUDA module includes:
-
-*
- Binaries for compute capabilities 1.3 and 2.0 (controlled by ``CUDA_ARCH_BIN`` in ``CMake``)
-
-*
- PTX code for compute capabilities 1.1 and 1.3 (controlled by ``CUDA_ARCH_PTX`` in ``CMake``)
-
-This means that for devices with CC 1.3 and 2.0 binary images are ready to run. For all newer platforms, the PTX code for 1.3 is JIT'ed to a binary image. For devices with CC 1.1 and 1.2, the PTX for 1.1 is JIT'ed. For devices with CC 1.0, no code is available and the functions throw
-:ocv:class:`Exception`. For platforms where JIT compilation is performed first, the run is slow.
-
-On a GPU with CC 1.0, you can still compile the CUDA module and most of the functions will run flawlessly. To achieve this, add "1.0" to the list of binaries, for example, ``CUDA_ARCH_BIN="1.0 1.3 2.0"`` . The functions that cannot be run on CC 1.0 GPUs throw an exception.
-
-You can always determine at runtime whether the OpenCV GPU-built binaries (or PTX code) are compatible with your GPU. The function
-:ocv:func:`cuda::DeviceInfo::isCompatible` returns the compatibility status (true/false).
-
-Utilizing Multiple GPUs
------------------------
-
-In the current version, each of the OpenCV CUDA algorithms can use only a single GPU. So, to utilize multiple GPUs, you have to manually distribute the work between GPUs.
-Switching active devie can be done using :ocv:func:`cuda::setDevice()` function. For more details please read Cuda C Programming Guide.
-
-While developing algorithms for multiple GPUs, note a data passing overhead. For primitive functions and small images, it can be significant, which may eliminate all the advantages of having multiple GPUs. But for high-level algorithms, consider using multi-GPU acceleration. For example, the Stereo Block Matching algorithm has been successfully parallelized using the following algorithm:
-
-
- 1. Split each image of the stereo pair into two horizontal overlapping stripes.
-
-
- 2. Process each pair of stripes (from the left and right images) on a separate Fermi* GPU.
-
-
- 3. Merge the results into a single disparity map.
-
-With this algorithm, a dual GPU gave a 180% performance increase comparing to the single Fermi GPU. For a source code example, see https://github.com/Itseez/opencv/tree/master/samples/gpu/.
+++ /dev/null
-Object Detection
-================
-
-.. highlight:: cpp
-
-
-
-cuda::HOGDescriptor
--------------------
-.. ocv:struct:: cuda::HOGDescriptor
-
-The class implements Histogram of Oriented Gradients ([Dalal2005]_) object detector. ::
-
- struct CV_EXPORTS HOGDescriptor
- {
- enum { DEFAULT_WIN_SIGMA = -1 };
- enum { DEFAULT_NLEVELS = 64 };
- enum { DESCR_FORMAT_ROW_BY_ROW, DESCR_FORMAT_COL_BY_COL };
-
- HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16),
- Size block_stride=Size(8, 8), Size cell_size=Size(8, 8),
- int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA,
- double threshold_L2hys=0.2, bool gamma_correction=true,
- int nlevels=DEFAULT_NLEVELS);
-
- size_t getDescriptorSize() const;
- size_t getBlockHistogramSize() const;
-
- void setSVMDetector(const vector<float>& detector);
-
- static vector<float> getDefaultPeopleDetector();
- static vector<float> getPeopleDetector48x96();
- static vector<float> getPeopleDetector64x128();
-
- void detect(const GpuMat& img, vector<Point>& found_locations,
- double hit_threshold=0, Size win_stride=Size(),
- Size padding=Size());
-
- void detectMultiScale(const GpuMat& img, vector<Rect>& found_locations,
- double hit_threshold=0, Size win_stride=Size(),
- Size padding=Size(), double scale0=1.05,
- int group_threshold=2);
-
- void getDescriptors(const GpuMat& img, Size win_stride,
- GpuMat& descriptors,
- int descr_format=DESCR_FORMAT_COL_BY_COL);
-
- Size win_size;
- Size block_size;
- Size block_stride;
- Size cell_size;
- int nbins;
- double win_sigma;
- double threshold_L2hys;
- bool gamma_correction;
- int nlevels;
-
- private:
- // Hidden
- }
-
-
-Interfaces of all methods are kept similar to the ``CPU HOG`` descriptor and detector analogues as much as possible.
-
-.. note::
-
- * An example applying the HOG descriptor for people detection can be found at opencv_source_code/samples/cpp/peopledetect.cpp
- * A CUDA example applying the HOG descriptor for people detection can be found at opencv_source_code/samples/gpu/hog.cpp
-
- * (Python) An example applying the HOG descriptor for people detection can be found at opencv_source_code/samples/python2/peopledetect.py
-
-
-
-cuda::HOGDescriptor::HOGDescriptor
-----------------------------------
-Creates the ``HOG`` descriptor and detector.
-
-.. ocv:function:: cuda::HOGDescriptor::HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16), Size block_stride=Size(8, 8), Size cell_size=Size(8, 8), int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA, double threshold_L2hys=0.2, bool gamma_correction=true, int nlevels=DEFAULT_NLEVELS)
-
- :param win_size: Detection window size. Align to block size and block stride.
-
- :param block_size: Block size in pixels. Align to cell size. Only (16,16) is supported for now.
-
- :param block_stride: Block stride. It must be a multiple of cell size.
-
- :param cell_size: Cell size. Only (8, 8) is supported for now.
-
- :param nbins: Number of bins. Only 9 bins per cell are supported for now.
-
- :param win_sigma: Gaussian smoothing window parameter.
-
- :param threshold_L2hys: L2-Hys normalization method shrinkage.
-
- :param gamma_correction: Flag to specify whether the gamma correction preprocessing is required or not.
-
- :param nlevels: Maximum number of detection window increases.
-
-
-
-cuda::HOGDescriptor::getDescriptorSize
---------------------------------------
-Returns the number of coefficients required for the classification.
-
-.. ocv:function:: size_t cuda::HOGDescriptor::getDescriptorSize() const
-
-
-
-cuda::HOGDescriptor::getBlockHistogramSize
-------------------------------------------
-Returns the block histogram size.
-
-.. ocv:function:: size_t cuda::HOGDescriptor::getBlockHistogramSize() const
-
-
-
-cuda::HOGDescriptor::setSVMDetector
------------------------------------
-Sets coefficients for the linear SVM classifier.
-
-.. ocv:function:: void cuda::HOGDescriptor::setSVMDetector(const vector<float>& detector)
-
-
-
-cuda::HOGDescriptor::getDefaultPeopleDetector
----------------------------------------------
-Returns coefficients of the classifier trained for people detection (for default window size).
-
-.. ocv:function:: static vector<float> cuda::HOGDescriptor::getDefaultPeopleDetector()
-
-
-
-cuda::HOGDescriptor::getPeopleDetector48x96
--------------------------------------------
-Returns coefficients of the classifier trained for people detection (for 48x96 windows).
-
-.. ocv:function:: static vector<float> cuda::HOGDescriptor::getPeopleDetector48x96()
-
-
-
-cuda::HOGDescriptor::getPeopleDetector64x128
---------------------------------------------
-Returns coefficients of the classifier trained for people detection (for 64x128 windows).
-
-.. ocv:function:: static vector<float> cuda::HOGDescriptor::getPeopleDetector64x128()
-
-
-
-cuda::HOGDescriptor::detect
----------------------------
-Performs object detection without a multi-scale window.
-
-.. ocv:function:: void cuda::HOGDescriptor::detect(const GpuMat& img, vector<Point>& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size())
-
- :param img: Source image. ``CV_8UC1`` and ``CV_8UC4`` types are supported for now.
-
- :param found_locations: Left-top corner points of detected objects boundaries.
-
- :param hit_threshold: Threshold for the distance between features and SVM classifying plane. Usually it is 0 and should be specfied in the detector coefficients (as the last free coefficient). But if the free coefficient is omitted (which is allowed), you can specify it manually here.
-
- :param win_stride: Window stride. It must be a multiple of block stride.
-
- :param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
-
-
-
-cuda::HOGDescriptor::detectMultiScale
--------------------------------------
-Performs object detection with a multi-scale window.
-
-.. ocv:function:: void cuda::HOGDescriptor::detectMultiScale(const GpuMat& img, vector<Rect>& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size(), double scale0=1.05, int group_threshold=2)
-
- :param img: Source image. See :ocv:func:`cuda::HOGDescriptor::detect` for type limitations.
-
- :param found_locations: Detected objects boundaries.
-
- :param hit_threshold: Threshold for the distance between features and SVM classifying plane. See :ocv:func:`cuda::HOGDescriptor::detect` for details.
-
- :param win_stride: Window stride. It must be a multiple of block stride.
-
- :param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
-
- :param scale0: Coefficient of the detection window increase.
-
- :param group_threshold: Coefficient to regulate the similarity threshold. When detected, some objects can be covered by many rectangles. 0 means not to perform grouping. See :ocv:func:`groupRectangles` .
-
-
-
-cuda::HOGDescriptor::getDescriptors
------------------------------------
-Returns block descriptors computed for the whole image.
-
-.. ocv:function:: void cuda::HOGDescriptor::getDescriptors(const GpuMat& img, Size win_stride, GpuMat& descriptors, int descr_format=DESCR_FORMAT_COL_BY_COL)
-
- :param img: Source image. See :ocv:func:`cuda::HOGDescriptor::detect` for type limitations.
-
- :param win_stride: Window stride. It must be a multiple of block stride.
-
- :param descriptors: 2D array of descriptors.
-
- :param descr_format: Descriptor storage format:
-
- * **DESCR_FORMAT_ROW_BY_ROW** - Row-major order.
-
- * **DESCR_FORMAT_COL_BY_COL** - Column-major order.
-
-The function is mainly used to learn the classifier.
-
-
-
-cuda::CascadeClassifier_CUDA
-----------------------------
-.. ocv:class:: cuda::CascadeClassifier_CUDA
-
-Cascade classifier class used for object detection. Supports HAAR and LBP cascades. ::
-
- class CV_EXPORTS CascadeClassifier_CUDA
- {
- public:
- CascadeClassifier_CUDA();
- CascadeClassifier_CUDA(const String& filename);
- ~CascadeClassifier_CUDA();
-
- bool empty() const;
- bool load(const String& filename);
- void release();
-
- /* Returns number of detected objects */
- int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size());
- int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, Size maxObjectSize, Size minSize = Size(), double scaleFactor = 1.1, int minNeighbors = 4);
-
- /* Finds only the largest object. Special mode if training is required.*/
- bool findLargestObject;
-
- /* Draws rectangles in input image */
- bool visualizeInPlace;
-
- Size getClassifierSize() const;
- };
-
-.. note::
-
- * A cascade classifier example can be found at opencv_source_code/samples/gpu/cascadeclassifier.cpp
- * A Nvidea API specific cascade classifier example can be found at opencv_source_code/samples/gpu/cascadeclassifier_nvidia_api.cpp
-
-
-
-cuda::CascadeClassifier_CUDA::CascadeClassifier_CUDA
-----------------------------------------------------
-Loads the classifier from a file. Cascade type is detected automatically by constructor parameter.
-
-.. ocv:function:: cuda::CascadeClassifier_CUDA::CascadeClassifier_CUDA(const String& filename)
-
- :param filename: Name of the file from which the classifier is loaded. Only the old ``haar`` classifier (trained by the ``haar`` training application) and NVIDIA's ``nvbin`` are supported for HAAR and only new type of OpenCV XML cascade supported for LBP.
-
-
-
-cuda::CascadeClassifier_CUDA::empty
------------------------------------
-Checks whether the classifier is loaded or not.
-
-.. ocv:function:: bool cuda::CascadeClassifier_CUDA::empty() const
-
-
-
-cuda::CascadeClassifier_CUDA::load
-----------------------------------
-Loads the classifier from a file. The previous content is destroyed.
-
-.. ocv:function:: bool cuda::CascadeClassifier_CUDA::load(const String& filename)
-
- :param filename: Name of the file from which the classifier is loaded. Only the old ``haar`` classifier (trained by the ``haar`` training application) and NVIDIA's ``nvbin`` are supported for HAAR and only new type of OpenCV XML cascade supported for LBP.
-
-
-
-cuda::CascadeClassifier_CUDA::release
--------------------------------------
-Destroys the loaded classifier.
-
-.. ocv:function:: void cuda::CascadeClassifier_CUDA::release()
-
-
-
-cuda::CascadeClassifier_CUDA::detectMultiScale
-----------------------------------------------
-Detects objects of different sizes in the input image.
-
-.. ocv:function:: int cuda::CascadeClassifier_CUDA::detectMultiScale(const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size())
-
-.. ocv:function:: int cuda::CascadeClassifier_CUDA::detectMultiScale(const GpuMat& image, GpuMat& objectsBuf, Size maxObjectSize, Size minSize = Size(), double scaleFactor = 1.1, int minNeighbors = 4)
-
- :param image: Matrix of type ``CV_8U`` containing an image where objects should be detected.
-
- :param objectsBuf: Buffer to store detected objects (rectangles). If it is empty, it is allocated with the default size. If not empty, the function searches not more than N objects, where ``N = sizeof(objectsBufer's data)/sizeof(cv::Rect)``.
-
- :param maxObjectSize: Maximum possible object size. Objects larger than that are ignored. Used for second signature and supported only for LBP cascades.
-
- :param scaleFactor: Parameter specifying how much the image size is reduced at each image scale.
-
- :param minNeighbors: Parameter specifying how many neighbors each candidate rectangle should have to retain it.
-
- :param minSize: Minimum possible object size. Objects smaller than that are ignored.
-
-The detected objects are returned as a list of rectangles.
-
-The function returns the number of detected objects, so you can retrieve them as in the following example: ::
-
- cuda::CascadeClassifier_CUDA cascade_gpu(...);
-
- Mat image_cpu = imread(...)
- GpuMat image_gpu(image_cpu);
-
- GpuMat objbuf;
- int detections_number = cascade_gpu.detectMultiScale( image_gpu,
- objbuf, 1.2, minNeighbors);
-
- Mat obj_host;
- // download only detected number of rectangles
- objbuf.colRange(0, detections_number).download(obj_host);
-
- Rect* faces = obj_host.ptr<Rect>();
- for(int i = 0; i < detections_num; ++i)
- cv::rectangle(image_cpu, faces[i], Scalar(255));
-
- imshow("Faces", image_cpu);
-
-
-.. seealso:: :ocv:func:`CascadeClassifier::detectMultiScale`
-
-
-
-.. [Dalal2005] Navneet Dalal and Bill Triggs. *Histogram of oriented gradients for human detection*. 2005.
+++ /dev/null
-Arithm Operations on Matrices
-=============================
-
-.. highlight:: cpp
-
-
-
-cuda::gemm
-----------
-Performs generalized matrix multiplication.
-
-.. ocv:function:: void cuda::gemm(InputArray src1, InputArray src2, double alpha, InputArray src3, double beta, OutputArray dst, int flags = 0, Stream& stream = Stream::Null())
-
- :param src1: First multiplied input matrix that should have ``CV_32FC1`` , ``CV_64FC1`` , ``CV_32FC2`` , or ``CV_64FC2`` type.
-
- :param src2: Second multiplied input matrix of the same type as ``src1`` .
-
- :param alpha: Weight of the matrix product.
-
- :param src3: Third optional delta matrix added to the matrix product. It should have the same type as ``src1`` and ``src2`` .
-
- :param beta: Weight of ``src3`` .
-
- :param dst: Destination matrix. It has the proper size and the same type as input matrices.
-
- :param flags: Operation flags:
-
- * **GEMM_1_T** transpose ``src1``
- * **GEMM_2_T** transpose ``src2``
- * **GEMM_3_T** transpose ``src3``
-
- :param stream: Stream for the asynchronous version.
-
-The function performs generalized matrix multiplication similar to the ``gemm`` functions in BLAS level 3. For example, ``gemm(src1, src2, alpha, src3, beta, dst, GEMM_1_T + GEMM_3_T)`` corresponds to
-
-.. math::
-
- \texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T
-
-.. note:: Transposition operation doesn't support ``CV_64FC2`` input type.
-
-.. seealso:: :ocv:func:`gemm`
-
-
-
-cuda::mulSpectrums
-------------------
-Performs a per-element multiplication of two Fourier spectrums.
-
-.. ocv:function:: void cuda::mulSpectrums(InputArray src1, InputArray src2, OutputArray dst, int flags, bool conjB=false, Stream& stream = Stream::Null())
-
- :param src1: First spectrum.
-
- :param src2: Second spectrum with the same size and type as ``a`` .
-
- :param dst: Destination spectrum.
-
- :param flags: Mock parameter used for CPU/CUDA interfaces similarity, simply add a `0` value.
-
- :param conjB: Optional flag to specify if the second spectrum needs to be conjugated before the multiplication.
-
- :param stream: Stream for the asynchronous version.
-
-Only full (not packed) ``CV_32FC2`` complex spectrums in the interleaved format are supported for now.
-
-.. seealso:: :ocv:func:`mulSpectrums`
-
-
-
-cuda::mulAndScaleSpectrums
---------------------------
-Performs a per-element multiplication of two Fourier spectrums and scales the result.
-
-.. ocv:function:: void cuda::mulAndScaleSpectrums(InputArray src1, InputArray src2, OutputArray dst, int flags, float scale, bool conjB=false, Stream& stream = Stream::Null())
-
- :param src1: First spectrum.
-
- :param src2: Second spectrum with the same size and type as ``a`` .
-
- :param dst: Destination spectrum.
-
- :param flags: Mock parameter used for CPU/CUDA interfaces similarity.
-
- :param scale: Scale constant.
-
- :param conjB: Optional flag to specify if the second spectrum needs to be conjugated before the multiplication.
-
-Only full (not packed) ``CV_32FC2`` complex spectrums in the interleaved format are supported for now.
-
-.. seealso:: :ocv:func:`mulSpectrums`
-
-
-
-cuda::dft
----------
-Performs a forward or inverse discrete Fourier transform (1D or 2D) of the floating point matrix.
-
-.. ocv:function:: void cuda::dft(InputArray src, OutputArray dst, Size dft_size, int flags=0, Stream& stream = Stream::Null())
-
- :param src: Source matrix (real or complex).
-
- :param dst: Destination matrix (real or complex).
-
- :param dft_size: Size of a discrete Fourier transform.
-
- :param flags: Optional flags:
-
- * **DFT_ROWS** transforms each individual row of the source matrix.
-
- * **DFT_SCALE** scales the result: divide it by the number of elements in the transform (obtained from ``dft_size`` ).
-
- * **DFT_INVERSE** inverts DFT. Use for complex-complex cases (real-complex and complex-real cases are always forward and inverse, respectively).
-
- * **DFT_REAL_OUTPUT** specifies the output as real. The source matrix is the result of real-complex transform, so the destination matrix must be real.
-
-Use to handle real matrices ( ``CV32FC1`` ) and complex matrices in the interleaved format ( ``CV32FC2`` ).
-
-The source matrix should be continuous, otherwise reallocation and data copying is performed. The function chooses an operation mode depending on the flags, size, and channel count of the source matrix:
-
- * If the source matrix is complex and the output is not specified as real, the destination matrix is complex and has the ``dft_size`` size and ``CV_32FC2`` type. The destination matrix contains a full result of the DFT (forward or inverse).
-
- * If the source matrix is complex and the output is specified as real, the function assumes that its input is the result of the forward transform (see the next item). The destination matrix has the ``dft_size`` size and ``CV_32FC1`` type. It contains the result of the inverse DFT.
-
- * If the source matrix is real (its type is ``CV_32FC1`` ), forward DFT is performed. The result of the DFT is packed into complex ( ``CV_32FC2`` ) matrix. So, the width of the destination matrix is ``dft_size.width / 2 + 1`` . But if the source is a single column, the height is reduced instead of the width.
-
-.. seealso:: :ocv:func:`dft`
-
-
-
-cuda::Convolution
------------------
-.. ocv:class:: cuda::Convolution : public Algorithm
-
-Base class for convolution (or cross-correlation) operator. ::
-
- class CV_EXPORTS Convolution : public Algorithm
- {
- public:
- virtual void convolve(InputArray image, InputArray templ, OutputArray result, bool ccorr = false, Stream& stream = Stream::Null()) = 0;
- };
-
-
-
-cuda::Convolution::convolve
----------------------------
-Computes a convolution (or cross-correlation) of two images.
-
-.. ocv:function:: void cuda::Convolution::convolve(InputArray image, InputArray templ, OutputArray result, bool ccorr = false, Stream& stream = Stream::Null())
-
- :param image: Source image. Only ``CV_32FC1`` images are supported for now.
-
- :param templ: Template image. The size is not greater than the ``image`` size. The type is the same as ``image`` .
-
- :param result: Result image. If ``image`` is *W x H* and ``templ`` is *w x h*, then ``result`` must be *W-w+1 x H-h+1*.
-
- :param ccorr: Flags to evaluate cross-correlation instead of convolution.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::createConvolution
------------------------
-Creates implementation for :ocv:class:`cuda::Convolution` .
-
-.. ocv:function:: Ptr<Convolution> createConvolution(Size user_block_size = Size())
-
- :param user_block_size: Block size. If you leave default value `Size(0,0)` then automatic estimation of block size will be used (which is optimized for speed). By varying `user_block_size` you can reduce memory requirements at the cost of speed.
+++ /dev/null
-Core Operations on Matrices
-===========================
-
-.. highlight:: cpp
-
-
-
-cuda::merge
------------
-Makes a multi-channel matrix out of several single-channel matrices.
-
-.. ocv:function:: void cuda::merge(const GpuMat* src, size_t n, OutputArray dst, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::merge(const std::vector<GpuMat>& src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Array/vector of source matrices.
-
- :param n: Number of source matrices.
-
- :param dst: Destination matrix.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`merge`
-
-
-
-cuda::split
------------
-Copies each plane of a multi-channel matrix into an array.
-
-.. ocv:function:: void cuda::split(InputArray src, GpuMat* dst, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::split(InputArray src, vector<GpuMat>& dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix.
-
- :param dst: Destination array/vector of single-channel matrices.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`split`
-
-
-
-cuda::transpose
----------------
-Transposes a matrix.
-
-.. ocv:function:: void cuda::transpose(InputArray src1, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src1: Source matrix. 1-, 4-, 8-byte element sizes are supported for now.
-
- :param dst: Destination matrix.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`transpose`
-
-
-
-cuda::flip
-----------
-Flips a 2D matrix around vertical, horizontal, or both axes.
-
-.. ocv:function:: void cuda::flip(InputArray src, OutputArray dst, int flipCode, Stream& stream = Stream::Null())
-
- :param src: Source matrix. Supports 1, 3 and 4 channels images with ``CV_8U``, ``CV_16U``, ``CV_32S`` or ``CV_32F`` depth.
-
- :param dst: Destination matrix.
-
- :param flipCode: Flip mode for the source:
-
- * ``0`` Flips around x-axis.
-
- * ``> 0`` Flips around y-axis.
-
- * ``< 0`` Flips around both axes.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`flip`
-
-
-
-cuda::LookUpTable
------------------
-.. ocv:class:: cuda::LookUpTable : public Algorithm
-
-Base class for transform using lookup table. ::
-
- class CV_EXPORTS LookUpTable : public Algorithm
- {
- public:
- virtual void transform(InputArray src, OutputArray dst, Stream& stream = Stream::Null()) = 0;
- };
-
-.. seealso:: :ocv:func:`LUT`
-
-
-
-cuda::LookUpTable::transform
-----------------------------
-Transforms the source matrix into the destination matrix using the given look-up table: ``dst(I) = lut(src(I))`` .
-
-.. ocv:function:: void cuda::LookUpTable::transform(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix. ``CV_8UC1`` and ``CV_8UC3`` matrices are supported for now.
-
- :param dst: Destination matrix.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::createLookUpTable
------------------------
-Creates implementation for :ocv:class:`cuda::LookUpTable` .
-
-.. ocv:function:: Ptr<LookUpTable> createLookUpTable(InputArray lut)
-
- :param lut: Look-up table of 256 elements. It is a continuous ``CV_8U`` matrix.
-
-
-
-cuda::copyMakeBorder
---------------------
-Forms a border around an image.
-
-.. ocv:function:: void cuda::copyMakeBorder(InputArray src, OutputArray dst, int top, int bottom, int left, int right, int borderType, Scalar value = Scalar(), Stream& stream = Stream::Null())
-
- :param src: Source image. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` , and ``CV_32FC1`` types are supported.
-
- :param dst: Destination image with the same type as ``src``. The size is ``Size(src.cols+left+right, src.rows+top+bottom)`` .
-
- :param top:
-
- :param bottom:
-
- :param left:
-
- :param right: Number of pixels in each direction from the source image rectangle to extrapolate. For example: ``top=1, bottom=1, left=1, right=1`` mean that 1 pixel-wide border needs to be built.
-
- :param borderType: Border type. See :ocv:func:`borderInterpolate` for details. ``BORDER_REFLECT101`` , ``BORDER_REPLICATE`` , ``BORDER_CONSTANT`` , ``BORDER_REFLECT`` and ``BORDER_WRAP`` are supported for now.
-
- :param value: Border value.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`copyMakeBorder`
+++ /dev/null
-***************************************************
-cudaarithm. CUDA-accelerated Operations on Matrices
-***************************************************
-
-.. toctree::
- :maxdepth: 1
-
- core
- element_operations
- reductions
- arithm
+++ /dev/null
-Per-element Operations
-======================
-
-.. highlight:: cpp
-
-
-
-cuda::add
----------
-Computes a matrix-matrix or matrix-scalar sum.
-
-.. ocv:function:: void cuda::add(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), int dtype = -1, Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar. Matrix should have the same size and type as ``src1`` .
-
- :param dst: Destination matrix that has the same size and number of channels as the input array(s). The depth is defined by ``dtype`` or ``src1`` depth.
-
- :param mask: Optional operation mask, 8-bit single channel array, that specifies elements of the destination array to be changed.
-
- :param dtype: Optional depth of the output array.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`add`
-
-
-
-cuda::subtract
---------------
-Computes a matrix-matrix or matrix-scalar difference.
-
-.. ocv:function:: void cuda::subtract(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), int dtype = -1, Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar. Matrix should have the same size and type as ``src1`` .
-
- :param dst: Destination matrix that has the same size and number of channels as the input array(s). The depth is defined by ``dtype`` or ``src1`` depth.
-
- :param mask: Optional operation mask, 8-bit single channel array, that specifies elements of the destination array to be changed.
-
- :param dtype: Optional depth of the output array.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`subtract`
-
-
-
-cuda::multiply
---------------
-Computes a matrix-matrix or matrix-scalar per-element product.
-
-.. ocv:function:: void cuda::multiply(InputArray src1, InputArray src2, OutputArray dst, double scale = 1, int dtype = -1, Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar.
-
- :param dst: Destination matrix that has the same size and number of channels as the input array(s). The depth is defined by ``dtype`` or ``src1`` depth.
-
- :param scale: Optional scale factor.
-
- :param dtype: Optional depth of the output array.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`multiply`
-
-
-
-cuda::divide
-------------
-Computes a matrix-matrix or matrix-scalar division.
-
-.. ocv:function:: void cuda::divide(InputArray src1, InputArray src2, OutputArray dst, double scale = 1, int dtype = -1, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::divide(double src1, InputArray src2, OutputArray dst, int dtype = -1, Stream& stream = Stream::Null())
-
- :param src1: First source matrix or a scalar.
-
- :param src2: Second source matrix or scalar.
-
- :param dst: Destination matrix that has the same size and number of channels as the input array(s). The depth is defined by ``dtype`` or ``src1`` depth.
-
- :param scale: Optional scale factor.
-
- :param dtype: Optional depth of the output array.
-
- :param stream: Stream for the asynchronous version.
-
-This function, in contrast to :ocv:func:`divide`, uses a round-down rounding mode.
-
-.. seealso:: :ocv:func:`divide`
-
-
-
-cuda::absdiff
--------------
-Computes per-element absolute difference of two matrices (or of a matrix and scalar).
-
-.. ocv:function:: void cuda::absdiff(InputArray src1, InputArray src2, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar.
-
- :param dst: Destination matrix that has the same size and type as the input array(s).
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`absdiff`
-
-
-
-cuda::abs
----------
-Computes an absolute value of each matrix element.
-
-.. ocv:function:: void cuda::abs(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix.
-
- :param dst: Destination matrix with the same size and type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`abs`
-
-
-
-cuda::sqr
----------
-Computes a square value of each matrix element.
-
-.. ocv:function:: void cuda::sqr(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix.
-
- :param dst: Destination matrix with the same size and type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::sqrt
-----------
-Computes a square root of each matrix element.
-
-.. ocv:function:: void cuda::sqrt(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix.
-
- :param dst: Destination matrix with the same size and type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`sqrt`
-
-
-
-cuda::exp
----------
-Computes an exponent of each matrix element.
-
-.. ocv:function:: void cuda::exp(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix.
-
- :param dst: Destination matrix with the same size and type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`exp`
-
-
-
-cuda::log
----------
-Computes a natural logarithm of absolute value of each matrix element.
-
-.. ocv:function:: void cuda::log(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix.
-
- :param dst: Destination matrix with the same size and type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`log`
-
-
-
-cuda::pow
----------
-Raises every matrix element to a power.
-
-.. ocv:function:: void cuda::pow(InputArray src, double power, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix.
-
- :param power: Exponent of power.
-
- :param dst: Destination matrix with the same size and type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-The function ``pow`` raises every element of the input matrix to ``power`` :
-
-.. math::
-
- \texttt{dst} (I) = \fork{\texttt{src}(I)^power}{if \texttt{power} is integer}{|\texttt{src}(I)|^power}{otherwise}
-
-.. seealso:: :ocv:func:`pow`
-
-
-
-cuda::compare
--------------
-Compares elements of two matrices (or of a matrix and scalar).
-
-.. ocv:function:: void cuda::compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop, Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar.
-
- :param dst: Destination matrix that has the same size and type as the input array(s).
-
- :param cmpop: Flag specifying the relation between the elements to be checked:
-
- * **CMP_EQ:** ``a(.) == b(.)``
- * **CMP_GT:** ``a(.) < b(.)``
- * **CMP_GE:** ``a(.) <= b(.)``
- * **CMP_LT:** ``a(.) < b(.)``
- * **CMP_LE:** ``a(.) <= b(.)``
- * **CMP_NE:** ``a(.) != b(.)``
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`compare`
-
-
-
-cuda::bitwise_not
------------------
-Performs a per-element bitwise inversion.
-
-.. ocv:function:: void cuda::bitwise_not(InputArray src, OutputArray dst, InputArray mask = noArray(), Stream& stream = Stream::Null())
-
- :param src: Source matrix.
-
- :param dst: Destination matrix with the same size and type as ``src`` .
-
- :param mask: Optional operation mask. 8-bit single channel image.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::bitwise_or
-----------------
-Performs a per-element bitwise disjunction of two matrices (or of matrix and scalar).
-
-.. ocv:function:: void cuda::bitwise_or(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar.
-
- :param dst: Destination matrix that has the same size and type as the input array(s).
-
- :param mask: Optional operation mask. 8-bit single channel image.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::bitwise_and
------------------
-Performs a per-element bitwise conjunction of two matrices (or of matrix and scalar).
-
-.. ocv:function:: void cuda::bitwise_and(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar.
-
- :param dst: Destination matrix that has the same size and type as the input array(s).
-
- :param mask: Optional operation mask. 8-bit single channel image.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::bitwise_xor
------------------
-Performs a per-element bitwise ``exclusive or`` operation of two matrices (or of matrix and scalar).
-
-.. ocv:function:: void cuda::bitwise_xor(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar.
-
- :param dst: Destination matrix that has the same size and type as the input array(s).
-
- :param mask: Optional operation mask. 8-bit single channel image.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::rshift
-------------
-Performs pixel by pixel right shift of an image by a constant value.
-
-.. ocv:function:: void cuda::rshift(InputArray src, Scalar_<int> val, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix. Supports 1, 3 and 4 channels images with integers elements.
-
- :param val: Constant values, one per channel.
-
- :param dst: Destination matrix with the same size and type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::lshift
-------------
-Performs pixel by pixel right left of an image by a constant value.
-
-.. ocv:function:: void cuda::lshift(InputArray src, Scalar_<int> val, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source matrix. Supports 1, 3 and 4 channels images with ``CV_8U`` , ``CV_16U`` or ``CV_32S`` depth.
-
- :param val: Constant values, one per channel.
-
- :param dst: Destination matrix with the same size and type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::min
----------
-Computes the per-element minimum of two matrices (or a matrix and a scalar).
-
-.. ocv:function:: void cuda::min(InputArray src1, InputArray src2, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar.
-
- :param dst: Destination matrix that has the same size and type as the input array(s).
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`min`
-
-
-
-cuda::max
----------
-Computes the per-element maximum of two matrices (or a matrix and a scalar).
-
-.. ocv:function:: void cuda::max(InputArray src1, InputArray src2, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src1: First source matrix or scalar.
-
- :param src2: Second source matrix or scalar.
-
- :param dst: Destination matrix that has the same size and type as the input array(s).
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`max`
-
-
-
-cuda::addWeighted
------------------
-Computes the weighted sum of two arrays.
-
-.. ocv:function:: void cuda::addWeighted(InputArray src1, double alpha, InputArray src2, double beta, double gamma, OutputArray dst, int dtype = -1, Stream& stream = Stream::Null())
-
- :param src1: First source array.
-
- :param alpha: Weight for the first array elements.
-
- :param src2: Second source array of the same size and channel number as ``src1`` .
-
- :param beta: Weight for the second array elements.
-
- :param dst: Destination array that has the same size and number of channels as the input arrays.
-
- :param gamma: Scalar added to each sum.
-
- :param dtype: Optional depth of the destination array. When both input arrays have the same depth, ``dtype`` can be set to ``-1``, which will be equivalent to ``src1.depth()``.
-
- :param stream: Stream for the asynchronous version.
-
-The function ``addWeighted`` calculates the weighted sum of two arrays as follows:
-
-.. math::
-
- \texttt{dst} (I)= \texttt{saturate} ( \texttt{src1} (I)* \texttt{alpha} + \texttt{src2} (I)* \texttt{beta} + \texttt{gamma} )
-
-where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
-
-.. seealso:: :ocv:func:`addWeighted`
-
-
-
-cuda::threshold
----------------
-Applies a fixed-level threshold to each array element.
-
-.. ocv:function:: double cuda::threshold(InputArray src, OutputArray dst, double thresh, double maxval, int type, Stream& stream = Stream::Null())
-
- :param src: Source array (single-channel).
-
- :param dst: Destination array with the same size and type as ``src`` .
-
- :param thresh: Threshold value.
-
- :param maxval: Maximum value to use with ``THRESH_BINARY`` and ``THRESH_BINARY_INV`` threshold types.
-
- :param type: Threshold type. For details, see :ocv:func:`threshold` . The ``THRESH_OTSU`` and ``THRESH_TRIANGLE`` threshold types are not supported.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`threshold`
-
-
-
-cuda::magnitude
----------------
-Computes magnitudes of complex matrix elements.
-
-.. ocv:function:: void cuda::magnitude(InputArray xy, OutputArray magnitude, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::magnitude(InputArray x, InputArray y, OutputArray magnitude, Stream& stream = Stream::Null())
-
- :param xy: Source complex matrix in the interleaved format ( ``CV_32FC2`` ).
-
- :param x: Source matrix containing real components ( ``CV_32FC1`` ).
-
- :param y: Source matrix containing imaginary components ( ``CV_32FC1`` ).
-
- :param magnitude: Destination matrix of float magnitudes ( ``CV_32FC1`` ).
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`magnitude`
-
-
-
-cuda::magnitudeSqr
-------------------
-Computes squared magnitudes of complex matrix elements.
-
-.. ocv:function:: void cuda::magnitudeSqr(InputArray xy, OutputArray magnitude, Stream& stream=Stream::Null() )
-
-.. ocv:function:: void cuda::magnitudeSqr(InputArray x, InputArray y, OutputArray magnitude, Stream& stream = Stream::Null())
-
- :param xy: Source complex matrix in the interleaved format ( ``CV_32FC2`` ).
-
- :param x: Source matrix containing real components ( ``CV_32FC1`` ).
-
- :param y: Source matrix containing imaginary components ( ``CV_32FC1`` ).
-
- :param magnitude: Destination matrix of float magnitude squares ( ``CV_32FC1`` ).
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::phase
------------
-Computes polar angles of complex matrix elements.
-
-.. ocv:function:: void cuda::phase(InputArray x, InputArray y, OutputArray angle, bool angleInDegrees = false, Stream& stream = Stream::Null())
-
- :param x: Source matrix containing real components ( ``CV_32FC1`` ).
-
- :param y: Source matrix containing imaginary components ( ``CV_32FC1`` ).
-
- :param angle: Destination matrix of angles ( ``CV_32FC1`` ).
-
- :param angleInDegrees: Flag for angles that must be evaluated in degrees.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`phase`
-
-
-
-cuda::cartToPolar
------------------
-Converts Cartesian coordinates into polar.
-
-.. ocv:function:: void cuda::cartToPolar(InputArray x, InputArray y, OutputArray magnitude, OutputArray angle, bool angleInDegrees = false, Stream& stream = Stream::Null())
-
- :param x: Source matrix containing real components ( ``CV_32FC1`` ).
-
- :param y: Source matrix containing imaginary components ( ``CV_32FC1`` ).
-
- :param magnitude: Destination matrix of float magnitudes ( ``CV_32FC1`` ).
-
- :param angle: Destination matrix of angles ( ``CV_32FC1`` ).
-
- :param angleInDegrees: Flag for angles that must be evaluated in degrees.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`cartToPolar`
-
-
-
-cuda::polarToCart
------------------
-Converts polar coordinates into Cartesian.
-
-.. ocv:function:: void cuda::polarToCart(InputArray magnitude, InputArray angle, OutputArray x, OutputArray y, bool angleInDegrees = false, Stream& stream = Stream::Null())
-
- :param magnitude: Source matrix containing magnitudes ( ``CV_32FC1`` ).
-
- :param angle: Source matrix containing angles ( ``CV_32FC1`` ).
-
- :param x: Destination matrix of real components ( ``CV_32FC1`` ).
-
- :param y: Destination matrix of imaginary components ( ``CV_32FC1`` ).
-
- :param angleInDegrees: Flag that indicates angles in degrees.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`polarToCart`
+++ /dev/null
-Matrix Reductions
-=================
-
-.. highlight:: cpp
-
-
-
-cuda::norm
-----------
-Returns the norm of a matrix (or difference of two matrices).
-
-.. ocv:function:: double cuda::norm(InputArray src1, int normType)
-
-.. ocv:function:: double cuda::norm(InputArray src1, int normType, GpuMat& buf)
-
-.. ocv:function:: double cuda::norm(InputArray src1, int normType, InputArray mask, GpuMat& buf)
-
-.. ocv:function:: double cuda::norm(InputArray src1, InputArray src2, int normType=NORM_L2)
-
- :param src1: Source matrix. Any matrices except 64F are supported.
-
- :param src2: Second source matrix (if any) with the same size and type as ``src1``.
-
- :param normType: Norm type. ``NORM_L1`` , ``NORM_L2`` , and ``NORM_INF`` are supported for now.
-
- :param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
-
- :param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
-.. seealso:: :ocv:func:`norm`
-
-
-
-cuda::sum
----------
-Returns the sum of matrix elements.
-
-.. ocv:function:: Scalar cuda::sum(InputArray src)
-
-.. ocv:function:: Scalar cuda::sum(InputArray src, GpuMat& buf)
-
-.. ocv:function:: Scalar cuda::sum(InputArray src, InputArray mask, GpuMat& buf)
-
- :param src: Source image of any depth except for ``CV_64F`` .
-
- :param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
-
- :param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
-.. seealso:: :ocv:func:`sum`
-
-
-
-cuda::absSum
-------------
-Returns the sum of absolute values for matrix elements.
-
-.. ocv:function:: Scalar cuda::absSum(InputArray src)
-
-.. ocv:function:: Scalar cuda::absSum(InputArray src, GpuMat& buf)
-
-.. ocv:function:: Scalar cuda::absSum(InputArray src, InputArray mask, GpuMat& buf)
-
- :param src: Source image of any depth except for ``CV_64F`` .
-
- :param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
-
- :param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
-
-
-cuda::sqrSum
-------------
-Returns the squared sum of matrix elements.
-
-.. ocv:function:: Scalar cuda::sqrSum(InputArray src)
-
-.. ocv:function:: Scalar cuda::sqrSum(InputArray src, GpuMat& buf)
-
-.. ocv:function:: Scalar cuda::sqrSum(InputArray src, InputArray mask, GpuMat& buf)
-
- :param src: Source image of any depth except for ``CV_64F`` .
-
- :param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
-
- :param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
-
-
-cuda::minMax
-------------
-Finds global minimum and maximum matrix elements and returns their values.
-
-.. ocv:function:: void cuda::minMax(InputArray src, double* minVal, double* maxVal=0, InputArray mask=noArray())
-
-.. ocv:function:: void cuda::minMax(InputArray src, double* minVal, double* maxVal, InputArray mask, GpuMat& buf)
-
- :param src: Single-channel source image.
-
- :param minVal: Pointer to the returned minimum value. Use ``NULL`` if not required.
-
- :param maxVal: Pointer to the returned maximum value. Use ``NULL`` if not required.
-
- :param mask: Optional mask to select a sub-matrix.
-
- :param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
-The function does not work with ``CV_64F`` images on GPUs with the compute capability < 1.3.
-
-.. seealso:: :ocv:func:`minMaxLoc`
-
-
-
-cuda::minMaxLoc
----------------
-Finds global minimum and maximum matrix elements and returns their values with locations.
-
-.. ocv:function:: void cuda::minMaxLoc(InputArray src, double* minVal, double* maxVal=0, Point* minLoc=0, Point* maxLoc=0, InputArray mask=noArray())
-
-.. ocv:function:: void cuda::minMaxLoc(InputArray src, double* minVal, double* maxVal, Point* minLoc, Point* maxLoc, InputArray mask, GpuMat& valbuf, GpuMat& locbuf)
-
- :param src: Single-channel source image.
-
- :param minVal: Pointer to the returned minimum value. Use ``NULL`` if not required.
-
- :param maxVal: Pointer to the returned maximum value. Use ``NULL`` if not required.
-
- :param minLoc: Pointer to the returned minimum location. Use ``NULL`` if not required.
-
- :param maxLoc: Pointer to the returned maximum location. Use ``NULL`` if not required.
-
- :param mask: Optional mask to select a sub-matrix.
-
- :param valbuf: Optional values buffer to avoid extra memory allocations. It is resized automatically.
-
- :param locbuf: Optional locations buffer to avoid extra memory allocations. It is resized automatically.
-
- The function does not work with ``CV_64F`` images on GPU with the compute capability < 1.3.
-
-.. seealso:: :ocv:func:`minMaxLoc`
-
-
-
-cuda::countNonZero
-------------------
-Counts non-zero matrix elements.
-
-.. ocv:function:: int cuda::countNonZero(InputArray src)
-
-.. ocv:function:: int cuda::countNonZero(InputArray src, GpuMat& buf)
-
- :param src: Single-channel source image.
-
- :param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
-The function does not work with ``CV_64F`` images on GPUs with the compute capability < 1.3.
-
-.. seealso:: :ocv:func:`countNonZero`
-
-
-
-cuda::reduce
-------------
-Reduces a matrix to a vector.
-
-.. ocv:function:: void cuda::reduce(InputArray mtx, OutputArray vec, int dim, int reduceOp, int dtype = -1, Stream& stream = Stream::Null())
-
- :param mtx: Source 2D matrix.
-
- :param vec: Destination vector. Its size and type is defined by ``dim`` and ``dtype`` parameters.
-
- :param dim: Dimension index along which the matrix is reduced. 0 means that the matrix is reduced to a single row. 1 means that the matrix is reduced to a single column.
-
- :param reduceOp: Reduction operation that could be one of the following:
-
- * **CV_REDUCE_SUM** The output is the sum of all rows/columns of the matrix.
-
- * **CV_REDUCE_AVG** The output is the mean vector of all rows/columns of the matrix.
-
- * **CV_REDUCE_MAX** The output is the maximum (column/row-wise) of all rows/columns of the matrix.
-
- * **CV_REDUCE_MIN** The output is the minimum (column/row-wise) of all rows/columns of the matrix.
-
- :param dtype: When it is negative, the destination vector will have the same type as the source matrix. Otherwise, its type will be ``CV_MAKE_TYPE(CV_MAT_DEPTH(dtype), mtx.channels())`` .
-
- :param stream: Stream for the asynchronous version.
-
-The function ``reduce`` reduces the matrix to a vector by treating the matrix rows/columns as a set of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained. For example, the function can be used to compute horizontal and vertical projections of a raster image. In case of ``CV_REDUCE_SUM`` and ``CV_REDUCE_AVG`` , the output may have a larger element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes.
-
-.. seealso:: :ocv:func:`reduce`
-
-
-
-cuda::meanStdDev
-----------------
-Computes a mean value and a standard deviation of matrix elements.
-
-.. ocv:function:: void cuda::meanStdDev(InputArray mtx, Scalar& mean, Scalar& stddev)
-.. ocv:function:: void cuda::meanStdDev(InputArray mtx, Scalar& mean, Scalar& stddev, GpuMat& buf)
-
- :param mtx: Source matrix. ``CV_8UC1`` matrices are supported for now.
-
- :param mean: Mean value.
-
- :param stddev: Standard deviation value.
-
- :param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
-.. seealso:: :ocv:func:`meanStdDev`
-
-
-
-cuda::rectStdDev
-----------------
-Computes a standard deviation of integral images.
-
-.. ocv:function:: void cuda::rectStdDev(InputArray src, InputArray sqr, OutputArray dst, Rect rect, Stream& stream = Stream::Null())
-
- :param src: Source image. Only the ``CV_32SC1`` type is supported.
-
- :param sqr: Squared source image. Only the ``CV_32FC1`` type is supported.
-
- :param dst: Destination image with the same type and size as ``src`` .
-
- :param rect: Rectangular window.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::normalize
----------------
-Normalizes the norm or value range of an array.
-
-.. ocv:function:: void cuda::normalize(InputArray src, OutputArray dst, double alpha = 1, double beta = 0, int norm_type = NORM_L2, int dtype = -1, InputArray mask = noArray())
-
-.. ocv:function:: void cuda::normalize(InputArray src, OutputArray dst, double alpha, double beta, int norm_type, int dtype, InputArray mask, GpuMat& norm_buf, GpuMat& cvt_buf)
-
- :param src: Input array.
-
- :param dst: Output array of the same size as ``src`` .
-
- :param alpha: Norm value to normalize to or the lower range boundary in case of the range normalization.
-
- :param beta: Upper range boundary in case of the range normalization; it is not used for the norm normalization.
-
- :param normType: Normalization type ( ``NORM_MINMAX`` , ``NORM_L2`` , ``NORM_L1`` or ``NORM_INF`` ).
-
- :param dtype: When negative, the output array has the same type as ``src``; otherwise, it has the same number of channels as ``src`` and the depth ``=CV_MAT_DEPTH(dtype)``.
-
- :param mask: Optional operation mask.
-
- :param norm_buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
- :param cvt_buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
-.. seealso:: :ocv:func:`normalize`
-
-
-
-cuda::integral
---------------
-Computes an integral image.
-
-.. ocv:function:: void cuda::integral(InputArray src, OutputArray sum, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::integral(InputArray src, OutputArray sum, GpuMat& buffer, Stream& stream = Stream::Null())
-
- :param src: Source image. Only ``CV_8UC1`` images are supported for now.
-
- :param sum: Integral image containing 32-bit unsigned integer values packed into ``CV_32SC1`` .
-
- :param buffer: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`integral`
-
-
-
-cuda::sqrIntegral
------------------
-Computes a squared integral image.
-
-.. ocv:function:: void cuda::sqrIntegral(InputArray src, OutputArray sqsum, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::sqrIntegral(InputArray src, OutputArray sqsum, GpuMat& buf, Stream& stream = Stream::Null())
-
- :param src: Source image. Only ``CV_8UC1`` images are supported for now.
-
- :param sqsum: Squared integral image containing 64-bit unsigned integer values packed into ``CV_64FC1`` .
-
- :param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
-
- :param stream: Stream for the asynchronous version.
+++ /dev/null
-Background Segmentation
-=======================
-
-.. highlight:: cpp
-
-
-
-cuda::BackgroundSubtractorMOG
------------------------------
-Gaussian Mixture-based Background/Foreground Segmentation Algorithm.
-
-.. ocv:class:: cuda::BackgroundSubtractorMOG : public cv::BackgroundSubtractorMOG
-
-The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [MOG2001]_.
-
-.. seealso:: :ocv:class:`BackgroundSubtractorMOG`
-
-.. note::
-
- * An example on gaussian mixture based background/foreground segmantation can be found at opencv_source_code/samples/gpu/bgfg_segm.cpp
-
-
-
-cuda::createBackgroundSubtractorMOG
------------------------------------
-Creates mixture-of-gaussian background subtractor
-
-.. ocv:function:: Ptr<cuda::BackgroundSubtractorMOG> cuda::createBackgroundSubtractorMOG(int history=200, int nmixtures=5, double backgroundRatio=0.7, double noiseSigma=0)
-
- :param history: Length of the history.
-
- :param nmixtures: Number of Gaussian mixtures.
-
- :param backgroundRatio: Background ratio.
-
- :param noiseSigma: Noise strength (standard deviation of the brightness or each color channel). 0 means some automatic value.
-
-
-
-cuda::BackgroundSubtractorMOG2
-------------------------------
-Gaussian Mixture-based Background/Foreground Segmentation Algorithm.
-
-.. ocv:class:: cuda::BackgroundSubtractorMOG2 : public cv::BackgroundSubtractorMOG2
-
-The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [MOG2004]_.
-
-.. seealso:: :ocv:class:`BackgroundSubtractorMOG2`
-
-
-
-cuda::createBackgroundSubtractorMOG2
-------------------------------------
-Creates MOG2 Background Subtractor
-
-.. ocv:function:: Ptr<cuda::BackgroundSubtractorMOG2> cuda::createBackgroundSubtractorMOG2( int history=500, double varThreshold=16, bool detectShadows=true )
-
- :param history: Length of the history.
-
- :param varThreshold: Threshold on the squared Mahalanobis distance between the pixel and the model to decide whether a pixel is well described by the background model. This parameter does not affect the background update.
-
- :param detectShadows: If true, the algorithm will detect shadows and mark them. It decreases the speed a bit, so if you do not need this feature, set the parameter to false.
-
-
-
-cuda::BackgroundSubtractorGMG
------------------------------
-Background/Foreground Segmentation Algorithm.
-
-.. ocv:class:: cuda::BackgroundSubtractorGMG : public cv::BackgroundSubtractorGMG
-
-The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [GMG2012]_.
-
-
-
-cuda::createBackgroundSubtractorGMG
------------------------------------
-Creates GMG Background Subtractor
-
-.. ocv:function:: Ptr<cuda::BackgroundSubtractorGMG> cuda::createBackgroundSubtractorGMG(int initializationFrames = 120, double decisionThreshold = 0.8)
-
- :param initializationFrames: Number of frames of video to use to initialize histograms.
-
- :param decisionThreshold: Value above which pixel is determined to be FG.
-
-
-
-cuda::BackgroundSubtractorFGD
------------------------------
-
-.. ocv:class:: cuda::BackgroundSubtractorFGD : public cv::BackgroundSubtractor
-
-The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [FGD2003]_. ::
-
- class CV_EXPORTS BackgroundSubtractorFGD : public cv::BackgroundSubtractor
- {
- public:
- virtual void getForegroundRegions(OutputArrayOfArrays foreground_regions) = 0;
- };
-
-.. seealso:: :ocv:class:`BackgroundSubtractor`
-
-
-
-cuda::BackgroundSubtractorFGD::getForegroundRegions
----------------------------------------------------
-Returns the output foreground regions calculated by :ocv:func:`findContours`.
-
-.. ocv:function:: void cuda::BackgroundSubtractorFGD::getForegroundRegions(OutputArrayOfArrays foreground_regions)
-
- :params foreground_regions: Output array (CPU memory).
-
-
-
-cuda::createBackgroundSubtractorFGD
------------------------------------
-Creates FGD Background Subtractor
-
-.. ocv:function:: Ptr<cuda::BackgroundSubtractorGMG> cuda::createBackgroundSubtractorFGD(const FGDParams& params = FGDParams())
-
- :param params: Algorithm's parameters. See [FGD2003]_ for explanation.
-
-
-
-.. [FGD2003] Liyuan Li, Weimin Huang, Irene Y.H. Gu, and Qi Tian. *Foreground Object Detection from Videos Containing Complex Background*. ACM MM2003 9p, 2003.
-.. [MOG2001] P. KadewTraKuPong and R. Bowden. *An improved adaptive background mixture model for real-time tracking with shadow detection*. Proc. 2nd European Workshop on Advanced Video-Based Surveillance Systems, 2001
-.. [MOG2004] Z. Zivkovic. *Improved adaptive Gausian mixture model for background subtraction*. International Conference Pattern Recognition, UK, August, 2004
-.. [GMG2012] A. Godbehere, A. Matsukawa and K. Goldberg. *Visual Tracking of Human Visitors under Variable-Lighting Conditions for a Responsive Audio Art Installation*. American Control Conference, Montreal, June 2012
+++ /dev/null
-****************************************************
-cudabgsegm. CUDA-accelerated Background Segmentation
-****************************************************
-
-.. toctree::
- :maxdepth: 1
-
- background_segmentation
+++ /dev/null
-***************************************************
-cudacodec. CUDA-accelerated Video Encoding/Decoding
-***************************************************
-
-.. toctree::
- :maxdepth: 1
-
- videodec
- videoenc
+++ /dev/null
-Video Decoding
-==============
-
-.. highlight:: cpp
-
-
-
-cudacodec::VideoReader
-----------------------
-Video reader interface.
-
-.. ocv:class:: cudacodec::VideoReader
-
-.. note::
-
- * An example on how to use the videoReader class can be found at opencv_source_code/samples/gpu/video_reader.cpp
-
-
-cudacodec::VideoReader::nextFrame
----------------------------------
-Grabs, decodes and returns the next video frame.
-
-.. ocv:function:: bool cudacodec::VideoReader::nextFrame(OutputArray frame)
-
-If no frames has been grabbed (there are no more frames in video file), the methods return ``false`` . The method throws :ocv:class:`Exception` if error occurs.
-
-
-
-cudacodec::VideoReader::format
-------------------------------
-Returns information about video file format.
-
-.. ocv:function:: FormatInfo cudacodec::VideoReader::format() const
-
-
-
-cudacodec::Codec
-----------------
-Video codecs supported by :ocv:class:`cudacodec::VideoReader` .
-
-.. ocv:enum:: cudacodec::Codec
-
- .. ocv:emember:: MPEG1 = 0
- .. ocv:emember:: MPEG2
- .. ocv:emember:: MPEG4
- .. ocv:emember:: VC1
- .. ocv:emember:: H264
- .. ocv:emember:: JPEG
- .. ocv:emember:: H264_SVC
- .. ocv:emember:: H264_MVC
-
- .. ocv:emember:: Uncompressed_YUV420 = (('I'<<24)|('Y'<<16)|('U'<<8)|('V'))
-
- Y,U,V (4:2:0)
-
- .. ocv:emember:: Uncompressed_YV12 = (('Y'<<24)|('V'<<16)|('1'<<8)|('2'))
-
- Y,V,U (4:2:0)
-
- .. ocv:emember:: Uncompressed_NV12 = (('N'<<24)|('V'<<16)|('1'<<8)|('2'))
-
- Y,UV (4:2:0)
-
- .. ocv:emember:: Uncompressed_YUYV = (('Y'<<24)|('U'<<16)|('Y'<<8)|('V'))
-
- YUYV/YUY2 (4:2:2)
-
- .. ocv:emember:: Uncompressed_UYVY = (('U'<<24)|('Y'<<16)|('V'<<8)|('Y'))
-
- UYVY (4:2:2)
-
-
-
-cudacodec::ChromaFormat
------------------------
-Chroma formats supported by :ocv:class:`cudacodec::VideoReader` .
-
-.. ocv:enum:: cudacodec::ChromaFormat
-
- .. ocv:emember:: Monochrome = 0
- .. ocv:emember:: YUV420
- .. ocv:emember:: YUV422
- .. ocv:emember:: YUV444
-
-
-
-cudacodec::FormatInfo
----------------------
-.. ocv:struct:: cudacodec::FormatInfo
-
-Struct providing information about video file format. ::
-
- struct FormatInfo
- {
- Codec codec;
- ChromaFormat chromaFormat;
- int width;
- int height;
- };
-
-
-
-cudacodec::createVideoReader
-----------------------------
-Creates video reader.
-
-.. ocv:function:: Ptr<VideoReader> cudacodec::createVideoReader(const String& filename)
-.. ocv:function:: Ptr<VideoReader> cudacodec::createVideoReader(const Ptr<RawVideoSource>& source)
-
- :param filename: Name of the input video file.
-
- :param source: RAW video source implemented by user.
-
-FFMPEG is used to read videos. User can implement own demultiplexing with :ocv:class:`cudacodec::RawVideoSource` .
-
-
-
-cudacodec::RawVideoSource
--------------------------
-.. ocv:class:: cudacodec::RawVideoSource
-
-Interface for video demultiplexing. ::
-
- class RawVideoSource
- {
- public:
- virtual ~RawVideoSource() {}
-
- virtual bool getNextPacket(unsigned char** data, int* size, bool* endOfFile) = 0;
-
- virtual FormatInfo format() const = 0;
- };
-
-User can implement own demultiplexing by implementing this interface.
-
-
-
-cudacodec::RawVideoSource::getNextPacket
-----------------------------------------
-Returns next packet with RAW video frame.
-
-.. ocv:function:: bool cudacodec::VideoSource::getNextPacket(unsigned char** data, int* size, bool* endOfFile) = 0
-
- :param data: Pointer to frame data.
-
- :param size: Size in bytes of current frame.
-
- :param endOfStream: Indicates that it is end of stream.
-
-
-
-cudacodec::RawVideoSource::format
----------------------------------
-Returns information about video file format.
-
-.. ocv:function:: virtual FormatInfo cudacodec::RawVideoSource::format() const = 0
+++ /dev/null
-Video Encoding
-==============
-
-.. highlight:: cpp
-
-
-
-cudacodec::VideoWriter
-----------------------
-Video writer interface.
-
-.. ocv:class:: cudacodec::VideoWriter
-
-The implementation uses H264 video codec.
-
-.. note:: Currently only Windows platform is supported.
-
-.. note::
-
- * An example on how to use the videoWriter class can be found at opencv_source_code/samples/gpu/video_writer.cpp
-
-
-cudacodec::VideoWriter::write
------------------------------
-Writes the next video frame.
-
-.. ocv:function:: void cudacodec::VideoWriter::write(InputArray frame, bool lastFrame = false) = 0
-
- :param frame: The written frame.
-
- :param lastFrame: Indicates that it is end of stream. The parameter can be ignored.
-
-The method write the specified image to video file. The image must have the same size and the same surface format as has been specified when opening the video writer.
-
-
-
-cudacodec::createVideoWriter
-----------------------------
-Creates video writer.
-
-.. ocv:function:: Ptr<cudacodec::VideoWriter> cudacodec::createVideoWriter(const String& fileName, Size frameSize, double fps, SurfaceFormat format = SF_BGR)
-.. ocv:function:: Ptr<cudacodec::VideoWriter> cudacodec::createVideoWriter(const String& fileName, Size frameSize, double fps, const EncoderParams& params, SurfaceFormat format = SF_BGR)
-.. ocv:function:: Ptr<cudacodec::VideoWriter> cudacodec::createVideoWriter(const Ptr<EncoderCallBack>& encoderCallback, Size frameSize, double fps, SurfaceFormat format = SF_BGR)
-.. ocv:function:: Ptr<cudacodec::VideoWriter> cudacodec::createVideoWriter(const Ptr<EncoderCallBack>& encoderCallback, Size frameSize, double fps, const EncoderParams& params, SurfaceFormat format = SF_BGR)
-
- :param fileName: Name of the output video file. Only AVI file format is supported.
-
- :param frameSize: Size of the input video frames.
-
- :param fps: Framerate of the created video stream.
-
- :param params: Encoder parameters. See :ocv:struct:`cudacodec::EncoderParams` .
-
- :param format: Surface format of input frames ( ``SF_UYVY`` , ``SF_YUY2`` , ``SF_YV12`` , ``SF_NV12`` , ``SF_IYUV`` , ``SF_BGR`` or ``SF_GRAY``). BGR or gray frames will be converted to YV12 format before encoding, frames with other formats will be used as is.
-
- :param encoderCallback: Callbacks for video encoder. See :ocv:class:`cudacodec::EncoderCallBack` . Use it if you want to work with raw video stream.
-
-The constructors initialize video writer. FFMPEG is used to write videos. User can implement own multiplexing with :ocv:class:`cudacodec::EncoderCallBack` .
-
-
-
-cudacodec::EncoderParams
-------------------------
-.. ocv:struct:: cudacodec::EncoderParams
-
-Different parameters for CUDA video encoder. ::
-
- struct EncoderParams
- {
- int P_Interval; // NVVE_P_INTERVAL,
- int IDR_Period; // NVVE_IDR_PERIOD,
- int DynamicGOP; // NVVE_DYNAMIC_GOP,
- int RCType; // NVVE_RC_TYPE,
- int AvgBitrate; // NVVE_AVG_BITRATE,
- int PeakBitrate; // NVVE_PEAK_BITRATE,
- int QP_Level_Intra; // NVVE_QP_LEVEL_INTRA,
- int QP_Level_InterP; // NVVE_QP_LEVEL_INTER_P,
- int QP_Level_InterB; // NVVE_QP_LEVEL_INTER_B,
- int DeblockMode; // NVVE_DEBLOCK_MODE,
- int ProfileLevel; // NVVE_PROFILE_LEVEL,
- int ForceIntra; // NVVE_FORCE_INTRA,
- int ForceIDR; // NVVE_FORCE_IDR,
- int ClearStat; // NVVE_CLEAR_STAT,
- int DIMode; // NVVE_SET_DEINTERLACE,
- int Presets; // NVVE_PRESETS,
- int DisableCabac; // NVVE_DISABLE_CABAC,
- int NaluFramingType; // NVVE_CONFIGURE_NALU_FRAMING_TYPE
- int DisableSPSPPS; // NVVE_DISABLE_SPS_PPS
-
- EncoderParams();
- explicit EncoderParams(const String& configFile);
-
- void load(const String& configFile);
- void save(const String& configFile) const;
- };
-
-
-
-cudacodec::EncoderParams::EncoderParams
----------------------------------------
-Constructors.
-
-.. ocv:function:: cudacodec::EncoderParams::EncoderParams()
-.. ocv:function:: cudacodec::EncoderParams::EncoderParams(const String& configFile)
-
- :param configFile: Config file name.
-
-Creates default parameters or reads parameters from config file.
-
-
-
-cudacodec::EncoderParams::load
-------------------------------
-Reads parameters from config file.
-
-.. ocv:function:: void cudacodec::EncoderParams::load(const String& configFile)
-
- :param configFile: Config file name.
-
-
-
-cudacodec::EncoderParams::save
-------------------------------
-Saves parameters to config file.
-
-.. ocv:function:: void cudacodec::EncoderParams::save(const String& configFile) const
-
- :param configFile: Config file name.
-
-
-
-cudacodec::EncoderCallBack
---------------------------
-.. ocv:class:: cudacodec::EncoderCallBack
-
-Callbacks for CUDA video encoder. ::
-
- class EncoderCallBack
- {
- public:
- enum PicType
- {
- IFRAME = 1,
- PFRAME = 2,
- BFRAME = 3
- };
-
- virtual ~EncoderCallBack() {}
-
- virtual unsigned char* acquireBitStream(int* bufferSize) = 0;
- virtual void releaseBitStream(unsigned char* data, int size) = 0;
- virtual void onBeginFrame(int frameNumber, PicType picType) = 0;
- virtual void onEndFrame(int frameNumber, PicType picType) = 0;
- };
-
-
-
-cudacodec::EncoderCallBack::acquireBitStream
---------------------------------------------
-Callback function to signal the start of bitstream that is to be encoded.
-
-.. ocv:function:: virtual uchar* cudacodec::EncoderCallBack::acquireBitStream(int* bufferSize) = 0
-
-Callback must allocate buffer for CUDA encoder and return pointer to it and it's size.
-
-
-
-cudacodec::EncoderCallBack::releaseBitStream
---------------------------------------------
-Callback function to signal that the encoded bitstream is ready to be written to file.
-
-.. ocv:function:: virtual void cudacodec::EncoderCallBack::releaseBitStream(unsigned char* data, int size) = 0
-
-
-
-cudacodec::EncoderCallBack::onBeginFrame
-----------------------------------------
-Callback function to signal that the encoding operation on the frame has started.
-
-.. ocv:function:: virtual void cudacodec::EncoderCallBack::onBeginFrame(int frameNumber, PicType picType) = 0
-
- :param picType: Specify frame type (I-Frame, P-Frame or B-Frame).
-
-
-
-cudacodec::EncoderCallBack::onEndFrame
---------------------------------------
-Callback function signals that the encoding operation on the frame has finished.
-
-.. ocv:function:: virtual void cudacodec::EncoderCallBack::onEndFrame(int frameNumber, PicType picType) = 0
-
- :param picType: Specify frame type (I-Frame, P-Frame or B-Frame).
+++ /dev/null
-******************************************************************
-cudafeatures2d. CUDA-accelerated Feature Detection and Description
-******************************************************************
-
-.. toctree::
- :maxdepth: 1
-
- feature_detection_and_description
+++ /dev/null
-Feature Detection and Description
-=================================
-
-.. highlight:: cpp
-
-
-
-cuda::FAST_CUDA
----------------
-.. ocv:class:: cuda::FAST_CUDA
-
-Class used for corner detection using the FAST algorithm. ::
-
- class FAST_CUDA
- {
- public:
- enum
- {
- LOCATION_ROW = 0,
- RESPONSE_ROW,
- ROWS_COUNT
- };
-
- // all features have same size
- static const int FEATURE_SIZE = 7;
-
- explicit FAST_CUDA(int threshold, bool nonmaxSuppression = true,
- double keypointsRatio = 0.05);
-
- void operator ()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints);
- void operator ()(const GpuMat& image, const GpuMat& mask,
- std::vector<KeyPoint>& keypoints);
-
- void downloadKeypoints(const GpuMat& d_keypoints,
- std::vector<KeyPoint>& keypoints);
-
- void convertKeypoints(const Mat& h_keypoints,
- std::vector<KeyPoint>& keypoints);
-
- void release();
-
- bool nonmaxSuppression;
-
- int threshold;
-
- double keypointsRatio;
-
- int calcKeyPointsLocation(const GpuMat& image, const GpuMat& mask);
-
- int getKeyPoints(GpuMat& keypoints);
- };
-
-
-The class ``FAST_CUDA`` implements FAST corner detection algorithm.
-
-.. seealso:: :ocv:func:`FAST`
-
-
-
-cuda::FAST_CUDA::FAST_CUDA
---------------------------
-Constructor.
-
-.. ocv:function:: cuda::FAST_CUDA::FAST_CUDA(int threshold, bool nonmaxSuppression = true, double keypointsRatio = 0.05)
-
- :param threshold: Threshold on difference between intensity of the central pixel and pixels on a circle around this pixel.
-
- :param nonmaxSuppression: If it is true, non-maximum suppression is applied to detected corners (keypoints).
-
- :param keypointsRatio: Inner buffer size for keypoints store is determined as (keypointsRatio * image_width * image_height).
-
-
-
-cuda::FAST_CUDA::operator ()
-----------------------------
-Finds the keypoints using FAST detector.
-
-.. ocv:function:: void cuda::FAST_CUDA::operator ()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints)
-.. ocv:function:: void cuda::FAST_CUDA::operator ()(const GpuMat& image, const GpuMat& mask, std::vector<KeyPoint>& keypoints)
-
- :param image: Image where keypoints (corners) are detected. Only 8-bit grayscale images are supported.
-
- :param mask: Optional input mask that marks the regions where we should detect features.
-
- :param keypoints: The output vector of keypoints. Can be stored both in CPU and GPU memory. For GPU memory:
-
- * keypoints.ptr<Vec2s>(LOCATION_ROW)[i] will contain location of i'th point
- * keypoints.ptr<float>(RESPONSE_ROW)[i] will contain response of i'th point (if non-maximum suppression is applied)
-
-
-
-cuda::FAST_CUDA::downloadKeypoints
-----------------------------------
-Download keypoints from GPU to CPU memory.
-
-.. ocv:function:: void cuda::FAST_CUDA::downloadKeypoints(const GpuMat& d_keypoints, std::vector<KeyPoint>& keypoints)
-
-
-
-cuda::FAST_CUDA::convertKeypoints
----------------------------------
-Converts keypoints from CUDA representation to vector of ``KeyPoint``.
-
-.. ocv:function:: void cuda::FAST_CUDA::convertKeypoints(const Mat& h_keypoints, std::vector<KeyPoint>& keypoints)
-
-
-
-cuda::FAST_CUDA::release
-------------------------
-Releases inner buffer memory.
-
-.. ocv:function:: void cuda::FAST_CUDA::release()
-
-
-
-cuda::FAST_CUDA::calcKeyPointsLocation
---------------------------------------
-Find keypoints and compute it's response if ``nonmaxSuppression`` is true.
-
-.. ocv:function:: int cuda::FAST_CUDA::calcKeyPointsLocation(const GpuMat& image, const GpuMat& mask)
-
- :param image: Image where keypoints (corners) are detected. Only 8-bit grayscale images are supported.
-
- :param mask: Optional input mask that marks the regions where we should detect features.
-
-The function returns count of detected keypoints.
-
-
-
-cuda::FAST_CUDA::getKeyPoints
------------------------------
-Gets final array of keypoints.
-
-.. ocv:function:: int cuda::FAST_CUDA::getKeyPoints(GpuMat& keypoints)
-
- :param keypoints: The output vector of keypoints.
-
-The function performs non-max suppression if needed and returns final count of keypoints.
-
-
-
-cuda::ORB_CUDA
---------------
-.. ocv:class:: cuda::ORB_CUDA
-
-Class for extracting ORB features and descriptors from an image. ::
-
- class ORB_CUDA
- {
- public:
- enum
- {
- X_ROW = 0,
- Y_ROW,
- RESPONSE_ROW,
- ANGLE_ROW,
- OCTAVE_ROW,
- SIZE_ROW,
- ROWS_COUNT
- };
-
- enum
- {
- DEFAULT_FAST_THRESHOLD = 20
- };
-
- explicit ORB_CUDA(int nFeatures = 500, float scaleFactor = 1.2f,
- int nLevels = 8, int edgeThreshold = 31,
- int firstLevel = 0, int WTA_K = 2,
- int scoreType = 0, int patchSize = 31);
-
- void operator()(const GpuMat& image, const GpuMat& mask,
- std::vector<KeyPoint>& keypoints);
- void operator()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints);
-
- void operator()(const GpuMat& image, const GpuMat& mask,
- std::vector<KeyPoint>& keypoints, GpuMat& descriptors);
- void operator()(const GpuMat& image, const GpuMat& mask,
- GpuMat& keypoints, GpuMat& descriptors);
-
- void downloadKeyPoints(GpuMat& d_keypoints, std::vector<KeyPoint>& keypoints);
-
- void convertKeyPoints(Mat& d_keypoints, std::vector<KeyPoint>& keypoints);
-
- int descriptorSize() const;
-
- void setParams(size_t n_features, const ORB::CommonParams& detector_params);
- void setFastParams(int threshold, bool nonmaxSuppression = true);
-
- void release();
-
- bool blurForDescriptor;
- };
-
-The class implements ORB feature detection and description algorithm.
-
-
-
-cuda::ORB_CUDA::ORB_CUDA
-------------------------
-Constructor.
-
-.. ocv:function:: cuda::ORB_CUDA::ORB_CUDA(int nFeatures = 500, float scaleFactor = 1.2f, int nLevels = 8, int edgeThreshold = 31, int firstLevel = 0, int WTA_K = 2, int scoreType = 0, int patchSize = 31)
-
- :param nFeatures: The number of desired features.
-
- :param scaleFactor: Coefficient by which we divide the dimensions from one scale pyramid level to the next.
-
- :param nLevels: The number of levels in the scale pyramid.
-
- :param edgeThreshold: How far from the boundary the points should be.
-
- :param firstLevel: The level at which the image is given. If 1, that means we will also look at the image `scaleFactor` times bigger.
-
-
-
-cuda::ORB_CUDA::operator()
---------------------------
-Detects keypoints and computes descriptors for them.
-
-.. ocv:function:: void cuda::ORB_CUDA::operator()(const GpuMat& image, const GpuMat& mask, std::vector<KeyPoint>& keypoints)
-
-.. ocv:function:: void cuda::ORB_CUDA::operator()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints)
-
-.. ocv:function:: void cuda::ORB_CUDA::operator()(const GpuMat& image, const GpuMat& mask, std::vector<KeyPoint>& keypoints, GpuMat& descriptors)
-
-.. ocv:function:: void cuda::ORB_CUDA::operator()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints, GpuMat& descriptors)
-
- :param image: Input 8-bit grayscale image.
-
- :param mask: Optional input mask that marks the regions where we should detect features.
-
- :param keypoints: The input/output vector of keypoints. Can be stored both in CPU and GPU memory. For GPU memory:
-
- * ``keypoints.ptr<float>(X_ROW)[i]`` contains x coordinate of the i'th feature.
- * ``keypoints.ptr<float>(Y_ROW)[i]`` contains y coordinate of the i'th feature.
- * ``keypoints.ptr<float>(RESPONSE_ROW)[i]`` contains the response of the i'th feature.
- * ``keypoints.ptr<float>(ANGLE_ROW)[i]`` contains orientation of the i'th feature.
- * ``keypoints.ptr<float>(OCTAVE_ROW)[i]`` contains the octave of the i'th feature.
- * ``keypoints.ptr<float>(SIZE_ROW)[i]`` contains the size of the i'th feature.
-
- :param descriptors: Computed descriptors. if ``blurForDescriptor`` is true, image will be blurred before descriptors calculation.
-
-
-
-cuda::ORB_CUDA::downloadKeyPoints
----------------------------------
-Download keypoints from GPU to CPU memory.
-
-.. ocv:function:: static void cuda::ORB_CUDA::downloadKeyPoints( const GpuMat& d_keypoints, std::vector<KeyPoint>& keypoints )
-
-
-
-cuda::ORB_CUDA::convertKeyPoints
---------------------------------
-Converts keypoints from CUDA representation to vector of ``KeyPoint``.
-
-.. ocv:function:: static void cuda::ORB_CUDA::convertKeyPoints( const Mat& d_keypoints, std::vector<KeyPoint>& keypoints )
-
-
-
-cuda::ORB_CUDA::release
------------------------
-Releases inner buffer memory.
-
-.. ocv:function:: void cuda::ORB_CUDA::release()
-
-
-
-cuda::BFMatcher_CUDA
---------------------
-.. ocv:class:: cuda::BFMatcher_CUDA
-
-Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest descriptor in the second set by trying each one. This descriptor matcher supports masking permissible matches between descriptor sets. ::
-
- class BFMatcher_CUDA
- {
- public:
- explicit BFMatcher_CUDA(int norm = cv::NORM_L2);
-
- // Add descriptors to train descriptor collection.
- void add(const std::vector<GpuMat>& descCollection);
-
- // Get train descriptors collection.
- const std::vector<GpuMat>& getTrainDescriptors() const;
-
- // Clear train descriptors collection.
- void clear();
-
- // Return true if there are no train descriptors in collection.
- bool empty() const;
-
- // Return true if the matcher supports mask in match methods.
- bool isMaskSupported() const;
-
- void matchSingle(const GpuMat& query, const GpuMat& train,
- GpuMat& trainIdx, GpuMat& distance,
- const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null());
-
- static void matchDownload(const GpuMat& trainIdx,
- const GpuMat& distance, std::vector<DMatch>& matches);
- static void matchConvert(const Mat& trainIdx,
- const Mat& distance, std::vector<DMatch>& matches);
-
- void match(const GpuMat& query, const GpuMat& train,
- std::vector<DMatch>& matches, const GpuMat& mask = GpuMat());
-
- void makeGpuCollection(GpuMat& trainCollection, GpuMat& maskCollection,
- const vector<GpuMat>& masks = std::vector<GpuMat>());
-
- void matchCollection(const GpuMat& query, const GpuMat& trainCollection,
- GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance,
- const GpuMat& maskCollection, Stream& stream = Stream::Null());
-
- static void matchDownload(const GpuMat& trainIdx, GpuMat& imgIdx,
- const GpuMat& distance, std::vector<DMatch>& matches);
- static void matchConvert(const Mat& trainIdx, const Mat& imgIdx,
- const Mat& distance, std::vector<DMatch>& matches);
-
- void match(const GpuMat& query, std::vector<DMatch>& matches,
- const std::vector<GpuMat>& masks = std::vector<GpuMat>());
-
- void knnMatchSingle(const GpuMat& query, const GpuMat& train,
- GpuMat& trainIdx, GpuMat& distance, GpuMat& allDist, int k,
- const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null());
-
- static void knnMatchDownload(const GpuMat& trainIdx, const GpuMat& distance,
- std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
- static void knnMatchConvert(const Mat& trainIdx, const Mat& distance,
- std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
-
- void knnMatch(const GpuMat& query, const GpuMat& train,
- std::vector< std::vector<DMatch> >& matches, int k,
- const GpuMat& mask = GpuMat(), bool compactResult = false);
-
- void knnMatch2Collection(const GpuMat& query, const GpuMat& trainCollection,
- GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance,
- const GpuMat& maskCollection = GpuMat(), Stream& stream = Stream::Null());
-
- static void knnMatch2Download(const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance,
- std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
- static void knnMatch2Convert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance,
- std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
-
- void knnMatch(const GpuMat& query, std::vector< std::vector<DMatch> >& matches, int k,
- const std::vector<GpuMat>& masks = std::vector<GpuMat>(),
- bool compactResult = false);
-
- void radiusMatchSingle(const GpuMat& query, const GpuMat& train,
- GpuMat& trainIdx, GpuMat& distance, GpuMat& nMatches, float maxDistance,
- const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null());
-
- static void radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, const GpuMat& nMatches,
- std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
- static void radiusMatchConvert(const Mat& trainIdx, const Mat& distance, const Mat& nMatches,
- std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
-
- void radiusMatch(const GpuMat& query, const GpuMat& train,
- std::vector< std::vector<DMatch> >& matches, float maxDistance,
- const GpuMat& mask = GpuMat(), bool compactResult = false);
-
- void radiusMatchCollection(const GpuMat& query, GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance, GpuMat& nMatches, float maxDistance,
- const std::vector<GpuMat>& masks = std::vector<GpuMat>(), Stream& stream = Stream::Null());
-
- static void radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance, const GpuMat& nMatches,
- std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
- static void radiusMatchConvert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, const Mat& nMatches,
- std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
-
- void radiusMatch(const GpuMat& query, std::vector< std::vector<DMatch> >& matches, float maxDistance,
- const std::vector<GpuMat>& masks = std::vector<GpuMat>(), bool compactResult = false);
-
- private:
- std::vector<GpuMat> trainDescCollection;
- };
-
-
-The class ``BFMatcher_CUDA`` has an interface similar to the class :ocv:class:`DescriptorMatcher`. It has two groups of ``match`` methods: for matching descriptors of one image with another image or with an image set. Also, all functions have an alternative to save results either to the GPU memory or to the CPU memory.
-
-.. seealso:: :ocv:class:`DescriptorMatcher`, :ocv:class:`BFMatcher`
-
-
-
-cuda::BFMatcher_CUDA::match
----------------------------
-Finds the best match for each descriptor from a query set with train descriptors.
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::match(const GpuMat& query, const GpuMat& train, std::vector<DMatch>& matches, const GpuMat& mask = GpuMat())
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::matchSingle(const GpuMat& query, const GpuMat& train, GpuMat& trainIdx, GpuMat& distance, const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::match(const GpuMat& query, std::vector<DMatch>& matches, const std::vector<GpuMat>& masks = std::vector<GpuMat>())
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::matchCollection( const GpuMat& query, const GpuMat& trainCollection, GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance, const GpuMat& masks=GpuMat(), Stream& stream=Stream::Null() )
-
-.. seealso:: :ocv:func:`DescriptorMatcher::match`
-
-
-
-cuda::BFMatcher_CUDA::makeGpuCollection
----------------------------------------
-Performs a GPU collection of train descriptors and masks in a suitable format for the :ocv:func:`cuda::BFMatcher_CUDA::matchCollection` function.
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::makeGpuCollection(GpuMat& trainCollection, GpuMat& maskCollection, const vector<GpuMat>& masks = std::vector<GpuMat>())
-
-
-
-cuda::BFMatcher_CUDA::matchDownload
------------------------------------
-Downloads matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::matchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::matchCollection` to vector with :ocv:class:`DMatch`.
-
-.. ocv:function:: static void cuda::BFMatcher_CUDA::matchDownload(const GpuMat& trainIdx, const GpuMat& distance, std::vector<DMatch>&matches)
-
-.. ocv:function:: static void cuda::BFMatcher_CUDA::matchDownload( const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance, std::vector<DMatch>& matches )
-
-
-
-cuda::BFMatcher_CUDA::matchConvert
-----------------------------------
-Converts matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::matchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::matchCollection` to vector with :ocv:class:`DMatch`.
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::matchConvert(const Mat& trainIdx, const Mat& distance, std::vector<DMatch>&matches)
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::matchConvert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, std::vector<DMatch>&matches)
-
-
-
-cuda::BFMatcher_CUDA::knnMatch
-------------------------------
-Finds the ``k`` best matches for each descriptor from a query set with train descriptors.
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch(const GpuMat& query, const GpuMat& train, std::vector< std::vector<DMatch> >&matches, int k, const GpuMat& mask = GpuMat(), bool compactResult = false)
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatchSingle(const GpuMat& query, const GpuMat& train, GpuMat& trainIdx, GpuMat& distance, GpuMat& allDist, int k, const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch(const GpuMat& query, std::vector< std::vector<DMatch> >&matches, int k, const std::vector<GpuMat>&masks = std::vector<GpuMat>(), bool compactResult = false )
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch2Collection(const GpuMat& query, const GpuMat& trainCollection, GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance, const GpuMat& maskCollection = GpuMat(), Stream& stream = Stream::Null())
-
- :param query: Query set of descriptors.
-
- :param train: Training set of descriptors. It is not be added to train descriptors collection stored in the class object.
-
- :param k: Number of the best matches per each query descriptor (or less if it is not possible).
-
- :param mask: Mask specifying permissible matches between the input query and train matrices of descriptors.
-
- :param compactResult: If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
-
- :param stream: Stream for the asynchronous version.
-
-The function returns detected ``k`` (or less if not possible) matches in the increasing order by distance.
-
-The third variant of the method stores the results in GPU memory.
-
-.. seealso:: :ocv:func:`DescriptorMatcher::knnMatch`
-
-
-
-cuda::BFMatcher_CUDA::knnMatchDownload
---------------------------------------
-Downloads matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::knnMatchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::knnMatch2Collection` to vector with :ocv:class:`DMatch`.
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch2Download(const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
-
-If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
-
-
-
-cuda::BFMatcher_CUDA::knnMatchConvert
--------------------------------------
-Converts matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::knnMatchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::knnMatch2Collection` to CPU vector with :ocv:class:`DMatch`.
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatchConvert(const Mat& trainIdx, const Mat& distance, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch2Convert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
-
-If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
-
-
-
-cuda::BFMatcher_CUDA::radiusMatch
----------------------------------
-For each query descriptor, finds the best matches with a distance less than a given threshold.
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatch(const GpuMat& query, const GpuMat& train, std::vector< std::vector<DMatch> >&matches, float maxDistance, const GpuMat& mask = GpuMat(), bool compactResult = false)
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchSingle(const GpuMat& query, const GpuMat& train, GpuMat& trainIdx, GpuMat& distance, GpuMat& nMatches, float maxDistance, const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatch(const GpuMat& query, std::vector< std::vector<DMatch> >&matches, float maxDistance, const std::vector<GpuMat>& masks = std::vector<GpuMat>(), bool compactResult = false)
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchCollection(const GpuMat& query, GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance, GpuMat& nMatches, float maxDistance, const std::vector<GpuMat>& masks = std::vector<GpuMat>(), Stream& stream = Stream::Null())
-
- :param query: Query set of descriptors.
-
- :param train: Training set of descriptors. It is not added to train descriptors collection stored in the class object.
-
- :param maxDistance: Distance threshold.
-
- :param mask: Mask specifying permissible matches between the input query and train matrices of descriptors.
-
- :param compactResult: If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
-
- :param stream: Stream for the asynchronous version.
-
-The function returns detected matches in the increasing order by distance.
-
-The methods work only on devices with the compute capability :math:`>=` 1.1.
-
-The third variant of the method stores the results in GPU memory and does not store the points by the distance.
-
-.. seealso:: :ocv:func:`DescriptorMatcher::radiusMatch`
-
-
-
-cuda::BFMatcher_CUDA::radiusMatchDownload
------------------------------------------
-Downloads matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::radiusMatchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::radiusMatchCollection` to vector with :ocv:class:`DMatch`.
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, const GpuMat& nMatches, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance, const GpuMat& nMatches, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
-
-If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
-
-
-
-
-cuda::BFMatcher_CUDA::radiusMatchConvert
-----------------------------------------
-Converts matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::radiusMatchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::radiusMatchCollection` to vector with :ocv:class:`DMatch`.
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchConvert(const Mat& trainIdx, const Mat& distance, const Mat& nMatches, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
-
-.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchConvert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, const Mat& nMatches, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
-
-If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
+++ /dev/null
-*********************************************
-cudafilters. CUDA-accelerated Image Filtering
-*********************************************
-
-.. toctree::
- :maxdepth: 1
-
- filtering
+++ /dev/null
-Image Filtering
-===============
-
-.. highlight:: cpp
-
-Functions and classes described in this section are used to perform various linear or non-linear filtering operations on 2D images.
-
-.. note::
-
- * An example containing all basic morphology operators like erode and dilate can be found at opencv_source_code/samples/gpu/morphology.cpp
-
-
-
-cuda::Filter
-------------
-.. ocv:class:: cuda::Filter
-
-Common interface for all CUDA filters ::
-
- class CV_EXPORTS Filter : public Algorithm
- {
- public:
- virtual void apply(InputArray src, OutputArray dst, Stream& stream = Stream::Null()) = 0;
- };
-
-
-
-cuda::Filter::apply
--------------------
-Applies the specified filter to the image.
-
-.. ocv:function:: void cuda::Filter::apply(InputArray src, OutputArray dst, Stream& stream = Stream::Null()) = 0
-
- :param src: Input image.
-
- :param dst: Output image.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::createBoxFilter
----------------------
-Creates a normalized 2D box filter.
-
-.. ocv:function:: Ptr<Filter> cuda::createBoxFilter(int srcType, int dstType, Size ksize, Point anchor = Point(-1,-1), int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
-
- :param srcType: Input image type. Only ``CV_8UC1`` and ``CV_8UC4`` are supported for now.
-
- :param dstType: Output image type. Only the same type as ``src`` is supported for now.
-
- :param ksize: Kernel size.
-
- :param anchor: Anchor point. The default value ``Point(-1, -1)`` means that the anchor is at the kernel center.
-
- :param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
-
- :param borderVal: Default border value.
-
-.. seealso:: :ocv:func:`boxFilter`
-
-
-
-cuda::createLinearFilter
-------------------------
-Creates a non-separable linear 2D filter.
-
-.. ocv:function:: Ptr<Filter> cuda::createLinearFilter(int srcType, int dstType, InputArray kernel, Point anchor = Point(-1,-1), int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
-
- :param srcType: Input image type. Supports ``CV_8U`` , ``CV_16U`` and ``CV_32F`` one and four channel image.
-
- :param dstType: Output image type. Only the same type as ``src`` is supported for now.
-
- :param kernel: 2D array of filter coefficients.
-
- :param anchor: Anchor point. The default value Point(-1, -1) means that the anchor is at the kernel center.
-
- :param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
-
- :param borderVal: Default border value.
-
-.. seealso:: :ocv:func:`filter2D`
-
-
-
-cuda::createLaplacianFilter
----------------------------
-Creates a Laplacian operator.
-
-.. ocv:function:: Ptr<Filter> cuda::createLaplacianFilter(int srcType, int dstType, int ksize = 1, double scale = 1, int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
-
- :param srcType: Input image type. Supports ``CV_8U`` , ``CV_16U`` and ``CV_32F`` one and four channel image.
-
- :param dstType: Output image type. Only the same type as ``src`` is supported for now.
-
- :param ksize: Aperture size used to compute the second-derivative filters (see :ocv:func:`getDerivKernels`). It must be positive and odd. Only ``ksize`` = 1 and ``ksize`` = 3 are supported.
-
- :param scale: Optional scale factor for the computed Laplacian values. By default, no scaling is applied (see :ocv:func:`getDerivKernels` ).
-
- :param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
-
- :param borderVal: Default border value.
-
-.. seealso:: :ocv:func:`Laplacian`
-
-
-
-cuda::createSeparableLinearFilter
----------------------------------
-Creates a separable linear filter.
-
-.. ocv:function:: Ptr<Filter> cuda::createSeparableLinearFilter(int srcType, int dstType, InputArray rowKernel, InputArray columnKernel, Point anchor = Point(-1,-1), int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
-
- :param srcType: Source array type.
-
- :param dstType: Destination array type.
-
- :param rowKernel: Horizontal filter coefficients. Support kernels with ``size <= 32`` .
-
- :param columnKernel: Vertical filter coefficients. Support kernels with ``size <= 32`` .
-
- :param anchor: Anchor position within the kernel. Negative values mean that anchor is positioned at the aperture center.
-
- :param rowBorderMode: Pixel extrapolation method in the vertical direction For details, see :ocv:func:`borderInterpolate`.
-
- :param columnBorderMode: Pixel extrapolation method in the horizontal direction.
-
-.. seealso:: :ocv:func:`sepFilter2D`
-
-
-
-cuda::createDerivFilter
------------------------
-Creates a generalized Deriv operator.
-
-.. ocv:function:: Ptr<Filter> cuda::createDerivFilter(int srcType, int dstType, int dx, int dy, int ksize, bool normalize = false, double scale = 1, int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
-
- :param srcType: Source image type.
-
- :param dstType: Destination array type.
-
- :param dx: Derivative order in respect of x.
-
- :param dy: Derivative order in respect of y.
-
- :param ksize: Aperture size. See :ocv:func:`getDerivKernels` for details.
-
- :param normalize: Flag indicating whether to normalize (scale down) the filter coefficients or not. See :ocv:func:`getDerivKernels` for details.
-
- :param scale: Optional scale factor for the computed derivative values. By default, no scaling is applied. For details, see :ocv:func:`getDerivKernels` .
-
- :param rowBorderMode: Pixel extrapolation method in the vertical direction. For details, see :ocv:func:`borderInterpolate`.
-
- :param columnBorderMode: Pixel extrapolation method in the horizontal direction.
-
-
-
-cuda::createSobelFilter
------------------------
-Creates a Sobel operator.
-
-.. ocv:function:: Ptr<Filter> cuda::createSobelFilter(int srcType, int dstType, int dx, int dy, int ksize = 3, double scale = 1, int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
-
- :param srcType: Source image type.
-
- :param dstType: Destination array type.
-
- :param dx: Derivative order in respect of x.
-
- :param dy: Derivative order in respect of y.
-
- :param ksize: Size of the extended Sobel kernel. Possible values are 1, 3, 5 or 7.
-
- :param scale: Optional scale factor for the computed derivative values. By default, no scaling is applied. For details, see :ocv:func:`getDerivKernels` .
-
- :param rowBorderMode: Pixel extrapolation method in the vertical direction. For details, see :ocv:func:`borderInterpolate`.
-
- :param columnBorderMode: Pixel extrapolation method in the horizontal direction.
-
-.. seealso:: :ocv:func:`Sobel`
-
-
-
-cuda::createScharrFilter
-------------------------
-Creates a vertical or horizontal Scharr operator.
-
-.. ocv:function:: Ptr<Filter> cuda::createScharrFilter(int srcType, int dstType, int dx, int dy, double scale = 1, int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
-
- :param srcType: Source image type.
-
- :param dstType: Destination array type.
-
- :param dx: Order of the derivative x.
-
- :param dy: Order of the derivative y.
-
- :param scale: Optional scale factor for the computed derivative values. By default, no scaling is applied. See :ocv:func:`getDerivKernels` for details.
-
- :param rowBorderMode: Pixel extrapolation method in the vertical direction. For details, see :ocv:func:`borderInterpolate`.
-
- :param columnBorderMode: Pixel extrapolation method in the horizontal direction.
-
-.. seealso:: :ocv:func:`Scharr`
-
-
-
-cuda::createGaussianFilter
---------------------------
-Creates a Gaussian filter.
-
-.. ocv:function:: Ptr<Filter> cuda::createGaussianFilter(int srcType, int dstType, Size ksize, double sigma1, double sigma2 = 0, int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
-
- :param srcType: Source image type.
-
- :param dstType: Destination array type.
-
- :param ksize: Aperture size. See :ocv:func:`getGaussianKernel` for details.
-
- :param sigma1: Gaussian sigma in the horizontal direction. See :ocv:func:`getGaussianKernel` for details.
-
- :param sigma2: Gaussian sigma in the vertical direction. If 0, then :math:`\texttt{sigma2}\leftarrow\texttt{sigma1}` .
-
- :param rowBorderMode: Pixel extrapolation method in the vertical direction. For details, see :ocv:func:`borderInterpolate`.
-
- :param columnBorderMode: Pixel extrapolation method in the horizontal direction.
-
-.. seealso:: :ocv:func:`GaussianBlur`
-
-
-
-cuda::createMorphologyFilter
-----------------------------
-Creates a 2D morphological filter.
-
-.. ocv:function:: Ptr<Filter> cuda::createMorphologyFilter(int op, int srcType, InputArray kernel, Point anchor = Point(-1, -1), int iterations = 1)
-
- :param op: Type of morphological operation. The following types are possible:
-
- * **MORPH_ERODE** erode
-
- * **MORPH_DILATE** dilate
-
- * **MORPH_OPEN** opening
-
- * **MORPH_CLOSE** closing
-
- * **MORPH_GRADIENT** morphological gradient
-
- * **MORPH_TOPHAT** "top hat"
-
- * **MORPH_BLACKHAT** "black hat"
-
- :param srcType: Input/output image type. Only ``CV_8UC1`` and ``CV_8UC4`` are supported.
-
- :param kernel: 2D 8-bit structuring element for the morphological operation.
-
- :param anchor: Anchor position within the structuring element. Negative values mean that the anchor is at the center.
-
- :param iterations: Number of times erosion and dilation to be applied.
-
-.. seealso:: :ocv:func:`morphologyEx`
-
-
-
-cuda::createBoxMaxFilter
-------------------------
-Creates the maximum filter.
-
-.. ocv:function:: Ptr<Filter> cuda::createBoxMaxFilter(int srcType, Size ksize, Point anchor = Point(-1, -1), int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
-
- :param srcType: Input/output image type. Only ``CV_8UC1`` and ``CV_8UC4`` are supported.
-
- :param ksize: Kernel size.
-
- :param anchor: Anchor point. The default value (-1) means that the anchor is at the kernel center.
-
- :param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
-
- :param borderVal: Default border value.
-
-
-
-cuda::createBoxMinFilter
-------------------------
-Creates the minimum filter.
-
-.. ocv:function:: Ptr<Filter> cuda::createBoxMinFilter(int srcType, Size ksize, Point anchor = Point(-1, -1), int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
-
- :param srcType: Input/output image type. Only ``CV_8UC1`` and ``CV_8UC4`` are supported.
-
- :param ksize: Kernel size.
-
- :param anchor: Anchor point. The default value (-1) means that the anchor is at the kernel center.
-
- :param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
-
- :param borderVal: Default border value.
-
-
-
-cuda::createRowSumFilter
-------------------------
-Creates a horizontal 1D box filter.
-
-.. ocv:function:: Ptr<Filter> cuda::createRowSumFilter(int srcType, int dstType, int ksize, int anchor = -1, int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
-
- :param srcType: Input image type. Only ``CV_8UC1`` type is supported for now.
-
- :param sumType: Output image type. Only ``CV_32FC1`` type is supported for now.
-
- :param ksize: Kernel size.
-
- :param anchor: Anchor point. The default value (-1) means that the anchor is at the kernel center.
-
- :param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
-
- :param borderVal: Default border value.
-
-
-
-cuda::createColumnSumFilter
----------------------------
-Creates a vertical 1D box filter.
-
-.. ocv:function:: Ptr<Filter> cuda::createColumnSumFilter(int srcType, int dstType, int ksize, int anchor = -1, int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
-
- :param srcType: Input image type. Only ``CV_8UC1`` type is supported for now.
-
- :param sumType: Output image type. Only ``CV_32FC1`` type is supported for now.
-
- :param ksize: Kernel size.
-
- :param anchor: Anchor point. The default value (-1) means that the anchor is at the kernel center.
-
- :param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
-
- :param borderVal: Default border value.
+++ /dev/null
-Color space processing
-======================
-
-.. highlight:: cpp
-
-
-
-cuda::cvtColor
---------------
-Converts an image from one color space to another.
-
-.. ocv:function:: void cuda::cvtColor(InputArray src, OutputArray dst, int code, int dcn = 0, Stream& stream = Stream::Null())
-
- :param src: Source image with ``CV_8U`` , ``CV_16U`` , or ``CV_32F`` depth and 1, 3, or 4 channels.
-
- :param dst: Destination image.
-
- :param code: Color space conversion code. For details, see :ocv:func:`cvtColor` .
-
- :param dcn: Number of channels in the destination image. If the parameter is 0, the number of the channels is derived automatically from ``src`` and the ``code`` .
-
- :param stream: Stream for the asynchronous version.
-
-3-channel color spaces (like ``HSV``, ``XYZ``, and so on) can be stored in a 4-channel image for better performance.
-
-.. seealso:: :ocv:func:`cvtColor`
-
-
-
-cuda::demosaicing
------------------
-Converts an image from Bayer pattern to RGB or grayscale.
-
-.. ocv:function:: void cuda::demosaicing(InputArray src, OutputArray dst, int code, int dcn = -1, Stream& stream = Stream::Null())
-
- :param src: Source image (8-bit or 16-bit single channel).
-
- :param dst: Destination image.
-
- :param code: Color space conversion code (see the description below).
-
- :param dcn: Number of channels in the destination image. If the parameter is 0, the number of the channels is derived automatically from ``src`` and the ``code`` .
-
- :param stream: Stream for the asynchronous version.
-
-The function can do the following transformations:
-
-* Demosaicing using bilinear interpolation
-
- * ``COLOR_BayerBG2GRAY`` , ``COLOR_BayerGB2GRAY`` , ``COLOR_BayerRG2GRAY`` , ``COLOR_BayerGR2GRAY``
-
- * ``COLOR_BayerBG2BGR`` , ``COLOR_BayerGB2BGR`` , ``COLOR_BayerRG2BGR`` , ``COLOR_BayerGR2BGR``
-
-* Demosaicing using Malvar-He-Cutler algorithm ([MHT2011]_)
-
- * ``COLOR_BayerBG2GRAY_MHT`` , ``COLOR_BayerGB2GRAY_MHT`` , ``COLOR_BayerRG2GRAY_MHT`` , ``COLOR_BayerGR2GRAY_MHT``
-
- * ``COLOR_BayerBG2BGR_MHT`` , ``COLOR_BayerGB2BGR_MHT`` , ``COLOR_BayerRG2BGR_MHT`` , ``COLOR_BayerGR2BGR_MHT``
-
-.. seealso:: :ocv:func:`cvtColor`
-
-
-
-cuda::swapChannels
-------------------
-Exchanges the color channels of an image in-place.
-
-.. ocv:function:: void cuda::swapChannels(InputOutputArray image, const int dstOrder[4], Stream& stream = Stream::Null())
-
- :param image: Source image. Supports only ``CV_8UC4`` type.
-
- :param dstOrder: Integer array describing how channel values are permutated. The n-th entry of the array contains the number of the channel that is stored in the n-th channel of the output image. E.g. Given an RGBA image, aDstOrder = [3,2,1,0] converts this to ABGR channel order.
-
- :param stream: Stream for the asynchronous version.
-
-The methods support arbitrary permutations of the original channels, including replication.
-
-
-
-cuda::gammaCorrection
----------------------
-Routines for correcting image color gamma.
-
-.. ocv:function:: void cuda::gammaCorrection(InputArray src, OutputArray dst, bool forward = true, Stream& stream = Stream::Null())
-
- :param src: Source image (3- or 4-channel 8 bit).
-
- :param dst: Destination image.
-
- :param forward: ``true`` for forward gamma correction or ``false`` for inverse gamma correction.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::alphaComp
----------------
-Composites two images using alpha opacity values contained in each image.
-
-.. ocv:function:: void cuda::alphaComp(InputArray img1, InputArray img2, OutputArray dst, int alpha_op, Stream& stream = Stream::Null())
-
- :param img1: First image. Supports ``CV_8UC4`` , ``CV_16UC4`` , ``CV_32SC4`` and ``CV_32FC4`` types.
-
- :param img2: Second image. Must have the same size and the same type as ``img1`` .
-
- :param dst: Destination image.
-
- :param alpha_op: Flag specifying the alpha-blending operation:
-
- * **ALPHA_OVER**
- * **ALPHA_IN**
- * **ALPHA_OUT**
- * **ALPHA_ATOP**
- * **ALPHA_XOR**
- * **ALPHA_PLUS**
- * **ALPHA_OVER_PREMUL**
- * **ALPHA_IN_PREMUL**
- * **ALPHA_OUT_PREMUL**
- * **ALPHA_ATOP_PREMUL**
- * **ALPHA_XOR_PREMUL**
- * **ALPHA_PLUS_PREMUL**
- * **ALPHA_PREMUL**
-
- :param stream: Stream for the asynchronous version.
-
-.. note::
-
- * An example demonstrating the use of alphaComp can be found at opencv_source_code/samples/gpu/alpha_comp.cpp
-
-
-.. [MHT2011] Pascal Getreuer, Malvar-He-Cutler Linear Image Demosaicking, Image Processing On Line, 2011
+++ /dev/null
-**********************************************
-cudaimgproc. CUDA-accelerated Image Processing
-**********************************************
-
-.. toctree::
- :maxdepth: 1
-
- color
- histogram
- hough
- feature_detection
- imgproc
+++ /dev/null
-Feature Detection
-=================
-
-.. highlight:: cpp
-
-
-
-cuda::CornernessCriteria
-------------------------
-.. ocv:class:: cuda::CornernessCriteria : public Algorithm
-
-Base class for Cornerness Criteria computation. ::
-
- class CV_EXPORTS CornernessCriteria : public Algorithm
- {
- public:
- virtual void compute(InputArray src, OutputArray dst, Stream& stream = Stream::Null()) = 0;
- };
-
-
-
-cuda::CornernessCriteria::compute
----------------------------------
-Computes the cornerness criteria at each image pixel.
-
-.. ocv:function:: void cuda::CornernessCriteria::compute(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source image.
-
- :param dst: Destination image containing cornerness values. It will have the same size as ``src`` and ``CV_32FC1`` type.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::createHarrisCorner
-------------------------
-Creates implementation for Harris cornerness criteria.
-
-.. ocv:function:: Ptr<CornernessCriteria> cuda::createHarrisCorner(int srcType, int blockSize, int ksize, double k, int borderType = BORDER_REFLECT101)
-
- :param srcType: Input source type. Only ``CV_8UC1`` and ``CV_32FC1`` are supported for now.
-
- :param blockSize: Neighborhood size.
-
- :param ksize: Aperture parameter for the Sobel operator.
-
- :param k: Harris detector free parameter.
-
- :param borderType: Pixel extrapolation method. Only ``BORDER_REFLECT101`` and ``BORDER_REPLICATE`` are supported for now.
-
-.. seealso:: :ocv:func:`cornerHarris`
-
-
-
-cuda::createMinEigenValCorner
------------------------------
-Creates implementation for the minimum eigen value of a 2x2 derivative covariation matrix (the cornerness criteria).
-
-.. ocv:function:: Ptr<CornernessCriteria> cuda::createMinEigenValCorner(int srcType, int blockSize, int ksize, int borderType = BORDER_REFLECT101)
-
- :param srcType: Input source type. Only ``CV_8UC1`` and ``CV_32FC1`` are supported for now.
-
- :param blockSize: Neighborhood size.
-
- :param ksize: Aperture parameter for the Sobel operator.
-
- :param borderType: Pixel extrapolation method. Only ``BORDER_REFLECT101`` and ``BORDER_REPLICATE`` are supported for now.
-
-.. seealso:: :ocv:func:`cornerMinEigenVal`
-
-
-
-cuda::CornersDetector
----------------------
-.. ocv:class:: cuda::CornersDetector : public Algorithm
-
-Base class for Corners Detector. ::
-
- class CV_EXPORTS CornersDetector : public Algorithm
- {
- public:
- virtual void detect(InputArray image, OutputArray corners, InputArray mask = noArray()) = 0;
- };
-
-
-
-cuda::CornersDetector::detect
------------------------------
-Determines strong corners on an image.
-
-.. ocv:function:: void cuda::CornersDetector::detect(InputArray image, OutputArray corners, InputArray mask = noArray())
-
- :param image: Input 8-bit or floating-point 32-bit, single-channel image.
-
- :param corners: Output vector of detected corners (1-row matrix with CV_32FC2 type with corners positions).
-
- :param mask: Optional region of interest. If the image is not empty (it needs to have the type ``CV_8UC1`` and the same size as ``image`` ), it specifies the region in which the corners are detected.
-
-
-
-cuda::createGoodFeaturesToTrackDetector
----------------------------------------
-Creates implementation for :ocv:class:`cuda::CornersDetector` .
-
-.. ocv:function:: Ptr<CornersDetector> cuda::createGoodFeaturesToTrackDetector(int srcType, int maxCorners = 1000, double qualityLevel = 0.01, double minDistance = 0.0, int blockSize = 3, bool useHarrisDetector = false, double harrisK = 0.04)
-
- :param srcType: Input source type. Only ``CV_8UC1`` and ``CV_32FC1`` are supported for now.
-
- :param maxCorners: Maximum number of corners to return. If there are more corners than are found, the strongest of them is returned.
-
- :param qualityLevel: Parameter characterizing the minimal accepted quality of image corners. The parameter value is multiplied by the best corner quality measure, which is the minimal eigenvalue (see :ocv:func:`cornerMinEigenVal` ) or the Harris function response (see :ocv:func:`cornerHarris` ). The corners with the quality measure less than the product are rejected. For example, if the best corner has the quality measure = 1500, and the ``qualityLevel=0.01`` , then all the corners with the quality measure less than 15 are rejected.
-
- :param minDistance: Minimum possible Euclidean distance between the returned corners.
-
- :param blockSize: Size of an average block for computing a derivative covariation matrix over each pixel neighborhood. See :ocv:func:`cornerEigenValsAndVecs` .
-
- :param useHarrisDetector: Parameter indicating whether to use a Harris detector (see :ocv:func:`cornerHarris`) or :ocv:func:`cornerMinEigenVal`.
-
- :param harrisK: Free parameter of the Harris detector.
-
-.. seealso:: :ocv:func:`goodFeaturesToTrack`
+++ /dev/null
-Histogram Calculation
-=====================
-
-.. highlight:: cpp
-
-
-
-cuda::calcHist
---------------
-Calculates histogram for one channel 8-bit image.
-
-.. ocv:function:: void cuda::calcHist(InputArray src, OutputArray hist, Stream& stream = Stream::Null())
-
- :param src: Source image with ``CV_8UC1`` type.
-
- :param hist: Destination histogram with one row, 256 columns, and the ``CV_32SC1`` type.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::equalizeHist
-------------------
-Equalizes the histogram of a grayscale image.
-
-.. ocv:function:: void cuda::equalizeHist(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::equalizeHist(InputArray src, OutputArray dst, InputOutputArray buf, Stream& stream = Stream::Null())
-
- :param src: Source image with ``CV_8UC1`` type.
-
- :param dst: Destination image.
-
- :param buf: Optional buffer to avoid extra memory allocations (for many calls with the same sizes).
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`equalizeHist`
-
-
-
-cuda::CLAHE
------------
-.. ocv:class:: cuda::CLAHE : public cv::CLAHE
-
-Base class for Contrast Limited Adaptive Histogram Equalization. ::
-
- class CV_EXPORTS CLAHE : public cv::CLAHE
- {
- public:
- using cv::CLAHE::apply;
- virtual void apply(InputArray src, OutputArray dst, Stream& stream) = 0;
- };
-
-
-
-cuda::CLAHE::apply
-------------------
-Equalizes the histogram of a grayscale image using Contrast Limited Adaptive Histogram Equalization.
-
-.. ocv:function:: void cuda::CLAHE::apply(InputArray src, OutputArray dst)
-
-.. ocv:function:: void cuda::CLAHE::apply(InputArray src, OutputArray dst, Stream& stream)
-
- :param src: Source image with ``CV_8UC1`` type.
-
- :param dst: Destination image.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::createCLAHE
------------------
-Creates implementation for :ocv:class:`cuda::CLAHE` .
-
-.. ocv:function:: Ptr<cuda::CLAHE> createCLAHE(double clipLimit = 40.0, Size tileGridSize = Size(8, 8))
-
- :param clipLimit: Threshold for contrast limiting.
-
- :param tileGridSize: Size of grid for histogram equalization. Input image will be divided into equally sized rectangular tiles. ``tileGridSize`` defines the number of tiles in row and column.
-
-
-
-
-cuda::evenLevels
-----------------
-Computes levels with even distribution.
-
-.. ocv:function:: void cuda::evenLevels(OutputArray levels, int nLevels, int lowerLevel, int upperLevel)
-
- :param levels: Destination array. ``levels`` has 1 row, ``nLevels`` columns, and the ``CV_32SC1`` type.
-
- :param nLevels: Number of computed levels. ``nLevels`` must be at least 2.
-
- :param lowerLevel: Lower boundary value of the lowest level.
-
- :param upperLevel: Upper boundary value of the greatest level.
-
-
-
-cuda::histEven
---------------
-Calculates a histogram with evenly distributed bins.
-
-.. ocv:function:: void cuda::histEven(InputArray src, OutputArray hist, int histSize, int lowerLevel, int upperLevel, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::histEven(InputArray src, OutputArray hist, InputOutputArray buf, int histSize, int lowerLevel, int upperLevel, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::histEven(InputArray src, GpuMat hist[4], int histSize[4], int lowerLevel[4], int upperLevel[4], Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::histEven(InputArray src, GpuMat hist[4], InputOutputArray buf, int histSize[4], int lowerLevel[4], int upperLevel[4], Stream& stream = Stream::Null())
-
- :param src: Source image. ``CV_8U``, ``CV_16U``, or ``CV_16S`` depth and 1 or 4 channels are supported. For a four-channel image, all channels are processed separately.
-
- :param hist: Destination histogram with one row, ``histSize`` columns, and the ``CV_32S`` type.
-
- :param histSize: Size of the histogram.
-
- :param lowerLevel: Lower boundary of lowest-level bin.
-
- :param upperLevel: Upper boundary of highest-level bin.
-
- :param buf: Optional buffer to avoid extra memory allocations (for many calls with the same sizes).
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::histRange
----------------
-Calculates a histogram with bins determined by the ``levels`` array.
-
-.. ocv:function:: void cuda::histRange(InputArray src, OutputArray hist, InputArray levels, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::histRange(InputArray src, OutputArray hist, InputArray levels, InputOutputArray buf, Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::histRange(InputArray src, GpuMat hist[4], const GpuMat levels[4], Stream& stream = Stream::Null())
-
-.. ocv:function:: void cuda::histRange(InputArray src, GpuMat hist[4], const GpuMat levels[4], InputOutputArray buf, Stream& stream = Stream::Null())
-
- :param src: Source image. ``CV_8U`` , ``CV_16U`` , or ``CV_16S`` depth and 1 or 4 channels are supported. For a four-channel image, all channels are processed separately.
-
- :param hist: Destination histogram with one row, ``(levels.cols-1)`` columns, and the ``CV_32SC1`` type.
-
- :param levels: Number of levels in the histogram.
-
- :param buf: Optional buffer to avoid extra memory allocations (for many calls with the same sizes).
-
- :param stream: Stream for the asynchronous version.
+++ /dev/null
-Hough Transform
-===============
-
-.. highlight:: cpp
-
-
-
-cuda::HoughLinesDetector
-------------------------
-.. ocv:class:: cuda::HoughLinesDetector : public Algorithm
-
-Base class for lines detector algorithm. ::
-
- class CV_EXPORTS HoughLinesDetector : public Algorithm
- {
- public:
- virtual void detect(InputArray src, OutputArray lines) = 0;
- virtual void downloadResults(InputArray d_lines, OutputArray h_lines, OutputArray h_votes = noArray()) = 0;
-
- virtual void setRho(float rho) = 0;
- virtual float getRho() const = 0;
-
- virtual void setTheta(float theta) = 0;
- virtual float getTheta() const = 0;
-
- virtual void setThreshold(int threshold) = 0;
- virtual int getThreshold() const = 0;
-
- virtual void setDoSort(bool doSort) = 0;
- virtual bool getDoSort() const = 0;
-
- virtual void setMaxLines(int maxLines) = 0;
- virtual int getMaxLines() const = 0;
- };
-
-
-
-cuda::HoughLinesDetector::detect
---------------------------------
-Finds lines in a binary image using the classical Hough transform.
-
-.. ocv:function:: void cuda::HoughLinesDetector::detect(InputArray src, OutputArray lines)
-
- :param src: 8-bit, single-channel binary source image.
-
- :param lines: Output vector of lines. Each line is represented by a two-element vector :math:`(\rho, \theta)` . :math:`\rho` is the distance from the coordinate origin :math:`(0,0)` (top-left corner of the image). :math:`\theta` is the line rotation angle in radians ( :math:`0 \sim \textrm{vertical line}, \pi/2 \sim \textrm{horizontal line}` ).
-
-.. seealso:: :ocv:func:`HoughLines`
-
-
-
-cuda::HoughLinesDetector::downloadResults
------------------------------------------
-Downloads results from :ocv:func:`cuda::HoughLinesDetector::detect` to host memory.
-
-.. ocv:function:: void cuda::HoughLinesDetector::downloadResults(InputArray d_lines, OutputArray h_lines, OutputArray h_votes = noArray())
-
- :param d_lines: Result of :ocv:func:`cuda::HoughLinesDetector::detect` .
-
- :param h_lines: Output host array.
-
- :param h_votes: Optional output array for line's votes.
-
-
-
-cuda::createHoughLinesDetector
-------------------------------
-Creates implementation for :ocv:class:`cuda::HoughLinesDetector` .
-
-.. ocv:function:: Ptr<HoughLinesDetector> cuda::createHoughLinesDetector(float rho, float theta, int threshold, bool doSort = false, int maxLines = 4096)
-
- :param rho: Distance resolution of the accumulator in pixels.
-
- :param theta: Angle resolution of the accumulator in radians.
-
- :param threshold: Accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` ).
-
- :param doSort: Performs lines sort by votes.
-
- :param maxLines: Maximum number of output lines.
-
-
-
-cuda::HoughSegmentDetector
---------------------------
-.. ocv:class:: cuda::HoughSegmentDetector : public Algorithm
-
-Base class for line segments detector algorithm. ::
-
- class CV_EXPORTS HoughSegmentDetector : public Algorithm
- {
- public:
- virtual void detect(InputArray src, OutputArray lines) = 0;
-
- virtual void setRho(float rho) = 0;
- virtual float getRho() const = 0;
-
- virtual void setTheta(float theta) = 0;
- virtual float getTheta() const = 0;
-
- virtual void setMinLineLength(int minLineLength) = 0;
- virtual int getMinLineLength() const = 0;
-
- virtual void setMaxLineGap(int maxLineGap) = 0;
- virtual int getMaxLineGap() const = 0;
-
- virtual void setMaxLines(int maxLines) = 0;
- virtual int getMaxLines() const = 0;
- };
-
-.. note::
-
- * An example using the Hough segment detector can be found at opencv_source_code/samples/gpu/houghlines.cpp
-
-
-cuda::HoughSegmentDetector::detect
-----------------------------------
-Finds line segments in a binary image using the probabilistic Hough transform.
-
-.. ocv:function:: void cuda::HoughSegmentDetector::detect(InputArray src, OutputArray lines)
-
- :param src: 8-bit, single-channel binary source image.
-
- :param lines: Output vector of lines. Each line is represented by a 4-element vector :math:`(x_1, y_1, x_2, y_2)` , where :math:`(x_1,y_1)` and :math:`(x_2, y_2)` are the ending points of each detected line segment.
-
-.. seealso:: :ocv:func:`HoughLinesP`
-
-
-
-cuda::createHoughSegmentDetector
---------------------------------
-Creates implementation for :ocv:class:`cuda::HoughSegmentDetector` .
-
-.. ocv:function:: Ptr<HoughSegmentDetector> cuda::createHoughSegmentDetector(float rho, float theta, int minLineLength, int maxLineGap, int maxLines = 4096)
-
- :param rho: Distance resolution of the accumulator in pixels.
-
- :param theta: Angle resolution of the accumulator in radians.
-
- :param minLineLength: Minimum line length. Line segments shorter than that are rejected.
-
- :param maxLineGap: Maximum allowed gap between points on the same line to link them.
-
- :param maxLines: Maximum number of output lines.
-
-
-
-cuda::HoughCirclesDetector
---------------------------
-.. ocv:class:: cuda::HoughCirclesDetector : public Algorithm
-
-Base class for circles detector algorithm. ::
-
- class CV_EXPORTS HoughCirclesDetector : public Algorithm
- {
- public:
- virtual void detect(InputArray src, OutputArray circles) = 0;
-
- virtual void setDp(float dp) = 0;
- virtual float getDp() const = 0;
-
- virtual void setMinDist(float minDist) = 0;
- virtual float getMinDist() const = 0;
-
- virtual void setCannyThreshold(int cannyThreshold) = 0;
- virtual int getCannyThreshold() const = 0;
-
- virtual void setVotesThreshold(int votesThreshold) = 0;
- virtual int getVotesThreshold() const = 0;
-
- virtual void setMinRadius(int minRadius) = 0;
- virtual int getMinRadius() const = 0;
-
- virtual void setMaxRadius(int maxRadius) = 0;
- virtual int getMaxRadius() const = 0;
-
- virtual void setMaxCircles(int maxCircles) = 0;
- virtual int getMaxCircles() const = 0;
- };
-
-
-
-cuda::HoughCirclesDetector::detect
-----------------------------------
-Finds circles in a grayscale image using the Hough transform.
-
-.. ocv:function:: void cuda::HoughCirclesDetector::detect(InputArray src, OutputArray circles)
-
- :param src: 8-bit, single-channel grayscale input image.
-
- :param circles: Output vector of found circles. Each vector is encoded as a 3-element floating-point vector :math:`(x, y, radius)` .
-
-.. seealso:: :ocv:func:`HoughCircles`
-
-
-
-cuda::createHoughCirclesDetector
---------------------------------
-Creates implementation for :ocv:class:`cuda::HoughCirclesDetector` .
-
-.. ocv:function:: Ptr<HoughCirclesDetector> cuda::createHoughCirclesDetector(float dp, float minDist, int cannyThreshold, int votesThreshold, int minRadius, int maxRadius, int maxCircles = 4096)
-
- :param dp: Inverse ratio of the accumulator resolution to the image resolution. For example, if ``dp=1`` , the accumulator has the same resolution as the input image. If ``dp=2`` , the accumulator has half as big width and height.
-
- :param minDist: Minimum distance between the centers of the detected circles. If the parameter is too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed.
-
- :param cannyThreshold: The higher threshold of the two passed to Canny edge detector (the lower one is twice smaller).
-
- :param votesThreshold: The accumulator threshold for the circle centers at the detection stage. The smaller it is, the more false circles may be detected.
-
- :param minRadius: Minimum circle radius.
-
- :param maxRadius: Maximum circle radius.
-
- :param maxCircles: Maximum number of output circles.
-
-
-
-cuda::createGeneralizedHoughBallard
------------------------------------
-Creates implementation for generalized hough transform from [Ballard1981]_ .
-
-.. ocv:function:: Ptr<GeneralizedHoughBallard> cuda::createGeneralizedHoughBallard()
-
-
-
-cuda::createGeneralizedHoughGuil
---------------------------------
-Creates implementation for generalized hough transform from [Guil1999]_ .
-
-.. ocv:function:: Ptr<GeneralizedHoughGuil> cuda::createGeneralizedHoughGuil()
-
-
-
-.. [Ballard1981] Ballard, D.H. (1981). Generalizing the Hough transform to detect arbitrary shapes. Pattern Recognition 13 (2): 111-122.
-.. [Guil1999] Guil, N., González-Linares, J.M. and Zapata, E.L. (1999). Bidimensional shape detection using an invariant approach. Pattern Recognition 32 (6): 1025-1038.
+++ /dev/null
-Image Processing
-================
-
-.. highlight:: cpp
-
-
-
-cuda::CannyEdgeDetector
------------------------
-.. ocv:class:: cuda::CannyEdgeDetector : public Algorithm
-
-Base class for Canny Edge Detector. ::
-
- class CV_EXPORTS CannyEdgeDetector : public Algorithm
- {
- public:
- virtual void detect(InputArray image, OutputArray edges) = 0;
- virtual void detect(InputArray dx, InputArray dy, OutputArray edges) = 0;
-
- virtual void setLowThreshold(double low_thresh) = 0;
- virtual double getLowThreshold() const = 0;
-
- virtual void setHighThreshold(double high_thresh) = 0;
- virtual double getHighThreshold() const = 0;
-
- virtual void setAppertureSize(int apperture_size) = 0;
- virtual int getAppertureSize() const = 0;
-
- virtual void setL2Gradient(bool L2gradient) = 0;
- virtual bool getL2Gradient() const = 0;
- };
-
-
-
-cuda::CannyEdgeDetector::detect
--------------------------------
-Finds edges in an image using the [Canny86]_ algorithm.
-
-.. ocv:function:: void cuda::CannyEdgeDetector::detect(InputArray image, OutputArray edges)
-
-.. ocv:function:: void cuda::CannyEdgeDetector::detect(InputArray dx, InputArray dy, OutputArray edges)
-
- :param image: Single-channel 8-bit input image.
-
- :param dx: First derivative of image in the vertical direction. Support only ``CV_32S`` type.
-
- :param dy: First derivative of image in the horizontal direction. Support only ``CV_32S`` type.
-
- :param edges: Output edge map. It has the same size and type as ``image`` .
-
-
-
-cuda::createCannyEdgeDetector
------------------------------
-Creates implementation for :ocv:class:`cuda::CannyEdgeDetector` .
-
-.. ocv:function:: Ptr<CannyEdgeDetector> cuda::createCannyEdgeDetector(double low_thresh, double high_thresh, int apperture_size = 3, bool L2gradient = false)
-
- :param low_thresh: First threshold for the hysteresis procedure.
-
- :param high_thresh: Second threshold for the hysteresis procedure.
-
- :param apperture_size: Aperture size for the :ocv:func:`Sobel` operator.
-
- :param L2gradient: Flag indicating whether a more accurate :math:`L_2` norm :math:`=\sqrt{(dI/dx)^2 + (dI/dy)^2}` should be used to compute the image gradient magnitude ( ``L2gradient=true`` ), or a faster default :math:`L_1` norm :math:`=|dI/dx|+|dI/dy|` is enough ( ``L2gradient=false`` ).
-
-
-
-cuda::meanShiftFiltering
-------------------------
-Performs mean-shift filtering for each point of the source image.
-
-.. ocv:function:: void cuda::meanShiftFiltering(InputArray src, OutputArray dst, int sp, int sr, TermCriteria criteria = TermCriteria(TermCriteria::MAX_ITER + TermCriteria::EPS, 5, 1), Stream& stream = Stream::Null())
-
- :param src: Source image. Only ``CV_8UC4`` images are supported for now.
-
- :param dst: Destination image containing the color of mapped points. It has the same size and type as ``src`` .
-
- :param sp: Spatial window radius.
-
- :param sr: Color window radius.
-
- :param criteria: Termination criteria. See :ocv:class:`TermCriteria`.
-
-It maps each point of the source image into another point. As a result, you have a new color and new position of each point.
-
-
-
-cuda::meanShiftProc
--------------------
-Performs a mean-shift procedure and stores information about processed points (their colors and positions) in two images.
-
-.. ocv:function:: void cuda::meanShiftProc(InputArray src, OutputArray dstr, OutputArray dstsp, int sp, int sr, TermCriteria criteria = TermCriteria(TermCriteria::MAX_ITER + TermCriteria::EPS, 5, 1), Stream& stream = Stream::Null())
-
- :param src: Source image. Only ``CV_8UC4`` images are supported for now.
-
- :param dstr: Destination image containing the color of mapped points. The size and type is the same as ``src`` .
-
- :param dstsp: Destination image containing the position of mapped points. The size is the same as ``src`` size. The type is ``CV_16SC2`` .
-
- :param sp: Spatial window radius.
-
- :param sr: Color window radius.
-
- :param criteria: Termination criteria. See :ocv:class:`TermCriteria`.
-
-.. seealso:: :ocv:func:`cuda::meanShiftFiltering`
-
-
-
-cuda::meanShiftSegmentation
----------------------------
-Performs a mean-shift segmentation of the source image and eliminates small segments.
-
-.. ocv:function:: void cuda::meanShiftSegmentation(InputArray src, OutputArray dst, int sp, int sr, int minsize, TermCriteria criteria = TermCriteria(TermCriteria::MAX_ITER + TermCriteria::EPS, 5, 1))
-
- :param src: Source image. Only ``CV_8UC4`` images are supported for now.
-
- :param dst: Segmented image with the same size and type as ``src`` (host memory).
-
- :param sp: Spatial window radius.
-
- :param sr: Color window radius.
-
- :param minsize: Minimum segment size. Smaller segments are merged.
-
- :param criteria: Termination criteria. See :ocv:class:`TermCriteria`.
-
-
-
-cuda::TemplateMatching
-----------------------
-.. ocv:class:: cuda::TemplateMatching : public Algorithm
-
-Base class for Template Matching. ::
-
- class CV_EXPORTS TemplateMatching : public Algorithm
- {
- public:
- virtual void match(InputArray image, InputArray templ, OutputArray result, Stream& stream = Stream::Null()) = 0;
- };
-
-
-
-cuda::TemplateMatching::match
------------------------------
-Computes a proximity map for a raster template and an image where the template is searched for.
-
-.. ocv:function:: void cuda::TemplateMatching::match(InputArray image, InputArray templ, OutputArray result, Stream& stream = Stream::Null())
-
- :param image: Source image.
-
- :param templ: Template image with the size and type the same as ``image`` .
-
- :param result: Map containing comparison results ( ``CV_32FC1`` ). If ``image`` is *W x H* and ``templ`` is *w x h*, then ``result`` must be *W-w+1 x H-h+1*.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::createTemplateMatching
-----------------------------
-Creates implementation for :ocv:class:`cuda::TemplateMatching` .
-
-.. ocv:function:: Ptr<TemplateMatching> cuda::createTemplateMatching(int srcType, int method, Size user_block_size = Size())
-
- :param srcType: Input source type. ``CV_32F`` and ``CV_8U`` depth images (1..4 channels) are supported for now.
-
- :param method: Specifies the way to compare the template with the image.
-
- :param user_block_size: You can use field `user_block_size` to set specific block size. If you leave its default value `Size(0,0)` then automatic estimation of block size will be used (which is optimized for speed). By varying `user_block_size` you can reduce memory requirements at the cost of speed.
-
-The following methods are supported for the ``CV_8U`` depth images for now:
-
- * ``CV_TM_SQDIFF``
- * ``CV_TM_SQDIFF_NORMED``
- * ``CV_TM_CCORR``
- * ``CV_TM_CCORR_NORMED``
- * ``CV_TM_CCOEFF``
- * ``CV_TM_CCOEFF_NORMED``
-
-The following methods are supported for the ``CV_32F`` images for now:
-
- * ``CV_TM_SQDIFF``
- * ``CV_TM_CCORR``
-
-.. seealso:: :ocv:func:`matchTemplate`
-
-
-
-cuda::bilateralFilter
----------------------
-Performs bilateral filtering of passed image
-
-.. ocv:function:: void cuda::bilateralFilter(InputArray src, OutputArray dst, int kernel_size, float sigma_color, float sigma_spatial, int borderMode=BORDER_DEFAULT, Stream& stream=Stream::Null())
-
- :param src: Source image. Supports only (channles != 2 && depth() != CV_8S && depth() != CV_32S && depth() != CV_64F).
-
- :param dst: Destination imagwe.
-
- :param kernel_size: Kernel window size.
-
- :param sigma_color: Filter sigma in the color space.
-
- :param sigma_spatial: Filter sigma in the coordinate space.
-
- :param borderMode: Border type. See :ocv:func:`borderInterpolate` for details. ``BORDER_REFLECT101`` , ``BORDER_REPLICATE`` , ``BORDER_CONSTANT`` , ``BORDER_REFLECT`` and ``BORDER_WRAP`` are supported for now.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`bilateralFilter`
-
-
-
-cuda::blendLinear
------------------
-Performs linear blending of two images.
-
-.. ocv:function:: void cuda::blendLinear(InputArray img1, InputArray img2, InputArray weights1, InputArray weights2, OutputArray result, Stream& stream = Stream::Null())
-
- :param img1: First image. Supports only ``CV_8U`` and ``CV_32F`` depth.
-
- :param img2: Second image. Must have the same size and the same type as ``img1`` .
-
- :param weights1: Weights for first image. Must have tha same size as ``img1`` . Supports only ``CV_32F`` type.
-
- :param weights2: Weights for second image. Must have tha same size as ``img2`` . Supports only ``CV_32F`` type.
-
- :param result: Destination image.
-
- :param stream: Stream for the asynchronous version.
+++ /dev/null
-******************************************
-cudaoptflow. CUDA-accelerated Optical Flow
-******************************************
-
-.. toctree::
- :maxdepth: 1
-
- optflow
+++ /dev/null
-Optical Flow
-============
-
-.. highlight:: cpp
-
-.. note::
-
- * A general optical flow example can be found at opencv_source_code/samples/gpu/optical_flow.cpp
- * A general optical flow example using the Nvidia API can be found at opencv_source_code/samples/gpu/opticalflow_nvidia_api.cpp
-
-
-
-cuda::BroxOpticalFlow
----------------------
-.. ocv:class:: cuda::BroxOpticalFlow
-
-Class computing the optical flow for two images using Brox et al Optical Flow algorithm ([Brox2004]_). ::
-
- class BroxOpticalFlow
- {
- public:
- BroxOpticalFlow(float alpha_, float gamma_, float scale_factor_, int inner_iterations_, int outer_iterations_, int solver_iterations_);
-
- //! Compute optical flow
- //! frame0 - source frame (supports only CV_32FC1 type)
- //! frame1 - frame to track (with the same size and type as frame0)
- //! u - flow horizontal component (along x axis)
- //! v - flow vertical component (along y axis)
- void operator ()(const GpuMat& frame0, const GpuMat& frame1, GpuMat& u, GpuMat& v, Stream& stream = Stream::Null());
-
- //! flow smoothness
- float alpha;
-
- //! gradient constancy importance
- float gamma;
-
- //! pyramid scale factor
- float scale_factor;
-
- //! number of lagged non-linearity iterations (inner loop)
- int inner_iterations;
-
- //! number of warping iterations (number of pyramid levels)
- int outer_iterations;
-
- //! number of linear system solver iterations
- int solver_iterations;
-
- GpuMat buf;
- };
-
-.. note::
-
- * An example illustrating the Brox et al optical flow algorithm can be found at opencv_source_code/samples/gpu/brox_optical_flow.cpp
-
-
-
-cuda::FarnebackOpticalFlow
---------------------------
-.. ocv:class:: cuda::FarnebackOpticalFlow
-
-Class computing a dense optical flow using the Gunnar Farneback’s algorithm. ::
-
- class CV_EXPORTS FarnebackOpticalFlow
- {
- public:
- FarnebackOpticalFlow()
- {
- numLevels = 5;
- pyrScale = 0.5;
- fastPyramids = false;
- winSize = 13;
- numIters = 10;
- polyN = 5;
- polySigma = 1.1;
- flags = 0;
- }
-
- int numLevels;
- double pyrScale;
- bool fastPyramids;
- int winSize;
- int numIters;
- int polyN;
- double polySigma;
- int flags;
-
- void operator ()(const GpuMat &frame0, const GpuMat &frame1, GpuMat &flowx, GpuMat &flowy, Stream &s = Stream::Null());
-
- void releaseMemory();
-
- private:
- /* hidden */
- };
-
-
-
-cuda::FarnebackOpticalFlow::operator ()
----------------------------------------
-Computes a dense optical flow using the Gunnar Farneback’s algorithm.
-
-.. ocv:function:: void cuda::FarnebackOpticalFlow::operator ()(const GpuMat &frame0, const GpuMat &frame1, GpuMat &flowx, GpuMat &flowy, Stream &s = Stream::Null())
-
- :param frame0: First 8-bit gray-scale input image
- :param frame1: Second 8-bit gray-scale input image
- :param flowx: Flow horizontal component
- :param flowy: Flow vertical component
- :param s: Stream
-
-.. seealso:: :ocv:func:`calcOpticalFlowFarneback`
-
-
-
-cuda::FarnebackOpticalFlow::releaseMemory
------------------------------------------
-Releases unused auxiliary memory buffers.
-
-.. ocv:function:: void cuda::FarnebackOpticalFlow::releaseMemory()
-
-
-
-cuda::PyrLKOpticalFlow
-----------------------
-.. ocv:class:: cuda::PyrLKOpticalFlow
-
-Class used for calculating an optical flow. ::
-
- class PyrLKOpticalFlow
- {
- public:
- PyrLKOpticalFlow();
-
- void sparse(const GpuMat& prevImg, const GpuMat& nextImg, const GpuMat& prevPts, GpuMat& nextPts,
- GpuMat& status, GpuMat* err = 0);
-
- void dense(const GpuMat& prevImg, const GpuMat& nextImg, GpuMat& u, GpuMat& v, GpuMat* err = 0);
-
- Size winSize;
- int maxLevel;
- int iters;
- bool useInitialFlow;
-
- void releaseMemory();
- };
-
-The class can calculate an optical flow for a sparse feature set or dense optical flow using the iterative Lucas-Kanade method with pyramids.
-
-.. seealso:: :ocv:func:`calcOpticalFlowPyrLK`
-
-.. note::
-
- * An example of the Lucas Kanade optical flow algorithm can be found at opencv_source_code/samples/gpu/pyrlk_optical_flow.cpp
-
-
-
-cuda::PyrLKOpticalFlow::sparse
-------------------------------
-Calculate an optical flow for a sparse feature set.
-
-.. ocv:function:: void cuda::PyrLKOpticalFlow::sparse(const GpuMat& prevImg, const GpuMat& nextImg, const GpuMat& prevPts, GpuMat& nextPts, GpuMat& status, GpuMat* err = 0)
-
- :param prevImg: First 8-bit input image (supports both grayscale and color images).
-
- :param nextImg: Second input image of the same size and the same type as ``prevImg`` .
-
- :param prevPts: Vector of 2D points for which the flow needs to be found. It must be one row matrix with CV_32FC2 type.
-
- :param nextPts: Output vector of 2D points (with single-precision floating-point coordinates) containing the calculated new positions of input features in the second image. When ``useInitialFlow`` is true, the vector must have the same size as in the input.
-
- :param status: Output status vector (CV_8UC1 type). Each element of the vector is set to 1 if the flow for the corresponding features has been found. Otherwise, it is set to 0.
-
- :param err: Output vector (CV_32FC1 type) that contains the difference between patches around the original and moved points or min eigen value if ``getMinEigenVals`` is checked. It can be NULL, if not needed.
-
-.. seealso:: :ocv:func:`calcOpticalFlowPyrLK`
-
-
-
-cuda::PyrLKOpticalFlow::dense
------------------------------
-Calculate dense optical flow.
-
-.. ocv:function:: void cuda::PyrLKOpticalFlow::dense(const GpuMat& prevImg, const GpuMat& nextImg, GpuMat& u, GpuMat& v, GpuMat* err = 0)
-
- :param prevImg: First 8-bit grayscale input image.
-
- :param nextImg: Second input image of the same size and the same type as ``prevImg`` .
-
- :param u: Horizontal component of the optical flow of the same size as input images, 32-bit floating-point, single-channel
-
- :param v: Vertical component of the optical flow of the same size as input images, 32-bit floating-point, single-channel
-
- :param err: Output vector (CV_32FC1 type) that contains the difference between patches around the original and moved points or min eigen value if ``getMinEigenVals`` is checked. It can be NULL, if not needed.
-
-
-
-cuda::PyrLKOpticalFlow::releaseMemory
--------------------------------------
-Releases inner buffers memory.
-
-.. ocv:function:: void cuda::PyrLKOpticalFlow::releaseMemory()
-
-
-
-cuda::interpolateFrames
------------------------
-Interpolates frames (images) using provided optical flow (displacement field).
-
-.. ocv:function:: void cuda::interpolateFrames(const GpuMat& frame0, const GpuMat& frame1, const GpuMat& fu, const GpuMat& fv, const GpuMat& bu, const GpuMat& bv, float pos, GpuMat& newFrame, GpuMat& buf, Stream& stream = Stream::Null())
-
- :param frame0: First frame (32-bit floating point images, single channel).
-
- :param frame1: Second frame. Must have the same type and size as ``frame0`` .
-
- :param fu: Forward horizontal displacement.
-
- :param fv: Forward vertical displacement.
-
- :param bu: Backward horizontal displacement.
-
- :param bv: Backward vertical displacement.
-
- :param pos: New frame position.
-
- :param newFrame: Output image.
-
- :param buf: Temporary buffer, will have width x 6*height size, CV_32FC1 type and contain 6 GpuMat: occlusion masks for first frame, occlusion masks for second, interpolated forward horizontal flow, interpolated forward vertical flow, interpolated backward horizontal flow, interpolated backward vertical flow.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-.. [Brox2004] T. Brox, A. Bruhn, N. Papenberg, J. Weickert. *High accuracy optical flow estimation based on a theory for warping*. ECCV 2004.
+++ /dev/null
-**************************************************
-cudastereo. CUDA-accelerated Stereo Correspondence
-**************************************************
-
-.. toctree::
- :maxdepth: 1
-
- stereo
+++ /dev/null
-Stereo Correspondence
-=====================
-
-.. highlight:: cpp
-
-.. note::
-
- * A basic stereo matching example can be found at opencv_source_code/samples/gpu/stereo_match.cpp
- * A stereo matching example using several GPU's can be found at opencv_source_code/samples/gpu/stereo_multi.cpp
- * A stereo matching example using several GPU's and driver API can be found at opencv_source_code/samples/gpu/driver_api_stereo_multi.cpp
-
-
-
-cuda::StereoBM
---------------
-.. ocv:class:: cuda::StereoBM : public cv::StereoBM
-
-Class computing stereo correspondence (disparity map) using the block matching algorithm. ::
-
-.. seealso:: :ocv:class:`StereoBM`
-
-
-
-cuda::createStereoBM
---------------------
-Creates StereoBM object.
-
-.. ocv:function:: Ptr<cuda::StereoBM> cuda::createStereoBM(int numDisparities = 64, int blockSize = 19)
-
- :param numDisparities: the disparity search range. For each pixel algorithm will find the best disparity from 0 (default minimum disparity) to ``numDisparities``. The search range can then be shifted by changing the minimum disparity.
-
- :param blockSize: the linear size of the blocks compared by the algorithm. The size should be odd (as the block is centered at the current pixel). Larger block size implies smoother, though less accurate disparity map. Smaller block size gives more detailed disparity map, but there is higher chance for algorithm to find a wrong correspondence.
-
-
-
-cuda::StereoBeliefPropagation
------------------------------
-.. ocv:class:: cuda::StereoBeliefPropagation : public cv::StereoMatcher
-
-Class computing stereo correspondence using the belief propagation algorithm. ::
-
- class CV_EXPORTS StereoBeliefPropagation : public cv::StereoMatcher
- {
- public:
- using cv::StereoMatcher::compute;
-
- virtual void compute(InputArray left, InputArray right, OutputArray disparity, Stream& stream) = 0;
-
- //! version for user specified data term
- virtual void compute(InputArray data, OutputArray disparity, Stream& stream = Stream::Null()) = 0;
-
- //! number of BP iterations on each level
- virtual int getNumIters() const = 0;
- virtual void setNumIters(int iters) = 0;
-
- //! number of levels
- virtual int getNumLevels() const = 0;
- virtual void setNumLevels(int levels) = 0;
-
- //! truncation of data cost
- virtual double getMaxDataTerm() const = 0;
- virtual void setMaxDataTerm(double max_data_term) = 0;
-
- //! data weight
- virtual double getDataWeight() const = 0;
- virtual void setDataWeight(double data_weight) = 0;
-
- //! truncation of discontinuity cost
- virtual double getMaxDiscTerm() const = 0;
- virtual void setMaxDiscTerm(double max_disc_term) = 0;
-
- //! discontinuity single jump
- virtual double getDiscSingleJump() const = 0;
- virtual void setDiscSingleJump(double disc_single_jump) = 0;
-
- virtual int getMsgType() const = 0;
- virtual void setMsgType(int msg_type) = 0;
-
- static void estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels);
- };
-
-
-The class implements algorithm described in [Felzenszwalb2006]_ . It can compute own data cost (using a truncated linear model) or use a user-provided data cost.
-
-.. note::
-
- ``StereoBeliefPropagation`` requires a lot of memory for message storage:
-
- .. math::
-
- width \_ step \cdot height \cdot ndisp \cdot 4 \cdot (1 + 0.25)
-
- and for data cost storage:
-
- .. math::
-
- width\_step \cdot height \cdot ndisp \cdot (1 + 0.25 + 0.0625 + \dotsm + \frac{1}{4^{levels}})
-
- ``width_step`` is the number of bytes in a line including padding.
-
-``StereoBeliefPropagation`` uses a truncated linear model for the data cost and discontinuity terms:
-
-.. math::
-
- DataCost = data \_ weight \cdot \min ( \lvert Img_Left(x,y)-Img_Right(x-d,y) \rvert , max \_ data \_ term)
-
-.. math::
-
- DiscTerm = \min (disc \_ single \_ jump \cdot \lvert f_1-f_2 \rvert , max \_ disc \_ term)
-
-For more details, see [Felzenszwalb2006]_.
-
-By default, ``StereoBeliefPropagation`` uses floating-point arithmetics and the ``CV_32FC1`` type for messages. But it can also use fixed-point arithmetics and the ``CV_16SC1`` message type for better performance. To avoid an overflow in this case, the parameters must satisfy the following requirement:
-
-.. math::
-
- 10 \cdot 2^{levels-1} \cdot max \_ data \_ term < SHRT \_ MAX
-
-.. seealso:: :ocv:class:`StereoMatcher`
-
-
-
-cuda::createStereoBeliefPropagation
------------------------------------
-Creates StereoBeliefPropagation object.
-
-.. ocv:function:: Ptr<cuda::StereoBeliefPropagation> cuda::createStereoBeliefPropagation(int ndisp = 64, int iters = 5, int levels = 5, int msg_type = CV_32F)
-
- :param ndisp: Number of disparities.
-
- :param iters: Number of BP iterations on each level.
-
- :param levels: Number of levels.
-
- :param msg_type: Type for messages. ``CV_16SC1`` and ``CV_32FC1`` types are supported.
-
-
-
-cuda::StereoBeliefPropagation::estimateRecommendedParams
---------------------------------------------------------
-Uses a heuristic method to compute the recommended parameters ( ``ndisp``, ``iters`` and ``levels`` ) for the specified image size ( ``width`` and ``height`` ).
-
-.. ocv:function:: void cuda::StereoBeliefPropagation::estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels)
-
-
-
-cuda::StereoBeliefPropagation::compute
---------------------------------------
-Enables the stereo correspondence operator that finds the disparity for the specified data cost.
-
-.. ocv:function:: void cuda::StereoBeliefPropagation::compute(InputArray data, OutputArray disparity, Stream& stream = Stream::Null())
-
- :param data: User-specified data cost, a matrix of ``msg_type`` type and ``Size(<image columns>*ndisp, <image rows>)`` size.
-
- :param disparity: Output disparity map. If ``disparity`` is empty, the output type is ``CV_16SC1`` . Otherwise, the type is retained.
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::StereoConstantSpaceBP
----------------------------
-.. ocv:class:: cuda::StereoConstantSpaceBP : public cuda::StereoBeliefPropagation
-
-Class computing stereo correspondence using the constant space belief propagation algorithm. ::
-
- class CV_EXPORTS StereoConstantSpaceBP : public cuda::StereoBeliefPropagation
- {
- public:
- //! number of active disparity on the first level
- virtual int getNrPlane() const = 0;
- virtual void setNrPlane(int nr_plane) = 0;
-
- virtual bool getUseLocalInitDataCost() const = 0;
- virtual void setUseLocalInitDataCost(bool use_local_init_data_cost) = 0;
-
- static void estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels, int& nr_plane);
- };
-
-
-The class implements algorithm described in [Yang2010]_. ``StereoConstantSpaceBP`` supports both local minimum and global minimum data cost initialization algorithms. For more details, see the paper mentioned above. By default, a local algorithm is used. To enable a global algorithm, set ``use_local_init_data_cost`` to ``false`` .
-
-``StereoConstantSpaceBP`` uses a truncated linear model for the data cost and discontinuity terms:
-
-.. math::
-
- DataCost = data \_ weight \cdot \min ( \lvert I_2-I_1 \rvert , max \_ data \_ term)
-
-.. math::
-
- DiscTerm = \min (disc \_ single \_ jump \cdot \lvert f_1-f_2 \rvert , max \_ disc \_ term)
-
-For more details, see [Yang2010]_.
-
-By default, ``StereoConstantSpaceBP`` uses floating-point arithmetics and the ``CV_32FC1`` type for messages. But it can also use fixed-point arithmetics and the ``CV_16SC1`` message type for better performance. To avoid an overflow in this case, the parameters must satisfy the following requirement:
-
-.. math::
-
- 10 \cdot 2^{levels-1} \cdot max \_ data \_ term < SHRT \_ MAX
-
-
-
-cuda::createStereoConstantSpaceBP
----------------------------------
-Creates StereoConstantSpaceBP object.
-
-.. ocv:function:: Ptr<cuda::StereoConstantSpaceBP> cuda::createStereoConstantSpaceBP(int ndisp = 128, int iters = 8, int levels = 4, int nr_plane = 4, int msg_type = CV_32F)
-
- :param ndisp: Number of disparities.
-
- :param iters: Number of BP iterations on each level.
-
- :param levels: Number of levels.
-
- :param nr_plane: Number of disparity levels on the first level.
-
- :param msg_type: Type for messages. ``CV_16SC1`` and ``CV_32FC1`` types are supported.
-
-
-
-cuda::StereoConstantSpaceBP::estimateRecommendedParams
-------------------------------------------------------
-Uses a heuristic method to compute parameters (ndisp, iters, levelsand nrplane) for the specified image size (widthand height).
-
-.. ocv:function:: void cuda::StereoConstantSpaceBP::estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels, int& nr_plane)
-
-
-
-cuda::DisparityBilateralFilter
-------------------------------
-.. ocv:class:: cuda::DisparityBilateralFilter : public cv::Algorithm
-
-Class refining a disparity map using joint bilateral filtering. ::
-
- class CV_EXPORTS DisparityBilateralFilter : public cv::Algorithm
- {
- public:
- //! the disparity map refinement operator. Refine disparity map using joint bilateral filtering given a single color image.
- //! disparity must have CV_8U or CV_16S type, image must have CV_8UC1 or CV_8UC3 type.
- virtual void apply(InputArray disparity, InputArray image, OutputArray dst, Stream& stream = Stream::Null()) = 0;
-
- virtual int getNumDisparities() const = 0;
- virtual void setNumDisparities(int numDisparities) = 0;
-
- virtual int getRadius() const = 0;
- virtual void setRadius(int radius) = 0;
-
- virtual int getNumIters() const = 0;
- virtual void setNumIters(int iters) = 0;
-
- //! truncation of data continuity
- virtual double getEdgeThreshold() const = 0;
- virtual void setEdgeThreshold(double edge_threshold) = 0;
-
- //! truncation of disparity continuity
- virtual double getMaxDiscThreshold() const = 0;
- virtual void setMaxDiscThreshold(double max_disc_threshold) = 0;
-
- //! filter range sigma
- virtual double getSigmaRange() const = 0;
- virtual void setSigmaRange(double sigma_range) = 0;
- };
-
-
-The class implements [Yang2010]_ algorithm.
-
-
-
-cuda::createDisparityBilateralFilter
-------------------------------------
-Creates DisparityBilateralFilter object.
-
-.. ocv:function:: Ptr<cuda::DisparityBilateralFilter> cuda::createDisparityBilateralFilter(int ndisp = 64, int radius = 3, int iters = 1)
-
- :param ndisp: Number of disparities.
-
- :param radius: Filter radius.
-
- :param iters: Number of iterations.
-
-
-
-cuda::DisparityBilateralFilter::apply
--------------------------------------
-Refines a disparity map using joint bilateral filtering.
-
-.. ocv:function:: void cuda::DisparityBilateralFilter::apply(InputArray disparity, InputArray image, OutputArray dst, Stream& stream = Stream::Null())
-
- :param disparity: Input disparity map. ``CV_8UC1`` and ``CV_16SC1`` types are supported.
-
- :param image: Input image. ``CV_8UC1`` and ``CV_8UC3`` types are supported.
-
- :param dst: Destination disparity map. It has the same size and type as ``disparity`` .
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::reprojectImageTo3D
-------------------------
-Reprojects a disparity image to 3D space.
-
-.. ocv:function:: void cuda::reprojectImageTo3D(InputArray disp, OutputArray xyzw, InputArray Q, int dst_cn = 4, Stream& stream = Stream::Null())
-
- :param disp: Input disparity image. ``CV_8U`` and ``CV_16S`` types are supported.
-
- :param xyzw: Output 3- or 4-channel floating-point image of the same size as ``disp`` . Each element of ``xyzw(x,y)`` contains 3D coordinates ``(x,y,z)`` or ``(x,y,z,1)`` of the point ``(x,y)`` , computed from the disparity map.
-
- :param Q: :math:`4 \times 4` perspective transformation matrix that can be obtained via :ocv:func:`stereoRectify` .
-
- :param dst_cn: The number of channels for output image. Can be 3 or 4.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`reprojectImageTo3D`
-
-
-
-cuda::drawColorDisp
--------------------
-Colors a disparity image.
-
-.. ocv:function:: void cuda::drawColorDisp(InputArray src_disp, OutputArray dst_disp, int ndisp, Stream& stream = Stream::Null())
-
- :param src_disp: Source disparity image. ``CV_8UC1`` and ``CV_16SC1`` types are supported.
-
- :param dst_disp: Output disparity image. It has the same size as ``src_disp`` . The type is ``CV_8UC4`` in ``BGRA`` format (alpha = 255).
-
- :param ndisp: Number of disparities.
-
- :param stream: Stream for the asynchronous version.
-
-This function draws a colored disparity map by converting disparity values from ``[0..ndisp)`` interval first to ``HSV`` color space (where different disparity values correspond to different hues) and then converting the pixels to ``RGB`` for visualization.
-
-
-
-.. [Felzenszwalb2006] Pedro F. Felzenszwalb algorithm [Pedro F. Felzenszwalb and Daniel P. Huttenlocher. *Efficient belief propagation for early vision*. International Journal of Computer Vision, 70(1), October 2006
-.. [Yang2010] Q. Yang, L. Wang, and N. Ahuja. *A constant-space belief propagation algorithm for stereo matching*. In CVPR, 2010.
+++ /dev/null
-*******************************************
-cudawarping. CUDA-accelerated Image Warping
-*******************************************
-
-.. toctree::
- :maxdepth: 1
-
- warping
+++ /dev/null
-Image Warping
-=============
-
-.. highlight:: cpp
-
-
-
-cuda::remap
------------
-Applies a generic geometrical transformation to an image.
-
-.. ocv:function:: void cuda::remap(InputArray src, OutputArray dst, InputArray xmap, InputArray ymap, int interpolation, int borderMode = BORDER_CONSTANT, Scalar borderValue = Scalar(), Stream& stream = Stream::Null())
-
- :param src: Source image.
-
- :param dst: Destination image with the size the same as ``xmap`` and the type the same as ``src`` .
-
- :param xmap: X values. Only ``CV_32FC1`` type is supported.
-
- :param ymap: Y values. Only ``CV_32FC1`` type is supported.
-
- :param interpolation: Interpolation method (see :ocv:func:`resize` ). ``INTER_NEAREST`` , ``INTER_LINEAR`` and ``INTER_CUBIC`` are supported for now.
-
- :param borderMode: Pixel extrapolation method (see :ocv:func:`borderInterpolate` ). ``BORDER_REFLECT101`` , ``BORDER_REPLICATE`` , ``BORDER_CONSTANT`` , ``BORDER_REFLECT`` and ``BORDER_WRAP`` are supported for now.
-
- :param borderValue: Value used in case of a constant border. By default, it is 0.
-
- :param stream: Stream for the asynchronous version.
-
-The function transforms the source image using the specified map:
-
-.. math::
-
- \texttt{dst} (x,y) = \texttt{src} (xmap(x,y), ymap(x,y))
-
-Values of pixels with non-integer coordinates are computed using the bilinear interpolation.
-
-.. seealso:: :ocv:func:`remap`
-
-
-
-cuda::resize
-------------
-Resizes an image.
-
-.. ocv:function:: void cuda::resize(InputArray src, OutputArray dst, Size dsize, double fx=0, double fy=0, int interpolation = INTER_LINEAR, Stream& stream = Stream::Null())
-
- :param src: Source image.
-
- :param dst: Destination image with the same type as ``src`` . The size is ``dsize`` (when it is non-zero) or the size is computed from ``src.size()`` , ``fx`` , and ``fy`` .
-
- :param dsize: Destination image size. If it is zero, it is computed as:
-
- .. math::
- \texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}
-
- Either ``dsize`` or both ``fx`` and ``fy`` must be non-zero.
-
- :param fx: Scale factor along the horizontal axis. If it is zero, it is computed as:
-
- .. math::
-
- \texttt{(double)dsize.width/src.cols}
-
- :param fy: Scale factor along the vertical axis. If it is zero, it is computed as:
-
- .. math::
-
- \texttt{(double)dsize.height/src.rows}
-
- :param interpolation: Interpolation method. ``INTER_NEAREST`` , ``INTER_LINEAR`` and ``INTER_CUBIC`` are supported for now.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`resize`
-
-
-
-cuda::warpAffine
-----------------
-Applies an affine transformation to an image.
-
-.. ocv:function:: void cuda::warpAffine(InputArray src, OutputArray dst, InputArray M, Size dsize, int flags = INTER_LINEAR, int borderMode = BORDER_CONSTANT, Scalar borderValue = Scalar(), Stream& stream = Stream::Null())
-
- :param src: Source image. ``CV_8U`` , ``CV_16U`` , ``CV_32S`` , or ``CV_32F`` depth and 1, 3, or 4 channels are supported.
-
- :param dst: Destination image with the same type as ``src`` . The size is ``dsize`` .
-
- :param M: *2x3* transformation matrix.
-
- :param dsize: Size of the destination image.
-
- :param flags: Combination of interpolation methods (see :ocv:func:`resize`) and the optional flag ``WARP_INVERSE_MAP`` specifying that ``M`` is an inverse transformation ( ``dst=>src`` ). Only ``INTER_NEAREST`` , ``INTER_LINEAR`` , and ``INTER_CUBIC`` interpolation methods are supported.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`warpAffine`
-
-
-
-cuda::buildWarpAffineMaps
--------------------------
-Builds transformation maps for affine transformation.
-
-.. ocv:function:: void cuda::buildWarpAffineMaps(InputArray M, bool inverse, Size dsize, OutputArray xmap, OutputArray ymap, Stream& stream = Stream::Null())
-
- :param M: *2x3* transformation matrix.
-
- :param inverse: Flag specifying that ``M`` is an inverse transformation ( ``dst=>src`` ).
-
- :param dsize: Size of the destination image.
-
- :param xmap: X values with ``CV_32FC1`` type.
-
- :param ymap: Y values with ``CV_32FC1`` type.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`cuda::warpAffine` , :ocv:func:`cuda::remap`
-
-
-
-cuda::warpPerspective
----------------------
-Applies a perspective transformation to an image.
-
-.. ocv:function:: void cuda::warpPerspective(InputArray src, OutputArray dst, InputArray M, Size dsize, int flags = INTER_LINEAR, int borderMode = BORDER_CONSTANT, Scalar borderValue = Scalar(), Stream& stream = Stream::Null())
-
- :param src: Source image. ``CV_8U`` , ``CV_16U`` , ``CV_32S`` , or ``CV_32F`` depth and 1, 3, or 4 channels are supported.
-
- :param dst: Destination image with the same type as ``src`` . The size is ``dsize`` .
-
- :param M: *3x3* transformation matrix.
-
- :param dsize: Size of the destination image.
-
- :param flags: Combination of interpolation methods (see :ocv:func:`resize` ) and the optional flag ``WARP_INVERSE_MAP`` specifying that ``M`` is the inverse transformation ( ``dst => src`` ). Only ``INTER_NEAREST`` , ``INTER_LINEAR`` , and ``INTER_CUBIC`` interpolation methods are supported.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`warpPerspective`
-
-
-
-cuda::buildWarpPerspectiveMaps
-------------------------------
-Builds transformation maps for perspective transformation.
-
-.. ocv:function:: void cuda::buildWarpAffineMaps(InputArray M, bool inverse, Size dsize, OutputArray xmap, OutputArray ymap, Stream& stream = Stream::Null())
-
- :param M: *3x3* transformation matrix.
-
- :param inverse: Flag specifying that ``M`` is an inverse transformation ( ``dst=>src`` ).
-
- :param dsize: Size of the destination image.
-
- :param xmap: X values with ``CV_32FC1`` type.
-
- :param ymap: Y values with ``CV_32FC1`` type.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`cuda::warpPerspective` , :ocv:func:`cuda::remap`
-
-
-
-cuda::buildWarpPlaneMaps
-------------------------
-Builds plane warping maps.
-
-.. ocv:function:: void cuda::buildWarpPlaneMaps(Size src_size, Rect dst_roi, InputArray K, InputArray R, InputArray T, float scale, OutputArray map_x, OutputArray map_y, Stream& stream = Stream::Null())
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::buildWarpCylindricalMaps
-------------------------------
-Builds cylindrical warping maps.
-
-.. ocv:function:: void cuda::buildWarpCylindricalMaps(Size src_size, Rect dst_roi, InputArray K, InputArray R, float scale, OutputArray map_x, OutputArray map_y, Stream& stream = Stream::Null())
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::buildWarpSphericalMaps
-----------------------------
-Builds spherical warping maps.
-
-.. ocv:function:: void cuda::buildWarpSphericalMaps(Size src_size, Rect dst_roi, InputArray K, InputArray R, float scale, OutputArray map_x, OutputArray map_y, Stream& stream = Stream::Null())
-
- :param stream: Stream for the asynchronous version.
-
-
-
-cuda::rotate
-------------
-Rotates an image around the origin (0,0) and then shifts it.
-
-.. ocv:function:: void cuda::rotate(InputArray src, OutputArray dst, Size dsize, double angle, double xShift = 0, double yShift = 0, int interpolation = INTER_LINEAR, Stream& stream = Stream::Null())
-
- :param src: Source image. Supports 1, 3 or 4 channels images with ``CV_8U`` , ``CV_16U`` or ``CV_32F`` depth.
-
- :param dst: Destination image with the same type as ``src`` . The size is ``dsize`` .
-
- :param dsize: Size of the destination image.
-
- :param angle: Angle of rotation in degrees.
-
- :param xShift: Shift along the horizontal axis.
-
- :param yShift: Shift along the vertical axis.
-
- :param interpolation: Interpolation method. Only ``INTER_NEAREST`` , ``INTER_LINEAR`` , and ``INTER_CUBIC`` are supported.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`cuda::warpAffine`
-
-
-
-cuda::pyrDown
--------------
-Smoothes an image and downsamples it.
-
-.. ocv:function:: void cuda::pyrDown(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source image.
-
- :param dst: Destination image. Will have ``Size((src.cols+1)/2, (src.rows+1)/2)`` size and the same type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`pyrDown`
-
-
-
-cuda::pyrUp
------------
-Upsamples an image and then smoothes it.
-
-.. ocv:function:: void cuda::pyrUp(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
-
- :param src: Source image.
-
- :param dst: Destination image. Will have ``Size(src.cols*2, src.rows*2)`` size and the same type as ``src`` .
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso:: :ocv:func:`pyrUp`
+++ /dev/null
-Common Interfaces of Descriptor Extractors
-==========================================
-
-.. highlight:: cpp
-
-Extractors of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
-between different algorithms solving the same problem. This section is devoted to computing descriptors
-represented as vectors in a multidimensional space. All objects that implement the ``vector``
-descriptor extractors inherit the
-:ocv:class:`DescriptorExtractor` interface.
-
-.. note::
-
- * An example explaining keypoint extraction can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
- * An example on descriptor evaluation can be found at opencv_source_code/samples/cpp/detector_descriptor_evaluation.cpp
-
-DescriptorExtractor
--------------------
-.. ocv:class:: DescriptorExtractor : public Algorithm
-
-Abstract base class for computing descriptors for image keypoints. ::
-
- class CV_EXPORTS DescriptorExtractor
- {
- public:
- virtual ~DescriptorExtractor();
-
- void compute( InputArray image, vector<KeyPoint>& keypoints,
- OutputArray descriptors ) const;
- void compute( InputArrayOfArrays images, vector<vector<KeyPoint> >& keypoints,
- OutputArrayOfArrays descriptors ) const;
-
- virtual void read( const FileNode& );
- virtual void write( FileStorage& ) const;
-
- virtual int descriptorSize() const = 0;
- virtual int descriptorType() const = 0;
- virtual int defaultNorm() const = 0;
-
- static Ptr<DescriptorExtractor> create( const String& descriptorExtractorType );
-
- protected:
- ...
- };
-
-
-In this interface, a keypoint descriptor can be represented as a
-dense, fixed-dimension vector of a basic type. Most descriptors
-follow this pattern as it simplifies computing
-distances between descriptors. Therefore, a collection of
-descriptors is represented as
-:ocv:class:`Mat` , where each row is a keypoint descriptor.
-
-
-
-DescriptorExtractor::compute
---------------------------------
-Computes the descriptors for a set of keypoints detected in an image (first variant) or image set (second variant).
-
-.. ocv:function:: void DescriptorExtractor::compute( InputArray image, vector<KeyPoint>& keypoints, OutputArray descriptors ) const
-
-.. ocv:function:: void DescriptorExtractor::compute( InputArrayOfArrays images, vector<vector<KeyPoint> >& keypoints, OutputArrayOfArrays descriptors ) const
-
-.. ocv:pyfunction:: cv2.DescriptorExtractor_create.compute(image, keypoints[, descriptors]) -> keypoints, descriptors
-
- :param image: Image.
-
- :param images: Image set.
-
- :param keypoints: Input collection of keypoints. Keypoints for which a descriptor cannot be computed are removed. Sometimes new keypoints can be added, for example: ``SIFT`` duplicates keypoint with several dominant orientations (for each orientation).
-
- :param descriptors: Computed descriptors. In the second variant of the method ``descriptors[i]`` are descriptors computed for a ``keypoints[i]``. Row ``j`` is the ``keypoints`` (or ``keypoints[i]``) is the descriptor for keypoint ``j``-th keypoint.
-
-
-DescriptorExtractor::create
--------------------------------
-Creates a descriptor extractor by name.
-
-.. ocv:function:: Ptr<DescriptorExtractor> DescriptorExtractor::create( const String& descriptorExtractorType )
-
-.. ocv:pyfunction:: cv2.DescriptorExtractor_create(descriptorExtractorType) -> retval
-
- :param descriptorExtractorType: Descriptor extractor type.
-
-The current implementation supports the following types of a descriptor extractor:
-
- * ``"BRISK"`` -- :ocv:class:`BRISK`
- * ``"ORB"`` -- :ocv:class:`ORB`
\ No newline at end of file
+++ /dev/null
-Common Interfaces of Descriptor Matchers
-========================================
-
-.. highlight:: cpp
-
-Matchers of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
-between different algorithms solving the same problem. This section is devoted to matching descriptors
-that are represented as vectors in a multidimensional space. All objects that implement ``vector``
-descriptor matchers inherit the
-:ocv:class:`DescriptorMatcher` interface.
-
-.. note::
-
- * An example explaining keypoint matching can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
- * An example on descriptor matching evaluation can be found at opencv_source_code/samples/cpp/detector_descriptor_matcher_evaluation.cpp
- * An example on one to many image matching can be found at opencv_source_code/samples/cpp/matching_to_many_images.cpp
-
-DescriptorMatcher
------------------
-.. ocv:class:: DescriptorMatcher : public Algorithm
-
-Abstract base class for matching keypoint descriptors. It has two groups
-of match methods: for matching descriptors of an image with another image or
-with an image set. ::
-
- class DescriptorMatcher
- {
- public:
- virtual ~DescriptorMatcher();
-
- virtual void add( InputArrayOfArrays descriptors );
-
- const vector<Mat>& getTrainDescriptors() const;
- virtual void clear();
- bool empty() const;
- virtual bool isMaskSupported() const = 0;
-
- virtual void train();
-
- /*
- * Group of methods to match descriptors from an image pair.
- */
- void match( InputArray queryDescriptors, InputArray trainDescriptors,
- vector<DMatch>& matches, InputArray mask=noArray() ) const;
- void knnMatch( InputArray queryDescriptors, InputArray trainDescriptors,
- vector<vector<DMatch> >& matches, int k,
- InputArray mask=noArray(), bool compactResult=false ) const;
- void radiusMatch( InputArray queryDescriptors, InputArray trainDescriptors,
- vector<vector<DMatch> >& matches, float maxDistance,
- InputArray mask=noArray(), bool compactResult=false ) const;
- /*
- * Group of methods to match descriptors from one image to an image set.
- */
- void match( InputArray queryDescriptors, vector<DMatch>& matches,
- InputArrayOfArrays masks=noArray() );
- void knnMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches,
- int k, InputArrayOfArrays masks=noArray(),
- bool compactResult=false );
- void radiusMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches,
- float maxDistance, InputArrayOfArrays masks=noArray(),
- bool compactResult=false );
-
- virtual void read( const FileNode& );
- virtual void write( FileStorage& ) const;
-
- virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
-
- static Ptr<DescriptorMatcher> create( const String& descriptorMatcherType );
-
- protected:
- vector<Mat> trainDescCollection;
- vector<UMat> utrainDescCollection;
- ...
- };
-
-
-DescriptorMatcher::add
---------------------------
-Adds descriptors to train a CPU(``trainDescCollectionis``) or GPU(``utrainDescCollectionis``) descriptor collection. If the collection is not empty, the new descriptors are added to existing train descriptors.
-
-.. ocv:function:: void DescriptorMatcher::add( InputArrayOfArrays descriptors )
-
- :param descriptors: Descriptors to add. Each ``descriptors[i]`` is a set of descriptors from the same train image.
-
-
-DescriptorMatcher::getTrainDescriptors
-------------------------------------------
-Returns a constant link to the train descriptor collection ``trainDescCollection`` .
-
-.. ocv:function:: const vector<Mat>& DescriptorMatcher::getTrainDescriptors() const
-
-
-
-
-
-DescriptorMatcher::clear
-----------------------------
-Clears the train descriptor collections.
-
-.. ocv:function:: void DescriptorMatcher::clear()
-
-
-
-DescriptorMatcher::empty
-----------------------------
-Returns true if there are no train descriptors in the both collections.
-
-.. ocv:function:: bool DescriptorMatcher::empty() const
-
-
-
-DescriptorMatcher::isMaskSupported
---------------------------------------
-Returns true if the descriptor matcher supports masking permissible matches.
-
-.. ocv:function:: bool DescriptorMatcher::isMaskSupported()
-
-
-
-DescriptorMatcher::train
-----------------------------
-Trains a descriptor matcher
-
-.. ocv:function:: void DescriptorMatcher::train()
-
-Trains a descriptor matcher (for example, the flann index). In all methods to match, the method ``train()`` is run every time before matching. Some descriptor matchers (for example, ``BruteForceMatcher``) have an empty implementation of this method. Other matchers really train their inner structures (for example, ``FlannBasedMatcher`` trains ``flann::Index`` ).
-
-
-
-DescriptorMatcher::match
-----------------------------
-Finds the best match for each descriptor from a query set.
-
-.. ocv:function:: void DescriptorMatcher::match( InputArray queryDescriptors, InputArray trainDescriptors, vector<DMatch>& matches, InputArray mask=noArray() ) const
-
-.. ocv:function:: void DescriptorMatcher::match(InputArray queryDescriptors, vector<DMatch>& matches, InputArrayOfArrays masks=noArray() )
-
- :param queryDescriptors: Query set of descriptors.
-
- :param trainDescriptors: Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
-
- :param matches: Matches. If a query descriptor is masked out in ``mask`` , no match is added for this descriptor. So, ``matches`` size may be smaller than the query descriptors count.
-
- :param mask: Mask specifying permissible matches between an input query and train matrices of descriptors.
-
- :param masks: Set of masks. Each ``masks[i]`` specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image ``trainDescCollection[i]``.
-
-In the first variant of this method, the train descriptors are passed as an input argument. In the second variant of the method, train descriptors collection that was set by ``DescriptorMatcher::add`` is used. Optional mask (or masks) can be passed to specify which query and training descriptors can be matched. Namely, ``queryDescriptors[i]`` can be matched with ``trainDescriptors[j]`` only if ``mask.at<uchar>(i,j)`` is non-zero.
-
-
-
-DescriptorMatcher::knnMatch
--------------------------------
-Finds the k best matches for each descriptor from a query set.
-
-.. ocv:function:: void DescriptorMatcher::knnMatch(InputArray queryDescriptors, InputArray trainDescriptors, vector<vector<DMatch> >& matches, int k, InputArray mask=noArray(), bool compactResult=false ) const
-
-.. ocv:function:: void DescriptorMatcher::knnMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches, int k, InputArrayOfArrays masks=noArray(), bool compactResult=false )
-
- :param queryDescriptors: Query set of descriptors.
-
- :param trainDescriptors: Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
-
- :param mask: Mask specifying permissible matches between an input query and train matrices of descriptors.
-
- :param masks: Set of masks. Each ``masks[i]`` specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image ``trainDescCollection[i]``.
-
- :param matches: Matches. Each ``matches[i]`` is k or less matches for the same query descriptor.
-
- :param k: Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total.
-
- :param compactResult: Parameter used when the mask (or masks) is not empty. If ``compactResult`` is false, the ``matches`` vector has the same size as ``queryDescriptors`` rows. If ``compactResult`` is true, the ``matches`` vector does not contain matches for fully masked-out query descriptors.
-
-These extended variants of :ocv:func:`DescriptorMatcher::match` methods find several best matches for each query descriptor. The matches are returned in the distance increasing order. See :ocv:func:`DescriptorMatcher::match` for the details about query and train descriptors.
-
-
-
-DescriptorMatcher::radiusMatch
-----------------------------------
-For each query descriptor, finds the training descriptors not farther than the specified distance.
-
-.. ocv:function:: void DescriptorMatcher::radiusMatch( InputArray queryDescriptors, InputArray trainDescriptors, vector<vector<DMatch> >& matches, float maxDistance, InputArray mask=noArray(), bool compactResult=false ) const
-
-.. ocv:function:: void DescriptorMatcher::radiusMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches, float maxDistance, InputArrayOfArrays masks=noArray(), bool compactResult=false )
-
- :param queryDescriptors: Query set of descriptors.
-
- :param trainDescriptors: Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
-
- :param mask: Mask specifying permissible matches between an input query and train matrices of descriptors.
-
- :param masks: Set of masks. Each ``masks[i]`` specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image ``trainDescCollection[i]``.
-
- :param matches: Found matches.
-
- :param compactResult: Parameter used when the mask (or masks) is not empty. If ``compactResult`` is false, the ``matches`` vector has the same size as ``queryDescriptors`` rows. If ``compactResult`` is true, the ``matches`` vector does not contain matches for fully masked-out query descriptors.
-
- :param maxDistance: Threshold for the distance between matched descriptors. Distance means here metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured in Pixels)!
-
-For each query descriptor, the methods find such training descriptors that the distance between the query descriptor and the training descriptor is equal or smaller than ``maxDistance``. Found matches are returned in the distance increasing order.
-
-
-
-DescriptorMatcher::clone
-----------------------------
-Clones the matcher.
-
-.. ocv:function:: Ptr<DescriptorMatcher> DescriptorMatcher::clone( bool emptyTrainData=false )
-
- :param emptyTrainData: If ``emptyTrainData`` is false, the method creates a deep copy of the object, that is, copies both parameters and train data. If ``emptyTrainData`` is true, the method creates an object copy with the current parameters but with empty train data.
-
-
-
-DescriptorMatcher::create
------------------------------
-Creates a descriptor matcher of a given type with the default parameters (using default constructor).
-
-.. ocv:function:: Ptr<DescriptorMatcher> DescriptorMatcher::create( const String& descriptorMatcherType )
-
- :param descriptorMatcherType: Descriptor matcher type. Now the following matcher types are supported:
-
- *
- ``BruteForce`` (it uses ``L2`` )
- *
- ``BruteForce-L1``
- *
- ``BruteForce-Hamming``
- *
- ``BruteForce-Hamming(2)``
- *
- ``FlannBased``
-
-
-
-
-
-BFMatcher
------------------
-.. ocv:class:: BFMatcher : public DescriptorMatcher
-
-Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest descriptor in the second set by trying each one. This descriptor matcher supports masking permissible matches of descriptor sets.
-
-
-BFMatcher::BFMatcher
---------------------
-Brute-force matcher constructor.
-
-.. ocv:function:: BFMatcher::BFMatcher( int normType=NORM_L2, bool crossCheck=false )
-
- :param normType: One of ``NORM_L1``, ``NORM_L2``, ``NORM_HAMMING``, ``NORM_HAMMING2``. ``L1`` and ``L2`` norms are preferable choices for SIFT and SURF descriptors, ``NORM_HAMMING`` should be used with ORB, BRISK and BRIEF, ``NORM_HAMMING2`` should be used with ORB when ``WTA_K==3`` or ``4`` (see ORB::ORB constructor description).
-
- :param crossCheck: If it is false, this is will be default BFMatcher behaviour when it finds the k nearest neighbors for each query descriptor. If ``crossCheck==true``, then the ``knnMatch()`` method with ``k=1`` will only return pairs ``(i,j)`` such that for ``i-th`` query descriptor the ``j-th`` descriptor in the matcher's collection is the nearest and vice versa, i.e. the ``BFMatcher`` will only return consistent pairs. Such technique usually produces best results with minimal number of outliers when there are enough matches. This is alternative to the ratio test, used by D. Lowe in SIFT paper.
-
-
-FlannBasedMatcher
------------------
-.. ocv:class:: FlannBasedMatcher : public DescriptorMatcher
-
-Flann-based descriptor matcher. This matcher trains :ocv:class:`flann::Index_` on a train descriptor collection and calls its nearest search methods to find the best matches. So, this matcher may be faster when matching a large train collection than the brute force matcher. ``FlannBasedMatcher`` does not support masking permissible matches of descriptor sets because ``flann::Index`` does not support this. ::
-
- class FlannBasedMatcher : public DescriptorMatcher
- {
- public:
- FlannBasedMatcher(
- const Ptr<flann::IndexParams>& indexParams=new flann::KDTreeIndexParams(),
- const Ptr<flann::SearchParams>& searchParams=new flann::SearchParams() );
-
- virtual void add( InputArrayOfArrays descriptors );
- virtual void clear();
-
- virtual void train();
- virtual bool isMaskSupported() const;
-
- virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const;
- protected:
- ...
- };
-
-..
+++ /dev/null
-Common Interfaces of Feature Detectors
-======================================
-
-.. highlight:: cpp
-
-Feature detectors in OpenCV have wrappers with a common interface that enables you to easily switch
-between different algorithms solving the same problem. All objects that implement keypoint detectors
-inherit the
-:ocv:class:`FeatureDetector` interface.
-
-.. note::
-
- * An example explaining keypoint detection can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
-
-FeatureDetector
----------------
-.. ocv:class:: FeatureDetector : public Algorithm
-
-Abstract base class for 2D image feature detectors. ::
-
- class CV_EXPORTS FeatureDetector
- {
- public:
- virtual ~FeatureDetector();
-
- void detect( InputArray image, vector<KeyPoint>& keypoints,
- InputArray mask=noArray() ) const;
-
- void detect( InputArrayOfArrays images,
- vector<vector<KeyPoint> >& keypoints,
- InputArrayOfArrays masks=noArray() ) const;
-
- virtual void read(const FileNode&);
- virtual void write(FileStorage&) const;
-
- static Ptr<FeatureDetector> create( const String& detectorType );
-
- protected:
- ...
- };
-
-FeatureDetector::detect
----------------------------
-Detects keypoints in an image (first variant) or image set (second variant).
-
-.. ocv:function:: void FeatureDetector::detect( InputArray image, vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const
-
-.. ocv:function:: void FeatureDetector::detect( InputArrayOfArrays images, vector<vector<KeyPoint> >& keypoints, InputArrayOfArrays masks=noArray() ) const
-
-.. ocv:pyfunction:: cv2.FeatureDetector_create.detect(image[, mask]) -> keypoints
-
- :param image: Image.
-
- :param images: Image set.
-
- :param keypoints: The detected keypoints. In the second variant of the method ``keypoints[i]`` is a set of keypoints detected in ``images[i]`` .
-
- :param mask: Mask specifying where to look for keypoints (optional). It must be a 8-bit integer matrix with non-zero values in the region of interest.
-
- :param masks: Masks for each input image specifying where to look for keypoints (optional). ``masks[i]`` is a mask for ``images[i]``.
-
-FastFeatureDetector
--------------------
-.. ocv:class:: FastFeatureDetector : public Feature2D
-
-Wrapping class for feature detection using the
-:ocv:func:`FAST` method. ::
-
- class FastFeatureDetector : public Feature2D
- {
- public:
- static Ptr<FastFeatureDetector> create( int threshold=1, bool nonmaxSuppression=true, type=FastFeatureDetector::TYPE_9_16 );
- };
-
-GFTTDetector
----------------------------
-.. ocv:class:: GFTTDetector : public FeatureDetector
-
-Wrapping class for feature detection using the
-:ocv:func:`goodFeaturesToTrack` function. ::
-
- class GFTTDetector : public Feature2D
- {
- public:
- enum { USE_HARRIS_DETECTOR=10000 };
- static Ptr<GFTTDetector> create( int maxCorners=1000, double qualityLevel=0.01,
- double minDistance=1, int blockSize=3,
- bool useHarrisDetector=false, double k=0.04 );
- };
-
-MSER
--------------------
-.. ocv:class:: MSER : public Feature2D
-
-Maximally stable region detector ::
-
- class MSER : public Feature2D
- {
- public:
- enum
- {
- DELTA=10000, MIN_AREA=10001, MAX_AREA=10002, PASS2_ONLY=10003,
- MAX_EVOLUTION=10004, AREA_THRESHOLD=10005,
- MIN_MARGIN=10006, EDGE_BLUR_SIZE=10007
- };
-
- //! the full constructor
- static Ptr<MSER> create( int _delta=5, int _min_area=60, int _max_area=14400,
- double _max_variation=0.25, double _min_diversity=.2,
- int _max_evolution=200, double _area_threshold=1.01,
- double _min_margin=0.003, int _edge_blur_size=5 );
-
- virtual void detectRegions( InputArray image,
- std::vector<std::vector<Point> >& msers,
- std::vector<Rect>& bboxes ) = 0;
- };
-
-SimpleBlobDetector
--------------------
-.. ocv:class:: SimpleBlobDetector : public FeatureDetector
-
-Class for extracting blobs from an image. ::
-
- class SimpleBlobDetector : public FeatureDetector
- {
- public:
- struct Params
- {
- Params();
- float thresholdStep;
- float minThreshold;
- float maxThreshold;
- size_t minRepeatability;
- float minDistBetweenBlobs;
-
- bool filterByColor;
- uchar blobColor;
-
- bool filterByArea;
- float minArea, maxArea;
-
- bool filterByCircularity;
- float minCircularity, maxCircularity;
-
- bool filterByInertia;
- float minInertiaRatio, maxInertiaRatio;
-
- bool filterByConvexity;
- float minConvexity, maxConvexity;
- };
-
- static Ptr<SimpleBlobDetector> create(const SimpleBlobDetector::Params
- ¶meters = SimpleBlobDetector::Params());
- };
-
-The class implements a simple algorithm for extracting blobs from an image:
-
-#. Convert the source image to binary images by applying thresholding with several thresholds from ``minThreshold`` (inclusive) to ``maxThreshold`` (exclusive) with distance ``thresholdStep`` between neighboring thresholds.
-
-#. Extract connected components from every binary image by :ocv:func:`findContours` and calculate their centers.
-
-#. Group centers from several binary images by their coordinates. Close centers form one group that corresponds to one blob, which is controlled by the ``minDistBetweenBlobs`` parameter.
-
-#. From the groups, estimate final centers of blobs and their radiuses and return as locations and sizes of keypoints.
-
-This class performs several filtrations of returned blobs. You should set ``filterBy*`` to true/false to turn on/off corresponding filtration. Available filtrations:
-
- * **By color**. This filter compares the intensity of a binary image at the center of a blob to ``blobColor``. If they differ, the blob is filtered out. Use ``blobColor = 0`` to extract dark blobs and ``blobColor = 255`` to extract light blobs.
-
- * **By area**. Extracted blobs have an area between ``minArea`` (inclusive) and ``maxArea`` (exclusive).
-
- * **By circularity**. Extracted blobs have circularity (:math:`\frac{4*\pi*Area}{perimeter * perimeter}`) between ``minCircularity`` (inclusive) and ``maxCircularity`` (exclusive).
-
- * **By ratio of the minimum inertia to maximum inertia**. Extracted blobs have this ratio between ``minInertiaRatio`` (inclusive) and ``maxInertiaRatio`` (exclusive).
-
- * **By convexity**. Extracted blobs have convexity (area / area of blob convex hull) between ``minConvexity`` (inclusive) and ``maxConvexity`` (exclusive).
-
-
-Default values of parameters are tuned to extract dark circular blobs.
+++ /dev/null
-Drawing Function of Keypoints and Matches
-=========================================
-
-
-
-drawMatches
----------------
-Draws the found matches of keypoints from two images.
-
-.. ocv:function:: void drawMatches( InputArray img1, const vector<KeyPoint>& keypoints1, InputArray img2, const vector<KeyPoint>& keypoints2, const vector<DMatch>& matches1to2, InputOutputArray outImg, const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1), const vector<char>& matchesMask=vector<char>(), int flags=DrawMatchesFlags::DEFAULT )
-
-.. ocv:function:: void drawMatches( InputArray img1, const vector<KeyPoint>& keypoints1, InputArray img2, const vector<KeyPoint>& keypoints2, const vector<vector<DMatch> >& matches1to2, InputOutputArray outImg, const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1), const vector<vector<char> >& matchesMask=vector<vector<char> >(), int flags=DrawMatchesFlags::DEFAULT )
-
-.. ocv:pyfunction:: cv2.drawMatches(img1, keypoints1, img2, keypoints2, matches1to2[, outImg[, matchColor[, singlePointColor[, matchesMask[, flags]]]]]) -> outImg
-
-.. ocv:pyfunction:: cv2.drawMatchesKnn(img1, keypoints1, img2, keypoints2, matches1to2[, outImg[, matchColor[, singlePointColor[, matchesMask[, flags]]]]]) -> outImg
-
-
- :param img1: First source image.
-
- :param keypoints1: Keypoints from the first source image.
-
- :param img2: Second source image.
-
- :param keypoints2: Keypoints from the second source image.
-
- :param matches1to2: Matches from the first image to the second one, which means that ``keypoints1[i]`` has a corresponding point in ``keypoints2[matches[i]]`` .
-
- :param outImg: Output image. Its content depends on the ``flags`` value defining what is drawn in the output image. See possible ``flags`` bit values below.
-
- :param matchColor: Color of matches (lines and connected keypoints). If ``matchColor==Scalar::all(-1)`` , the color is generated randomly.
-
- :param singlePointColor: Color of single keypoints (circles), which means that keypoints do not have the matches. If ``singlePointColor==Scalar::all(-1)`` , the color is generated randomly.
-
- :param matchesMask: Mask determining which matches are drawn. If the mask is empty, all matches are drawn.
-
- :param flags: Flags setting drawing features. Possible ``flags`` bit values are defined by ``DrawMatchesFlags``.
-
-This function draws matches of keypoints from two images in the output image. Match is a line connecting two keypoints (circles). The structure ``DrawMatchesFlags`` is defined as follows:
-
-.. code-block:: cpp
-
- struct DrawMatchesFlags
- {
- enum
- {
- DEFAULT = 0, // Output image matrix will be created (Mat::create),
- // i.e. existing memory of output image may be reused.
- // Two source images, matches, and single keypoints
- // will be drawn.
- // For each keypoint, only the center point will be
- // drawn (without a circle around the keypoint with the
- // keypoint size and orientation).
- DRAW_OVER_OUTIMG = 1, // Output image matrix will not be
- // created (using Mat::create). Matches will be drawn
- // on existing content of output image.
- NOT_DRAW_SINGLE_POINTS = 2, // Single keypoints will not be drawn.
- DRAW_RICH_KEYPOINTS = 4 // For each keypoint, the circle around
- // keypoint with keypoint size and orientation will
- // be drawn.
- };
- };
-
-..
-
-
-
-drawKeypoints
------------------
-Draws keypoints.
-
-.. ocv:function:: void drawKeypoints( InputArray image, const vector<KeyPoint>& keypoints, InputOutputArray outImage, const Scalar& color=Scalar::all(-1), int flags=DrawMatchesFlags::DEFAULT )
-
-.. ocv:pyfunction:: cv2.drawKeypoints(image, keypoints[, outImage[, color[, flags]]]) -> outImage
-
- :param image: Source image.
-
- :param keypoints: Keypoints from the source image.
-
- :param outImage: Output image. Its content depends on the ``flags`` value defining what is drawn in the output image. See possible ``flags`` bit values below.
-
- :param color: Color of keypoints.
-
- :param flags: Flags setting drawing features. Possible ``flags`` bit values are defined by ``DrawMatchesFlags``. See details above in :ocv:func:`drawMatches` .
-
-.. note:: For Python API, flags are modified as `cv2.DRAW_MATCHES_FLAGS_DEFAULT`, `cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS`, `cv2.DRAW_MATCHES_FLAGS_DRAW_OVER_OUTIMG`, `cv2.DRAW_MATCHES_FLAGS_NOT_DRAW_SINGLE_POINTS`
+++ /dev/null
-Feature Detection and Description
-=================================
-
-.. highlight:: cpp
-
-.. note::
-
- * An example explaining keypoint detection and description can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
-
-FAST
-----
-Detects corners using the FAST algorithm
-
-.. ocv:function:: void FAST( InputArray image, vector<KeyPoint>& keypoints, int threshold, bool nonmaxSuppression=true )
-.. ocv:function:: void FAST( InputArray image, vector<KeyPoint>& keypoints, int threshold, bool nonmaxSuppression, int type )
-
- :param image: grayscale image where keypoints (corners) are detected.
-
- :param keypoints: keypoints detected on the image.
-
- :param threshold: threshold on difference between intensity of the central pixel and pixels of a circle around this pixel.
-
- :param nonmaxSuppression: if true, non-maximum suppression is applied to detected corners (keypoints).
-
- :param type: one of the three neighborhoods as defined in the paper: ``FastFeatureDetector::TYPE_9_16``, ``FastFeatureDetector::TYPE_7_12``, ``FastFeatureDetector::TYPE_5_8``
-
-Detects corners using the FAST algorithm by [Rosten06]_.
-
-.. note:: In Python API, types are given as ``cv2.FAST_FEATURE_DETECTOR_TYPE_5_8``, ``cv2.FAST_FEATURE_DETECTOR_TYPE_7_12`` and ``cv2.FAST_FEATURE_DETECTOR_TYPE_9_16``. For corner detection, use ``cv2.FAST.detect()`` method.
-
-
-.. [Rosten06] E. Rosten. Machine Learning for High-speed Corner Detection, 2006.
-
-MSER
-----
-.. ocv:class:: MSER : public FeatureDetector
-
-Maximally stable extremal region extractor. ::
-
- class MSER : public CvMSERParams
- {
- public:
- // default constructor
- MSER();
- // constructor that initializes all the algorithm parameters
- MSER( int _delta, int _min_area, int _max_area,
- float _max_variation, float _min_diversity,
- int _max_evolution, double _area_threshold,
- double _min_margin, int _edge_blur_size );
- // runs the extractor on the specified image; returns the MSERs,
- // each encoded as a contour (vector<Point>, see findContours)
- // the optional mask marks the area where MSERs are searched for
- void detectRegions( InputArray image, vector<vector<Point> >& msers, vector<Rect>& bboxes ) const;
- };
-
-The class encapsulates all the parameters of the MSER extraction algorithm (see
-http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions). Also see http://code.opencv.org/projects/opencv/wiki/MSER for useful comments and parameters description.
-
-.. note::
-
- * (Python) A complete example showing the use of the MSER detector can be found at opencv_source_code/samples/python2/mser.py
-
-
-ORB
----
-.. ocv:class:: ORB : public Feature2D
-
-Class implementing the ORB (*oriented BRIEF*) keypoint detector and descriptor extractor, described in [RRKB11]_. The algorithm uses FAST in pyramids to detect stable keypoints, selects the strongest features using FAST or Harris response, finds their orientation using first-order moments and computes the descriptors using BRIEF (where the coordinates of random point pairs (or k-tuples) are rotated according to the measured orientation).
-
-.. [RRKB11] Ethan Rublee, Vincent Rabaud, Kurt Konolige, Gary R. Bradski: ORB: An efficient alternative to SIFT or SURF. ICCV 2011: 2564-2571.
-
-ORB::ORB
---------
-The ORB constructor
-
-.. ocv:function:: ORB::ORB(int nfeatures = 500, float scaleFactor = 1.2f, int nlevels = 8, int edgeThreshold = 31, int firstLevel = 0, int WTA_K=2, int scoreType=ORB::HARRIS_SCORE, int patchSize=31)
-
-.. ocv:pyfunction:: cv2.ORB([, nfeatures[, scaleFactor[, nlevels[, edgeThreshold[, firstLevel[, WTA_K[, scoreType[, patchSize]]]]]]]]) -> <ORB object>
-
-
- :param nfeatures: The maximum number of features to retain.
-
- :param scaleFactor: Pyramid decimation ratio, greater than 1. ``scaleFactor==2`` means the classical pyramid, where each next level has 4x less pixels than the previous, but such a big scale factor will degrade feature matching scores dramatically. On the other hand, too close to 1 scale factor will mean that to cover certain scale range you will need more pyramid levels and so the speed will suffer.
-
- :param nlevels: The number of pyramid levels. The smallest level will have linear size equal to ``input_image_linear_size/pow(scaleFactor, nlevels)``.
-
- :param edgeThreshold: This is size of the border where the features are not detected. It should roughly match the ``patchSize`` parameter.
-
- :param firstLevel: It should be 0 in the current implementation.
-
- :param WTA_K: The number of points that produce each element of the oriented BRIEF descriptor. The default value 2 means the BRIEF where we take a random point pair and compare their brightnesses, so we get 0/1 response. Other possible values are 3 and 4. For example, 3 means that we take 3 random points (of course, those point coordinates are random, but they are generated from the pre-defined seed, so each element of BRIEF descriptor is computed deterministically from the pixel rectangle), find point of maximum brightness and output index of the winner (0, 1 or 2). Such output will occupy 2 bits, and therefore it will need a special variant of Hamming distance, denoted as ``NORM_HAMMING2`` (2 bits per bin). When ``WTA_K=4``, we take 4 random points to compute each bin (that will also occupy 2 bits with possible values 0, 1, 2 or 3).
-
- :param scoreType: The default HARRIS_SCORE means that Harris algorithm is used to rank features (the score is written to ``KeyPoint::score`` and is used to retain best ``nfeatures`` features); FAST_SCORE is alternative value of the parameter that produces slightly less stable keypoints, but it is a little faster to compute.
-
- :param patchSize: size of the patch used by the oriented BRIEF descriptor. Of course, on smaller pyramid layers the perceived image area covered by a feature will be larger.
-
-ORB::operator()
----------------
-Finds keypoints in an image and computes their descriptors
-
-.. ocv:function:: void ORB::operator()(InputArray image, InputArray mask, vector<KeyPoint>& keypoints, OutputArray descriptors, bool useProvidedKeypoints=false ) const
-
-.. ocv:pyfunction:: cv2.ORB.detect(image[, mask]) -> keypoints
-.. ocv:pyfunction:: cv2.ORB.compute(image, keypoints[, descriptors]) -> keypoints, descriptors
-.. ocv:pyfunction:: cv2.ORB.detectAndCompute(image, mask[, descriptors[, useProvidedKeypoints]]) -> keypoints, descriptors
-
-
- :param image: The input 8-bit grayscale image.
-
- :param mask: The operation mask.
-
- :param keypoints: The output vector of keypoints.
-
- :param descriptors: The output descriptors. Pass ``cv::noArray()`` if you do not need it.
-
- :param useProvidedKeypoints: If it is true, then the method will use the provided vector of keypoints instead of detecting them.
-
-
-BRISK
------
-.. ocv:class:: BRISK : public Feature2D
-
-Class implementing the BRISK keypoint detector and descriptor extractor, described in [LCS11]_.
-
-.. [LCS11] Stefan Leutenegger, Margarita Chli and Roland Siegwart: BRISK: Binary Robust Invariant Scalable Keypoints. ICCV 2011: 2548-2555.
-
-BRISK::BRISK
-------------
-The BRISK constructor
-
-.. ocv:function:: BRISK::BRISK(int thresh=30, int octaves=3, float patternScale=1.0f)
-
-.. ocv:pyfunction:: cv2.BRISK([, thresh[, octaves[, patternScale]]]) -> <BRISK object>
-
- :param thresh: FAST/AGAST detection threshold score.
-
- :param octaves: detection octaves. Use 0 to do single scale.
-
- :param patternScale: apply this scale to the pattern used for sampling the neighbourhood of a keypoint.
-
-BRISK::BRISK
-------------
-The BRISK constructor for a custom pattern
-
-.. ocv:function:: BRISK::BRISK(std::vector<float> &radiusList, std::vector<int> &numberList, float dMax=5.85f, float dMin=8.2f, std::vector<int> indexChange=std::vector<int>())
-
-.. ocv:pyfunction:: cv2.BRISK(radiusList, numberList[, dMax[, dMin[, indexChange]]]) -> <BRISK object>
-
- :param radiusList: defines the radii (in pixels) where the samples around a keypoint are taken (for keypoint scale 1).
-
- :param numberList: defines the number of sampling points on the sampling circle. Must be the same size as radiusList..
-
- :param dMax: threshold for the short pairings used for descriptor formation (in pixels for keypoint scale 1).
-
- :param dMin: threshold for the long pairings used for orientation determination (in pixels for keypoint scale 1).
-
- :param indexChanges: index remapping of the bits.
-
-BRISK::operator()
------------------
-Finds keypoints in an image and computes their descriptors
-
-.. ocv:function:: void BRISK::operator()(InputArray image, InputArray mask, vector<KeyPoint>& keypoints, OutputArray descriptors, bool useProvidedKeypoints=false ) const
-
-.. ocv:pyfunction:: cv2.BRISK.detect(image[, mask]) -> keypoints
-.. ocv:pyfunction:: cv2.BRISK.compute(image, keypoints[, descriptors]) -> keypoints, descriptors
-.. ocv:pyfunction:: cv2.BRISK.detectAndCompute(image, mask[, descriptors[, useProvidedKeypoints]]) -> keypoints, descriptors
-
- :param image: The input 8-bit grayscale image.
-
- :param mask: The operation mask.
-
- :param keypoints: The output vector of keypoints.
-
- :param descriptors: The output descriptors. Pass ``cv::noArray()`` if you do not need it.
-
- :param useProvidedKeypoints: If it is true, then the method will use the provided vector of keypoints instead of detecting them.
-
-KAZE
-----
-.. ocv:class:: KAZE : public Feature2D
-
-Class implementing the KAZE keypoint detector and descriptor extractor, described in [ABD12]_. ::
-
- class CV_EXPORTS_W KAZE : public Feature2D
- {
- public:
- CV_WRAP KAZE();
- CV_WRAP explicit KAZE(bool extended, bool upright, float threshold = 0.001f,
- int octaves = 4, int sublevels = 4, int diffusivity = DIFF_PM_G2);
- };
-
-.. note:: AKAZE descriptor can only be used with KAZE or AKAZE keypoints
-
-.. [ABD12] KAZE Features. Pablo F. Alcantarilla, Adrien Bartoli and Andrew J. Davison. In European Conference on Computer Vision (ECCV), Fiorenze, Italy, October 2012.
-
-KAZE::KAZE
-----------
-The KAZE constructor
-
-.. ocv:function:: KAZE::KAZE(bool extended, bool upright, float threshold, int octaves, int sublevels, int diffusivity)
-
- :param extended: Set to enable extraction of extended (128-byte) descriptor.
- :param upright: Set to enable use of upright descriptors (non rotation-invariant).
- :param threshold: Detector response threshold to accept point
- :param octaves: Maximum octave evolution of the image
- :param sublevels: Default number of sublevels per scale level
- :param diffusivity: Diffusivity type. DIFF_PM_G1, DIFF_PM_G2, DIFF_WEICKERT or DIFF_CHARBONNIER
-
-AKAZE
------
-.. ocv:class:: AKAZE : public Feature2D
-
-Class implementing the AKAZE keypoint detector and descriptor extractor, described in [ANB13]_. ::
-
- class CV_EXPORTS_W AKAZE : public Feature2D
- {
- public:
- CV_WRAP AKAZE();
- CV_WRAP explicit AKAZE(int descriptor_type, int descriptor_size = 0, int descriptor_channels = 3,
- float threshold = 0.001f, int octaves = 4, int sublevels = 4, int diffusivity = DIFF_PM_G2);
- };
-
-.. note:: AKAZE descriptors can only be used with KAZE or AKAZE keypoints. Try to avoid using *extract* and *detect* instead of *operator()* due to performance reasons.
-
-.. [ANB13] Fast Explicit Diffusion for Accelerated Features in Nonlinear Scale Spaces. Pablo F. Alcantarilla, Jesús Nuevo and Adrien Bartoli. In British Machine Vision Conference (BMVC), Bristol, UK, September 2013.
-
-AKAZE::AKAZE
-------------
-The AKAZE constructor
-
-.. ocv:function:: AKAZE::AKAZE(int descriptor_type, int descriptor_size, int descriptor_channels, float threshold, int octaves, int sublevels, int diffusivity)
-
- :param descriptor_type: Type of the extracted descriptor: DESCRIPTOR_KAZE, DESCRIPTOR_KAZE_UPRIGHT, DESCRIPTOR_MLDB or DESCRIPTOR_MLDB_UPRIGHT.
- :param descriptor_size: Size of the descriptor in bits. 0 -> Full size
- :param descriptor_channels: Number of channels in the descriptor (1, 2, 3)
- :param threshold: Detector response threshold to accept point
- :param octaves: Maximum octave evolution of the image
- :param sublevels: Default number of sublevels per scale level
- :param diffusivity: Diffusivity type. DIFF_PM_G1, DIFF_PM_G2, DIFF_WEICKERT or DIFF_CHARBONNIER
-
-SIFT
-----
-
-.. ocv:class:: SIFT : public Feature2D
-
-The SIFT algorithm has been moved to opencv_contrib/xfeatures2d module.
+++ /dev/null
-*********************************
-features2d. 2D Features Framework
-*********************************
-
-.. highlight:: cpp
-
-.. toctree::
- :maxdepth: 2
-
- feature_detection_and_description
- common_interfaces_of_feature_detectors
- common_interfaces_of_descriptor_extractors
- common_interfaces_of_descriptor_matchers
- drawing_function_of_keypoints_and_matches
- object_categorization
+++ /dev/null
-Object Categorization
-=====================
-
-.. highlight:: cpp
-
-This section describes approaches based on local 2D features and used to categorize objects.
-
-.. note::
-
- * A complete Bag-Of-Words sample can be found at opencv_source_code/samples/cpp/bagofwords_classification.cpp
-
- * (Python) An example using the features2D framework to perform object categorization can be found at opencv_source_code/samples/python2/find_obj.py
-
-BOWTrainer
-----------
-.. ocv:class:: BOWTrainer
-
-Abstract base class for training the *bag of visual words* vocabulary from a set of descriptors.
-For details, see, for example, *Visual Categorization with Bags of Keypoints* by Gabriella Csurka, Christopher R. Dance,
-Lixin Fan, Jutta Willamowski, Cedric Bray, 2004. ::
-
- class BOWTrainer
- {
- public:
- BOWTrainer(){}
- virtual ~BOWTrainer(){}
-
- void add( const Mat& descriptors );
- const vector<Mat>& getDescriptors() const;
- int descriptorsCount() const;
-
- virtual void clear();
-
- virtual Mat cluster() const = 0;
- virtual Mat cluster( const Mat& descriptors ) const = 0;
-
- protected:
- ...
- };
-
-BOWTrainer::add
--------------------
-Adds descriptors to a training set.
-
-.. ocv:function:: void BOWTrainer::add( const Mat& descriptors )
-
- :param descriptors: Descriptors to add to a training set. Each row of the ``descriptors`` matrix is a descriptor.
-
-The training set is clustered using ``clustermethod`` to construct the vocabulary.
-
-BOWTrainer::getDescriptors
-------------------------------
-Returns a training set of descriptors.
-
-.. ocv:function:: const vector<Mat>& BOWTrainer::getDescriptors() const
-
-
-
-BOWTrainer::descriptorsCount
----------------------------------
-Returns the count of all descriptors stored in the training set.
-
-.. ocv:function:: int BOWTrainer::descriptorsCount() const
-
-
-
-BOWTrainer::cluster
------------------------
-Clusters train descriptors.
-
-.. ocv:function:: Mat BOWTrainer::cluster() const
-
-.. ocv:function:: Mat BOWTrainer::cluster( const Mat& descriptors ) const
-
- :param descriptors: Descriptors to cluster. Each row of the ``descriptors`` matrix is a descriptor. Descriptors are not added to the inner train descriptor set.
-
-The vocabulary consists of cluster centers. So, this method returns the vocabulary. In the first variant of the method, train descriptors stored in the object are clustered. In the second variant, input descriptors are clustered.
-
-BOWKMeansTrainer
-----------------
-.. ocv:class:: BOWKMeansTrainer : public BOWTrainer
-
-:ocv:func:`kmeans` -based class to train visual vocabulary using the *bag of visual words* approach.
-::
-
- class BOWKMeansTrainer : public BOWTrainer
- {
- public:
- BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(),
- int attempts=3, int flags=KMEANS_PP_CENTERS );
- virtual ~BOWKMeansTrainer(){}
-
- // Returns trained vocabulary (i.e. cluster centers).
- virtual Mat cluster() const;
- virtual Mat cluster( const Mat& descriptors ) const;
-
- protected:
- ...
- };
-
-BOWKMeansTrainer::BOWKMeansTrainer
-----------------------------------
-
-The constructor.
-
-.. ocv:function:: BOWKMeansTrainer::BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(), int attempts=3, int flags=KMEANS_PP_CENTERS )
-
- See :ocv:func:`kmeans` function parameters.
-
-BOWImgDescriptorExtractor
--------------------------
-.. ocv:class:: BOWImgDescriptorExtractor
-
-Class to compute an image descriptor using the *bag of visual words*. Such a computation consists of the following steps:
-
- #. Compute descriptors for a given image and its keypoints set.
- #. Find the nearest visual words from the vocabulary for each keypoint descriptor.
- #. Compute the bag-of-words image descriptor as is a normalized histogram of vocabulary words encountered in the image. The ``i``-th bin of the histogram is a frequency of ``i``-th word of the vocabulary in the given image.
-
-The class declaration is the following: ::
-
- class BOWImgDescriptorExtractor
- {
- public:
- BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor,
- const Ptr<DescriptorMatcher>& dmatcher );
- BOWImgDescriptorExtractor( const Ptr<DescriptorMatcher>& dmatcher );
- virtual ~BOWImgDescriptorExtractor(){}
-
- void setVocabulary( const Mat& vocabulary );
- const Mat& getVocabulary() const;
- void compute( InputArray image, vector<KeyPoint>& keypoints,
- OutputArray imgDescriptor,
- vector<vector<int> >* pointIdxsOfClusters=0,
- Mat* descriptors=0 );
- void compute( InputArray descriptors, OutputArray imgDescriptor,
- std::vector<std::vector<int> >* pointIdxsOfClusters=0 );
- int descriptorSize() const;
- int descriptorType() const;
-
- protected:
- ...
- };
-
-
-
-
-BOWImgDescriptorExtractor::BOWImgDescriptorExtractor
---------------------------------------------------------
-The constructor.
-
-.. ocv:function:: BOWImgDescriptorExtractor::BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor, const Ptr<DescriptorMatcher>& dmatcher )
-.. ocv:function:: BOWImgDescriptorExtractor::BOWImgDescriptorExtractor( const Ptr<DescriptorMatcher>& dmatcher )
-
- :param dextractor: Descriptor extractor that is used to compute descriptors for an input image and its keypoints.
-
- :param dmatcher: Descriptor matcher that is used to find the nearest word of the trained vocabulary for each keypoint descriptor of the image.
-
-
-
-BOWImgDescriptorExtractor::setVocabulary
---------------------------------------------
-Sets a visual vocabulary.
-
-.. ocv:function:: void BOWImgDescriptorExtractor::setVocabulary( const Mat& vocabulary )
-
- :param vocabulary: Vocabulary (can be trained using the inheritor of :ocv:class:`BOWTrainer` ). Each row of the vocabulary is a visual word (cluster center).
-
-
-
-BOWImgDescriptorExtractor::getVocabulary
---------------------------------------------
-Returns the set vocabulary.
-
-.. ocv:function:: const Mat& BOWImgDescriptorExtractor::getVocabulary() const
-
-
-
-BOWImgDescriptorExtractor::compute
---------------------------------------
-Computes an image descriptor using the set visual vocabulary.
-
-.. ocv:function:: void BOWImgDescriptorExtractor::compute( InputArray image, vector<KeyPoint>& keypoints, OutputArray imgDescriptor, vector<vector<int> >* pointIdxsOfClusters=0, Mat* descriptors=0 )
-.. ocv:function:: void BOWImgDescriptorExtractor::compute( InputArray keypointDescriptors, OutputArray imgDescriptor, std::vector<std::vector<int> >* pointIdxsOfClusters=0 )
-
- :param image: Image, for which the descriptor is computed.
-
- :param keypoints: Keypoints detected in the input image.
-
- :param keypointDescriptors: Computed descriptors to match with vocabulary.
-
- :param imgDescriptor: Computed output image descriptor.
-
- :param pointIdxsOfClusters: Indices of keypoints that belong to the cluster. This means that ``pointIdxsOfClusters[i]`` are keypoint indices that belong to the ``i`` -th cluster (word of vocabulary) returned if it is non-zero.
-
- :param descriptors: Descriptors of the image keypoints that are returned if they are non-zero.
-
-
-
-BOWImgDescriptorExtractor::descriptorSize
----------------------------------------------
-Returns an image descriptor size if the vocabulary is set. Otherwise, it returns 0.
-
-.. ocv:function:: int BOWImgDescriptorExtractor::descriptorSize() const
-
-
-
-BOWImgDescriptorExtractor::descriptorType
----------------------------------------------
-
-Returns an image descriptor type.
-
-.. ocv:function:: int BOWImgDescriptorExtractor::descriptorType() const
+++ /dev/null
-********************************************************
-flann. Clustering and Search in Multi-Dimensional Spaces
-********************************************************
-
-.. toctree::
- :maxdepth: 2
-
- flann_fast_approximate_nearest_neighbor_search
- flann_clustering
+++ /dev/null
-Clustering
-==========
-
-.. highlight:: cpp
-
-flann::hierarchicalClustering<Distance>
---------------------------------------------
-Clusters features using hierarchical k-means algorithm.
-
-.. ocv:function:: template<typename Distance> int flann::hierarchicalClustering(const Mat& features, Mat& centers, const cvflann::KMeansIndexParams& params, Distance d = Distance())
-
- :param features: The points to be clustered. The matrix must have elements of type ``Distance::ElementType``.
-
- :param centers: The centers of the clusters obtained. The matrix must have type ``Distance::ResultType``. The number of rows in this matrix represents the number of clusters desired, however, because of the way the cut in the hierarchical tree is chosen, the number of clusters computed will be the highest number of the form ``(branching-1)*k+1`` that's lower than the number of clusters desired, where ``branching`` is the tree's branching factor (see description of the KMeansIndexParams).
-
- :param params: Parameters used in the construction of the hierarchical k-means tree.
-
- :param d: Distance to be used for clustering.
-
-The method clusters the given feature vectors by constructing a hierarchical k-means tree and choosing a cut in the tree that minimizes the cluster's variance. It returns the number of clusters found.
+++ /dev/null
-Fast Approximate Nearest Neighbor Search
-========================================
-
-.. highlight:: cpp
-
-
-This section documents OpenCV's interface to the FLANN library. FLANN (Fast Library for Approximate Nearest Neighbors) is a library that contains a collection of algorithms optimized for fast nearest neighbor search in large datasets and for high dimensional features. More information about FLANN can be found in [Muja2009]_ .
-
-.. [Muja2009] Marius Muja, David G. Lowe. Fast Approximate Nearest Neighbors with Automatic Algorithm Configuration, 2009
-
-flann::Index\_
------------------
-
-.. ocv:class:: flann::Index_
-
-The FLANN nearest neighbor index class. This class is templated with the type of elements for which the index is built.
-
-
-flann::Index_<T>::Index\_
---------------------------
-Constructs a nearest neighbor search index for a given dataset.
-
-.. ocv:function:: flann::Index_<T>::Index_(const Mat& features, const IndexParams& params)
-
- :param features: Matrix of containing the features(points) to index. The size of the matrix is ``num_features x feature_dimensionality`` and the data type of the elements in the matrix must coincide with the type of the index.
-
- :param params: Structure containing the index parameters. The type of index that will be constructed depends on the type of this parameter. See the description.
-
-The method constructs a fast search structure from a set of features using the specified algorithm with specified parameters, as defined by ``params``. ``params`` is a reference to one of the following class ``IndexParams`` descendants:
-
- *
-
- **LinearIndexParams** When passing an object of this type, the index will perform a linear, brute-force search. ::
-
- struct LinearIndexParams : public IndexParams
- {
- };
-
- ..
-
- *
-
- **KDTreeIndexParams** When passing an object of this type the index constructed will consist of a set of randomized kd-trees which will be searched in parallel. ::
-
- struct KDTreeIndexParams : public IndexParams
- {
- KDTreeIndexParams( int trees = 4 );
- };
-
- ..
-
- * **trees** The number of parallel kd-trees to use. Good values are in the range [1..16]
-
- *
-
- **KMeansIndexParams** When passing an object of this type the index constructed will be a hierarchical k-means tree. ::
-
- struct KMeansIndexParams : public IndexParams
- {
- KMeansIndexParams(
- int branching = 32,
- int iterations = 11,
- flann_centers_init_t centers_init = CENTERS_RANDOM,
- float cb_index = 0.2 );
- };
-
- ..
-
- * **branching** The branching factor to use for the hierarchical k-means tree
-
- * **iterations** The maximum number of iterations to use in the k-means clustering stage when building the k-means tree. A value of -1 used here means that the k-means clustering should be iterated until convergence
-
- * **centers_init** The algorithm to use for selecting the initial centers when performing a k-means clustering step. The possible values are ``CENTERS_RANDOM`` (picks the initial cluster centers randomly), ``CENTERS_GONZALES`` (picks the initial centers using Gonzales' algorithm) and ``CENTERS_KMEANSPP`` (picks the initial centers using the algorithm suggested in arthur_kmeanspp_2007 )
-
- * **cb_index** This parameter (cluster boundary index) influences the way exploration is performed in the hierarchical kmeans tree. When ``cb_index`` is zero the next kmeans domain to be explored is chosen to be the one with the closest center. A value greater then zero also takes into account the size of the domain.
-
- *
- **CompositeIndexParams** When using a parameters object of this type the index created combines the randomized kd-trees and the hierarchical k-means tree. ::
-
- struct CompositeIndexParams : public IndexParams
- {
- CompositeIndexParams(
- int trees = 4,
- int branching = 32,
- int iterations = 11,
- flann_centers_init_t centers_init = CENTERS_RANDOM,
- float cb_index = 0.2 );
- };
-
- *
- **LshIndexParams** When using a parameters object of this type the index created uses multi-probe LSH (by ``Multi-Probe LSH: Efficient Indexing for High-Dimensional Similarity Search`` by Qin Lv, William Josephson, Zhe Wang, Moses Charikar, Kai Li., Proceedings of the 33rd International Conference on Very Large Data Bases (VLDB). Vienna, Austria. September 2007) ::
-
- struct LshIndexParams : public IndexParams
- {
- LshIndexParams(
- unsigned int table_number,
- unsigned int key_size,
- unsigned int multi_probe_level );
- };
-
- ..
-
- * **table_number** the number of hash tables to use (between 10 and 30 usually).
-
-
- * **key_size** the size of the hash key in bits (between 10 and 20 usually).
-
-
- * **multi_probe_level** the number of bits to shift to check for neighboring buckets (0 is regular LSH, 2 is recommended).
-
- *
- **AutotunedIndexParams** When passing an object of this type the index created is automatically tuned to offer the best performance, by choosing the optimal index type (randomized kd-trees, hierarchical kmeans, linear) and parameters for the dataset provided. ::
-
- struct AutotunedIndexParams : public IndexParams
- {
- AutotunedIndexParams(
- float target_precision = 0.9,
- float build_weight = 0.01,
- float memory_weight = 0,
- float sample_fraction = 0.1 );
- };
-
- ..
-
- * **target_precision** Is a number between 0 and 1 specifying the percentage of the approximate nearest-neighbor searches that return the exact nearest-neighbor. Using a higher value for this parameter gives more accurate results, but the search takes longer. The optimum value usually depends on the application.
-
-
- * **build_weight** Specifies the importance of the index build time raported to the nearest-neighbor search time. In some applications it's acceptable for the index build step to take a long time if the subsequent searches in the index can be performed very fast. In other applications it's required that the index be build as fast as possible even if that leads to slightly longer search times.
-
-
- * **memory_weight** Is used to specify the tradeoff between time (index build time and search time) and memory used by the index. A value less than 1 gives more importance to the time spent and a value greater than 1 gives more importance to the memory usage.
-
-
- * **sample_fraction** Is a number between 0 and 1 indicating what fraction of the dataset to use in the automatic parameter configuration algorithm. Running the algorithm on the full dataset gives the most accurate results, but for very large datasets can take longer than desired. In such case using just a fraction of the data helps speeding up this algorithm while still giving good approximations of the optimum parameters.
-
- *
- **SavedIndexParams** This object type is used for loading a previously saved index from the disk. ::
-
- struct SavedIndexParams : public IndexParams
- {
- SavedIndexParams( String filename );
- };
-
-
- ..
-
- * **filename** The filename in which the index was saved.
-
-
-flann::Index_<T>::knnSearch
-----------------------------
-Performs a K-nearest neighbor search for a given query point using the index.
-
-.. ocv:function:: void flann::Index_<T>::knnSearch(const vector<T>& query, vector<int>& indices, vector<float>& dists, int knn, const SearchParams& params)
-
-.. ocv:function:: void flann::Index_<T>::knnSearch(const Mat& queries, Mat& indices, Mat& dists, int knn, const SearchParams& params)
-
- :param query: The query point
-
- :param indices: Vector that will contain the indices of the K-nearest neighbors found. It must have at least knn size.
-
- :param dists: Vector that will contain the distances to the K-nearest neighbors found. It must have at least knn size.
-
- :param knn: Number of nearest neighbors to search for.
-
- :param params:
-
- Search parameters ::
-
- struct SearchParams {
- SearchParams(int checks = 32);
- };
-
- ..
-
- * **checks** The number of times the tree(s) in the index should be recursively traversed. A higher value for this parameter would give better search precision, but also take more time. If automatic configuration was used when the index was created, the number of checks required to achieve the specified precision was also computed, in which case this parameter is ignored.
-
-
-flann::Index_<T>::radiusSearch
---------------------------------------
-Performs a radius nearest neighbor search for a given query point.
-
-.. ocv:function:: int flann::Index_<T>::radiusSearch(const vector<T>& query, vector<int>& indices, vector<float>& dists, float radius, const SearchParams& params)
-
-.. ocv:function:: int flann::Index_<T>::radiusSearch(const Mat& query, Mat& indices, Mat& dists, float radius, const SearchParams& params)
-
- :param query: The query point
-
- :param indices: Vector that will contain the indices of the points found within the search radius in decreasing order of the distance to the query point. If the number of neighbors in the search radius is bigger than the size of this vector, the ones that don't fit in the vector are ignored.
-
- :param dists: Vector that will contain the distances to the points found within the search radius
-
- :param radius: The search radius
-
- :param params: Search parameters
-
-
-flann::Index_<T>::save
-------------------------------
-Saves the index to a file.
-
-.. ocv:function:: void flann::Index_<T>::save(String filename)
-
- :param filename: The file to save the index to
-
-
-flann::Index_<T>::getIndexParameters
---------------------------------------------
-Returns the index parameters.
-
-.. ocv:function:: const IndexParams* flann::Index_<T>::getIndexParameters()
-
-The method is useful in the case of auto-tuned indices, when the parameters are chosen during the index construction. Then, the method can be used to retrieve the actual parameter values.
+++ /dev/null
-*************************************
-highgui. High-level GUI and Media I/O
-*************************************
-
-While OpenCV was designed for use in full-scale
-applications and can be used within functionally rich UI frameworks (such as Qt*, WinForms*, or Cocoa*) or without any UI at all, sometimes there it is required to try functionality quickly and visualize the results. This is what the HighGUI module has been designed for.
-
-It provides easy interface to:
-
-* Create and manipulate windows that can display images and "remember" their content (no need to handle repaint events from OS).
-* Add trackbars to the windows, handle simple mouse events as well as keyboard commands.
-
-.. toctree::
- :maxdepth: 2
-
- user_interface
- qt_new_functions
+++ /dev/null
-Qt New Functions
-================
-.. highlight:: cpp
-
-.. image:: pics/qtgui.png
-
-This figure explains new functionality implemented with Qt* GUI. The new GUI provides a statusbar, a toolbar, and a control panel. The control panel can have trackbars and buttonbars attached to it. If you cannot see the control panel, press Ctrl+P or right-click any Qt window and select **Display properties window**.
-
-*
- To attach a trackbar, the window name parameter must be NULL.
-
-*
- To attach a buttonbar, a button must be created.
- If the last bar attached to the control panel is a buttonbar, the new button is added to the right of the last button.
- If the last bar attached to the control panel is a trackbar, or the control panel is empty, a new buttonbar is created. Then, a new button is attached to it.
-
-See below the example used to generate the figure: ::
-
- int main(int argc, char *argv[])
- int value = 50;
- int value2 = 0;
-
- cvNamedWindow("main1",CV_WINDOW_NORMAL);
- cvNamedWindow("main2",CV_WINDOW_AUTOSIZE | CV_GUI_NORMAL);
-
- cvCreateTrackbar( "track1", "main1", &value, 255, NULL);//OK tested
- char* nameb1 = "button1";
- char* nameb2 = "button2";
- cvCreateButton(nameb1,callbackButton,nameb1,CV_CHECKBOX,1);
-
- cvCreateButton(nameb2,callbackButton,nameb2,CV_CHECKBOX,0);
- cvCreateTrackbar( "track2", NULL, &value2, 255, NULL);
- cvCreateButton("button5",callbackButton1,NULL,CV_RADIOBOX,0);
- cvCreateButton("button6",callbackButton2,NULL,CV_RADIOBOX,1);
-
- cvSetMouseCallback( "main2",on_mouse,NULL );
-
- IplImage* img1 = cvLoadImage("files/flower.jpg");
- IplImage* img2 = cvCreateImage(cvGetSize(img1),8,3);
- CvCapture* video = cvCaptureFromFile("files/hockey.avi");
- IplImage* img3 = cvCreateImage(cvGetSize(cvQueryFrame(video)),8,3);
-
- while(cvWaitKey(33) != 27)
- {
- cvAddS(img1,cvScalarAll(value),img2);
- cvAddS(cvQueryFrame(video),cvScalarAll(value2),img3);
- cvShowImage("main1",img2);
- cvShowImage("main2",img3);
- }
-
- cvDestroyAllWindows();
- cvReleaseImage(&img1);
- cvReleaseImage(&img2);
- cvReleaseImage(&img3);
- cvReleaseCapture(&video);
- return 0;
- }
-
-
-setWindowProperty
----------------------
-Changes parameters of a window dynamically.
-
-.. ocv:function:: void setWindowProperty( const String& winname, int prop_id, double prop_value )
-
-.. ocv:pyfunction:: cv2.setWindowProperty(winname, prop_id, prop_value) -> None
-
-.. ocv:cfunction:: void cvSetWindowProperty( const char* name, int prop_id, double prop_value )
-
- :param name: Name of the window.
-
- :param prop_id: Window property to edit. The following operation flags are available:
-
- * **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
-
- * **CV_WND_PROP_AUTOSIZE** Change if the window is resizable (``CV_WINDOW_NORMAL`` or ``CV_WINDOW_AUTOSIZE`` ).
-
- * **CV_WND_PROP_ASPECTRATIO** Change if the aspect ratio of the image is preserved ( ``CV_WINDOW_FREERATIO`` or ``CV_WINDOW_KEEPRATIO`` ).
-
-
- :param prop_value: New value of the window property. The following operation flags are available:
-
- * **CV_WINDOW_NORMAL** Change the window to normal size or make the window resizable.
-
- * **CV_WINDOW_AUTOSIZE** Constrain the size by the displayed image. The window is not resizable.
-
- * **CV_WINDOW_FULLSCREEN** Change the window to fullscreen.
-
- * **CV_WINDOW_FREERATIO** Make the window resizable without any ratio constraints.
-
- * **CV_WINDOW_KEEPRATIO** Make the window resizable, but preserve the proportions of the displayed image.
-
-
-The function ``setWindowProperty`` enables changing properties of a window.
-
-getWindowProperty
----------------------
-Provides parameters of a window.
-
-.. ocv:function:: double getWindowProperty( const String& winname, int prop_id )
-
-.. ocv:pyfunction:: cv2.getWindowProperty(winname, prop_id) -> retval
-
-.. ocv:cfunction:: double cvGetWindowProperty( const char* name, int prop_id )
-
- :param name: Name of the window.
-
- :param prop_id: Window property to retrieve. The following operation flags are available:
-
- * **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
-
- * **CV_WND_PROP_AUTOSIZE** Change if the window is resizable (``CV_WINDOW_NORMAL`` or ``CV_WINDOW_AUTOSIZE`` ).
-
- * **CV_WND_PROP_ASPECTRATIO** Change if the aspect ratio of the image is preserved (``CV_WINDOW_FREERATIO`` or ``CV_WINDOW_KEEPRATIO`` ).
-
-
-See
-:ocv:func:`setWindowProperty` to know the meaning of the returned values.
-
-The function ``getWindowProperty`` returns properties of a window.
-
-fontQt
-----------
-Creates the font to draw a text on an image.
-
-.. ocv:function:: QtFont fontQt( const String& nameFont, int pointSize=-1, Scalar color=Scalar::all(0), int weight=QT_FONT_NORMAL, int style=QT_STYLE_NORMAL, int spacing=0 )
-
-.. ocv:cfunction:: CvFont cvFontQt(const char* nameFont, int pointSize=-1, CvScalar color=cvScalarAll(0), int weight=CV_FONT_NORMAL, int style=CV_STYLE_NORMAL, int spacing=0)
-
- :param nameFont: Name of the font. The name should match the name of a system font (such as *Times*). If the font is not found, a default one is used.
-
- :param pointSize: Size of the font. If not specified, equal zero or negative, the point size of the font is set to a system-dependent default value. Generally, this is 12 points.
-
- :param color: Color of the font in BGRA where A = 255 is fully transparent. Use the macro ``CV _ RGB`` for simplicity.
-
- :param weight: Font weight. The following operation flags are available:
-
- * **CV_FONT_LIGHT** Weight of 25
-
- * **CV_FONT_NORMAL** Weight of 50
-
- * **CV_FONT_DEMIBOLD** Weight of 63
-
- * **CV_FONT_BOLD** Weight of 75
-
- * **CV_FONT_BLACK** Weight of 87
-
- You can also specify a positive integer for better control.
-
- :param style: Font style. The following operation flags are available:
-
- * **CV_STYLE_NORMAL** Normal font
-
- * **CV_STYLE_ITALIC** Italic font
-
- * **CV_STYLE_OBLIQUE** Oblique font
-
- :param spacing: Spacing between characters. It can be negative or positive.
-
-The function ``fontQt`` creates a ``CvFont`` object. This ``CvFont`` is not compatible with ``putText`` .
-
-A basic usage of this function is the following: ::
-
- CvFont font = fontQt(''Times'');
- addText( img1, ``Hello World !'', Point(50,50), font);
-
-
-addText
------------
-Creates the font to draw a text on an image.
-
-.. ocv:function:: void addText( const Mat& img, const String& text, Point org, const QtFont& font )
-
-.. ocv:cfunction:: void cvAddText( const CvArr* img, const char* text, CvPoint org, CvFont * arg2 )
-
- :param img: 8-bit 3-channel image where the text should be drawn.
-
- :param text: Text to write on an image.
-
- :param org: Point(x,y) where the text should start on an image.
-
- :param font: Font to use to draw a text.
-
-The function ``addText`` draws
-*text*
-on an image
-*img*
-using a specific font
-*font*
-(see example :ocv:func:`fontQt` )
-
-.. index:: displayOverlay
-
-displayOverlay
-------------------
-Displays a text on a window image as an overlay for a specified duration.
-
-.. ocv:function:: void displayOverlay( const String& winname, const String& text, int delayms=0 )
-
-.. ocv:cfunction:: void cvDisplayOverlay(const char* name, const char* text, int delayms = 0)
-
- :param name: Name of the window.
-
- :param text: Overlay text to write on a window image.
-
- :param delayms: The period (in milliseconds), during which the overlay text is displayed. If this function is called before the previous overlay text timed out, the timer is restarted and the text is updated. If this value is zero, the text never disappears.
-
-The function ``displayOverlay`` displays useful information/tips on top of the window for a certain amount of time *delayms*. The function does not modify the image, displayed in the window, that is, after the specified delay the original content of the window is restored.
-
-
-displayStatusBar
---------------------
-Displays a text on the window statusbar during the specified period of time.
-
-.. ocv:function:: void displayStatusBar( const String& winname, const String& text, int delayms=0 )
-
-.. ocv:cfunction:: void cvDisplayStatusBar(const char* name, const char* text, int delayms = 0)
-
- :param name: Name of the window.
-
- :param text: Text to write on the window statusbar.
-
- :param delayms: Duration (in milliseconds) to display the text. If this function is called before the previous text timed out, the timer is restarted and the text is updated. If this value is zero, the text never disappears.
-
-The function ``displayOverlay`` displays useful information/tips on top of the window for a certain amount of time
-*delayms*
-. This information is displayed on the window statusbar (the window must be created with the ``CV_GUI_EXPANDED`` flags).
-
-setOpenGlDrawCallback
-------------------------
-Sets a callback function to be called to draw on top of displayed image.
-
-.. ocv:function:: void setOpenGlDrawCallback( const String& winname, OpenGlDrawCallback onOpenGlDraw, void* userdata=0 )
-
-.. ocv:cfunction:: void cvSetOpenGlDrawCallback( const char* window_name, CvOpenGlDrawCallback callback, void* userdata=NULL )
-
- :param window_name: Name of the window.
-
- :param onOpenGlDraw: Pointer to the function to be called every frame. This function should be prototyped as ``void Foo(void*)`` .
-
- :param userdata: Pointer passed to the callback function. *(Optional)*
-
-The function ``setOpenGlDrawCallback`` can be used to draw 3D data on the window. See the example of callback function below: ::
-
- void on_opengl(void* param)
- {
- glLoadIdentity();
-
- glTranslated(0.0, 0.0, -1.0);
-
- glRotatef( 55, 1, 0, 0 );
- glRotatef( 45, 0, 1, 0 );
- glRotatef( 0, 0, 0, 1 );
-
- static const int coords[6][4][3] = {
- { { +1, -1, -1 }, { -1, -1, -1 }, { -1, +1, -1 }, { +1, +1, -1 } },
- { { +1, +1, -1 }, { -1, +1, -1 }, { -1, +1, +1 }, { +1, +1, +1 } },
- { { +1, -1, +1 }, { +1, -1, -1 }, { +1, +1, -1 }, { +1, +1, +1 } },
- { { -1, -1, -1 }, { -1, -1, +1 }, { -1, +1, +1 }, { -1, +1, -1 } },
- { { +1, -1, +1 }, { -1, -1, +1 }, { -1, -1, -1 }, { +1, -1, -1 } },
- { { -1, -1, +1 }, { +1, -1, +1 }, { +1, +1, +1 }, { -1, +1, +1 } }
- };
-
- for (int i = 0; i < 6; ++i) {
- glColor3ub( i*20, 100+i*10, i*42 );
- glBegin(GL_QUADS);
- for (int j = 0; j < 4; ++j) {
- glVertex3d(0.2 * coords[i][j][0], 0.2 * coords[i][j][1], 0.2 * coords[i][j][2]);
- }
- glEnd();
- }
- }
-
-
-saveWindowParameters
-------------------------
-Saves parameters of the specified window.
-
-.. ocv:function:: void saveWindowParameters( const String& windowName )
-
-.. ocv:cfunction:: void cvSaveWindowParameters(const char* name)
-
- :param name: Name of the window.
-
-The function ``saveWindowParameters`` saves size, location, flags, trackbars value, zoom and panning location of the window
-``window_name`` .
-
-loadWindowParameters
-------------------------
-Loads parameters of the specified window.
-
-.. ocv:function:: void loadWindowParameters( const String& windowName )
-
-.. ocv:cfunction:: void cvLoadWindowParameters(const char* name)
-
- :param name: Name of the window.
-
-The function ``loadWindowParameters`` loads size, location, flags, trackbars value, zoom and panning location of the window
-``window_name`` .
-
-createButton
-----------------
-Attaches a button to the control panel.
-
-.. ocv:function:: int createButton( const String& bar_name, ButtonCallback on_change, void* userdata=0, int type=QT_PUSH_BUTTON, bool initial_button_state=false )
-
-.. ocv:cfunction:: int cvCreateButton( const char* button_name=NULL, CvButtonCallback on_change=NULL, void* userdata=NULL, int button_type=CV_PUSH_BUTTON, int initial_button_state=0 )
-
- :param button_name: Name of the button.
-
- :param on_change: Pointer to the function to be called every time the button changes its state. This function should be prototyped as ``void Foo(int state,*void);`` . *state* is the current state of the button. It could be -1 for a push button, 0 or 1 for a check/radio box button.
-
- :param userdata: Pointer passed to the callback function.
-
- :param button_type: Optional type of the button.
-
- * **CV_PUSH_BUTTON** Push button
-
- * **CV_CHECKBOX** Checkbox button
-
- * **CV_RADIOBOX** Radiobox button. The radiobox on the same buttonbar (same line) are exclusive, that is only one can be selected at a time.
-
- :param initial_button_state: Default state of the button. Use for checkbox and radiobox. Its value could be 0 or 1. *(Optional)*
-
-The function ``createButton`` attaches a button to the control panel. Each button is added to a buttonbar to the right of the last button.
-A new buttonbar is created if nothing was attached to the control panel before, or if the last element attached to the control panel was a trackbar.
-
-See below various examples of the ``createButton`` function call: ::
-
- createButton(NULL,callbackButton);//create a push button "button 0", that will call callbackButton.
- createButton("button2",callbackButton,NULL,CV_CHECKBOX,0);
- createButton("button3",callbackButton,&value);
- createButton("button5",callbackButton1,NULL,CV_RADIOBOX);
- createButton("button6",callbackButton2,NULL,CV_PUSH_BUTTON,1);
-
-..
+++ /dev/null
-User Interface
-==============
-
-.. highlight:: cpp
-
-createTrackbar
-------------------
-Creates a trackbar and attaches it to the specified window.
-
-.. ocv:function:: int createTrackbar( const String& trackbarname, const String& winname, int* value, int count, TrackbarCallback onChange=0, void* userdata=0)
-
-.. ocv:pyfunction:: cv2.createTrackbar(trackbarName, windowName, value, count, onChange) -> None
-
-.. ocv:cfunction:: int cvCreateTrackbar( const char* trackbar_name, const char* window_name, int* value, int count, CvTrackbarCallback on_change=NULL )
-
- :param trackbarname: Name of the created trackbar.
-
- :param winname: Name of the window that will be used as a parent of the created trackbar.
-
- :param value: Optional pointer to an integer variable whose value reflects the position of the slider. Upon creation, the slider position is defined by this variable.
-
- :param count: Maximal position of the slider. The minimal position is always 0.
-
- :param onChange: Pointer to the function to be called every time the slider changes position. This function should be prototyped as ``void Foo(int,void*);`` , where the first parameter is the trackbar position and the second parameter is the user data (see the next parameter). If the callback is the NULL pointer, no callbacks are called, but only ``value`` is updated.
-
- :param userdata: User data that is passed as is to the callback. It can be used to handle trackbar events without using global variables.
-
-The function ``createTrackbar`` creates a trackbar (a slider or range control) with the specified name and range, assigns a variable ``value`` to be a position synchronized with the trackbar and specifies the callback function ``onChange`` to be called on the trackbar position change. The created trackbar is displayed in the specified window ``winname``.
-
-.. note::
-
- **[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar should be attached to the control panel.
-
-Clicking the label of each trackbar enables editing the trackbar values manually.
-
-.. note::
-
- * An example of using the trackbar functionality can be found at opencv_source_code/samples/cpp/connected_components.cpp
-
-getTrackbarPos
-------------------
-Returns the trackbar position.
-
-.. ocv:function:: int getTrackbarPos( const String& trackbarname, const String& winname )
-
-.. ocv:pyfunction:: cv2.getTrackbarPos(trackbarname, winname) -> retval
-
-.. ocv:cfunction:: int cvGetTrackbarPos( const char* trackbar_name, const char* window_name )
-
- :param trackbarname: Name of the trackbar.
-
- :param winname: Name of the window that is the parent of the trackbar.
-
-The function returns the current position of the specified trackbar.
-
-.. note::
-
- **[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar is attached to the control panel.
-
-imshow
-----------
-Displays an image in the specified window.
-
-.. ocv:function:: void imshow( const String& winname, InputArray mat )
-
-.. ocv:pyfunction:: cv2.imshow(winname, mat) -> None
-
-.. ocv:cfunction:: void cvShowImage( const char* name, const CvArr* image )
-
- :param winname: Name of the window.
-
- :param image: Image to be shown.
-
-The function ``imshow`` displays an image in the specified window. If the window was created with the ``CV_WINDOW_AUTOSIZE`` flag, the image is shown with its original size. Otherwise, the image is scaled to fit the window. The function may scale the image, depending on its depth:
-
- * If the image is 8-bit unsigned, it is displayed as is.
-
- * If the image is 16-bit unsigned or 32-bit integer, the pixels are divided by 256. That is, the value range [0,255*256] is mapped to [0,255].
-
- * If the image is 32-bit floating-point, the pixel values are multiplied by 255. That is, the value range [0,1] is mapped to [0,255].
-
-If window was created with OpenGL support, ``imshow`` also support :ocv:class:`ogl::Buffer` , :ocv:class:`ogl::Texture2D` and :ocv:class:`cuda::GpuMat` as input.
-
-.. note:: This function should be followed by ``waitKey`` function which displays the image for specified milliseconds. Otherwise, it won't display the image. For example, ``waitKey(0)`` will display the window infinitely until any keypress (it is suitable for image display). ``waitKey(25)`` will display a frame for 25 ms, after which display will be automatically closed. (If you put it in a loop to read videos, it will display the video frame-by-frame)
-
-.. note::
-
- [Windows Backend Only] Pressing Ctrl+C will copy the image to the clipboard.
-
-namedWindow
----------------
-Creates a window.
-
-.. ocv:function:: void namedWindow( const String& winname, int flags=WINDOW_AUTOSIZE )
-
-.. ocv:pyfunction:: cv2.namedWindow(winname[, flags]) -> None
-
-.. ocv:cfunction:: int cvNamedWindow( const char* name, int flags=CV_WINDOW_AUTOSIZE )
-
- :param name: Name of the window in the window caption that may be used as a window identifier.
-
- :param flags: Flags of the window. The supported flags are:
-
- * **WINDOW_NORMAL** If this is set, the user can resize the window (no constraint).
-
- * **WINDOW_AUTOSIZE** If this is set, the window size is automatically adjusted to fit the displayed image (see :ocv:func:`imshow` ), and you cannot change the window size manually.
-
- * **WINDOW_OPENGL** If this is set, the window will be created with OpenGL support.
-
-The function ``namedWindow`` creates a window that can be used as a placeholder for images and trackbars. Created windows are referred to by their names.
-
-If a window with the same name already exists, the function does nothing.
-
-You can call :ocv:func:`destroyWindow` or :ocv:func:`destroyAllWindows` to close the window and de-allocate any associated memory usage. For a simple program, you do not really have to call these functions because all the resources and windows of the application are closed automatically by the operating system upon exit.
-
-.. note::
-
- Qt backend supports additional flags:
-
- * **CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE:** ``CV_WINDOW_NORMAL`` enables you to resize the window, whereas ``CV_WINDOW_AUTOSIZE`` adjusts automatically the window size to fit the displayed image (see :ocv:func:`imshow` ), and you cannot change the window size manually.
-
- * **CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO:** ``CV_WINDOW_FREERATIO`` adjusts the image with no respect to its ratio, whereas ``CV_WINDOW_KEEPRATIO`` keeps the image ratio.
-
- * **CV_GUI_NORMAL or CV_GUI_EXPANDED:** ``CV_GUI_NORMAL`` is the old way to draw the window without statusbar and toolbar, whereas ``CV_GUI_EXPANDED`` is a new enhanced GUI.
-
- By default, ``flags == CV_WINDOW_AUTOSIZE | CV_WINDOW_KEEPRATIO | CV_GUI_EXPANDED``
-
-
-destroyWindow
--------------
-Destroys a window.
-
-.. ocv:function:: void destroyWindow( const String& winname )
-
-.. ocv:pyfunction:: cv2.destroyWindow(winname) -> None
-
-.. ocv:cfunction:: void cvDestroyWindow( const char* name )
-
- :param winname: Name of the window to be destroyed.
-
-The function ``destroyWindow`` destroys the window with the given name.
-
-
-destroyAllWindows
------------------
-Destroys all of the HighGUI windows.
-
-.. ocv:function:: void destroyAllWindows()
-
-.. ocv:pyfunction:: cv2.destroyAllWindows() -> None
-
-.. ocv:cfunction:: void cvDestroyAllWindows()
-
-The function ``destroyAllWindows`` destroys all of the opened HighGUI windows.
-
-
-MoveWindow
-----------
-Moves window to the specified position
-
-.. ocv:function:: void moveWindow( const String& winname, int x, int y )
-
-.. ocv:pyfunction:: cv2.moveWindow(winname, x, y) -> None
-
-.. ocv:cfunction:: void cvMoveWindow( const char* name, int x, int y )
-
- :param winname: Window name
-
- :param x: The new x-coordinate of the window
-
- :param y: The new y-coordinate of the window
-
-
-ResizeWindow
-------------
-Resizes window to the specified size
-
-.. ocv:function:: void resizeWindow( const String& winname, int width, int height )
-
-.. ocv:pyfunction:: cv2.resizeWindow(winname, width, height) -> None
-
-.. ocv:cfunction:: void cvResizeWindow( const char* name, int width, int height )
-
- :param winname: Window name
-
- :param width: The new window width
-
- :param height: The new window height
-
-.. note::
-
- * The specified window size is for the image area. Toolbars are not counted.
-
- * Only windows created without CV_WINDOW_AUTOSIZE flag can be resized.
-
-
-SetMouseCallback
-----------------
-Sets mouse handler for the specified window
-
-.. ocv:function:: void setMouseCallback( const String& winname, MouseCallback onMouse, void* userdata=0 )
-
-.. ocv:pyfunction:: cv2.setMouseCallback(windowName, onMouse [, param]) -> None
-
-.. ocv:cfunction:: void cvSetMouseCallback( const char* window_name, CvMouseCallback on_mouse, void* param=NULL )
-
- :param winname: Window name
-
- :param onMouse: Mouse callback. See OpenCV samples, such as https://github.com/Itseez/opencv/tree/master/samples/cpp/ffilldemo.cpp, on how to specify and use the callback.
-
- :param userdata: The optional parameter passed to the callback.
-
-
-getMouseWheelDelta
-------------------
-Gets the mouse-wheel motion delta, when handling mouse-wheel events EVENT_MOUSEWHEEL and EVENT_MOUSEHWHEEL.
-
-.. ocv:function:: int getMouseWheelDelta(int flags)
-
- :param flags: The mouse callback flags parameter.
-
-For regular mice with a scroll-wheel, delta will be a multiple of 120. The value 120 corresponds to a one notch rotation of the wheel or the threshold for action to be taken and one such action should occur for each delta.
-Some high-precision mice with higher-resolution freely-rotating wheels may generate smaller values.
-
-For EVENT_MOUSEWHEEL positive and negative values mean forward and backward scrolling, respectively.
-For EVENT_MOUSEHWHEEL, where available, positive and negative values mean right and left scrolling, respectively.
-
-With the C API, the macro CV_GET_WHEEL_DELTA(flags) can be used alternatively.
-
-.. note::
-
- Mouse-wheel events are currently supported only on Windows.
-
-setTrackbarPos
-------------------
-Sets the trackbar position.
-
-.. ocv:function:: void setTrackbarPos( const String& trackbarname, const String& winname, int pos )
-
-.. ocv:pyfunction:: cv2.setTrackbarPos(trackbarname, winname, pos) -> None
-
-.. ocv:cfunction:: void cvSetTrackbarPos( const char* trackbar_name, const char* window_name, int pos )
-
- :param trackbarname: Name of the trackbar.
-
- :param winname: Name of the window that is the parent of trackbar.
-
- :param pos: New position.
-
-The function sets the position of the specified trackbar in the specified window.
-
-.. note::
-
- **[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar is attached to the control panel.
-
-waitKey
------------
-Waits for a pressed key.
-
-.. ocv:function:: int waitKey(int delay=0)
-
-.. ocv:pyfunction:: cv2.waitKey([delay]) -> retval
-
-.. ocv:cfunction:: int cvWaitKey( int delay=0 )
-
- :param delay: Delay in milliseconds. 0 is the special value that means "forever".
-
-The function ``waitKey`` waits for a key event infinitely (when
-:math:`\texttt{delay}\leq 0` ) or for ``delay`` milliseconds, when it is positive. Since the OS has a minimum time between switching threads, the function will not wait exactly ``delay`` ms, it will wait at least ``delay`` ms, depending on what else is running on your computer at that time. It returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
-
-.. note::
-
- This function is the only method in HighGUI that can fetch and handle events, so it needs to be called periodically for normal event processing unless HighGUI is used within an environment that takes care of event processing.
-
-.. note::
-
- The function only works if there is at least one HighGUI window created and the window is active. If there are several HighGUI windows, any of them can be active.
-
-setOpenGlDrawCallback
----------------------
-Set OpenGL render handler for the specified window.
-
-.. ocv:function:: void setOpenGlDrawCallback(const string& winname, OpenGlDrawCallback onOpenGlDraw, void* userdata = 0)
-
- :param winname: Window name
-
- :param onOpenGlDraw: Draw callback.
-
- :param userdata: The optional parameter passed to the callback.
-
-setOpenGlContext
-----------------
-Sets the specified window as current OpenGL context.
-
-.. ocv:function:: void setOpenGlContext(const String& winname)
-
- :param winname: Window name
-
-updateWindow
-------------
-Force window to redraw its context and call draw callback ( :ocv:func:`setOpenGlDrawCallback` ).
-
-.. ocv:function:: void updateWindow(const String& winname)
-
- :param winname: Window name
+++ /dev/null
-*****************************************
-imgcodecs. Image file reading and writing
-*****************************************
-
-This module of the OpenCV help you read and write images to/from disk or memory.
-
-.. toctree::
- :maxdepth: 2
-
- reading_and_writing_images
+++ /dev/null
-Reading and Writing Images
-==========================
-
-.. highlight:: cpp
-
-imdecode
---------
-Reads an image from a buffer in memory.
-
-.. ocv:function:: Mat imdecode( InputArray buf, int flags )
-
-.. ocv:function:: Mat imdecode( InputArray buf, int flags, Mat* dst )
-
-.. ocv:cfunction:: IplImage* cvDecodeImage( const CvMat* buf, int iscolor=CV_LOAD_IMAGE_COLOR)
-
-.. ocv:cfunction:: CvMat* cvDecodeImageM( const CvMat* buf, int iscolor=CV_LOAD_IMAGE_COLOR)
-
-.. ocv:pyfunction:: cv2.imdecode(buf, flags) -> retval
-
- :param buf: Input array or vector of bytes.
-
- :param flags: The same flags as in :ocv:func:`imread` .
-
- :param dst: The optional output placeholder for the decoded matrix. It can save the image reallocations when the function is called repeatedly for images of the same size.
-
-The function reads an image from the specified buffer in the memory.
-If the buffer is too short or contains invalid data, the empty matrix/image is returned.
-
-See
-:ocv:func:`imread` for the list of supported formats and flags description.
-
-.. note:: In the case of color images, the decoded images will have the channels stored in ``B G R`` order.
-
-imencode
---------
-Encodes an image into a memory buffer.
-
-.. ocv:function:: bool imencode( const String& ext, InputArray img, vector<uchar>& buf, const vector<int>& params=vector<int>())
-
-.. ocv:cfunction:: CvMat* cvEncodeImage( const char* ext, const CvArr* image, const int* params=0 )
-
-.. ocv:pyfunction:: cv2.imencode(ext, img[, params]) -> retval, buf
-
- :param ext: File extension that defines the output format.
-
- :param img: Image to be written.
-
- :param buf: Output buffer resized to fit the compressed image.
-
- :param params: Format-specific parameters. See :ocv:func:`imwrite` .
-
-The function compresses the image and stores it in the memory buffer that is resized to fit the result.
-See
-:ocv:func:`imwrite` for the list of supported formats and flags description.
-
-.. note:: ``cvEncodeImage`` returns single-row matrix of type ``CV_8UC1`` that contains encoded image as array of bytes.
-
-imread
-------
-Loads an image from a file.
-
-.. ocv:function:: Mat imread( const String& filename, int flags=IMREAD_COLOR )
-
-.. ocv:pyfunction:: cv2.imread(filename[, flags]) -> retval
-
-.. ocv:cfunction:: IplImage* cvLoadImage( const char* filename, int iscolor=CV_LOAD_IMAGE_COLOR )
-
-.. ocv:cfunction:: CvMat* cvLoadImageM( const char* filename, int iscolor=CV_LOAD_IMAGE_COLOR )
-
- :param filename: Name of file to be loaded.
-
- :param flags: Flags specifying the color type of a loaded image:
-
- * CV_LOAD_IMAGE_ANYDEPTH - If set, return 16-bit/32-bit image when the input has the corresponding depth, otherwise convert it to 8-bit.
-
- * CV_LOAD_IMAGE_COLOR - If set, always convert image to the color one
-
- * CV_LOAD_IMAGE_GRAYSCALE - If set, always convert image to the grayscale one
-
- * **>0** Return a 3-channel color image.
- .. note:: In the current implementation the alpha channel, if any, is stripped from the output image. Use negative value if you need the alpha channel.
-
- * **=0** Return a grayscale image.
-
- * **<0** Return the loaded image as is (with alpha channel).
-
-The function ``imread`` loads an image from the specified file and returns it. If the image cannot be read (because of missing file, improper permissions, unsupported or invalid format), the function returns an empty matrix ( ``Mat::data==NULL`` ). Currently, the following file formats are supported:
-
- * Windows bitmaps - ``*.bmp, *.dib`` (always supported)
-
- * JPEG files - ``*.jpeg, *.jpg, *.jpe`` (see the *Notes* section)
-
- * JPEG 2000 files - ``*.jp2`` (see the *Notes* section)
-
- * Portable Network Graphics - ``*.png`` (see the *Notes* section)
-
- * WebP - ``*.webp`` (see the *Notes* section)
-
- * Portable image format - ``*.pbm, *.pgm, *.ppm`` (always supported)
-
- * Sun rasters - ``*.sr, *.ras`` (always supported)
-
- * TIFF files - ``*.tiff, *.tif`` (see the *Notes* section)
-
-.. note::
-
- * The function determines the type of an image by the content, not by the file extension.
-
- * On Microsoft Windows* OS and MacOSX*, the codecs shipped with an OpenCV image (libjpeg, libpng, libtiff, and libjasper) are used by default. So, OpenCV can always read JPEGs, PNGs, and TIFFs. On MacOSX, there is also an option to use native MacOSX image readers. But beware that currently these native image loaders give images with different pixel values because of the color management embedded into MacOSX.
-
- * On Linux*, BSD flavors and other Unix-like open-source operating systems, OpenCV looks for codecs supplied with an OS image. Install the relevant packages (do not forget the development files, for example, "libjpeg-dev", in Debian* and Ubuntu*) to get the codec support or turn on the ``OPENCV_BUILD_3RDPARTY_LIBS`` flag in CMake.
-
-.. note:: In the case of color images, the decoded images will have the channels stored in ``B G R`` order.
-
-imwrite
------------
-Saves an image to a specified file.
-
-.. ocv:function:: bool imwrite( const String& filename, InputArray img, const vector<int>& params=vector<int>() )
-
-.. ocv:pyfunction:: cv2.imwrite(filename, img[, params]) -> retval
-
-.. ocv:cfunction:: int cvSaveImage( const char* filename, const CvArr* image, const int* params=0 )
-
- :param filename: Name of the file.
-
- :param image: Image to be saved.
-
- :param params: Format-specific save parameters encoded as pairs ``paramId_1, paramValue_1, paramId_2, paramValue_2, ...`` . The following parameters are currently supported:
-
- * For JPEG, it can be a quality ( ``CV_IMWRITE_JPEG_QUALITY`` ) from 0 to 100 (the higher is the better). Default value is 95.
-
- * For WEBP, it can be a quality ( CV_IMWRITE_WEBP_QUALITY ) from 1 to 100 (the higher is the better).
- By default (without any parameter) and for quality above 100 the lossless compression is used.
-
- * For PNG, it can be the compression level ( ``CV_IMWRITE_PNG_COMPRESSION`` ) from 0 to 9. A higher value means a smaller size and longer compression time. Default value is 3.
-
- * For PPM, PGM, or PBM, it can be a binary format flag ( ``CV_IMWRITE_PXM_BINARY`` ), 0 or 1. Default value is 1.
-
-The function ``imwrite`` saves the image to the specified file. The image format is chosen based on the ``filename`` extension (see
-:ocv:func:`imread` for the list of extensions). Only 8-bit (or 16-bit unsigned (``CV_16U``) in case of PNG, JPEG 2000, and TIFF) single-channel or 3-channel (with 'BGR' channel order) images can be saved using this function. If the format, depth or channel order is different, use
-:ocv:func:`Mat::convertTo` , and
-:ocv:func:`cvtColor` to convert it before saving. Or, use the universal :ocv:class:`FileStorage` I/O functions to save the image to XML or YAML format.
-
-It is possible to store PNG images with an alpha channel using this function. To do this, create 8-bit (or 16-bit) 4-channel image BGRA, where the alpha channel goes last. Fully transparent pixels should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535. The sample below shows how to create such a BGRA image and store to PNG file. It also demonstrates how to set custom compression parameters ::
-
- #include <vector>
- #include <stdio.h>
- #include <opencv2/opencv.hpp>
-
- using namespace cv;
- using namespace std;
-
- void createAlphaMat(Mat &mat)
- {
- for (int i = 0; i < mat.rows; ++i) {
- for (int j = 0; j < mat.cols; ++j) {
- Vec4b& rgba = mat.at<Vec4b>(i, j);
- rgba[0] = UCHAR_MAX;
- rgba[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX);
- rgba[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX);
- rgba[3] = saturate_cast<uchar>(0.5 * (rgba[1] + rgba[2]));
- }
- }
- }
-
- int main(int argv, char **argc)
- {
- // Create mat with alpha channel
- Mat mat(480, 640, CV_8UC4);
- createAlphaMat(mat);
-
- vector<int> compression_params;
- compression_params.push_back(CV_IMWRITE_PNG_COMPRESSION);
- compression_params.push_back(9);
-
- try {
- imwrite("alpha.png", mat, compression_params);
- }
- catch (runtime_error& ex) {
- fprintf(stderr, "Exception converting image to PNG format: %s\n", ex.what());
- return 1;
- }
-
- fprintf(stdout, "Saved PNG file with alpha data.\n");
- return 0;
- }
+++ /dev/null
-ColorMaps in OpenCV
-===================
-
-applyColorMap
--------------
-
-Applies a GNU Octave/MATLAB equivalent colormap on a given image.
-
-.. ocv:function:: void applyColorMap(InputArray src, OutputArray dst, int colormap)
-
- :param src: The source image, grayscale or colored does not matter.
- :param dst: The result is the colormapped source image. Note: :ocv:func:`Mat::create` is called on dst.
- :param colormap: The colormap to apply, see the list of available colormaps below.
-
-Currently the following GNU Octave/MATLAB equivalent colormaps are implemented:
-
-.. code-block:: cpp
-
- enum
- {
- COLORMAP_AUTUMN = 0,
- COLORMAP_BONE = 1,
- COLORMAP_JET = 2,
- COLORMAP_WINTER = 3,
- COLORMAP_RAINBOW = 4,
- COLORMAP_OCEAN = 5,
- COLORMAP_SUMMER = 6,
- COLORMAP_SPRING = 7,
- COLORMAP_COOL = 8,
- COLORMAP_HSV = 9,
- COLORMAP_PINK = 10,
- COLORMAP_HOT = 11
- }
-
-
-Description
-===========
-
-The human perception isn't built for observing fine changes in grayscale images. Human eyes are more sensitive to observing changes between colors, so you often need to recolor your grayscale images to get a clue about them. OpenCV now comes with various colormaps to enhance the visualization in your computer vision application.
-
-In OpenCV you only need :ocv:func:`applyColorMap` to apply a colormap on a given image. The following sample code reads the path to an image from command line, applies a Jet colormap on it and shows the result:
-
-.. code-block:: cpp
-
- #include <opencv2/core.hpp>
- #include <opencv2/imgproc.hpp>
- #include <opencv2/imgcodecs.hpp>
- #include <opencv2/highgui.hpp>
- using namespace cv;
-
- #include <iostream>
- using namespace std;
-
- int main(int argc, const char *argv[])
- {
- // We need an input image. (can be grayscale or color)
- if (argc < 2)
- {
- cerr << "We need an image to process here. Please run: colorMap [path_to_image]" << endl;
- return -1;
- }
-
- Mat img_in = imread(argv[1]);
-
- if(img_in.empty())
- {
- cerr << "Sample image (" << argv[1] << ") is empty. Please adjust your path, so it points to a valid input image!" << endl;
- return -1;
- }
-
- // Holds the colormap version of the image:
- Mat img_color;
- // Apply the colormap:
- applyColorMap(img_in, img_color, COLORMAP_JET);
- // Show the result:
- imshow("colorMap", img_color);
- waitKey(0);
-
- return 0;
- }
-
-And here are the color scales for each of the available colormaps:
-
-+-----------------------+---------------------------------------------------+
-| Class | Scale |
-+=======================+===================================================+
-| COLORMAP_AUTUMN | .. image:: pics/colormaps/colorscale_autumn.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_BONE | .. image:: pics/colormaps/colorscale_bone.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_COOL | .. image:: pics/colormaps/colorscale_cool.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_HOT | .. image:: pics/colormaps/colorscale_hot.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_HSV | .. image:: pics/colormaps/colorscale_hsv.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_JET | .. image:: pics/colormaps/colorscale_jet.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_OCEAN | .. image:: pics/colormaps/colorscale_ocean.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_PINK | .. image:: pics/colormaps/colorscale_pink.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_RAINBOW | .. image:: pics/colormaps/colorscale_rainbow.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_SPRING | .. image:: pics/colormaps/colorscale_spring.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_SUMMER | .. image:: pics/colormaps/colorscale_summer.jpg |
-+-----------------------+---------------------------------------------------+
-| COLORMAP_WINTER | .. image:: pics/colormaps/colorscale_winter.jpg |
-+-----------------------+---------------------------------------------------+
+++ /dev/null
-Drawing Functions
-=================
-
-.. highlight:: cpp
-
-Drawing functions work with matrices/images of arbitrary depth.
-The boundaries of the shapes can be rendered with antialiasing (implemented only for 8-bit images for now).
-All the functions include the parameter ``color`` that uses an RGB value (that may be constructed
-with the ``Scalar`` constructor
-) for color
-images and brightness for grayscale images. For color images, the channel ordering
-is normally *Blue, Green, Red*.
-This is what :ocv:func:`imshow`, :ocv:func:`imread`, and :ocv:func:`imwrite` expect.
-So, if you form a color using the
-``Scalar`` constructor, it should look like:
-
-.. math::
-
- \texttt{Scalar} (blue \_ component, green \_ component, red \_ component[, alpha \_ component])
-
-If you are using your own image rendering and I/O functions, you can use any channel ordering. The drawing functions process each channel independently and do not depend on the channel order or even on the used color space. The whole image can be converted from BGR to RGB or to a different color space using
-:ocv:func:`cvtColor` .
-
-If a drawn figure is partially or completely outside the image, the drawing functions clip it. Also, many drawing functions can handle pixel coordinates specified with sub-pixel accuracy. This means that the coordinates can be passed as fixed-point numbers encoded as integers. The number of fractional bits is specified by the ``shift`` parameter and the real point coordinates are calculated as
-:math:`\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})` . This feature is especially effective when rendering antialiased shapes.
-
-.. note:: The functions do not support alpha-transparency when the target image is 4-channel. In this case, the ``color[3]`` is simply copied to the repainted pixels. Thus, if you want to paint semi-transparent shapes, you can paint them in a separate buffer and then blend it with the main image.
-
-.. note::
-
- * An example on using variate drawing functions like line, rectangle, ... can be found at opencv_source_code/samples/cpp/drawing.cpp
-
-circle
-----------
-Draws a circle.
-
-.. ocv:function:: void circle( InputOutputArray img, Point center, int radius, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
-
-.. ocv:pyfunction:: cv2.circle(img, center, radius, color[, thickness[, lineType[, shift]]]) -> img
-
-.. ocv:cfunction:: void cvCircle( CvArr* img, CvPoint center, int radius, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
-
- :param img: Image where the circle is drawn.
-
- :param center: Center of the circle.
-
- :param radius: Radius of the circle.
-
- :param color: Circle color.
-
- :param thickness: Thickness of the circle outline, if positive. Negative thickness means that a filled circle is to be drawn.
-
- :param lineType: Type of the circle boundary. See the :ocv:func:`line` description.
-
- :param shift: Number of fractional bits in the coordinates of the center and in the radius value.
-
-The function ``circle`` draws a simple or filled circle with a given center and radius.
-
-clipLine
-------------
-Clips the line against the image rectangle.
-
-.. ocv:function:: bool clipLine(Size imgSize, Point& pt1, Point& pt2)
-
-.. ocv:function:: bool clipLine(Rect imgRect, Point& pt1, Point& pt2)
-
-.. ocv:pyfunction:: cv2.clipLine(imgRect, pt1, pt2) -> retval, pt1, pt2
-
-.. ocv:cfunction:: int cvClipLine( CvSize img_size, CvPoint* pt1, CvPoint* pt2 )
-
- :param imgSize: Image size. The image rectangle is ``Rect(0, 0, imgSize.width, imgSize.height)`` .
-
- :param imgRect: Image rectangle.
-
- :param pt1: First line point.
-
- :param pt2: Second line point.
-
-The functions ``clipLine`` calculate a part of the line segment that is entirely within the specified rectangle.
-They return ``false`` if the line segment is completely outside the rectangle. Otherwise, they return ``true`` .
-
-ellipse
------------
-Draws a simple or thick elliptic arc or fills an ellipse sector.
-
-.. ocv:function:: void ellipse( InputOutputArray img, Point center, Size axes, double angle, double startAngle, double endAngle, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
-
-.. ocv:function:: void ellipse( InputOutputArray img, const RotatedRect& box, const Scalar& color, int thickness=1, int lineType=LINE_8 )
-
-.. ocv:pyfunction:: cv2.ellipse(img, center, axes, angle, startAngle, endAngle, color[, thickness[, lineType[, shift]]]) -> img
-
-.. ocv:pyfunction:: cv2.ellipse(img, box, color[, thickness[, lineType]]) -> img
-
-.. ocv:cfunction:: void cvEllipse( CvArr* img, CvPoint center, CvSize axes, double angle, double start_angle, double end_angle, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
-
-.. ocv:cfunction:: void cvEllipseBox( CvArr* img, CvBox2D box, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
-
- :param img: Image.
-
- :param center: Center of the ellipse.
-
- :param axes: Half of the size of the ellipse main axes.
-
- :param angle: Ellipse rotation angle in degrees.
-
- :param startAngle: Starting angle of the elliptic arc in degrees.
-
- :param endAngle: Ending angle of the elliptic arc in degrees.
-
- :param box: Alternative ellipse representation via :ocv:class:`RotatedRect` or ``CvBox2D``. This means that the function draws an ellipse inscribed in the rotated rectangle.
-
- :param color: Ellipse color.
-
- :param thickness: Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that a filled ellipse sector is to be drawn.
-
- :param lineType: Type of the ellipse boundary. See the :ocv:func:`line` description.
-
- :param shift: Number of fractional bits in the coordinates of the center and values of axes.
-
-The functions ``ellipse`` with less parameters draw an ellipse outline, a filled ellipse, an elliptic arc, or a filled ellipse sector.
-A piecewise-linear curve is used to approximate the elliptic arc boundary. If you need more control of the ellipse rendering, you can retrieve the curve using
-:ocv:func:`ellipse2Poly` and then render it with
-:ocv:func:`polylines` or fill it with
-:ocv:func:`fillPoly` . If you use the first variant of the function and want to draw the whole ellipse, not an arc, pass ``startAngle=0`` and ``endAngle=360`` . The figure below explains the meaning of the parameters.
-
-**Figure 1. Parameters of Elliptic Arc**
-
-.. image:: pics/ellipse.png
-
-ellipse2Poly
-----------------
-Approximates an elliptic arc with a polyline.
-
-.. ocv:function:: void ellipse2Poly( Point center, Size axes, int angle, int arcStart, int arcEnd, int delta, vector<Point>& pts )
-
-.. ocv:pyfunction:: cv2.ellipse2Poly(center, axes, angle, arcStart, arcEnd, delta) -> pts
-
- :param center: Center of the arc.
-
- :param axes: Half of the size of the ellipse main axes. See the :ocv:func:`ellipse` for details.
-
- :param angle: Rotation angle of the ellipse in degrees. See the :ocv:func:`ellipse` for details.
-
- :param arcStart: Starting angle of the elliptic arc in degrees.
-
- :param arcEnd: Ending angle of the elliptic arc in degrees.
-
- :param delta: Angle between the subsequent polyline vertices. It defines the approximation accuracy.
-
- :param pts: Output vector of polyline vertices.
-
-The function ``ellipse2Poly`` computes the vertices of a polyline that approximates the specified elliptic arc. It is used by
-:ocv:func:`ellipse` .
-
-
-fillConvexPoly
-------------------
-Fills a convex polygon.
-
-.. ocv:function:: void fillConvexPoly( Mat& img, const Point* pts, int npts, const Scalar& color, int lineType=LINE_8, int shift=0 )
-
-.. ocv:function:: void fillConvexPoly( InputOutputArray img, InputArray points, const Scalar& color, int lineType=LINE_8, int shift=0 )
-
-.. ocv:pyfunction:: cv2.fillConvexPoly(img, points, color[, lineType[, shift]]) -> img
-
-.. ocv:cfunction:: void cvFillConvexPoly( CvArr* img, const CvPoint* pts, int npts, CvScalar color, int line_type=8, int shift=0 )
-
- :param img: Image.
-
- :param pts: Polygon vertices.
-
- :param npts: Number of polygon vertices.
-
- :param color: Polygon color.
-
- :param lineType: Type of the polygon boundaries. See the :ocv:func:`line` description.
-
- :param shift: Number of fractional bits in the vertex coordinates.
-
-The function ``fillConvexPoly`` draws a filled convex polygon.
-This function is much faster than the function ``fillPoly`` . It can fill not only convex polygons but any monotonic polygon without self-intersections,
-that is, a polygon whose contour intersects every horizontal line (scan line) twice at the most (though, its top-most and/or the bottom edge could be horizontal).
-
-
-
-fillPoly
-------------
-Fills the area bounded by one or more polygons.
-
-.. ocv:function:: void fillPoly( Mat& img, const Point** pts, const int* npts, int ncontours, const Scalar& color, int lineType=LINE_8, int shift=0, Point offset=Point() )
-
-.. ocv:function:: void fillPoly( InputOutputArray img, InputArrayOfArrays pts, const Scalar& color, int lineType=LINE_8, int shift=0, Point offset=Point() )
-
-.. ocv:pyfunction:: cv2.fillPoly(img, pts, color[, lineType[, shift[, offset]]]) -> img
-
-.. ocv:cfunction:: void cvFillPoly( CvArr* img, CvPoint** pts, const int* npts, int contours, CvScalar color, int line_type=8, int shift=0 )
-
- :param img: Image.
-
- :param pts: Array of polygons where each polygon is represented as an array of points.
-
- :param npts: Array of polygon vertex counters.
-
- :param ncontours: Number of contours that bind the filled region.
-
- :param color: Polygon color.
-
- :param lineType: Type of the polygon boundaries. See the :ocv:func:`line` description.
-
- :param shift: Number of fractional bits in the vertex coordinates.
-
- :param offset: Optional offset of all points of the contours.
-
-The function ``fillPoly`` fills an area bounded by several polygonal contours. The function can fill complex areas, for example,
-areas with holes, contours with self-intersections (some of their parts), and so forth.
-
-
-
-getTextSize
----------------
-Calculates the width and height of a text string.
-
-.. ocv:function:: Size getTextSize(const String& text, int fontFace, double fontScale, int thickness, int* baseLine)
-
-.. ocv:pyfunction:: cv2.getTextSize(text, fontFace, fontScale, thickness) -> retval, baseLine
-
-.. ocv:cfunction:: void cvGetTextSize( const char* text_string, const CvFont* font, CvSize* text_size, int* baseline )
-
- :param text: Input text string.
-
- :param text_string: Input text string in C format.
-
- :param fontFace: Font to use. See the :ocv:func:`putText` for details.
-
- :param fontScale: Font scale. See the :ocv:func:`putText` for details.
-
- :param thickness: Thickness of lines used to render the text. See :ocv:func:`putText` for details.
-
- :param baseLine: Output parameter - y-coordinate of the baseline relative to the bottom-most text point.
-
- :param baseline: Output parameter - y-coordinate of the baseline relative to the bottom-most text point.
-
- :param font: Font description in terms of old C API.
-
- :param text_size: Output parameter - The size of a box that contains the specified text.
-
-The function ``getTextSize`` calculates and returns the size of a box that contains the specified text.
-That is, the following code renders some text, the tight box surrounding it, and the baseline: ::
-
- String text = "Funny text inside the box";
- int fontFace = FONT_HERSHEY_SCRIPT_SIMPLEX;
- double fontScale = 2;
- int thickness = 3;
-
- Mat img(600, 800, CV_8UC3, Scalar::all(0));
-
- int baseline=0;
- Size textSize = getTextSize(text, fontFace,
- fontScale, thickness, &baseline);
- baseline += thickness;
-
- // center the text
- Point textOrg((img.cols - textSize.width)/2,
- (img.rows + textSize.height)/2);
-
- // draw the box
- rectangle(img, textOrg + Point(0, baseline),
- textOrg + Point(textSize.width, -textSize.height),
- Scalar(0,0,255));
- // ... and the baseline first
- line(img, textOrg + Point(0, thickness),
- textOrg + Point(textSize.width, thickness),
- Scalar(0, 0, 255));
-
- // then put the text itself
- putText(img, text, textOrg, fontFace, fontScale,
- Scalar::all(255), thickness, 8);
-
-
-InitFont
---------
-Initializes font structure (OpenCV 1.x API).
-
-.. ocv:cfunction:: void cvInitFont( CvFont* font, int font_face, double hscale, double vscale, double shear=0, int thickness=1, int line_type=8 )
-
- :param font: Pointer to the font structure initialized by the function
-
- :param font_face: Font name identifier. Only a subset of Hershey fonts http://sources.isc.org/utils/misc/hershey-font.txt are supported now:
-
- * **CV_FONT_HERSHEY_SIMPLEX** normal size sans-serif font
-
- * **CV_FONT_HERSHEY_PLAIN** small size sans-serif font
-
- * **CV_FONT_HERSHEY_DUPLEX** normal size sans-serif font (more complex than ``CV_FONT_HERSHEY_SIMPLEX`` )
-
- * **CV_FONT_HERSHEY_COMPLEX** normal size serif font
-
- * **CV_FONT_HERSHEY_TRIPLEX** normal size serif font (more complex than ``CV_FONT_HERSHEY_COMPLEX`` )
-
- * **CV_FONT_HERSHEY_COMPLEX_SMALL** smaller version of ``CV_FONT_HERSHEY_COMPLEX``
-
- * **CV_FONT_HERSHEY_SCRIPT_SIMPLEX** hand-writing style font
-
- * **CV_FONT_HERSHEY_SCRIPT_COMPLEX** more complex variant of ``CV_FONT_HERSHEY_SCRIPT_SIMPLEX``
-
- The parameter can be composited from one of the values above and an optional ``CV_FONT_ITALIC`` flag, which indicates italic or oblique font.
-
-
- :param hscale: Horizontal scale. If equal to ``1.0f`` , the characters have the original width depending on the font type. If equal to ``0.5f`` , the characters are of half the original width.
-
-
- :param vscale: Vertical scale. If equal to ``1.0f`` , the characters have the original height depending on the font type. If equal to ``0.5f`` , the characters are of half the original height.
-
-
- :param shear: Approximate tangent of the character slope relative to the vertical line. A zero value means a non-italic font, ``1.0f`` means about a 45 degree slope, etc.
-
-
- :param thickness: Thickness of the text strokes
-
-
- :param line_type: Type of the strokes, see :ocv:func:`line` description
-
-
-The function initializes the font structure that can be passed to text rendering functions.
-
-.. seealso:: :ocv:cfunc:`PutText`
-
-.. _Line:
-
-line
---------
-Draws a line segment connecting two points.
-
-.. ocv:function:: void line( InputOutputArray img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
-
-.. ocv:pyfunction:: cv2.line(img, pt1, pt2, color[, thickness[, lineType[, shift]]]) -> img
-
-.. ocv:cfunction:: void cvLine( CvArr* img, CvPoint pt1, CvPoint pt2, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
-
- :param img: Image.
-
- :param pt1: First point of the line segment.
-
- :param pt2: Second point of the line segment.
-
- :param color: Line color.
-
- :param thickness: Line thickness.
-
- :param lineType: Type of the line:
-
- * **LINE_8** (or omitted) - 8-connected line.
-
- * **LINE_4** - 4-connected line.
-
- * **LINE_AA** - antialiased line.
-
- :param shift: Number of fractional bits in the point coordinates.
-
-The function ``line`` draws the line segment between ``pt1`` and ``pt2`` points in the image. The line is clipped by the image boundaries. For non-antialiased lines with integer coordinates, the 8-connected or 4-connected Bresenham algorithm is used. Thick lines are drawn with rounding endings.
-Antialiased lines are drawn using Gaussian filtering.
-
-
-arrowedLine
-----------------
-Draws a arrow segment pointing from the first point to the second one.
-
-.. ocv:function:: void arrowedLine(InputOutputArray img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=8, int shift=0, double tipLength=0.1)
-
- :param img: Image.
-
- :param pt1: The point the arrow starts from.
-
- :param pt2: The point the arrow points to.
-
- :param color: Line color.
-
- :param thickness: Line thickness.
-
- :param lineType: Type of the line:
-
- * **8** (or omitted) - 8-connected line.
-
- * **4** - 4-connected line.
-
- * **CV_AA** - antialiased line.
-
- :param shift: Number of fractional bits in the point coordinates.
-
- :param tipLength: The length of the arrow tip in relation to the arrow length
-
-The function ``arrowedLine`` draws an arrow between ``pt1`` and ``pt2`` points in the image. See also :ocv:func:`line`.
-
-
-LineIterator
-------------
-.. ocv:class:: LineIterator
-
-Class for iterating pixels on a raster line. ::
-
- class LineIterator
- {
- public:
- // creates iterators for the line connecting pt1 and pt2
- // the line will be clipped on the image boundaries
- // the line is 8-connected or 4-connected
- // If leftToRight=true, then the iteration is always done
- // from the left-most point to the right most,
- // not to depend on the ordering of pt1 and pt2 parameters
- LineIterator(const Mat& img, Point pt1, Point pt2,
- int connectivity=8, bool leftToRight=false);
- // returns pointer to the current line pixel
- uchar* operator *();
- // move the iterator to the next pixel
- LineIterator& operator ++();
- LineIterator operator ++(int);
- Point pos() const;
-
- // internal state of the iterator
- uchar* ptr;
- int err, count;
- int minusDelta, plusDelta;
- int minusStep, plusStep;
- };
-
-The class ``LineIterator`` is used to get each pixel of a raster line. It can be treated as versatile implementation of the Bresenham algorithm where you can stop at each pixel and do some extra processing, for example, grab pixel values along the line or draw a line with an effect (for example, with XOR operation).
-
-The number of pixels along the line is stored in ``LineIterator::count`` . The method ``LineIterator::pos`` returns the current position in the image ::
-
- // grabs pixels along the line (pt1, pt2)
- // from 8-bit 3-channel image to the buffer
- LineIterator it(img, pt1, pt2, 8);
- LineIterator it2 = it;
- vector<Vec3b> buf(it.count);
-
- for(int i = 0; i < it.count; i++, ++it)
- buf[i] = *(const Vec3b)*it;
-
- // alternative way of iterating through the line
- for(int i = 0; i < it2.count; i++, ++it2)
- {
- Vec3b val = img.at<Vec3b>(it2.pos());
- CV_Assert(buf[i] == val);
- }
-
-
-rectangle
--------------
-Draws a simple, thick, or filled up-right rectangle.
-
-.. ocv:function:: void rectangle( InputOutputArray img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
-
-.. ocv:function:: void rectangle( Mat& img, Rect rec, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
-
-.. ocv:pyfunction:: cv2.rectangle(img, pt1, pt2, color[, thickness[, lineType[, shift]]]) -> img
-
-.. ocv:cfunction:: void cvRectangle( CvArr* img, CvPoint pt1, CvPoint pt2, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
-
- :param img: Image.
-
- :param pt1: Vertex of the rectangle.
-
- :param pt2: Vertex of the rectangle opposite to ``pt1`` .
-
- :param rec: Alternative specification of the drawn rectangle.
-
- :param color: Rectangle color or brightness (grayscale image).
-
- :param thickness: Thickness of lines that make up the rectangle. Negative values, like ``CV_FILLED`` , mean that the function has to draw a filled rectangle.
-
- :param lineType: Type of the line. See the :ocv:func:`line` description.
-
- :param shift: Number of fractional bits in the point coordinates.
-
-The function ``rectangle`` draws a rectangle outline or a filled rectangle whose two opposite corners are ``pt1`` and ``pt2``, or ``r.tl()`` and ``r.br()-Point(1,1)``.
-
-
-
-polylines
--------------
-Draws several polygonal curves.
-
-.. ocv:function:: void polylines( Mat& img, const Point* const* pts, const int* npts, int ncontours, bool isClosed, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
-
-.. ocv:function:: void polylines( InputOutputArray img, InputArrayOfArrays pts, bool isClosed, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
-
-.. ocv:pyfunction:: cv2.polylines(img, pts, isClosed, color[, thickness[, lineType[, shift]]]) -> img
-
-.. ocv:cfunction:: void cvPolyLine( CvArr* img, CvPoint** pts, const int* npts, int contours, int is_closed, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
-
- :param img: Image.
-
- :param pts: Array of polygonal curves.
-
- :param npts: Array of polygon vertex counters.
-
- :param ncontours: Number of curves.
-
- :param isClosed: Flag indicating whether the drawn polylines are closed or not. If they are closed, the function draws a line from the last vertex of each curve to its first vertex.
-
- :param color: Polyline color.
-
- :param thickness: Thickness of the polyline edges.
-
- :param lineType: Type of the line segments. See the :ocv:func:`line` description.
-
- :param shift: Number of fractional bits in the vertex coordinates.
-
-The function ``polylines`` draws one or more polygonal curves.
-
-
-drawContours
-----------------
-Draws contours outlines or filled contours.
-
-.. ocv:function:: void drawContours( InputOutputArray image, InputArrayOfArrays contours, int contourIdx, const Scalar& color, int thickness=1, int lineType=LINE_8, InputArray hierarchy=noArray(), int maxLevel=INT_MAX, Point offset=Point() )
-
-.. ocv:pyfunction:: cv2.drawContours(image, contours, contourIdx, color[, thickness[, lineType[, hierarchy[, maxLevel[, offset]]]]]) -> image
-
-.. ocv:cfunction:: void cvDrawContours( CvArr * img, CvSeq* contour, CvScalar external_color, CvScalar hole_color, int max_level, int thickness=1, int line_type=8, CvPoint offset=cvPoint(0,0) )
-
- :param image: Destination image.
-
- :param contours: All the input contours. Each contour is stored as a point vector.
-
- :param contourIdx: Parameter indicating a contour to draw. If it is negative, all the contours are drawn.
-
- :param color: Color of the contours.
-
- :param thickness: Thickness of lines the contours are drawn with. If it is negative (for example, ``thickness=CV_FILLED`` ), the contour interiors are
- drawn.
-
- :param lineType: Line connectivity. See :ocv:func:`line` for details.
-
- :param hierarchy: Optional information about hierarchy. It is only needed if you want to draw only some of the contours (see ``maxLevel`` ).
-
- :param maxLevel: Maximal level for drawn contours. If it is 0, only
- the specified contour is drawn. If it is 1, the function draws the contour(s) and all the nested contours. If it is 2, the function draws the contours, all the nested contours, all the nested-to-nested contours, and so on. This parameter is only taken into account when there is ``hierarchy`` available.
-
- :param offset: Optional contour shift parameter. Shift all the drawn contours by the specified :math:`\texttt{offset}=(dx,dy)` .
-
- :param contour: Pointer to the first contour.
-
- :param external_color: Color of external contours.
-
- :param hole_color: Color of internal contours (holes).
-
-The function draws contour outlines in the image if
-:math:`\texttt{thickness} \ge 0` or fills the area bounded by the contours if
-:math:`\texttt{thickness}<0` . The example below shows how to retrieve connected components from the binary image and label them: ::
-
- #include "opencv2/imgproc.hpp"
- #include "opencv2/highgui.hpp"
-
- using namespace cv;
- using namespace std;
-
- int main( int argc, char** argv )
- {
- Mat src;
- // the first command-line parameter must be a filename of the binary
- // (black-n-white) image
- if( argc != 2 || !(src=imread(argv[1], 0)).data)
- return -1;
-
- Mat dst = Mat::zeros(src.rows, src.cols, CV_8UC3);
-
- src = src > 1;
- namedWindow( "Source", 1 );
- imshow( "Source", src );
-
- vector<vector<Point> > contours;
- vector<Vec4i> hierarchy;
-
- findContours( src, contours, hierarchy,
- RETR_CCOMP, CHAIN_APPROX_SIMPLE );
-
- // iterate through all the top-level contours,
- // draw each connected component with its own random color
- int idx = 0;
- for( ; idx >= 0; idx = hierarchy[idx][0] )
- {
- Scalar color( rand()&255, rand()&255, rand()&255 );
- drawContours( dst, contours, idx, color, FILLED, 8, hierarchy );
- }
-
- namedWindow( "Components", 1 );
- imshow( "Components", dst );
- waitKey(0);
- }
-
-.. note::
-
- * An example using the drawContour functionality can be found at opencv_source_code/samples/cpp/contours2.cpp
- * An example using drawContours to clean up a background segmentation result at opencv_source_code/samples/cpp/segment_objects.cpp
-
- * (Python) An example using the drawContour functionality can be found at opencv_source/samples/python2/contours.py
-
-
-putText
------------
-Draws a text string.
-
-.. ocv:function:: void putText( InputOutputArray img, const String& text, Point org, int fontFace, double fontScale, Scalar color, int thickness=1, int lineType=LINE_8, bool bottomLeftOrigin=false )
-
-.. ocv:pyfunction:: cv2.putText(img, text, org, fontFace, fontScale, color[, thickness[, lineType[, bottomLeftOrigin]]]) -> None
-
-.. ocv:cfunction:: void cvPutText( CvArr* img, const char* text, CvPoint org, const CvFont* font, CvScalar color )
-
- :param img: Image.
-
- :param text: Text string to be drawn.
-
- :param org: Bottom-left corner of the text string in the image.
-
- :param font: ``CvFont`` structure initialized using :ocv:cfunc:`InitFont`.
-
- :param fontFace: Font type. One of ``FONT_HERSHEY_SIMPLEX``, ``FONT_HERSHEY_PLAIN``, ``FONT_HERSHEY_DUPLEX``, ``FONT_HERSHEY_COMPLEX``, ``FONT_HERSHEY_TRIPLEX``, ``FONT_HERSHEY_COMPLEX_SMALL``, ``FONT_HERSHEY_SCRIPT_SIMPLEX``, or ``FONT_HERSHEY_SCRIPT_COMPLEX``,
- where each of the font ID's can be combined with ``FONT_ITALIC`` to get the slanted letters.
-
- :param fontScale: Font scale factor that is multiplied by the font-specific base size.
-
- :param color: Text color.
-
- :param thickness: Thickness of the lines used to draw a text.
-
- :param lineType: Line type. See the ``line`` for details.
-
- :param bottomLeftOrigin: When true, the image data origin is at the bottom-left corner. Otherwise, it is at the top-left corner.
-
-The function ``putText`` renders the specified text string in the image.
-Symbols that cannot be rendered using the specified font are
-replaced by question marks. See
-:ocv:func:`getTextSize` for a text rendering code example.
+++ /dev/null
-Feature Detection
-=================
-
-.. highlight:: cpp
-
-
-
-Canny
----------
-Finds edges in an image using the [Canny86]_ algorithm.
-
-.. ocv:function:: void Canny( InputArray image, OutputArray edges, double threshold1, double threshold2, int apertureSize=3, bool L2gradient=false )
-
-.. ocv:pyfunction:: cv2.Canny(image, threshold1, threshold2[, edges[, apertureSize[, L2gradient]]]) -> edges
-
-.. ocv:cfunction:: void cvCanny( const CvArr* image, CvArr* edges, double threshold1, double threshold2, int aperture_size=3 )
-
- :param image: 8-bit input image.
-
- :param edges: output edge map; single channels 8-bit image, which has the same size as ``image`` .
-
- :param threshold1: first threshold for the hysteresis procedure.
-
- :param threshold2: second threshold for the hysteresis procedure.
-
- :param apertureSize: aperture size for the :ocv:func:`Sobel` operator.
-
- :param L2gradient: a flag, indicating whether a more accurate :math:`L_2` norm :math:`=\sqrt{(dI/dx)^2 + (dI/dy)^2}` should be used to calculate the image gradient magnitude ( ``L2gradient=true`` ), or whether the default :math:`L_1` norm :math:`=|dI/dx|+|dI/dy|` is enough ( ``L2gradient=false`` ).
-
-The function finds edges in the input image ``image`` and marks them in the output map ``edges`` using the Canny algorithm. The smallest value between ``threshold1`` and ``threshold2`` is used for edge linking. The largest value is used to find initial segments of strong edges. See
-http://en.wikipedia.org/wiki/Canny_edge_detector
-
-.. note::
-
- * An example on using the canny edge detector can be found at opencv_source_code/samples/cpp/edge.cpp
-
- * (Python) An example on using the canny edge detector can be found at opencv_source_code/samples/python/edge.py
-
-cornerEigenValsAndVecs
-----------------------
-Calculates eigenvalues and eigenvectors of image blocks for corner detection.
-
-.. ocv:function:: void cornerEigenValsAndVecs( InputArray src, OutputArray dst, int blockSize, int ksize, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.cornerEigenValsAndVecs(src, blockSize, ksize[, dst[, borderType]]) -> dst
-
-.. ocv:cfunction:: void cvCornerEigenValsAndVecs( const CvArr* image, CvArr* eigenvv, int block_size, int aperture_size=3 )
-
- :param src: Input single-channel 8-bit or floating-point image.
-
- :param dst: Image to store the results. It has the same size as ``src`` and the type ``CV_32FC(6)`` .
-
- :param blockSize: Neighborhood size (see details below).
-
- :param ksize: Aperture parameter for the :ocv:func:`Sobel` operator.
-
- :param borderType: Pixel extrapolation method. See :ocv:func:`borderInterpolate` .
-
-For every pixel
-:math:`p` , the function ``cornerEigenValsAndVecs`` considers a ``blockSize`` :math:`\times` ``blockSize`` neighborhood
-:math:`S(p)` . It calculates the covariation matrix of derivatives over the neighborhood as:
-
-.. math::
-
- M = \begin{bmatrix} \sum _{S(p)}(dI/dx)^2 & \sum _{S(p)}dI/dx dI/dy \\ \sum _{S(p)}dI/dx dI/dy & \sum _{S(p)}(dI/dy)^2 \end{bmatrix}
-
-where the derivatives are computed using the
-:ocv:func:`Sobel` operator.
-
-After that, it finds eigenvectors and eigenvalues of
-:math:`M` and stores them in the destination image as
-:math:`(\lambda_1, \lambda_2, x_1, y_1, x_2, y_2)` where
-
-* :math:`\lambda_1, \lambda_2` are the non-sorted eigenvalues of :math:`M`
-
-* :math:`x_1, y_1` are the eigenvectors corresponding to :math:`\lambda_1`
-
-* :math:`x_2, y_2` are the eigenvectors corresponding to :math:`\lambda_2`
-
-The output of the function can be used for robust edge or corner detection.
-
-.. seealso::
-
- :ocv:func:`cornerMinEigenVal`,
- :ocv:func:`cornerHarris`,
- :ocv:func:`preCornerDetect`
-
-.. note::
-
- * (Python) An example on how to use eigenvectors and eigenvalues to estimate image texture flow direction can be found at opencv_source_code/samples/python2/texture_flow.py
-
-cornerHarris
-------------
-Harris corner detector.
-
-.. ocv:function:: void cornerHarris( InputArray src, OutputArray dst, int blockSize, int ksize, double k, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.cornerHarris(src, blockSize, ksize, k[, dst[, borderType]]) -> dst
-
-.. ocv:cfunction:: void cvCornerHarris( const CvArr* image, CvArr* harris_response, int block_size, int aperture_size=3, double k=0.04 )
-
- :param src: Input single-channel 8-bit or floating-point image.
-
- :param dst: Image to store the Harris detector responses. It has the type ``CV_32FC1`` and the same size as ``src`` .
-
- :param blockSize: Neighborhood size (see the details on :ocv:func:`cornerEigenValsAndVecs` ).
-
- :param ksize: Aperture parameter for the :ocv:func:`Sobel` operator.
-
- :param k: Harris detector free parameter. See the formula below.
-
- :param borderType: Pixel extrapolation method. See :ocv:func:`borderInterpolate` .
-
-The function runs the Harris corner detector on the image. Similarly to
-:ocv:func:`cornerMinEigenVal` and
-:ocv:func:`cornerEigenValsAndVecs` , for each pixel
-:math:`(x, y)` it calculates a
-:math:`2\times2` gradient covariance matrix
-:math:`M^{(x,y)}` over a
-:math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood. Then, it computes the following characteristic:
-
-.. math::
-
- \texttt{dst} (x,y) = \mathrm{det} M^{(x,y)} - k \cdot \left ( \mathrm{tr} M^{(x,y)} \right )^2
-
-Corners in the image can be found as the local maxima of this response map.
-
-
-
-cornerMinEigenVal
------------------
-Calculates the minimal eigenvalue of gradient matrices for corner detection.
-
-.. ocv:function:: void cornerMinEigenVal( InputArray src, OutputArray dst, int blockSize, int ksize=3, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.cornerMinEigenVal(src, blockSize[, dst[, ksize[, borderType]]]) -> dst
-
-.. ocv:cfunction:: void cvCornerMinEigenVal( const CvArr* image, CvArr* eigenval, int block_size, int aperture_size=3 )
-
- :param src: Input single-channel 8-bit or floating-point image.
-
- :param dst: Image to store the minimal eigenvalues. It has the type ``CV_32FC1`` and the same size as ``src`` .
-
- :param blockSize: Neighborhood size (see the details on :ocv:func:`cornerEigenValsAndVecs` ).
-
- :param ksize: Aperture parameter for the :ocv:func:`Sobel` operator.
-
- :param borderType: Pixel extrapolation method. See :ocv:func:`borderInterpolate` .
-
-The function is similar to
-:ocv:func:`cornerEigenValsAndVecs` but it calculates and stores only the minimal eigenvalue of the covariance matrix of derivatives, that is,
-:math:`\min(\lambda_1, \lambda_2)` in terms of the formulae in the
-:ocv:func:`cornerEigenValsAndVecs` description.
-
-
-
-cornerSubPix
-----------------
-Refines the corner locations.
-
-.. ocv:function:: void cornerSubPix( InputArray image, InputOutputArray corners, Size winSize, Size zeroZone, TermCriteria criteria )
-
-.. ocv:pyfunction:: cv2.cornerSubPix(image, corners, winSize, zeroZone, criteria) -> corners
-
-.. ocv:cfunction:: void cvFindCornerSubPix( const CvArr* image, CvPoint2D32f* corners, int count, CvSize win, CvSize zero_zone, CvTermCriteria criteria )
-
- :param image: Input image.
-
- :param corners: Initial coordinates of the input corners and refined coordinates provided for output.
-
- :param winSize: Half of the side length of the search window. For example, if ``winSize=Size(5,5)`` , then a :math:`5*2+1 \times 5*2+1 = 11 \times 11` search window is used.
-
- :param zeroZone: Half of the size of the dead region in the middle of the search zone over which the summation in the formula below is not done. It is used sometimes to avoid possible singularities of the autocorrelation matrix. The value of (-1,-1) indicates that there is no such a size.
-
- :param criteria: Criteria for termination of the iterative process of corner refinement. That is, the process of corner position refinement stops either after ``criteria.maxCount`` iterations or when the corner position moves by less than ``criteria.epsilon`` on some iteration.
-
-The function iterates to find the sub-pixel accurate location of corners or radial saddle points, as shown on the figure below.
-
-.. image:: pics/cornersubpix.png
-
-Sub-pixel accurate corner locator is based on the observation that every vector from the center
-:math:`q` to a point
-:math:`p` located within a neighborhood of
-:math:`q` is orthogonal to the image gradient at
-:math:`p` subject to image and measurement noise. Consider the expression:
-
-.. math::
-
- \epsilon _i = {DI_{p_i}}^T \cdot (q - p_i)
-
-where
-:math:`{DI_{p_i}}` is an image gradient at one of the points
-:math:`p_i` in a neighborhood of
-:math:`q` . The value of
-:math:`q` is to be found so that
-:math:`\epsilon_i` is minimized. A system of equations may be set up with
-:math:`\epsilon_i` set to zero:
-
-.. math::
-
- \sum _i(DI_{p_i} \cdot {DI_{p_i}}^T) - \sum _i(DI_{p_i} \cdot {DI_{p_i}}^T \cdot p_i)
-
-where the gradients are summed within a neighborhood ("search window") of
-:math:`q` . Calling the first gradient term
-:math:`G` and the second gradient term
-:math:`b` gives:
-
-.. math::
-
- q = G^{-1} \cdot b
-
-The algorithm sets the center of the neighborhood window at this new center
-:math:`q` and then iterates until the center stays within a set threshold.
-
-
-
-goodFeaturesToTrack
--------------------
-Determines strong corners on an image.
-
-.. ocv:function:: void goodFeaturesToTrack( InputArray image, OutputArray corners, int maxCorners, double qualityLevel, double minDistance, InputArray mask=noArray(), int blockSize=3, bool useHarrisDetector=false, double k=0.04 )
-
-.. ocv:pyfunction:: cv2.goodFeaturesToTrack(image, maxCorners, qualityLevel, minDistance[, corners[, mask[, blockSize[, useHarrisDetector[, k]]]]]) -> corners
-
-.. ocv:cfunction:: void cvGoodFeaturesToTrack( const CvArr* image, CvArr* eig_image, CvArr* temp_image, CvPoint2D32f* corners, int* corner_count, double quality_level, double min_distance, const CvArr* mask=NULL, int block_size=3, int use_harris=0, double k=0.04 )
-
- :param image: Input 8-bit or floating-point 32-bit, single-channel image.
-
- :param eig_image: The parameter is ignored.
-
- :param temp_image: The parameter is ignored.
-
- :param corners: Output vector of detected corners.
-
- :param maxCorners: Maximum number of corners to return. If there are more corners than are found, the strongest of them is returned.
-
- :param qualityLevel: Parameter characterizing the minimal accepted quality of image corners. The parameter value is multiplied by the best corner quality measure, which is the minimal eigenvalue (see :ocv:func:`cornerMinEigenVal` ) or the Harris function response (see :ocv:func:`cornerHarris` ). The corners with the quality measure less than the product are rejected. For example, if the best corner has the quality measure = 1500, and the ``qualityLevel=0.01`` , then all the corners with the quality measure less than 15 are rejected.
-
- :param minDistance: Minimum possible Euclidean distance between the returned corners.
-
- :param mask: Optional region of interest. If the image is not empty (it needs to have the type ``CV_8UC1`` and the same size as ``image`` ), it specifies the region in which the corners are detected.
-
- :param blockSize: Size of an average block for computing a derivative covariation matrix over each pixel neighborhood. See :ocv:func:`cornerEigenValsAndVecs` .
-
- :param useHarrisDetector: Parameter indicating whether to use a Harris detector (see :ocv:func:`cornerHarris`) or :ocv:func:`cornerMinEigenVal`.
-
- :param k: Free parameter of the Harris detector.
-
-The function finds the most prominent corners in the image or in the specified image region, as described in [Shi94]_:
-
-#.
- Function calculates the corner quality measure at every source image pixel using the
- :ocv:func:`cornerMinEigenVal` or
- :ocv:func:`cornerHarris` .
-
-#.
- Function performs a non-maximum suppression (the local maximums in *3 x 3* neighborhood are retained).
-
-#.
- The corners with the minimal eigenvalue less than
- :math:`\texttt{qualityLevel} \cdot \max_{x,y} qualityMeasureMap(x,y)` are rejected.
-
-#.
- The remaining corners are sorted by the quality measure in the descending order.
-
-#.
- Function throws away each corner for which there is a stronger corner at a distance less than ``maxDistance``.
-
-The function can be used to initialize a point-based tracker of an object.
-
-.. note:: If the function is called with different values ``A`` and ``B`` of the parameter ``qualityLevel`` , and ``A`` > ``B``, the vector of returned corners with ``qualityLevel=A`` will be the prefix of the output vector with ``qualityLevel=B`` .
-
-.. seealso::
-
- :ocv:func:`cornerMinEigenVal`,
- :ocv:func:`cornerHarris`,
- :ocv:func:`calcOpticalFlowPyrLK`,
- :ocv:func:`estimateRigidTransform`,
-
-
-HoughCircles
-------------
-Finds circles in a grayscale image using a modification of the Hough transform.
-
-.. ocv:function:: void HoughCircles( InputArray image, OutputArray circles, int method, double dp, double minDist, double param1=100, double param2=100, int minRadius=0, int maxRadius=0 )
-
-.. ocv:cfunction:: CvSeq* cvHoughCircles( CvArr* image, void* circle_storage, int method, double dp, double min_dist, double param1=100, double param2=100, int min_radius=0, int max_radius=0 )
-
-.. ocv:pyfunction:: cv2.HoughCircles(image, method, dp, minDist[, circles[, param1[, param2[, minRadius[, maxRadius]]]]]) -> circles
-
- :param image: 8-bit, single-channel, grayscale input image.
-
- :param circles: Output vector of found circles. Each vector is encoded as a 3-element floating-point vector :math:`(x, y, radius)` .
-
- :param circle_storage: In C function this is a memory storage that will contain the output sequence of found circles.
-
- :param method: Detection method to use. Currently, the only implemented method is ``CV_HOUGH_GRADIENT`` , which is basically *21HT* , described in [Yuen90]_.
-
- :param dp: Inverse ratio of the accumulator resolution to the image resolution. For example, if ``dp=1`` , the accumulator has the same resolution as the input image. If ``dp=2`` , the accumulator has half as big width and height.
-
- :param minDist: Minimum distance between the centers of the detected circles. If the parameter is too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed.
-
- :param param1: First method-specific parameter. In case of ``CV_HOUGH_GRADIENT`` , it is the higher threshold of the two passed to the :ocv:func:`Canny` edge detector (the lower one is twice smaller).
-
- :param param2: Second method-specific parameter. In case of ``CV_HOUGH_GRADIENT`` , it is the accumulator threshold for the circle centers at the detection stage. The smaller it is, the more false circles may be detected. Circles, corresponding to the larger accumulator values, will be returned first.
-
- :param minRadius: Minimum circle radius.
-
- :param maxRadius: Maximum circle radius.
-
-Example: ::
-
- #include <opencv2/imgproc.hpp>
- #include <opencv2/highgui.hpp>
- #include <math.h>
-
- using namespace cv;
-
- int main(int argc, char** argv)
- {
- Mat img, gray;
- if( argc != 2 && !(img=imread(argv[1], 1)).data)
- return -1;
- cvtColor(img, gray, COLOR_BGR2GRAY);
- // smooth it, otherwise a lot of false circles may be detected
- GaussianBlur( gray, gray, Size(9, 9), 2, 2 );
- vector<Vec3f> circles;
- HoughCircles(gray, circles, HOUGH_GRADIENT,
- 2, gray->rows/4, 200, 100 );
- for( size_t i = 0; i < circles.size(); i++ )
- {
- Point center(cvRound(circles[i][0]), cvRound(circles[i][1]));
- int radius = cvRound(circles[i][2]);
- // draw the circle center
- circle( img, center, 3, Scalar(0,255,0), -1, 8, 0 );
- // draw the circle outline
- circle( img, center, radius, Scalar(0,0,255), 3, 8, 0 );
- }
- namedWindow( "circles", 1 );
- imshow( "circles", img );
- return 0;
- }
-
-.. note:: The elements of the output vector of found circles ("circles" in the above example) are sorted in descending order of accumulator values. This way, the centres with the most supporting pixels appear first.
-
-.. note:: Usually the function detects the centers of circles well. However, it may fail to find correct radii. You can assist to the function by specifying the radius range ( ``minRadius`` and ``maxRadius`` ) if you know it. Or, you may ignore the returned radius, use only the center, and find the correct radius using an additional procedure.
-
-.. seealso::
-
- :ocv:func:`fitEllipse`,
- :ocv:func:`minEnclosingCircle`
-
-.. note::
-
- * An example using the Hough circle detector can be found at opencv_source_code/samples/cpp/houghcircles.cpp
-
-HoughLines
-----------
-Finds lines in a binary image using the standard Hough transform.
-
-.. ocv:function:: void HoughLines( InputArray image, OutputArray lines, double rho, double theta, int threshold, double srn=0, double stn=0, double min_theta=0, double max_theta=CV_PI )
-
-.. ocv:pyfunction:: cv2.HoughLines(image, rho, theta, threshold[, lines[, srn[, stn[, min_theta[, max_theta]]]]]) -> lines
-
-.. ocv:cfunction:: CvSeq* cvHoughLines2( CvArr* image, void* line_storage, int method, double rho, double theta, int threshold, double param1=0, double param2=0, double min_theta=0, double max_theta=CV_PI )
-
- :param image: 8-bit, single-channel binary source image. The image may be modified by the function.
-
- :param lines: Output vector of lines. Each line is represented by a two-element vector :math:`(\rho, \theta)` . :math:`\rho` is the distance from the coordinate origin :math:`(0,0)` (top-left corner of the image). :math:`\theta` is the line rotation angle in radians ( :math:`0 \sim \textrm{vertical line}, \pi/2 \sim \textrm{horizontal line}` ).
-
- :param rho: Distance resolution of the accumulator in pixels.
-
- :param theta: Angle resolution of the accumulator in radians.
-
- :param threshold: Accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` ).
-
- :param srn: For the multi-scale Hough transform, it is a divisor for the distance resolution ``rho`` . The coarse accumulator distance resolution is ``rho`` and the accurate accumulator resolution is ``rho/srn`` . If both ``srn=0`` and ``stn=0`` , the classical Hough transform is used. Otherwise, both these parameters should be positive.
-
- :param stn: For the multi-scale Hough transform, it is a divisor for the distance resolution ``theta``.
-
- :param min_theta: For standard and multi-scale Hough transform, minimum angle to check for lines. Must fall between 0 and max_theta.
-
- :param max_theta: For standard and multi-scale Hough transform, maximum angle to check for lines. Must fall between min_theta and CV_PI.
-
- :param method: One of the following Hough transform variants:
-
- * **CV_HOUGH_STANDARD** classical or standard Hough transform. Every line is represented by two floating-point numbers :math:`(\rho, \theta)` , where :math:`\rho` is a distance between (0,0) point and the line, and :math:`\theta` is the angle between x-axis and the normal to the line. Thus, the matrix must be (the created sequence will be) of ``CV_32FC2`` type
-
-
- * **CV_HOUGH_PROBABILISTIC** probabilistic Hough transform (more efficient in case if the picture contains a few long linear segments). It returns line segments rather than the whole line. Each segment is represented by starting and ending points, and the matrix must be (the created sequence will be) of the ``CV_32SC4`` type.
-
- * **CV_HOUGH_MULTI_SCALE** multi-scale variant of the classical Hough transform. The lines are encoded the same way as ``CV_HOUGH_STANDARD``.
-
-
- :param param1: First method-dependent parameter:
-
- * For the classical Hough transform, it is not used (0).
-
- * For the probabilistic Hough transform, it is the minimum line length.
-
- * For the multi-scale Hough transform, it is ``srn``.
-
- :param param2: Second method-dependent parameter:
-
- * For the classical Hough transform, it is not used (0).
-
- * For the probabilistic Hough transform, it is the maximum gap between line segments lying on the same line to treat them as a single line segment (that is, to join them).
-
- * For the multi-scale Hough transform, it is ``stn``.
-
-The function implements the standard or standard multi-scale Hough transform algorithm for line detection. See http://homepages.inf.ed.ac.uk/rbf/HIPR2/hough.htm for a good explanation of Hough transform.
-See also the example in :ocv:func:`HoughLinesP` description.
-
-.. note::
-
- * An example using the Hough line detector can be found at opencv_source_code/samples/cpp/houghlines.cpp
-
-HoughLinesP
------------
-Finds line segments in a binary image using the probabilistic Hough transform.
-
-.. ocv:function:: void HoughLinesP( InputArray image, OutputArray lines, double rho, double theta, int threshold, double minLineLength=0, double maxLineGap=0 )
-
-.. ocv:pyfunction:: cv2.HoughLinesP(image, rho, theta, threshold[, lines[, minLineLength[, maxLineGap]]]) -> lines
-
- :param image: 8-bit, single-channel binary source image. The image may be modified by the function.
-
- :param lines: Output vector of lines. Each line is represented by a 4-element vector :math:`(x_1, y_1, x_2, y_2)` , where :math:`(x_1,y_1)` and :math:`(x_2, y_2)` are the ending points of each detected line segment.
-
- :param rho: Distance resolution of the accumulator in pixels.
-
- :param theta: Angle resolution of the accumulator in radians.
-
- :param threshold: Accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` ).
-
- :param minLineLength: Minimum line length. Line segments shorter than that are rejected.
-
- :param maxLineGap: Maximum allowed gap between points on the same line to link them.
-
-The function implements the probabilistic Hough transform algorithm for line detection, described in
-[Matas00]_. See the line detection example below: ::
-
- /* This is a standalone program. Pass an image name as the first parameter
- of the program. Switch between standard and probabilistic Hough transform
- by changing "#if 1" to "#if 0" and back */
- #include <opencv2/imgproc.hpp>
- #include <opencv2/highgui.hpp>
-
- using namespace cv;
-
- int main(int argc, char** argv)
- {
- Mat src, dst, color_dst;
- if( argc != 2 || !(src=imread(argv[1], 0)).data)
- return -1;
-
- Canny( src, dst, 50, 200, 3 );
- cvtColor( dst, color_dst, COLOR_GRAY2BGR );
-
- #if 0
- vector<Vec2f> lines;
- HoughLines( dst, lines, 1, CV_PI/180, 100 );
-
- for( size_t i = 0; i < lines.size(); i++ )
- {
- float rho = lines[i][0];
- float theta = lines[i][1];
- double a = cos(theta), b = sin(theta);
- double x0 = a*rho, y0 = b*rho;
- Point pt1(cvRound(x0 + 1000*(-b)),
- cvRound(y0 + 1000*(a)));
- Point pt2(cvRound(x0 - 1000*(-b)),
- cvRound(y0 - 1000*(a)));
- line( color_dst, pt1, pt2, Scalar(0,0,255), 3, 8 );
- }
- #else
- vector<Vec4i> lines;
- HoughLinesP( dst, lines, 1, CV_PI/180, 80, 30, 10 );
- for( size_t i = 0; i < lines.size(); i++ )
- {
- line( color_dst, Point(lines[i][0], lines[i][1]),
- Point(lines[i][2], lines[i][3]), Scalar(0,0,255), 3, 8 );
- }
- #endif
- namedWindow( "Source", 1 );
- imshow( "Source", src );
-
- namedWindow( "Detected Lines", 1 );
- imshow( "Detected Lines", color_dst );
-
- waitKey(0);
- return 0;
- }
-
-This is a sample picture the function parameters have been tuned for:
-
-.. image:: pics/building.jpg
-
-And this is the output of the above program in case of the probabilistic Hough transform:
-
-.. image:: pics/houghp.png
-
-.. seealso::
-
- :ocv:class:`LineSegmentDetector`
-
-
-
-LineSegmentDetector
--------------------
-Line segment detector class, following the algorithm described at [Rafael12]_.
-
-.. ocv:class:: LineSegmentDetector : public Algorithm
-
-
-createLineSegmentDetector
--------------------------
-Creates a smart pointer to a LineSegmentDetector object and initializes it.
-
-.. ocv:function:: Ptr<LineSegmentDetector> createLineSegmentDetector(int _refine = LSD_REFINE_STD, double _scale = 0.8, double _sigma_scale = 0.6, double _quant = 2.0, double _ang_th = 22.5, double _log_eps = 0, double _density_th = 0.7, int _n_bins = 1024)
-
-.. ocv:pyfunction:: cv2.createLineSegmentDetector([, _refine[, _scale[, _sigma_scale[, _quant[, _ang_th[, _log_eps[, _density_th[, _n_bins]]]]]]]]) -> retval
-
- :param _refine: The way found lines will be refined:
-
- * **LSD_REFINE_NONE** - No refinement applied.
-
- * **LSD_REFINE_STD** - Standard refinement is applied. E.g. breaking arches into smaller straighter line approximations.
-
- * **LSD_REFINE_ADV** - Advanced refinement. Number of false alarms is calculated, lines are refined through increase of precision, decrement in size, etc.
-
- :param scale: The scale of the image that will be used to find the lines. Range (0..1].
-
- :param sigma_scale: Sigma for Gaussian filter. It is computed as sigma = _sigma_scale/_scale.
-
- :param quant: Bound to the quantization error on the gradient norm.
-
- :param ang_th: Gradient angle tolerance in degrees.
-
- :param log_eps: Detection threshold: -log10(NFA) > log_eps. Used only when advancent refinement is chosen.
-
- :param density_th: Minimal density of aligned region points in the enclosing rectangle.
-
- :param n_bins: Number of bins in pseudo-ordering of gradient modulus.
-
-The LineSegmentDetector algorithm is defined using the standard values. Only advanced users may want to edit those, as to tailor it for their own application.
-
-
-LineSegmentDetector::detect
----------------------------
-Finds lines in the input image. See the lsd_lines.cpp sample for possible usage.
-
-.. ocv:function:: void LineSegmentDetector::detect(const InputArray _image, OutputArray _lines, OutputArray width = noArray(), OutputArray prec = noArray(), OutputArray nfa = noArray())
-
-.. ocv:pyfunction:: cv2.createLineSegmentDetector.detect(_image[, _lines[, width[, prec[, nfa]]]]) -> _lines, width, prec, nfa
-
- :param _image A grayscale (CV_8UC1) input image.
- If only a roi needs to be selected, use ::
- lsd_ptr->detect(image(roi), lines, ...);
- lines += Scalar(roi.x, roi.y, roi.x, roi.y);
-
- :param lines: A vector of Vec4i elements specifying the beginning and ending point of a line. Where Vec4i is (x1, y1, x2, y2), point 1 is the start, point 2 - end. Returned lines are strictly oriented depending on the gradient.
-
- :param width: Vector of widths of the regions, where the lines are found. E.g. Width of line.
-
- :param prec: Vector of precisions with which the lines are found.
-
- :param nfa: Vector containing number of false alarms in the line region, with precision of 10%. The bigger the value, logarithmically better the detection.
-
- * -1 corresponds to 10 mean false alarms
-
- * 0 corresponds to 1 mean false alarm
-
- * 1 corresponds to 0.1 mean false alarms
-
- This vector will be calculated only when the objects type is LSD_REFINE_ADV.
-
-This is the output of the default parameters of the algorithm on the above shown image.
-
-.. image:: pics/building_lsd.png
-
-.. note::
-
- * An example using the LineSegmentDetector can be found at opencv_source_code/samples/cpp/lsd_lines.cpp
-
-LineSegmentDetector::drawSegments
----------------------------------
-Draws the line segments on a given image.
-
-.. ocv:function:: void LineSegmentDetector::drawSegments(InputOutputArray _image, InputArray lines)
-
-.. ocv:pyfunction:: cv2.createLineSegmentDetector.drawSegments(_image, lines) -> _image
-
- :param image: The image, where the liens will be drawn. Should be bigger or equal to the image, where the lines were found.
-
- :param lines: A vector of the lines that needed to be drawn.
-
-
-LineSegmentDetector::compareSegments
-------------------------------------
-Draws two groups of lines in blue and red, counting the non overlapping (mismatching) pixels.
-
-.. ocv:function:: int LineSegmentDetector::compareSegments(const Size& size, InputArray lines1, InputArray lines2, InputOutputArray _image = noArray())
-
-.. ocv:pyfunction:: cv2.createLineSegmentDetector.compareSegments(size, lines1, lines2[, _image]) -> retval, _image
-
- :param size: The size of the image, where lines1 and lines2 were found.
-
- :param lines1: The first group of lines that needs to be drawn. It is visualized in blue color.
-
- :param lines2: The second group of lines. They visualized in red color.
-
- :param image: Optional image, where the lines will be drawn. The image should be color(3-channel) in order for lines1 and lines2 to be drawn in the above mentioned colors.
-
-
-
-preCornerDetect
----------------
-Calculates a feature map for corner detection.
-
-.. ocv:function:: void preCornerDetect( InputArray src, OutputArray dst, int ksize, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.preCornerDetect(src, ksize[, dst[, borderType]]) -> dst
-
-.. ocv:cfunction:: void cvPreCornerDetect( const CvArr* image, CvArr* corners, int aperture_size=3 )
-
- :param src: Source single-channel 8-bit of floating-point image.
-
- :param dst: Output image that has the type ``CV_32F`` and the same size as ``src`` .
-
- :param ksize: Aperture size of the :ocv:func:`Sobel` .
-
- :param borderType: Pixel extrapolation method. See :ocv:func:`borderInterpolate` .
-
-The function calculates the complex spatial derivative-based function of the source image
-
-.. math::
-
- \texttt{dst} = (D_x \texttt{src} )^2 \cdot D_{yy} \texttt{src} + (D_y \texttt{src} )^2 \cdot D_{xx} \texttt{src} - 2 D_x \texttt{src} \cdot D_y \texttt{src} \cdot D_{xy} \texttt{src}
-
-where
-:math:`D_x`,:math:`D_y` are the first image derivatives,
-:math:`D_{xx}`,:math:`D_{yy}` are the second image derivatives, and
-:math:`D_{xy}` is the mixed derivative.
-
-The corners can be found as local maximums of the functions, as shown below: ::
-
- Mat corners, dilated_corners;
- preCornerDetect(image, corners, 3);
- // dilation with 3x3 rectangular structuring element
- dilate(corners, dilated_corners, Mat(), 1);
- Mat corner_mask = corners == dilated_corners;
-
-.. [Canny86] J. Canny. *A Computational Approach to Edge Detection*, IEEE Trans. on Pattern Analysis and Machine Intelligence, 8(6), pp. 679-698 (1986).
-
-.. [Matas00] Matas, J. and Galambos, C. and Kittler, J.V., *Robust Detection of Lines Using the Progressive Probabilistic Hough Transform*. CVIU 78 1, pp 119-137 (2000)
-
-.. [Shi94] J. Shi and C. Tomasi. *Good Features to Track*. Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition, pages 593-600, June 1994.
-
-.. [Yuen90] Yuen, H. K. and Princen, J. and Illingworth, J. and Kittler, J., *Comparative study of Hough transform methods for circle finding*. Image Vision Comput. 8 1, pp 71–77 (1990)
-
-.. [Rafael12] Rafael Grompone von Gioi, Jérémie Jakubowicz, Jean-Michel Morel, and Gregory Randall, LSD: a Line Segment Detector, Image Processing On Line, vol. 2012. http://dx.doi.org/10.5201/ipol.2012.gjmr-lsd
+++ /dev/null
-Image Filtering
-===============
-
-.. highlight:: cpp
-
-Functions and classes described in this section are used to perform various linear or non-linear filtering operations on 2D images (represented as
-:ocv:func:`Mat`'s). It means that for each pixel location
-:math:`(x,y)` in the source image (normally, rectangular), its neighborhood is considered and used to compute the response. In case of a linear filter, it is a weighted sum of pixel values. In case of morphological operations, it is the minimum or maximum values, and so on. The computed response is stored in the destination image at the same location
-:math:`(x,y)` . It means that the output image will be of the same size as the input image. Normally, the functions support multi-channel arrays, in which case every channel is processed independently. Therefore, the output image will also have the same number of channels as the input one.
-
-Another common feature of the functions and classes described in this section is that, unlike simple arithmetic functions, they need to extrapolate values of some non-existing pixels. For example, if you want to smooth an image using a Gaussian
-:math:`3 \times 3` filter, then, when processing the left-most pixels in each row, you need pixels to the left of them, that is, outside of the image. You can let these pixels be the same as the left-most image pixels ("replicated border" extrapolation method), or assume that all the non-existing pixels are zeros ("constant border" extrapolation method), and so on.
-OpenCV enables you to specify the extrapolation method. For details, see the function ``borderInterpolate`` and discussion of the ``borderType`` parameter in the section and various functions below. ::
-
- /*
- Various border types, image boundaries are denoted with '|'
-
- * BORDER_REPLICATE: aaaaaa|abcdefgh|hhhhhhh
- * BORDER_REFLECT: fedcba|abcdefgh|hgfedcb
- * BORDER_REFLECT_101: gfedcb|abcdefgh|gfedcba
- * BORDER_WRAP: cdefgh|abcdefgh|abcdefg
- * BORDER_CONSTANT: iiiiii|abcdefgh|iiiiiii with some specified 'i'
- */
-
-.. note::
-
- * (Python) A complete example illustrating different morphological operations like erode/dilate, open/close, blackhat/tophat ... can be found at opencv_source_code/samples/python2/morphology.py
-
-bilateralFilter
--------------------
-Applies the bilateral filter to an image.
-
-.. ocv:function:: void bilateralFilter( InputArray src, OutputArray dst, int d, double sigmaColor, double sigmaSpace, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.bilateralFilter(src, d, sigmaColor, sigmaSpace[, dst[, borderType]]) -> dst
-
- :param src: Source 8-bit or floating-point, 1-channel or 3-channel image.
-
- :param dst: Destination image of the same size and type as ``src`` .
-
- :param d: Diameter of each pixel neighborhood that is used during filtering. If it is non-positive, it is computed from ``sigmaSpace`` .
-
- :param sigmaColor: Filter sigma in the color space. A larger value of the parameter means that farther colors within the pixel neighborhood (see ``sigmaSpace`` ) will be mixed together, resulting in larger areas of semi-equal color.
-
- :param sigmaSpace: Filter sigma in the coordinate space. A larger value of the parameter means that farther pixels will influence each other as long as their colors are close enough (see ``sigmaColor`` ). When ``d>0`` , it specifies the neighborhood size regardless of ``sigmaSpace`` . Otherwise, ``d`` is proportional to ``sigmaSpace`` .
-
-The function applies bilateral filtering to the input image, as described in
-http://www.dai.ed.ac.uk/CVonline/LOCAL\_COPIES/MANDUCHI1/Bilateral\_Filtering.html
-``bilateralFilter`` can reduce unwanted noise very well while keeping edges fairly sharp. However, it is very slow compared to most filters.
-
-*Sigma values*: For simplicity, you can set the 2 sigma values to be the same. If they are small (< 10), the filter will not have much effect, whereas if they are large (> 150), they will have a very strong effect, making the image look "cartoonish".
-
-*Filter size*: Large filters (d > 5) are very slow, so it is recommended to use d=5 for real-time applications, and perhaps d=9 for offline applications that need heavy noise filtering.
-
-This filter does not work inplace.
-
-
-blur
-----
-Blurs an image using the normalized box filter.
-
-.. ocv:function:: void blur( InputArray src, OutputArray dst, Size ksize, Point anchor=Point(-1,-1), int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.blur(src, ksize[, dst[, anchor[, borderType]]]) -> dst
-
- :param src: input image; it can have any number of channels, which are processed independently, but the depth should be ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F`` or ``CV_64F``.
-
- :param dst: output image of the same size and type as ``src``.
-
- :param ksize: blurring kernel size.
-
- :param anchor: anchor point; default value ``Point(-1,-1)`` means that the anchor is at the kernel center.
-
- :param borderType: border mode used to extrapolate pixels outside of the image.
-
-The function smoothes an image using the kernel:
-
-.. math::
-
- \texttt{K} = \frac{1}{\texttt{ksize.width*ksize.height}} \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \hdotsfor{6} \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \end{bmatrix}
-
-The call ``blur(src, dst, ksize, anchor, borderType)`` is equivalent to ``boxFilter(src, dst, src.type(), anchor, true, borderType)`` .
-
-.. seealso::
-
- :ocv:func:`boxFilter`,
- :ocv:func:`bilateralFilter`,
- :ocv:func:`GaussianBlur`,
- :ocv:func:`medianBlur`
-
-
-boxFilter
----------
-Blurs an image using the box filter.
-
-.. ocv:function:: void boxFilter( InputArray src, OutputArray dst, int ddepth, Size ksize, Point anchor=Point(-1,-1), bool normalize=true, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.boxFilter(src, ddepth, ksize[, dst[, anchor[, normalize[, borderType]]]]) -> dst
-
- :param src: input image.
-
- :param dst: output image of the same size and type as ``src``.
-
- :param ddepth: the output image depth (-1 to use ``src.depth()``).
-
- :param ksize: blurring kernel size.
-
- :param anchor: anchor point; default value ``Point(-1,-1)`` means that the anchor is at the kernel center.
-
- :param normalize: flag, specifying whether the kernel is normalized by its area or not.
-
- :param borderType: border mode used to extrapolate pixels outside of the image.
-
-The function smoothes an image using the kernel:
-
-.. math::
-
- \texttt{K} = \alpha \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \hdotsfor{6} \\ 1 & 1 & 1 & \cdots & 1 & 1 \end{bmatrix}
-
-where
-
-.. math::
-
- \alpha = \fork{\frac{1}{\texttt{ksize.width*ksize.height}}}{when \texttt{normalize=true}}{1}{otherwise}
-
-Unnormalized box filter is useful for computing various integral characteristics over each pixel neighborhood, such as covariance matrices of image derivatives (used in dense optical flow algorithms, and so on). If you need to compute pixel sums over variable-size windows, use :ocv:func:`integral` .
-
-.. seealso::
-
- :ocv:func:`blur`,
- :ocv:func:`bilateralFilter`,
- :ocv:func:`GaussianBlur`,
- :ocv:func:`medianBlur`,
- :ocv:func:`integral`
-
-
-
-buildPyramid
-------------
-Constructs the Gaussian pyramid for an image.
-
-.. ocv:function:: void buildPyramid( InputArray src, OutputArrayOfArrays dst, int maxlevel, int borderType=BORDER_DEFAULT )
-
- :param src: Source image. Check :ocv:func:`pyrDown` for the list of supported types.
-
- :param dst: Destination vector of ``maxlevel+1`` images of the same type as ``src`` . ``dst[0]`` will be the same as ``src`` . ``dst[1]`` is the next pyramid layer, a smoothed and down-sized ``src`` , and so on.
-
- :param maxlevel: 0-based index of the last (the smallest) pyramid layer. It must be non-negative.
-
- :param borderType: Pixel extrapolation method (BORDER_CONSTANT don't supported). See ``borderInterpolate`` for details.
-
-The function constructs a vector of images and builds the Gaussian pyramid by recursively applying
-:ocv:func:`pyrDown` to the previously built pyramid layers, starting from ``dst[0]==src`` .
-
-
-dilate
-------
-Dilates an image by using a specific structuring element.
-
-.. ocv:function:: void dilate( InputArray src, OutputArray dst, InputArray kernel, Point anchor=Point(-1,-1), int iterations=1, int borderType=BORDER_CONSTANT, const Scalar& borderValue=morphologyDefaultBorderValue() )
-
-.. ocv:pyfunction:: cv2.dilate(src, kernel[, dst[, anchor[, iterations[, borderType[, borderValue]]]]]) -> dst
-
-.. ocv:cfunction:: void cvDilate( const CvArr* src, CvArr* dst, IplConvKernel* element=NULL, int iterations=1 )
-
- :param src: input image; the number of channels can be arbitrary, but the depth should be one of ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F` or ``CV_64F``.
-
- :param dst: output image of the same size and type as ``src``.
-
- :param kernel: structuring element used for dilation; if ``elemenat=Mat()`` , a ``3 x 3`` rectangular structuring element is used. Kernel can be created using :ocv:func:`getStructuringElement`
-
- :param anchor: position of the anchor within the element; default value ``(-1, -1)`` means that the anchor is at the element center.
-
- :param iterations: number of times dilation is applied.
-
- :param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
-
- :param borderValue: border value in case of a constant border
-
-The function dilates the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the maximum is taken:
-
-.. math::
-
- \texttt{dst} (x,y) = \max _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')
-
-The function supports the in-place mode. Dilation can be applied several ( ``iterations`` ) times. In case of multi-channel images, each channel is processed independently.
-
-.. seealso::
-
- :ocv:func:`erode`,
- :ocv:func:`morphologyEx`,
- :ocv:func:`getStructuringElement`
-
-
-.. note::
-
- * An example using the morphological dilate operation can be found at opencv_source_code/samples/cpp/morphology2.cpp
-
-
-erode
------
-Erodes an image by using a specific structuring element.
-
-.. ocv:function:: void erode( InputArray src, OutputArray dst, InputArray kernel, Point anchor=Point(-1,-1), int iterations=1, int borderType=BORDER_CONSTANT, const Scalar& borderValue=morphologyDefaultBorderValue() )
-
-.. ocv:pyfunction:: cv2.erode(src, kernel[, dst[, anchor[, iterations[, borderType[, borderValue]]]]]) -> dst
-
-.. ocv:cfunction:: void cvErode( const CvArr* src, CvArr* dst, IplConvKernel* element=NULL, int iterations=1)
-
- :param src: input image; the number of channels can be arbitrary, but the depth should be one of ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F` or ``CV_64F``.
-
- :param dst: output image of the same size and type as ``src``.
-
- :param kernel: structuring element used for erosion; if ``element=Mat()`` , a ``3 x 3`` rectangular structuring element is used. Kernel can be created using :ocv:func:`getStructuringElement`.
-
- :param anchor: position of the anchor within the element; default value ``(-1, -1)`` means that the anchor is at the element center.
-
- :param iterations: number of times erosion is applied.
-
- :param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
-
- :param borderValue: border value in case of a constant border
-
-The function erodes the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the minimum is taken:
-
-.. math::
-
- \texttt{dst} (x,y) = \min _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')
-
-The function supports the in-place mode. Erosion can be applied several ( ``iterations`` ) times. In case of multi-channel images, each channel is processed independently.
-
-.. seealso::
-
- :ocv:func:`dilate`,
- :ocv:func:`morphologyEx`,
- :ocv:func:`getStructuringElement`
-
-.. note::
-
- * An example using the morphological erode operation can be found at opencv_source_code/samples/cpp/morphology2.cpp
-
-filter2D
---------
-Convolves an image with the kernel.
-
-.. ocv:function:: void filter2D( InputArray src, OutputArray dst, int ddepth, InputArray kernel, Point anchor=Point(-1,-1), double delta=0, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.filter2D(src, ddepth, kernel[, dst[, anchor[, delta[, borderType]]]]) -> dst
-
-.. ocv:cfunction:: void cvFilter2D( const CvArr* src, CvArr* dst, const CvMat* kernel, CvPoint anchor=cvPoint(-1,-1) )
-
- :param src: input image.
-
- :param dst: output image of the same size and the same number of channels as ``src``.
-
-
- :param ddepth: desired depth of the destination image; if it is negative, it will be the same as ``src.depth()``; the following combinations of ``src.depth()`` and ``ddepth`` are supported:
- * ``src.depth()`` = ``CV_8U``, ``ddepth`` = -1/``CV_16S``/``CV_32F``/``CV_64F``
- * ``src.depth()`` = ``CV_16U``/``CV_16S``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
- * ``src.depth()`` = ``CV_32F``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
- * ``src.depth()`` = ``CV_64F``, ``ddepth`` = -1/``CV_64F``
-
- when ``ddepth=-1``, the output image will have the same depth as the source.
-
- :param kernel: convolution kernel (or rather a correlation kernel), a single-channel floating point matrix; if you want to apply different kernels to different channels, split the image into separate color planes using :ocv:func:`split` and process them individually.
-
- :param anchor: anchor of the kernel that indicates the relative position of a filtered point within the kernel; the anchor should lie within the kernel; default value (-1,-1) means that the anchor is at the kernel center.
-
- :param delta: optional value added to the filtered pixels before storing them in ``dst``.
-
- :param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
-
-The function applies an arbitrary linear filter to an image. In-place operation is supported. When the aperture is partially outside the image, the function interpolates outlier pixel values according to the specified border mode.
-
-The function does actually compute correlation, not the convolution:
-
-.. math::
-
- \texttt{dst} (x,y) = \sum _{ \stackrel{0\leq x' < \texttt{kernel.cols},}{0\leq y' < \texttt{kernel.rows}} } \texttt{kernel} (x',y')* \texttt{src} (x+x'- \texttt{anchor.x} ,y+y'- \texttt{anchor.y} )
-
-That is, the kernel is not mirrored around the anchor point. If you need a real convolution, flip the kernel using
-:ocv:func:`flip` and set the new anchor to ``(kernel.cols - anchor.x - 1, kernel.rows - anchor.y - 1)`` .
-
-The function uses the DFT-based algorithm in case of sufficiently large kernels (~``11 x 11`` or larger) and the direct algorithm for small kernels.
-
-.. seealso::
-
- :ocv:func:`sepFilter2D`,
- :ocv:func:`dft`,
- :ocv:func:`matchTemplate`
-
-
-
-GaussianBlur
-------------
-Blurs an image using a Gaussian filter.
-
-.. ocv:function:: void GaussianBlur( InputArray src, OutputArray dst, Size ksize, double sigmaX, double sigmaY=0, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.GaussianBlur(src, ksize, sigmaX[, dst[, sigmaY[, borderType]]]) -> dst
-
- :param src: input image; the image can have any number of channels, which are processed independently, but the depth should be ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F`` or ``CV_64F``.
-
- :param dst: output image of the same size and type as ``src``.
-
- :param ksize: Gaussian kernel size. ``ksize.width`` and ``ksize.height`` can differ but they both must be positive and odd. Or, they can be zero's and then they are computed from ``sigma*`` .
-
- :param sigmaX: Gaussian kernel standard deviation in X direction.
-
- :param sigmaY: Gaussian kernel standard deviation in Y direction; if ``sigmaY`` is zero, it is set to be equal to ``sigmaX``, if both sigmas are zeros, they are computed from ``ksize.width`` and ``ksize.height`` , respectively (see :ocv:func:`getGaussianKernel` for details); to fully control the result regardless of possible future modifications of all this semantics, it is recommended to specify all of ``ksize``, ``sigmaX``, and ``sigmaY``.
-
- :param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
-
-The function convolves the source image with the specified Gaussian kernel. In-place filtering is supported.
-
-.. seealso::
-
- :ocv:func:`sepFilter2D`,
- :ocv:func:`filter2D`,
- :ocv:func:`blur`,
- :ocv:func:`boxFilter`,
- :ocv:func:`bilateralFilter`,
- :ocv:func:`medianBlur`
-
-
-getDerivKernels
----------------
-Returns filter coefficients for computing spatial image derivatives.
-
-.. ocv:function:: void getDerivKernels( OutputArray kx, OutputArray ky, int dx, int dy, int ksize, bool normalize=false, int ktype=CV_32F )
-
-.. ocv:pyfunction:: cv2.getDerivKernels(dx, dy, ksize[, kx[, ky[, normalize[, ktype]]]]) -> kx, ky
-
- :param kx: Output matrix of row filter coefficients. It has the type ``ktype`` .
-
- :param ky: Output matrix of column filter coefficients. It has the type ``ktype`` .
-
- :param dx: Derivative order in respect of x.
-
- :param dy: Derivative order in respect of y.
-
- :param ksize: Aperture size. It can be ``CV_SCHARR`` , 1, 3, 5, or 7.
-
- :param normalize: Flag indicating whether to normalize (scale down) the filter coefficients or not. Theoretically, the coefficients should have the denominator :math:`=2^{ksize*2-dx-dy-2}` . If you are going to filter floating-point images, you are likely to use the normalized kernels. But if you compute derivatives of an 8-bit image, store the results in a 16-bit image, and wish to preserve all the fractional bits, you may want to set ``normalize=false`` .
-
- :param ktype: Type of filter coefficients. It can be ``CV_32f`` or ``CV_64F`` .
-
-The function computes and returns the filter coefficients for spatial image derivatives. When ``ksize=CV_SCHARR`` , the Scharr
-:math:`3 \times 3` kernels are generated (see
-:ocv:func:`Scharr` ). Otherwise, Sobel kernels are generated (see
-:ocv:func:`Sobel` ). The filters are normally passed to
-:ocv:func:`sepFilter2D` or to
-
-
-getGaussianKernel
------------------
-Returns Gaussian filter coefficients.
-
-.. ocv:function:: Mat getGaussianKernel( int ksize, double sigma, int ktype=CV_64F )
-
-.. ocv:pyfunction:: cv2.getGaussianKernel(ksize, sigma[, ktype]) -> retval
-
- :param ksize: Aperture size. It should be odd ( :math:`\texttt{ksize} \mod 2 = 1` ) and positive.
-
- :param sigma: Gaussian standard deviation. If it is non-positive, it is computed from ``ksize`` as \ ``sigma = 0.3*((ksize-1)*0.5 - 1) + 0.8`` .
- :param ktype: Type of filter coefficients. It can be ``CV_32F`` or ``CV_64F`` .
-
-The function computes and returns the
-:math:`\texttt{ksize} \times 1` matrix of Gaussian filter coefficients:
-
-.. math::
-
- G_i= \alpha *e^{-(i-( \texttt{ksize} -1)/2)^2/(2* \texttt{sigma} )^2},
-
-where
-:math:`i=0..\texttt{ksize}-1` and
-:math:`\alpha` is the scale factor chosen so that
-:math:`\sum_i G_i=1`.
-
-Two of such generated kernels can be passed to
-:ocv:func:`sepFilter2D`. Those functions automatically recognize smoothing kernels (a symmetrical kernel with sum of weights equal to 1) and handle them accordingly. You may also use the higher-level
-:ocv:func:`GaussianBlur`.
-
-.. seealso::
-
- :ocv:func:`sepFilter2D`,
- :ocv:func:`getDerivKernels`,
- :ocv:func:`getStructuringElement`,
- :ocv:func:`GaussianBlur`
-
-
-
-getGaborKernel
------------------
-Returns Gabor filter coefficients.
-
-.. ocv:function:: Mat getGaborKernel( Size ksize, double sigma, double theta, double lambd, double gamma, double psi = CV_PI*0.5, int ktype = CV_64F )
-
-.. ocv:pyfunction:: cv2.getGaborKernel(ksize, sigma, theta, lambd, gamma[, psi[, ktype]]) -> retval
-
- :param ksize: Size of the filter returned.
-
- :param sigma: Standard deviation of the gaussian envelope.
-
- :param theta: Orientation of the normal to the parallel stripes of a Gabor function.
-
- :param lambd: Wavelength of the sinusoidal factor.
-
- :param gamma: Spatial aspect ratio.
-
- :param psi: Phase offset.
-
- :param ktype: Type of filter coefficients. It can be ``CV_32F`` or ``CV_64F`` .
-
-For more details about gabor filter equations and parameters, see: `Gabor Filter <http://en.wikipedia.org/wiki/Gabor_filter>`_.
-
-
-getStructuringElement
----------------------
-Returns a structuring element of the specified size and shape for morphological operations.
-
-.. ocv:function:: Mat getStructuringElement(int shape, Size ksize, Point anchor=Point(-1,-1))
-
-.. ocv:pyfunction:: cv2.getStructuringElement(shape, ksize[, anchor]) -> retval
-
-.. ocv:cfunction:: IplConvKernel* cvCreateStructuringElementEx( int cols, int rows, int anchor_x, int anchor_y, int shape, int* values=NULL )
-
- :param shape: Element shape that could be one of the following:
-
- * **MORPH_RECT** - a rectangular structuring element:
-
- .. math::
-
- E_{ij}=1
-
- * **MORPH_ELLIPSE** - an elliptic structuring element, that is, a filled ellipse inscribed into the rectangle ``Rect(0, 0, esize.width, 0.esize.height)``
-
- * **MORPH_CROSS** - a cross-shaped structuring element:
-
- .. math::
-
- E_{ij} = \fork{1}{if i=\texttt{anchor.y} or j=\texttt{anchor.x}}{0}{otherwise}
-
- * **CV_SHAPE_CUSTOM** - custom structuring element (OpenCV 1.x API)
-
- :param ksize: Size of the structuring element.
-
- :param cols: Width of the structuring element
-
- :param rows: Height of the structuring element
-
- :param anchor: Anchor position within the element. The default value :math:`(-1, -1)` means that the anchor is at the center. Note that only the shape of a cross-shaped element depends on the anchor position. In other cases the anchor just regulates how much the result of the morphological operation is shifted.
-
- :param anchor_x: x-coordinate of the anchor
-
- :param anchor_y: y-coordinate of the anchor
-
- :param values: integer array of ``cols``*``rows`` elements that specifies the custom shape of the structuring element, when ``shape=CV_SHAPE_CUSTOM``.
-
-The function constructs and returns the structuring element that can be further passed to
-:ocv:func:`erode`,
-:ocv:func:`dilate` or
-:ocv:func:`morphologyEx` . But you can also construct an arbitrary binary mask yourself and use it as the structuring element.
-
-.. note:: When using OpenCV 1.x C API, the created structuring element ``IplConvKernel* element`` must be released in the end using ``cvReleaseStructuringElement(&element)``.
-
-
-medianBlur
-----------
-Blurs an image using the median filter.
-
-.. ocv:function:: void medianBlur( InputArray src, OutputArray dst, int ksize )
-
-.. ocv:pyfunction:: cv2.medianBlur(src, ksize[, dst]) -> dst
-
- :param src: input 1-, 3-, or 4-channel image; when ``ksize`` is 3 or 5, the image depth should be ``CV_8U``, ``CV_16U``, or ``CV_32F``, for larger aperture sizes, it can only be ``CV_8U``.
-
- :param dst: destination array of the same size and type as ``src``.
-
- :param ksize: aperture linear size; it must be odd and greater than 1, for example: 3, 5, 7 ...
-
-The function smoothes an image using the median filter with the
-:math:`\texttt{ksize} \times \texttt{ksize}` aperture. Each channel of a multi-channel image is processed independently. In-place operation is supported.
-
-.. seealso::
-
- :ocv:func:`bilateralFilter`,
- :ocv:func:`blur`,
- :ocv:func:`boxFilter`,
- :ocv:func:`GaussianBlur`
-
-
-
-morphologyEx
-------------
-Performs advanced morphological transformations.
-
-.. ocv:function:: void morphologyEx( InputArray src, OutputArray dst, int op, InputArray kernel, Point anchor=Point(-1,-1), int iterations=1, int borderType=BORDER_CONSTANT, const Scalar& borderValue=morphologyDefaultBorderValue() )
-
-.. ocv:pyfunction:: cv2.morphologyEx(src, op, kernel[, dst[, anchor[, iterations[, borderType[, borderValue]]]]]) -> dst
-
-.. ocv:cfunction:: void cvMorphologyEx( const CvArr* src, CvArr* dst, CvArr* temp, IplConvKernel* element, int operation, int iterations=1 )
-
- :param src: Source image. The number of channels can be arbitrary. The depth should be one of ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F` or ``CV_64F``.
-
- :param dst: Destination image of the same size and type as ``src`` .
-
- :param kernel: Structuring element. It can be created using :ocv:func:`getStructuringElement`.
-
- :param anchor: Anchor position with the kernel. Negative values mean that the anchor is at the kernel center.
-
- :param op: Type of a morphological operation that can be one of the following:
-
- * **MORPH_OPEN** - an opening operation
-
- * **MORPH_CLOSE** - a closing operation
-
- * **MORPH_GRADIENT** - a morphological gradient
-
- * **MORPH_TOPHAT** - "top hat"
-
- * **MORPH_BLACKHAT** - "black hat"
-
- :param iterations: Number of times erosion and dilation are applied.
-
- :param borderType: Pixel extrapolation method. See ``borderInterpolate`` for details.
-
- :param borderValue: Border value in case of a constant border. The default value has a special meaning.
-
-The function can perform advanced morphological transformations using an erosion and dilation as basic operations.
-
-Opening operation:
-
-.. math::
-
- \texttt{dst} = \mathrm{open} ( \texttt{src} , \texttt{element} )= \mathrm{dilate} ( \mathrm{erode} ( \texttt{src} , \texttt{element} ))
-
-Closing operation:
-
-.. math::
-
- \texttt{dst} = \mathrm{close} ( \texttt{src} , \texttt{element} )= \mathrm{erode} ( \mathrm{dilate} ( \texttt{src} , \texttt{element} ))
-
-Morphological gradient:
-
-.. math::
-
- \texttt{dst} = \mathrm{morph\_grad} ( \texttt{src} , \texttt{element} )= \mathrm{dilate} ( \texttt{src} , \texttt{element} )- \mathrm{erode} ( \texttt{src} , \texttt{element} )
-
-"Top hat":
-
-.. math::
-
- \texttt{dst} = \mathrm{tophat} ( \texttt{src} , \texttt{element} )= \texttt{src} - \mathrm{open} ( \texttt{src} , \texttt{element} )
-
-"Black hat":
-
-.. math::
-
- \texttt{dst} = \mathrm{blackhat} ( \texttt{src} , \texttt{element} )= \mathrm{close} ( \texttt{src} , \texttt{element} )- \texttt{src}
-
-Any of the operations can be done in-place. In case of multi-channel images, each channel is processed independently.
-
-.. seealso::
-
- :ocv:func:`dilate`,
- :ocv:func:`erode`,
- :ocv:func:`getStructuringElement`
-
-.. note::
-
- * An example using the morphologyEx function for the morphological opening and closing operations can be found at opencv_source_code/samples/cpp/morphology2.cpp
-
-Laplacian
----------
-Calculates the Laplacian of an image.
-
-.. ocv:function:: void Laplacian( InputArray src, OutputArray dst, int ddepth, int ksize=1, double scale=1, double delta=0, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.Laplacian(src, ddepth[, dst[, ksize[, scale[, delta[, borderType]]]]]) -> dst
-
-.. ocv:cfunction:: void cvLaplace( const CvArr* src, CvArr* dst, int aperture_size=3 )
-
- :param src: Source image.
-
- :param dst: Destination image of the same size and the same number of channels as ``src`` .
-
- :param ddepth: Desired depth of the destination image.
-
- :param ksize: Aperture size used to compute the second-derivative filters. See :ocv:func:`getDerivKernels` for details. The size must be positive and odd.
-
- :param scale: Optional scale factor for the computed Laplacian values. By default, no scaling is applied. See :ocv:func:`getDerivKernels` for details.
-
- :param delta: Optional delta value that is added to the results prior to storing them in ``dst`` .
-
- :param borderType: Pixel extrapolation method. See ``borderInterpolate`` for details.
-
-The function calculates the Laplacian of the source image by adding up the second x and y derivatives calculated using the Sobel operator:
-
-.. math::
-
- \texttt{dst} = \Delta \texttt{src} = \frac{\partial^2 \texttt{src}}{\partial x^2} + \frac{\partial^2 \texttt{src}}{\partial y^2}
-
-This is done when ``ksize > 1`` . When ``ksize == 1`` , the Laplacian is computed by filtering the image with the following
-:math:`3 \times 3` aperture:
-
-.. math::
-
- \vecthreethree {0}{1}{0}{1}{-4}{1}{0}{1}{0}
-
-.. seealso::
-
- :ocv:func:`Sobel`,
- :ocv:func:`Scharr`
-
-.. note::
-
- * An example using the Laplace transformation for edge detection can be found at opencv_source_code/samples/cpp/laplace.cpp
-
-pyrDown
--------
-Blurs an image and downsamples it.
-
-.. ocv:function:: void pyrDown( InputArray src, OutputArray dst, const Size& dstsize=Size(), int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.pyrDown(src[, dst[, dstsize[, borderType]]]) -> dst
-
-.. ocv:cfunction:: void cvPyrDown( const CvArr* src, CvArr* dst, int filter=CV_GAUSSIAN_5x5 )
-
- :param src: input image.
-
- :param dst: output image; it has the specified size and the same type as ``src``.
-
- :param dstsize: size of the output image.
-
- :param borderType: Pixel extrapolation method (BORDER_CONSTANT don't supported). See ``borderInterpolate`` for details.
-
-By default, size of the output image is computed as ``Size((src.cols+1)/2, (src.rows+1)/2)``, but in any case, the following conditions should be satisfied:
-
-.. math::
-
- \begin{array}{l}
- | \texttt{dstsize.width} *2-src.cols| \leq 2 \\ | \texttt{dstsize.height} *2-src.rows| \leq 2 \end{array}
-
-The function performs the downsampling step of the Gaussian pyramid construction. First, it convolves the source image with the kernel:
-
-.. math::
-
- \frac{1}{256} \begin{bmatrix} 1 & 4 & 6 & 4 & 1 \\ 4 & 16 & 24 & 16 & 4 \\ 6 & 24 & 36 & 24 & 6 \\ 4 & 16 & 24 & 16 & 4 \\ 1 & 4 & 6 & 4 & 1 \end{bmatrix}
-
-Then, it downsamples the image by rejecting even rows and columns.
-
-pyrUp
------
-Upsamples an image and then blurs it.
-
-.. ocv:function:: void pyrUp( InputArray src, OutputArray dst, const Size& dstsize=Size(), int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.pyrUp(src[, dst[, dstsize[, borderType]]]) -> dst
-
-.. ocv:cfunction:: cvPyrUp( const CvArr* src, CvArr* dst, int filter=CV_GAUSSIAN_5x5 )
-
- :param src: input image.
-
- :param dst: output image. It has the specified size and the same type as ``src`` .
-
- :param dstsize: size of the output image.
-
- :param borderType: Pixel extrapolation method (only BORDER_DEFAULT supported). See ``borderInterpolate`` for details.
-
-By default, size of the output image is computed as ``Size(src.cols*2, (src.rows*2)``, but in any case, the following conditions should be satisfied:
-
-.. math::
-
- \begin{array}{l}
- | \texttt{dstsize.width} -src.cols*2| \leq ( \texttt{dstsize.width} \mod 2) \\ | \texttt{dstsize.height} -src.rows*2| \leq ( \texttt{dstsize.height} \mod 2) \end{array}
-
-The function performs the upsampling step of the Gaussian pyramid construction, though it can actually be used to construct the Laplacian pyramid. First, it upsamples the source image by injecting even zero rows and columns and then convolves the result with the same kernel as in
-:ocv:func:`pyrDown` multiplied by 4.
-
-.. note::
-
- * (Python) An example of Laplacian Pyramid construction and merging can be found at opencv_source_code/samples/python2/lappyr.py
-
-
-pyrMeanShiftFiltering
----------------------
-Performs initial step of meanshift segmentation of an image.
-
-.. ocv:function:: void pyrMeanShiftFiltering( InputArray src, OutputArray dst, double sp, double sr, int maxLevel=1, TermCriteria termcrit=TermCriteria(TermCriteria::MAX_ITER+TermCriteria::EPS,5,1) )
-
-.. ocv:pyfunction:: cv2.pyrMeanShiftFiltering(src, sp, sr[, dst[, maxLevel[, termcrit]]]) -> dst
-
-.. ocv:cfunction:: void cvPyrMeanShiftFiltering( const CvArr* src, CvArr* dst, double sp, double sr, int max_level=1, CvTermCriteria termcrit= cvTermCriteria(CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,5,1))
-
- :param src: The source 8-bit, 3-channel image.
-
- :param dst: The destination image of the same format and the same size as the source.
-
- :param sp: The spatial window radius.
-
- :param sr: The color window radius.
-
- :param maxLevel: Maximum level of the pyramid for the segmentation.
-
- :param termcrit: Termination criteria: when to stop meanshift iterations.
-
-
-The function implements the filtering stage of meanshift segmentation, that is, the output of the function is the filtered "posterized" image with color gradients and fine-grain texture flattened. At every pixel
-``(X,Y)`` of the input image (or down-sized input image, see below) the function executes meanshift
-iterations, that is, the pixel ``(X,Y)`` neighborhood in the joint space-color hyperspace is considered:
-
- .. math::
-
- (x,y): X- \texttt{sp} \le x \le X+ \texttt{sp} , Y- \texttt{sp} \le y \le Y+ \texttt{sp} , ||(R,G,B)-(r,g,b)|| \le \texttt{sr}
-
-
-where ``(R,G,B)`` and ``(r,g,b)`` are the vectors of color components at ``(X,Y)`` and ``(x,y)``, respectively (though, the algorithm does not depend on the color space used, so any 3-component color space can be used instead). Over the neighborhood the average spatial value ``(X',Y')`` and average color vector ``(R',G',B')`` are found and they act as the neighborhood center on the next iteration:
-
- .. math::
-
- (X,Y)~(X',Y'), (R,G,B)~(R',G',B').
-
-After the iterations over, the color components of the initial pixel (that is, the pixel from where the iterations started) are set to the final value (average color at the last iteration):
-
- .. math::
-
- I(X,Y) <- (R*,G*,B*)
-
-When ``maxLevel > 0``, the gaussian pyramid of ``maxLevel+1`` levels is built, and the above procedure is run on the smallest layer first. After that, the results are propagated to the larger layer and the iterations are run again only on those pixels where the layer colors differ by more than ``sr`` from the lower-resolution layer of the pyramid. That makes boundaries of color regions sharper. Note that the results will be actually different from the ones obtained by running the meanshift procedure on the whole original image (i.e. when ``maxLevel==0``).
-
-.. note::
-
- * An example using mean-shift image segmentation can be found at opencv_source_code/samples/cpp/meanshift_segmentation.cpp
-
-sepFilter2D
------------
-Applies a separable linear filter to an image.
-
-.. ocv:function:: void sepFilter2D( InputArray src, OutputArray dst, int ddepth, InputArray kernelX, InputArray kernelY, Point anchor=Point(-1,-1), double delta=0, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.sepFilter2D(src, ddepth, kernelX, kernelY[, dst[, anchor[, delta[, borderType]]]]) -> dst
-
- :param src: Source image.
-
- :param dst: Destination image of the same size and the same number of channels as ``src`` .
-
- :param ddepth: Destination image depth. The following combination of ``src.depth()`` and ``ddepth`` are supported:
- * ``src.depth()`` = ``CV_8U``, ``ddepth`` = -1/``CV_16S``/``CV_32F``/``CV_64F``
- * ``src.depth()`` = ``CV_16U``/``CV_16S``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
- * ``src.depth()`` = ``CV_32F``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
- * ``src.depth()`` = ``CV_64F``, ``ddepth`` = -1/``CV_64F``
-
- when ``ddepth=-1``, the destination image will have the same depth as the source.
-
- :param kernelX: Coefficients for filtering each row.
-
- :param kernelY: Coefficients for filtering each column.
-
- :param anchor: Anchor position within the kernel. The default value :math:`(-1,-1)` means that the anchor is at the kernel center.
-
- :param delta: Value added to the filtered results before storing them.
-
- :param borderType: Pixel extrapolation method. See ``borderInterpolate`` for details.
-
-The function applies a separable linear filter to the image. That is, first, every row of ``src`` is filtered with the 1D kernel ``kernelX`` . Then, every column of the result is filtered with the 1D kernel ``kernelY`` . The final result shifted by ``delta`` is stored in ``dst`` .
-
-.. seealso::
-
- :ocv:func:`filter2D`,
- :ocv:func:`Sobel`,
- :ocv:func:`GaussianBlur`,
- :ocv:func:`boxFilter`,
- :ocv:func:`blur`
-
-
-Smooth
-------
-Smooths the image in one of several ways.
-
-.. ocv:cfunction:: void cvSmooth( const CvArr* src, CvArr* dst, int smoothtype=CV_GAUSSIAN, int size1=3, int size2=0, double sigma1=0, double sigma2=0 )
-
- :param src: The source image
-
- :param dst: The destination image
-
- :param smoothtype: Type of the smoothing:
-
- * **CV_BLUR_NO_SCALE** linear convolution with :math:`\texttt{size1}\times\texttt{size2}` box kernel (all 1's). If you want to smooth different pixels with different-size box kernels, you can use the integral image that is computed using :ocv:func:`integral`
-
-
- * **CV_BLUR** linear convolution with :math:`\texttt{size1}\times\texttt{size2}` box kernel (all 1's) with subsequent scaling by :math:`1/(\texttt{size1}\cdot\texttt{size2})`
-
-
- * **CV_GAUSSIAN** linear convolution with a :math:`\texttt{size1}\times\texttt{size2}` Gaussian kernel
-
-
- * **CV_MEDIAN** median filter with a :math:`\texttt{size1}\times\texttt{size1}` square aperture
-
-
- * **CV_BILATERAL** bilateral filter with a :math:`\texttt{size1}\times\texttt{size1}` square aperture, color sigma= ``sigma1`` and spatial sigma= ``sigma2`` . If ``size1=0`` , the aperture square side is set to ``cvRound(sigma2*1.5)*2+1`` . Information about bilateral filtering can be found at http://www.dai.ed.ac.uk/CVonline/LOCAL\_COPIES/MANDUCHI1/Bilateral\_Filtering.html
-
-
- :param size1: The first parameter of the smoothing operation, the aperture width. Must be a positive odd number (1, 3, 5, ...)
-
- :param size2: The second parameter of the smoothing operation, the aperture height. Ignored by ``CV_MEDIAN`` and ``CV_BILATERAL`` methods. In the case of simple scaled/non-scaled and Gaussian blur if ``size2`` is zero, it is set to ``size1`` . Otherwise it must be a positive odd number.
-
- :param sigma1: In the case of a Gaussian parameter this parameter may specify Gaussian :math:`\sigma` (standard deviation). If it is zero, it is calculated from the kernel size:
-
- .. math::
-
- \sigma = 0.3 (n/2 - 1) + 0.8 \quad \text{where} \quad n= \begin{array}{l l} \mbox{\texttt{size1} for horizontal kernel} \\ \mbox{\texttt{size2} for vertical kernel} \end{array}
-
- Using standard sigma for small kernels ( :math:`3\times 3` to :math:`7\times 7` ) gives better speed. If ``sigma1`` is not zero, while ``size1`` and ``size2`` are zeros, the kernel size is calculated from the sigma (to provide accurate enough operation).
-
-The function smooths an image using one of several methods. Every of the methods has some features and restrictions listed below:
-
- * Blur with no scaling works with single-channel images only and supports accumulation of 8-bit to 16-bit format (similar to :ocv:func:`Sobel` and :ocv:func:`Laplacian`) and 32-bit floating point to 32-bit floating-point format.
-
- * Simple blur and Gaussian blur support 1- or 3-channel, 8-bit and 32-bit floating point images. These two methods can process images in-place.
-
- * Median and bilateral filters work with 1- or 3-channel 8-bit images and can not process images in-place.
-
-.. note:: The function is now obsolete. Use :ocv:func:`GaussianBlur`, :ocv:func:`blur`, :ocv:func:`medianBlur` or :ocv:func:`bilateralFilter`.
-
-
-Sobel
------
-Calculates the first, second, third, or mixed image derivatives using an extended Sobel operator.
-
-.. ocv:function:: void Sobel( InputArray src, OutputArray dst, int ddepth, int dx, int dy, int ksize=3, double scale=1, double delta=0, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.Sobel(src, ddepth, dx, dy[, dst[, ksize[, scale[, delta[, borderType]]]]]) -> dst
-
-.. ocv:cfunction:: void cvSobel( const CvArr* src, CvArr* dst, int xorder, int yorder, int aperture_size=3 )
-
- :param src: input image.
-
- :param dst: output image of the same size and the same number of channels as ``src`` .
-
- :param ddepth: output image depth; the following combinations of ``src.depth()`` and ``ddepth`` are supported:
- * ``src.depth()`` = ``CV_8U``, ``ddepth`` = -1/``CV_16S``/``CV_32F``/``CV_64F``
- * ``src.depth()`` = ``CV_16U``/``CV_16S``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
- * ``src.depth()`` = ``CV_32F``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
- * ``src.depth()`` = ``CV_64F``, ``ddepth`` = -1/``CV_64F``
-
- when ``ddepth=-1``, the destination image will have the same depth as the source; in the case of 8-bit input images it will result in truncated derivatives.
-
- :param xorder: order of the derivative x.
-
- :param yorder: order of the derivative y.
-
- :param ksize: size of the extended Sobel kernel; it must be 1, 3, 5, or 7.
-
- :param scale: optional scale factor for the computed derivative values; by default, no scaling is applied (see :ocv:func:`getDerivKernels` for details).
-
- :param delta: optional delta value that is added to the results prior to storing them in ``dst``.
-
- :param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
-
-In all cases except one, the
-:math:`\texttt{ksize} \times
-\texttt{ksize}` separable kernel is used to calculate the
-derivative. When
-:math:`\texttt{ksize = 1}` , the
-:math:`3 \times 1` or
-:math:`1 \times 3` kernel is used (that is, no Gaussian smoothing is done). ``ksize = 1`` can only be used for the first or the second x- or y- derivatives.
-
-There is also the special value ``ksize = CV_SCHARR`` (-1) that corresponds to the
-:math:`3\times3` Scharr
-filter that may give more accurate results than the
-:math:`3\times3` Sobel. The Scharr aperture is
-
-.. math::
-
- \vecthreethree{-3}{0}{3}{-10}{0}{10}{-3}{0}{3}
-
-for the x-derivative, or transposed for the y-derivative.
-
-The function calculates an image derivative by convolving the image with the appropriate kernel:
-
-.. math::
-
- \texttt{dst} = \frac{\partial^{xorder+yorder} \texttt{src}}{\partial x^{xorder} \partial y^{yorder}}
-
-The Sobel operators combine Gaussian smoothing and differentiation,
-so the result is more or less resistant to the noise. Most often,
-the function is called with ( ``xorder`` = 1, ``yorder`` = 0, ``ksize`` = 3) or ( ``xorder`` = 0, ``yorder`` = 1, ``ksize`` = 3) to calculate the first x- or y- image
-derivative. The first case corresponds to a kernel of:
-
-.. math::
-
- \vecthreethree{-1}{0}{1}{-2}{0}{2}{-1}{0}{1}
-
-The second case corresponds to a kernel of:
-
-.. math::
-
- \vecthreethree{-1}{-2}{-1}{0}{0}{0}{1}{2}{1}
-
-.. seealso::
-
- :ocv:func:`Scharr`,
- :ocv:func:`Laplacian`,
- :ocv:func:`sepFilter2D`,
- :ocv:func:`filter2D`,
- :ocv:func:`GaussianBlur`,
- :ocv:func:`cartToPolar`
-
-
-
-Scharr
-------
-Calculates the first x- or y- image derivative using Scharr operator.
-
-.. ocv:function:: void Scharr( InputArray src, OutputArray dst, int ddepth, int dx, int dy, double scale=1, double delta=0, int borderType=BORDER_DEFAULT )
-
-.. ocv:pyfunction:: cv2.Scharr(src, ddepth, dx, dy[, dst[, scale[, delta[, borderType]]]]) -> dst
-
- :param src: input image.
-
- :param dst: output image of the same size and the same number of channels as ``src``.
-
- :param ddepth: output image depth (see :ocv:func:`Sobel` for the list of supported combination of ``src.depth()`` and ``ddepth``).
-
- :param dx: order of the derivative x.
-
- :param dy: order of the derivative y.
-
- :param scale: optional scale factor for the computed derivative values; by default, no scaling is applied (see :ocv:func:`getDerivKernels` for details).
-
- :param delta: optional delta value that is added to the results prior to storing them in ``dst``.
-
- :param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
-
-The function computes the first x- or y- spatial image derivative using the Scharr operator. The call
-
-.. math::
-
- \texttt{Scharr(src, dst, ddepth, dx, dy, scale, delta, borderType)}
-
-is equivalent to
-
-.. math::
-
- \texttt{Sobel(src, dst, ddepth, dx, dy, CV\_SCHARR, scale, delta, borderType)} .
-
-.. seealso::
-
- :ocv:func:`cartToPolar`
+++ /dev/null
-Geometric Image Transformations
-===============================
-.. highlight:: cpp
-
-The functions in this section perform various geometrical transformations of 2D images. They do not change the image content but deform the pixel grid and map this deformed grid to the destination image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order, from destination to the source. That is, for each pixel :math:`(x, y)` of the destination image, the functions compute coordinates of the corresponding "donor" pixel in the source image and copy the pixel value:
-
-.. math::
-
- \texttt{dst} (x,y)= \texttt{src} (f_x(x,y), f_y(x,y))
-
-In case when you specify the forward mapping
-:math:`\left<g_x, g_y\right>: \texttt{src} \rightarrow \texttt{dst}` , the OpenCV functions first compute the corresponding inverse mapping
-:math:`\left<f_x, f_y\right>: \texttt{dst} \rightarrow \texttt{src}` and then use the above formula.
-
-The actual implementations of the geometrical transformations, from the most generic
-:ocv:func:`remap` and to the simplest and the fastest
-:ocv:func:`resize` , need to solve two main problems with the above formula:
-
-*
- Extrapolation of non-existing pixels. Similarly to the filtering functions described in the previous section, for some
- :math:`(x,y)` , either one of
- :math:`f_x(x,y)` , or
- :math:`f_y(x,y)` , or both of them may fall outside of the image. In this case, an extrapolation method needs to be used. OpenCV provides the same selection of extrapolation methods as in the filtering functions. In addition, it provides the method ``BORDER_TRANSPARENT`` . This means that the corresponding pixels in the destination image will not be modified at all.
-
-*
- Interpolation of pixel values. Usually
- :math:`f_x(x,y)` and
- :math:`f_y(x,y)` are floating-point numbers. This means that
- :math:`\left<f_x, f_y\right>` can be either an affine or perspective transformation, or radial lens distortion correction, and so on. So, a pixel value at fractional coordinates needs to be retrieved. In the simplest case, the coordinates can be just rounded to the nearest integer coordinates and the corresponding pixel can be used. This is called a nearest-neighbor interpolation. However, a better result can be achieved by using more sophisticated `interpolation methods <http://en.wikipedia.org/wiki/Multivariate_interpolation>`_
- , where a polynomial function is fit into some neighborhood of the computed pixel
- :math:`(f_x(x,y), f_y(x,y))` , and then the value of the polynomial at
- :math:`(f_x(x,y), f_y(x,y))` is taken as the interpolated pixel value. In OpenCV, you can choose between several interpolation methods. See
- :ocv:func:`resize` for details.
-
-convertMaps
------------
-Converts image transformation maps from one representation to another.
-
-.. ocv:function:: void convertMaps( InputArray map1, InputArray map2, OutputArray dstmap1, OutputArray dstmap2, int dstmap1type, bool nninterpolation=false )
-
-.. ocv:pyfunction:: cv2.convertMaps(map1, map2, dstmap1type[, dstmap1[, dstmap2[, nninterpolation]]]) -> dstmap1, dstmap2
-
- :param map1: The first input map of type ``CV_16SC2`` , ``CV_32FC1`` , or ``CV_32FC2`` .
-
- :param map2: The second input map of type ``CV_16UC1`` , ``CV_32FC1`` , or none (empty matrix), respectively.
-
- :param dstmap1: The first output map that has the type ``dstmap1type`` and the same size as ``src`` .
-
- :param dstmap2: The second output map.
-
- :param dstmap1type: Type of the first output map that should be ``CV_16SC2`` , ``CV_32FC1`` , or ``CV_32FC2`` .
-
- :param nninterpolation: Flag indicating whether the fixed-point maps are used for the nearest-neighbor or for a more complex interpolation.
-
-The function converts a pair of maps for
-:ocv:func:`remap` from one representation to another. The following options ( ``(map1.type(), map2.type())`` :math:`\rightarrow` ``(dstmap1.type(), dstmap2.type())`` ) are supported:
-
-*
- :math:`\texttt{(CV\_32FC1, CV\_32FC1)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` . This is the most frequently used conversion operation, in which the original floating-point maps (see
- :ocv:func:`remap` ) are converted to a more compact and much faster fixed-point representation. The first output array contains the rounded coordinates and the second array (created only when ``nninterpolation=false`` ) contains indices in the interpolation tables.
-
-*
- :math:`\texttt{(CV\_32FC2)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` . The same as above but the original maps are stored in one 2-channel matrix.
-
-*
- Reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same as the originals.
-
-.. seealso::
-
- :ocv:func:`remap`,
- :ocv:func:`undistort`,
- :ocv:func:`initUndistortRectifyMap`
-
-
-
-getAffineTransform
-----------------------
-Calculates an affine transform from three pairs of the corresponding points.
-
-.. ocv:function:: Mat getAffineTransform( InputArray src, InputArray dst )
-
-.. ocv:function:: Mat getAffineTransform( const Point2f src[], const Point2f dst[] )
-
-.. ocv:pyfunction:: cv2.getAffineTransform(src, dst) -> retval
-
-.. ocv:cfunction:: CvMat* cvGetAffineTransform( const CvPoint2D32f * src, const CvPoint2D32f * dst, CvMat * map_matrix )
-
- :param src: Coordinates of triangle vertices in the source image.
-
- :param dst: Coordinates of the corresponding triangle vertices in the destination image.
-
-The function calculates the :math:`2 \times 3` matrix of an affine transform so that:
-
-.. math::
-
- \begin{bmatrix} x'_i \\ y'_i \end{bmatrix} = \texttt{map\_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}
-
-where
-
-.. math::
-
- dst(i)=(x'_i,y'_i),
- src(i)=(x_i, y_i),
- i=0,1,2
-
-.. seealso::
-
- :ocv:func:`warpAffine`,
- :ocv:func:`transform`
-
-
-
-getPerspectiveTransform
----------------------------
-Calculates a perspective transform from four pairs of the corresponding points.
-
-.. ocv:function:: Mat getPerspectiveTransform( InputArray src, InputArray dst )
-
-.. ocv:function:: Mat getPerspectiveTransform( const Point2f src[], const Point2f dst[] )
-
-.. ocv:pyfunction:: cv2.getPerspectiveTransform(src, dst) -> retval
-
-.. ocv:cfunction:: CvMat* cvGetPerspectiveTransform( const CvPoint2D32f* src, const CvPoint2D32f* dst, CvMat* map_matrix )
-
- :param src: Coordinates of quadrangle vertices in the source image.
-
- :param dst: Coordinates of the corresponding quadrangle vertices in the destination image.
-
-The function calculates the :math:`3 \times 3` matrix of a perspective transform so that:
-
-.. math::
-
- \begin{bmatrix} t_i x'_i \\ t_i y'_i \\ t_i \end{bmatrix} = \texttt{map\_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}
-
-where
-
-.. math::
-
- dst(i)=(x'_i,y'_i),
- src(i)=(x_i, y_i),
- i=0,1,2,3
-
-.. seealso::
-
- :ocv:func:`findHomography`,
- :ocv:func:`warpPerspective`,
- :ocv:func:`perspectiveTransform`
-
-
-getRectSubPix
------------------
-Retrieves a pixel rectangle from an image with sub-pixel accuracy.
-
-.. ocv:function:: void getRectSubPix( InputArray image, Size patchSize, Point2f center, OutputArray patch, int patchType=-1 )
-
-.. ocv:pyfunction:: cv2.getRectSubPix(image, patchSize, center[, patch[, patchType]]) -> patch
-
-.. ocv:cfunction:: void cvGetRectSubPix( const CvArr* src, CvArr* dst, CvPoint2D32f center )
-
- :param src: Source image.
-
- :param patchSize: Size of the extracted patch.
-
- :param center: Floating point coordinates of the center of the extracted rectangle within the source image. The center must be inside the image.
-
- :param dst: Extracted patch that has the size ``patchSize`` and the same number of channels as ``src`` .
-
- :param patchType: Depth of the extracted pixels. By default, they have the same depth as ``src`` .
-
-The function ``getRectSubPix`` extracts pixels from ``src`` :
-
-.. math::
-
- dst(x, y) = src(x + \texttt{center.x} - ( \texttt{dst.cols} -1)*0.5, y + \texttt{center.y} - ( \texttt{dst.rows} -1)*0.5)
-
-where the values of the pixels at non-integer coordinates are retrieved
-using bilinear interpolation. Every channel of multi-channel
-images is processed independently. While the center of the rectangle
-must be inside the image, parts of the rectangle may be
-outside. In this case, the replication border mode (see
-:ocv:func:`borderInterpolate` ) is used to extrapolate
-the pixel values outside of the image.
-
-.. seealso::
-
- :ocv:func:`warpAffine`,
- :ocv:func:`warpPerspective`
-
-
-getRotationMatrix2D
------------------------
-Calculates an affine matrix of 2D rotation.
-
-.. ocv:function:: Mat getRotationMatrix2D( Point2f center, double angle, double scale )
-
-.. ocv:pyfunction:: cv2.getRotationMatrix2D(center, angle, scale) -> retval
-
-.. ocv:cfunction:: CvMat* cv2DRotationMatrix( CvPoint2D32f center, double angle, double scale, CvMat* map_matrix )
-
- :param center: Center of the rotation in the source image.
-
- :param angle: Rotation angle in degrees. Positive values mean counter-clockwise rotation (the coordinate origin is assumed to be the top-left corner).
-
- :param scale: Isotropic scale factor.
-
- :param map_matrix: The output affine transformation, 2x3 floating-point matrix.
-
-The function calculates the following matrix:
-
-.. math::
-
- \begin{bmatrix} \alpha & \beta & (1- \alpha ) \cdot \texttt{center.x} - \beta \cdot \texttt{center.y} \\ - \beta & \alpha & \beta \cdot \texttt{center.x} + (1- \alpha ) \cdot \texttt{center.y} \end{bmatrix}
-
-where
-
-.. math::
-
- \begin{array}{l} \alpha = \texttt{scale} \cdot \cos \texttt{angle} , \\ \beta = \texttt{scale} \cdot \sin \texttt{angle} \end{array}
-
-The transformation maps the rotation center to itself. If this is not the target, adjust the shift.
-
-.. seealso::
-
- :ocv:func:`getAffineTransform`,
- :ocv:func:`warpAffine`,
- :ocv:func:`transform`
-
-
-
-invertAffineTransform
--------------------------
-Inverts an affine transformation.
-
-.. ocv:function:: void invertAffineTransform(InputArray M, OutputArray iM)
-
-.. ocv:pyfunction:: cv2.invertAffineTransform(M[, iM]) -> iM
-
- :param M: Original affine transformation.
-
- :param iM: Output reverse affine transformation.
-
-The function computes an inverse affine transformation represented by
-:math:`2 \times 3` matrix ``M`` :
-
-.. math::
-
- \begin{bmatrix} a_{11} & a_{12} & b_1 \\ a_{21} & a_{22} & b_2 \end{bmatrix}
-
-The result is also a
-:math:`2 \times 3` matrix of the same type as ``M`` .
-
-LinearPolar
------------
-Remaps an image to polar space.
-
-.. ocv:cfunction:: void cvLinearPolar( const CvArr* src, CvArr* dst, CvPoint2D32f center, double maxRadius, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS )
-
- :param src: Source image
-
- :param dst: Destination image
-
- :param center: The transformation center;
-
- :param maxRadius: Inverse magnitude scale parameter. See below
-
- :param flags: A combination of interpolation methods and the following optional flags:
-
- * **CV_WARP_FILL_OUTLIERS** fills all of the destination image pixels. If some of them correspond to outliers in the source image, they are set to zero
-
- * **CV_WARP_INVERSE_MAP** See below
-
-The function ``cvLinearPolar`` transforms the source image using the following transformation:
-
- *
- Forward transformation (``CV_WARP_INVERSE_MAP`` is not set):
-
- .. math::
-
- dst( \phi , \rho ) = src(x,y)
-
-
- *
- Inverse transformation (``CV_WARP_INVERSE_MAP`` is set):
-
- .. math::
-
- dst(x,y) = src( \phi , \rho )
-
-
-where
-
- .. math::
-
- \rho = (src.width/maxRadius) \cdot \sqrt{x^2 + y^2} , \phi =atan(y/x)
-
-
-The function can not operate in-place.
-
-.. note::
-
- * An example using the LinearPolar operation can be found at opencv_source_code/samples/c/polar_transforms.c
-
-
-
-LogPolar
---------
-Remaps an image to log-polar space.
-
-.. ocv:cfunction:: void cvLogPolar( const CvArr* src, CvArr* dst, CvPoint2D32f center, double M, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS )
-
- :param src: Source image
-
- :param dst: Destination image
-
- :param center: The transformation center; where the output precision is maximal
-
- :param M: Magnitude scale parameter. See below
-
- :param flags: A combination of interpolation methods and the following optional flags:
-
- * **CV_WARP_FILL_OUTLIERS** fills all of the destination image pixels. If some of them correspond to outliers in the source image, they are set to zero
-
- * **CV_WARP_INVERSE_MAP** See below
-
-The function ``cvLogPolar`` transforms the source image using the following transformation:
-
- *
- Forward transformation (``CV_WARP_INVERSE_MAP`` is not set):
-
- .. math::
-
- dst( \phi , \rho ) = src(x,y)
-
-
- *
- Inverse transformation (``CV_WARP_INVERSE_MAP`` is set):
-
- .. math::
-
- dst(x,y) = src( \phi , \rho )
-
-
-where
-
- .. math::
-
- \rho = M \cdot \log{\sqrt{x^2 + y^2}} , \phi =atan(y/x)
-
-
-The function emulates the human "foveal" vision and can be used for fast scale and rotation-invariant template matching, for object tracking and so forth. The function can not operate in-place.
-
-.. note::
-
- * An example using the geometric logpolar operation in 4 applications can be found at opencv_source_code/samples/cpp/logpolar_bsm.cpp
-
-remap
------
-Applies a generic geometrical transformation to an image.
-
-.. ocv:function:: void remap( InputArray src, OutputArray dst, InputArray map1, InputArray map2, int interpolation, int borderMode=BORDER_CONSTANT, const Scalar& borderValue=Scalar())
-
-.. ocv:pyfunction:: cv2.remap(src, map1, map2, interpolation[, dst[, borderMode[, borderValue]]]) -> dst
-
-.. ocv:cfunction:: void cvRemap( const CvArr* src, CvArr* dst, const CvArr* mapx, const CvArr* mapy, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS, CvScalar fillval=cvScalarAll(0) )
-
- :param src: Source image.
-
- :param dst: Destination image. It has the same size as ``map1`` and the same type as ``src`` .
- :param map1: The first map of either ``(x,y)`` points or just ``x`` values having the type ``CV_16SC2`` , ``CV_32FC1`` , or ``CV_32FC2`` . See :ocv:func:`convertMaps` for details on converting a floating point representation to fixed-point for speed.
-
- :param map2: The second map of ``y`` values having the type ``CV_16UC1`` , ``CV_32FC1`` , or none (empty map if ``map1`` is ``(x,y)`` points), respectively.
-
- :param interpolation: Interpolation method (see :ocv:func:`resize` ). The method ``INTER_AREA`` is not supported by this function.
-
- :param borderMode: Pixel extrapolation method (see :ocv:func:`borderInterpolate` ). When \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function.
-
- :param borderValue: Value used in case of a constant border. By default, it is 0.
-
-The function ``remap`` transforms the source image using the specified map:
-
-.. math::
-
- \texttt{dst} (x,y) = \texttt{src} (map_x(x,y),map_y(x,y))
-
-where values of pixels with non-integer coordinates are computed using one of available interpolation methods.
-:math:`map_x` and
-:math:`map_y` can be encoded as separate floating-point maps in
-:math:`map_1` and
-:math:`map_2` respectively, or interleaved floating-point maps of
-:math:`(x,y)` in
-:math:`map_1` , or
-fixed-point maps created by using
-:ocv:func:`convertMaps` . The reason you might want to convert from floating to fixed-point
-representations of a map is that they can yield much faster (~2x) remapping operations. In the converted case,
-:math:`map_1` contains pairs ``(cvFloor(x), cvFloor(y))`` and
-:math:`map_2` contains indices in a table of interpolation coefficients.
-
-This function cannot operate in-place.
-
-
-
-resize
-------
-Resizes an image.
-
-.. ocv:function:: void resize( InputArray src, OutputArray dst, Size dsize, double fx=0, double fy=0, int interpolation=INTER_LINEAR )
-
-.. ocv:pyfunction:: cv2.resize(src, dsize[, dst[, fx[, fy[, interpolation]]]]) -> dst
-
-.. ocv:cfunction:: void cvResize( const CvArr* src, CvArr* dst, int interpolation=CV_INTER_LINEAR )
-
- :param src: input image.
-
- :param dst: output image; it has the size ``dsize`` (when it is non-zero) or the size computed from ``src.size()``, ``fx``, and ``fy``; the type of ``dst`` is the same as of ``src``.
-
- :param dsize: output image size; if it equals zero, it is computed as:
-
- .. math::
-
- \texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}
-
-
- Either ``dsize`` or both ``fx`` and ``fy`` must be non-zero.
-
- :param fx: scale factor along the horizontal axis; when it equals 0, it is computed as
-
- .. math::
-
- \texttt{(double)dsize.width/src.cols}
-
- :param fy: scale factor along the vertical axis; when it equals 0, it is computed as
-
- .. math::
-
- \texttt{(double)dsize.height/src.rows}
-
- :param interpolation: interpolation method:
-
- * **INTER_NEAREST** - a nearest-neighbor interpolation
-
- * **INTER_LINEAR** - a bilinear interpolation (used by default)
-
- * **INTER_AREA** - resampling using pixel area relation. It may be a preferred method for image decimation, as it gives moire'-free results. But when the image is zoomed, it is similar to the ``INTER_NEAREST`` method.
-
- * **INTER_CUBIC** - a bicubic interpolation over 4x4 pixel neighborhood
-
- * **INTER_LANCZOS4** - a Lanczos interpolation over 8x8 pixel neighborhood
-
-The function ``resize`` resizes the image ``src`` down to or up to the specified size.
-Note that the initial ``dst`` type or size are not taken into account. Instead, the size and type are derived from the ``src``,``dsize``,``fx`` , and ``fy`` . If you want to resize ``src`` so that it fits the pre-created ``dst`` , you may call the function as follows: ::
-
- // explicitly specify dsize=dst.size(); fx and fy will be computed from that.
- resize(src, dst, dst.size(), 0, 0, interpolation);
-
-
-If you want to decimate the image by factor of 2 in each direction, you can call the function this way: ::
-
- // specify fx and fy and let the function compute the destination image size.
- resize(src, dst, Size(), 0.5, 0.5, interpolation);
-
-To shrink an image, it will generally look best with CV_INTER_AREA interpolation, whereas to enlarge an image, it will generally look best with CV_INTER_CUBIC (slow) or CV_INTER_LINEAR (faster but still looks OK).
-
-.. seealso::
-
- :ocv:func:`warpAffine`,
- :ocv:func:`warpPerspective`,
- :ocv:func:`remap`
-
-
-warpAffine
-----------
-Applies an affine transformation to an image.
-
-.. ocv:function:: void warpAffine( InputArray src, OutputArray dst, InputArray M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar& borderValue=Scalar())
-
-.. ocv:pyfunction:: cv2.warpAffine(src, M, dsize[, dst[, flags[, borderMode[, borderValue]]]]) -> dst
-
-.. ocv:cfunction:: void cvWarpAffine( const CvArr* src, CvArr* dst, const CvMat* map_matrix, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS, CvScalar fillval=cvScalarAll(0) )
-
-.. ocv:cfunction:: void cvGetQuadrangleSubPix( const CvArr* src, CvArr* dst, const CvMat* map_matrix )
-
- :param src: input image.
-
- :param dst: output image that has the size ``dsize`` and the same type as ``src`` .
-
- :param M: :math:`2\times 3` transformation matrix.
-
- :param dsize: size of the output image.
-
- :param flags: combination of interpolation methods (see :ocv:func:`resize` ) and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` ).
-
- :param borderMode: pixel extrapolation method (see :ocv:func:`borderInterpolate`); when \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image corresponding to the "outliers" in the source image are not modified by the function.
-
- :param borderValue: value used in case of a constant border; by default, it is 0.
-
-The function ``warpAffine`` transforms the source image using the specified matrix:
-
-.. math::
-
- \texttt{dst} (x,y) = \texttt{src} ( \texttt{M} _{11} x + \texttt{M} _{12} y + \texttt{M} _{13}, \texttt{M} _{21} x + \texttt{M} _{22} y + \texttt{M} _{23})
-
-when the flag ``WARP_INVERSE_MAP`` is set. Otherwise, the transformation is first inverted with
-:ocv:func:`invertAffineTransform` and then put in the formula above instead of ``M`` .
-The function cannot operate in-place.
-
-.. seealso::
-
- :ocv:func:`warpPerspective`,
- :ocv:func:`resize`,
- :ocv:func:`remap`,
- :ocv:func:`getRectSubPix`,
- :ocv:func:`transform`
-
-
-.. note:: ``cvGetQuadrangleSubPix`` is similar to ``cvWarpAffine``, but the outliers are extrapolated using replication border mode.
-
-warpPerspective
----------------
-Applies a perspective transformation to an image.
-
-.. ocv:function:: void warpPerspective( InputArray src, OutputArray dst, InputArray M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar& borderValue=Scalar())
-
-.. ocv:pyfunction:: cv2.warpPerspective(src, M, dsize[, dst[, flags[, borderMode[, borderValue]]]]) -> dst
-
-.. ocv:cfunction:: void cvWarpPerspective( const CvArr* src, CvArr* dst, const CvMat* map_matrix, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS, CvScalar fillval=cvScalarAll(0) )
-
- :param src: input image.
-
- :param dst: output image that has the size ``dsize`` and the same type as ``src`` .
-
- :param M: :math:`3\times 3` transformation matrix.
-
- :param dsize: size of the output image.
-
- :param flags: combination of interpolation methods (``INTER_LINEAR`` or ``INTER_NEAREST``) and the optional flag ``WARP_INVERSE_MAP``, that sets ``M`` as the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` ).
-
- :param borderMode: pixel extrapolation method (``BORDER_CONSTANT`` or ``BORDER_REPLICATE``).
-
- :param borderValue: value used in case of a constant border; by default, it equals 0.
-
-The function ``warpPerspective`` transforms the source image using the specified matrix:
-
-.. math::
-
- \texttt{dst} (x,y) = \texttt{src} \left ( \frac{M_{11} x + M_{12} y + M_{13}}{M_{31} x + M_{32} y + M_{33}} ,
- \frac{M_{21} x + M_{22} y + M_{23}}{M_{31} x + M_{32} y + M_{33}} \right )
-
-when the flag ``WARP_INVERSE_MAP`` is set. Otherwise, the transformation is first inverted with
-:ocv:func:`invert` and then put in the formula above instead of ``M`` .
-The function cannot operate in-place.
-
-.. seealso::
-
- :ocv:func:`warpAffine`,
- :ocv:func:`resize`,
- :ocv:func:`remap`,
- :ocv:func:`getRectSubPix`,
- :ocv:func:`perspectiveTransform`
-
-
-
-
-initUndistortRectifyMap
------------------------
-Computes the undistortion and rectification transformation map.
-
-.. ocv:function:: void initUndistortRectifyMap( InputArray cameraMatrix, InputArray distCoeffs, InputArray R, InputArray newCameraMatrix, Size size, int m1type, OutputArray map1, OutputArray map2 )
-
-.. ocv:pyfunction:: cv2.initUndistortRectifyMap(cameraMatrix, distCoeffs, R, newCameraMatrix, size, m1type[, map1[, map2]]) -> map1, map2
-
-.. ocv:cfunction:: void cvInitUndistortRectifyMap( const CvMat* camera_matrix, const CvMat* dist_coeffs, const CvMat * R, const CvMat* new_camera_matrix, CvArr* mapx, CvArr* mapy )
-.. ocv:cfunction:: void cvInitUndistortMap( const CvMat* camera_matrix, const CvMat* distortion_coeffs, CvArr* mapx, CvArr* mapy )
-
- :param cameraMatrix: Input camera matrix :math:`A=\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}` .
-
- :param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5, or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
-
- :param R: Optional rectification transformation in the object space (3x3 matrix). ``R1`` or ``R2`` , computed by :ocv:func:`stereoRectify` can be passed here. If the matrix is empty, the identity transformation is assumed. In ``cvInitUndistortMap`` R assumed to be an identity matrix.
-
- :param newCameraMatrix: New camera matrix :math:`A'=\vecthreethree{f_x'}{0}{c_x'}{0}{f_y'}{c_y'}{0}{0}{1}` .
-
- :param size: Undistorted image size.
-
- :param m1type: Type of the first output map that can be ``CV_32FC1`` or ``CV_16SC2`` . See :ocv:func:`convertMaps` for details.
-
- :param map1: The first output map.
-
- :param map2: The second output map.
-
-The function computes the joint undistortion and rectification transformation and represents the result in the form of maps for
-:ocv:func:`remap` . The undistorted image looks like original, as if it is captured with a camera using the camera matrix ``=newCameraMatrix`` and zero distortion. In case of a monocular camera, ``newCameraMatrix`` is usually equal to ``cameraMatrix`` , or it can be computed by
-:ocv:func:`getOptimalNewCameraMatrix` for a better control over scaling. In case of a stereo camera, ``newCameraMatrix`` is normally set to ``P1`` or ``P2`` computed by
-:ocv:func:`stereoRectify` .
-
-Also, this new camera is oriented differently in the coordinate space, according to ``R`` . That, for example, helps to align two heads of a stereo camera so that the epipolar lines on both images become horizontal and have the same y- coordinate (in case of a horizontally aligned stereo camera).
-
-The function actually builds the maps for the inverse mapping algorithm that is used by
-:ocv:func:`remap` . That is, for each pixel
-:math:`(u, v)` in the destination (corrected and rectified) image, the function computes the corresponding coordinates in the source image (that is, in the original image from camera). The following process is applied:
-
-.. math::
-
- \begin{array}{l} x \leftarrow (u - {c'}_x)/{f'}_x \\ y \leftarrow (v - {c'}_y)/{f'}_y \\{[X\,Y\,W]} ^T \leftarrow R^{-1}*[x \, y \, 1]^T \\ x' \leftarrow X/W \\ y' \leftarrow Y/W \\ x" \leftarrow x' (1 + k_1 r^2 + k_2 r^4 + k_3 r^6) + 2p_1 x' y' + p_2(r^2 + 2 x'^2) \\ y" \leftarrow y' (1 + k_1 r^2 + k_2 r^4 + k_3 r^6) + p_1 (r^2 + 2 y'^2) + 2 p_2 x' y' \\ map_x(u,v) \leftarrow x" f_x + c_x \\ map_y(u,v) \leftarrow y" f_y + c_y \end{array}
-
-where
-:math:`(k_1, k_2, p_1, p_2[, k_3])` are the distortion coefficients.
-
-In case of a stereo camera, this function is called twice: once for each camera head, after
-:ocv:func:`stereoRectify` , which in its turn is called after
-:ocv:func:`stereoCalibrate` . But if the stereo camera was not calibrated, it is still possible to compute the rectification transformations directly from the fundamental matrix using
-:ocv:func:`stereoRectifyUncalibrated` . For each camera, the function computes homography ``H`` as the rectification transformation in a pixel domain, not a rotation matrix ``R`` in 3D space. ``R`` can be computed from ``H`` as
-
-.. math::
-
- \texttt{R} = \texttt{cameraMatrix} ^{-1} \cdot \texttt{H} \cdot \texttt{cameraMatrix}
-
-where ``cameraMatrix`` can be chosen arbitrarily.
-
-
-
-
-getDefaultNewCameraMatrix
--------------------------
-Returns the default new camera matrix.
-
-.. ocv:function:: Mat getDefaultNewCameraMatrix(InputArray cameraMatrix, Size imgsize=Size(), bool centerPrincipalPoint=false )
-
-.. ocv:pyfunction:: cv2.getDefaultNewCameraMatrix(cameraMatrix[, imgsize[, centerPrincipalPoint]]) -> retval
-
- :param cameraMatrix: Input camera matrix.
-
- :param imgsize: Camera view image size in pixels.
-
- :param centerPrincipalPoint: Location of the principal point in the new camera matrix. The parameter indicates whether this location should be at the image center or not.
-
-The function returns the camera matrix that is either an exact copy of the input ``cameraMatrix`` (when ``centerPrinicipalPoint=false`` ), or the modified one (when ``centerPrincipalPoint=true``).
-
-In the latter case, the new camera matrix will be:
-
-.. math::
-
- \begin{bmatrix} f_x && 0 && ( \texttt{imgSize.width} -1)*0.5 \\ 0 && f_y && ( \texttt{imgSize.height} -1)*0.5 \\ 0 && 0 && 1 \end{bmatrix} ,
-
-where
-:math:`f_x` and
-:math:`f_y` are
-:math:`(0,0)` and
-:math:`(1,1)` elements of ``cameraMatrix`` , respectively.
-
-By default, the undistortion functions in OpenCV (see
-:ocv:func:`initUndistortRectifyMap`,
-:ocv:func:`undistort`) do not move the principal point. However, when you work with stereo, it is important to move the principal points in both views to the same y-coordinate (which is required by most of stereo correspondence algorithms), and may be to the same x-coordinate too. So, you can form the new camera matrix for each view where the principal points are located at the center.
-
-
-
-
-undistort
--------------
-Transforms an image to compensate for lens distortion.
-
-.. ocv:function:: void undistort( InputArray src, OutputArray dst, InputArray cameraMatrix, InputArray distCoeffs, InputArray newCameraMatrix=noArray() )
-
-.. ocv:pyfunction:: cv2.undistort(src, cameraMatrix, distCoeffs[, dst[, newCameraMatrix]]) -> dst
-
-.. ocv:cfunction:: void cvUndistort2( const CvArr* src, CvArr* dst, const CvMat* camera_matrix, const CvMat* distortion_coeffs, const CvMat* new_camera_matrix=0 )
-
- :param src: Input (distorted) image.
-
- :param dst: Output (corrected) image that has the same size and type as ``src`` .
-
- :param cameraMatrix: Input camera matrix :math:`A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}` .
-
- :param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5, or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
-
- :param newCameraMatrix: Camera matrix of the distorted image. By default, it is the same as ``cameraMatrix`` but you may additionally scale and shift the result by using a different matrix.
-
-The function transforms an image to compensate radial and tangential lens distortion.
-
-The function is simply a combination of
-:ocv:func:`initUndistortRectifyMap` (with unity ``R`` ) and
-:ocv:func:`remap` (with bilinear interpolation). See the former function for details of the transformation being performed.
-
-Those pixels in the destination image, for which there is no correspondent pixels in the source image, are filled with zeros (black color).
-
-A particular subset of the source image that will be visible in the corrected image can be regulated by ``newCameraMatrix`` . You can use
-:ocv:func:`getOptimalNewCameraMatrix` to compute the appropriate ``newCameraMatrix`` depending on your requirements.
-
-The camera matrix and the distortion parameters can be determined using
-:ocv:func:`calibrateCamera` . If the resolution of images is different from the resolution used at the calibration stage,
-:math:`f_x, f_y, c_x` and
-:math:`c_y` need to be scaled accordingly, while the distortion coefficients remain the same.
-
-
-
-
-undistortPoints
--------------------
-Computes the ideal point coordinates from the observed point coordinates.
-
-.. ocv:function:: void undistortPoints( InputArray src, OutputArray dst, InputArray cameraMatrix, InputArray distCoeffs, InputArray R=noArray(), InputArray P=noArray())
-
-.. ocv:cfunction:: void cvUndistortPoints( const CvMat* src, CvMat* dst, const CvMat* camera_matrix, const CvMat* dist_coeffs, const CvMat* R=0, const CvMat* P=0 )
-
- :param src: Observed point coordinates, 1xN or Nx1 2-channel (CV_32FC2 or CV_64FC2).
-
- :param dst: Output ideal point coordinates after undistortion and reverse perspective transformation. If matrix ``P`` is identity or omitted, ``dst`` will contain normalized point coordinates.
-
- :param cameraMatrix: Camera matrix :math:`\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}` .
-
- :param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5, or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
-
- :param R: Rectification transformation in the object space (3x3 matrix). ``R1`` or ``R2`` computed by :ocv:func:`stereoRectify` can be passed here. If the matrix is empty, the identity transformation is used.
-
- :param P: New camera matrix (3x3) or new projection matrix (3x4). ``P1`` or ``P2`` computed by :ocv:func:`stereoRectify` can be passed here. If the matrix is empty, the identity new camera matrix is used.
-
-The function is similar to
-:ocv:func:`undistort` and
-:ocv:func:`initUndistortRectifyMap` but it operates on a sparse set of points instead of a raster image. Also the function performs a reverse transformation to
-:ocv:func:`projectPoints` . In case of a 3D object, it does not reconstruct its 3D coordinates, but for a planar object, it does, up to a translation vector, if the proper ``R`` is specified. ::
-
- // (u,v) is the input point, (u', v') is the output point
- // camera_matrix=[fx 0 cx; 0 fy cy; 0 0 1]
- // P=[fx' 0 cx' tx; 0 fy' cy' ty; 0 0 1 tz]
- x" = (u - cx)/fx
- y" = (v - cy)/fy
- (x',y') = undistort(x",y",dist_coeffs)
- [X,Y,W]T = R*[x' y' 1]T
- x = X/W, y = Y/W
- // only performed if P=[fx' 0 cx' [tx]; 0 fy' cy' [ty]; 0 0 1 [tz]] is specified
- u' = x*fx' + cx'
- v' = y*fy' + cy',
-
-where ``undistort()`` is an approximate iterative algorithm that estimates the normalized original point coordinates out of the normalized distorted point coordinates ("normalized" means that the coordinates do not depend on the camera matrix).
-
-The function can be used for both a stereo camera head or a monocular camera (when R is empty).
+++ /dev/null
-Histograms
-==========
-
-.. highlight:: cpp
-
-
-
-calcHist
-------------
-Calculates a histogram of a set of arrays.
-
-.. ocv:function:: void calcHist( const Mat* images, int nimages, const int* channels, InputArray mask, OutputArray hist, int dims, const int* histSize, const float** ranges, bool uniform=true, bool accumulate=false )
-
-.. ocv:function:: void calcHist( const Mat* images, int nimages, const int* channels, InputArray mask, SparseMat& hist, int dims, const int* histSize, const float** ranges, bool uniform=true, bool accumulate=false )
-
-.. ocv:pyfunction:: cv2.calcHist(images, channels, mask, histSize, ranges[, hist[, accumulate]]) -> hist
-
-.. ocv:cfunction:: void cvCalcHist( IplImage** image, CvHistogram* hist, int accumulate=0, const CvArr* mask=NULL )
-
- :param images: Source arrays. They all should have the same depth, ``CV_8U`` or ``CV_32F`` , and the same size. Each of them can have an arbitrary number of channels.
-
- :param nimages: Number of source images.
-
- :param channels: List of the ``dims`` channels used to compute the histogram. The first array channels are numerated from 0 to ``images[0].channels()-1`` , the second array channels are counted from ``images[0].channels()`` to ``images[0].channels() + images[1].channels()-1``, and so on.
-
- :param mask: Optional mask. If the matrix is not empty, it must be an 8-bit array of the same size as ``images[i]`` . The non-zero mask elements mark the array elements counted in the histogram.
-
- :param hist: Output histogram, which is a dense or sparse ``dims`` -dimensional array.
-
- :param dims: Histogram dimensionality that must be positive and not greater than ``CV_MAX_DIMS`` (equal to 32 in the current OpenCV version).
-
- :param histSize: Array of histogram sizes in each dimension.
-
- :param ranges: Array of the ``dims`` arrays of the histogram bin boundaries in each dimension. When the histogram is uniform ( ``uniform`` =true), then for each dimension ``i`` it is enough to specify the lower (inclusive) boundary :math:`L_0` of the 0-th histogram bin and the upper (exclusive) boundary :math:`U_{\texttt{histSize}[i]-1}` for the last histogram bin ``histSize[i]-1`` . That is, in case of a uniform histogram each of ``ranges[i]`` is an array of 2 elements. When the histogram is not uniform ( ``uniform=false`` ), then each of ``ranges[i]`` contains ``histSize[i]+1`` elements: :math:`L_0, U_0=L_1, U_1=L_2, ..., U_{\texttt{histSize[i]}-2}=L_{\texttt{histSize[i]}-1}, U_{\texttt{histSize[i]}-1}` . The array elements, that are not between :math:`L_0` and :math:`U_{\texttt{histSize[i]}-1}` , are not counted in the histogram.
-
- :param uniform: Flag indicating whether the histogram is uniform or not (see above).
-
- :param accumulate: Accumulation flag. If it is set, the histogram is not cleared in the beginning when it is allocated. This feature enables you to compute a single histogram from several sets of arrays, or to update the histogram in time.
-
-The functions ``calcHist`` calculate the histogram of one or more
-arrays. The elements of a tuple used to increment
-a histogram bin are taken from the corresponding
-input arrays at the same location. The sample below shows how to compute a 2D Hue-Saturation histogram for a color image. ::
-
- #include <opencv2/imgproc.hpp>
- #include <opencv2/highgui.hpp>
-
- using namespace cv;
-
- int main( int argc, char** argv )
- {
- Mat src, hsv;
- if( argc != 2 || !(src=imread(argv[1], 1)).data )
- return -1;
-
- cvtColor(src, hsv, COLOR_BGR2HSV);
-
- // Quantize the hue to 30 levels
- // and the saturation to 32 levels
- int hbins = 30, sbins = 32;
- int histSize[] = {hbins, sbins};
- // hue varies from 0 to 179, see cvtColor
- float hranges[] = { 0, 180 };
- // saturation varies from 0 (black-gray-white) to
- // 255 (pure spectrum color)
- float sranges[] = { 0, 256 };
- const float* ranges[] = { hranges, sranges };
- MatND hist;
- // we compute the histogram from the 0-th and 1-st channels
- int channels[] = {0, 1};
-
- calcHist( &hsv, 1, channels, Mat(), // do not use mask
- hist, 2, histSize, ranges,
- true, // the histogram is uniform
- false );
- double maxVal=0;
- minMaxLoc(hist, 0, &maxVal, 0, 0);
-
- int scale = 10;
- Mat histImg = Mat::zeros(sbins*scale, hbins*10, CV_8UC3);
-
- for( int h = 0; h < hbins; h++ )
- for( int s = 0; s < sbins; s++ )
- {
- float binVal = hist.at<float>(h, s);
- int intensity = cvRound(binVal*255/maxVal);
- rectangle( histImg, Point(h*scale, s*scale),
- Point( (h+1)*scale - 1, (s+1)*scale - 1),
- Scalar::all(intensity),
- CV_FILLED );
- }
-
- namedWindow( "Source", 1 );
- imshow( "Source", src );
-
- namedWindow( "H-S Histogram", 1 );
- imshow( "H-S Histogram", histImg );
- waitKey();
- }
-
-.. note::
-
- * An example for creating histograms of an image can be found at opencv_source_code/samples/cpp/demhist.cpp
-
- * (Python) An example for creating color histograms can be found at opencv_source/samples/python2/color_histogram.py
- * (Python) An example illustrating RGB and grayscale histogram plotting can be found at opencv_source/samples/python2/hist.py
-
-
-calcBackProject
--------------------
-Calculates the back projection of a histogram.
-
-.. ocv:function:: void calcBackProject( const Mat* images, int nimages, const int* channels, InputArray hist, OutputArray backProject, const float** ranges, double scale=1, bool uniform=true )
-
-.. ocv:function:: void calcBackProject( const Mat* images, int nimages, const int* channels, const SparseMat& hist, OutputArray backProject, const float** ranges, double scale=1, bool uniform=true )
-
-.. ocv:pyfunction:: cv2.calcBackProject(images, channels, hist, ranges, scale[, dst]) -> dst
-
-.. ocv:cfunction:: void cvCalcBackProject( IplImage** image, CvArr* backProject, const CvHistogram* hist )
-
- :param images: Source arrays. They all should have the same depth, ``CV_8U`` or ``CV_32F`` , and the same size. Each of them can have an arbitrary number of channels.
-
- :param nimages: Number of source images.
-
- :param channels: The list of channels used to compute the back projection. The number of channels must match the histogram dimensionality. The first array channels are numerated from 0 to ``images[0].channels()-1`` , the second array channels are counted from ``images[0].channels()`` to ``images[0].channels() + images[1].channels()-1``, and so on.
-
- :param hist: Input histogram that can be dense or sparse.
-
- :param backProject: Destination back projection array that is a single-channel array of the same size and depth as ``images[0]`` .
-
- :param ranges: Array of arrays of the histogram bin boundaries in each dimension. See :ocv:func:`calcHist` .
-
- :param scale: Optional scale factor for the output back projection.
-
- :param uniform: Flag indicating whether the histogram is uniform or not (see above).
-
-The functions ``calcBackProject`` calculate the back project of the histogram. That is, similarly to ``calcHist`` , at each location ``(x, y)`` the function collects the values from the selected channels in the input images and finds the corresponding histogram bin. But instead of incrementing it, the function reads the bin value, scales it by ``scale`` , and stores in ``backProject(x,y)`` . In terms of statistics, the function computes probability of each element value in respect with the empirical probability distribution represented by the histogram. See how, for example, you can find and track a bright-colored object in a scene:
-
-#.
- Before tracking, show the object to the camera so that it covers almost the whole frame. Calculate a hue histogram. The histogram may have strong maximums, corresponding to the dominant colors in the object.
-
-#.
- When tracking, calculate a back projection of a hue plane of each input video frame using that pre-computed histogram. Threshold the back projection to suppress weak colors. It may also make sense to suppress pixels with non-sufficient color saturation and too dark or too bright pixels.
-
-#.
- Find connected components in the resulting picture and choose, for example, the largest component.
-
-This is an approximate algorithm of the
-:ocv:func:`CamShift` color object tracker.
-
-.. seealso:: :ocv:func:`calcHist`
-.. _compareHist:
-
-compareHist
------------
-Compares two histograms.
-
-.. ocv:function:: double compareHist( InputArray H1, InputArray H2, int method )
-
-.. ocv:function:: double compareHist( const SparseMat& H1, const SparseMat& H2, int method )
-
-.. ocv:pyfunction:: cv2.compareHist(H1, H2, method) -> retval
-
-.. ocv:cfunction:: double cvCompareHist( const CvHistogram* hist1, const CvHistogram* hist2, int method )
-
- :param H1: First compared histogram.
-
- :param H2: Second compared histogram of the same size as ``H1`` .
-
- :param method: Comparison method that could be one of the following:
-
- * **CV_COMP_CORREL** Correlation
-
- * **CV_COMP_CHISQR** Chi-Square
-
- * **CV_COMP_CHISQR_ALT** Alternative Chi-Square
-
- * **CV_COMP_INTERSECT** Intersection
-
- * **CV_COMP_BHATTACHARYYA** Bhattacharyya distance
-
- * **CV_COMP_HELLINGER** Synonym for ``CV_COMP_BHATTACHARYYA``
-
- * **CV_COMP_KL_DIV** Kullback-Leibler divergence
-
-The functions ``compareHist`` compare two dense or two sparse histograms using the specified method:
-
-* Correlation (``method=CV_COMP_CORREL``)
-
- .. math::
-
- d(H_1,H_2) = \frac{\sum_I (H_1(I) - \bar{H_1}) (H_2(I) - \bar{H_2})}{\sqrt{\sum_I(H_1(I) - \bar{H_1})^2 \sum_I(H_2(I) - \bar{H_2})^2}}
-
- where
-
- .. math::
-
- \bar{H_k} = \frac{1}{N} \sum _J H_k(J)
-
- and
- :math:`N` is a total number of histogram bins.
-
-* Chi-Square (``method=CV_COMP_CHISQR``)
-
- .. math::
-
- d(H_1,H_2) = \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)}
-
-* Alternative Chi-Square (``method=CV_COMP_CHISQR_ALT``)
-
- .. math::
-
- d(H_1,H_2) = 2 * \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)+H_2(I)}
-
- This alternative formula is regularly used for texture comparison. See e.g. [Puzicha1997]_.
-
-* Intersection (``method=CV_COMP_INTERSECT``)
-
- .. math::
-
- d(H_1,H_2) = \sum _I \min (H_1(I), H_2(I))
-
-* Bhattacharyya distance (``method=CV_COMP_BHATTACHARYYA`` or ``method=CV_COMP_HELLINGER``). In fact, OpenCV computes Hellinger distance, which is related to Bhattacharyya coefficient.
-
- .. math::
-
- d(H_1,H_2) = \sqrt{1 - \frac{1}{\sqrt{\bar{H_1} \bar{H_2} N^2}} \sum_I \sqrt{H_1(I) \cdot H_2(I)}}
-
-* Kullback-Leibler divergence (``method=CV_COMP_KL_DIV``).
-
- .. math::
-
- d(H_1,H_2) = \sum _I H_1(I) \log \left(\frac{H_1(I)}{H_2(I)}\right)
-
-The function returns
-:math:`d(H_1, H_2)` .
-
-While the function works well with 1-, 2-, 3-dimensional dense histograms, it may not be suitable for high-dimensional sparse histograms. In such histograms, because of aliasing and sampling problems, the coordinates of non-zero histogram bins can slightly shift. To compare such histograms or more general sparse configurations of weighted points, consider using the
-:ocv:func:`EMD` function.
-
-
-
-
-EMD
-------
-Computes the "minimal work" distance between two weighted point configurations.
-
-.. ocv:function:: float EMD( InputArray signature1, InputArray signature2, int distType, InputArray cost=noArray(), float* lowerBound=0, OutputArray flow=noArray() )
-
-.. ocv:cfunction:: float cvCalcEMD2( const CvArr* signature1, const CvArr* signature2, int distance_type, CvDistanceFunction distance_func=NULL, const CvArr* cost_matrix=NULL, CvArr* flow=NULL, float* lower_bound=NULL, void* userdata=NULL )
-
- :param signature1: First signature, a :math:`\texttt{size1}\times \texttt{dims}+1` floating-point matrix. Each row stores the point weight followed by the point coordinates. The matrix is allowed to have a single column (weights only) if the user-defined cost matrix is used.
-
- :param signature2: Second signature of the same format as ``signature1`` , though the number of rows may be different. The total weights may be different. In this case an extra "dummy" point is added to either ``signature1`` or ``signature2`` .
-
- :param distType: Used metric. ``CV_DIST_L1, CV_DIST_L2`` , and ``CV_DIST_C`` stand for one of the standard metrics. ``CV_DIST_USER`` means that a pre-calculated cost matrix ``cost`` is used.
-
- :param distance_func: Custom distance function supported by the old interface. ``CvDistanceFunction`` is defined as: ::
-
- typedef float (CV_CDECL * CvDistanceFunction)( const float* a,
- const float* b, void* userdata );
-
- where ``a`` and ``b`` are point coordinates and ``userdata`` is the same as the last parameter.
-
- :param cost: User-defined :math:`\texttt{size1}\times \texttt{size2}` cost matrix. Also, if a cost matrix is used, lower boundary ``lowerBound`` cannot be calculated because it needs a metric function.
-
- :param lowerBound: Optional input/output parameter: lower boundary of a distance between the two signatures that is a distance between mass centers. The lower boundary may not be calculated if the user-defined cost matrix is used, the total weights of point configurations are not equal, or if the signatures consist of weights only (the signature matrices have a single column). You **must** initialize ``*lowerBound`` . If the calculated distance between mass centers is greater or equal to ``*lowerBound`` (it means that the signatures are far enough), the function does not calculate EMD. In any case ``*lowerBound`` is set to the calculated distance between mass centers on return. Thus, if you want to calculate both distance between mass centers and EMD, ``*lowerBound`` should be set to 0.
-
- :param flow: Resultant :math:`\texttt{size1} \times \texttt{size2}` flow matrix: :math:`\texttt{flow}_{i,j}` is a flow from :math:`i` -th point of ``signature1`` to :math:`j` -th point of ``signature2`` .
-
- :param userdata: Optional pointer directly passed to the custom distance function.
-
-The function computes the earth mover distance and/or a lower boundary of the distance between the two weighted point configurations. One of the applications described in [RubnerSept98]_ is multi-dimensional histogram comparison for image retrieval. EMD is a transportation problem that is solved using some modification of a simplex algorithm, thus the complexity is exponential in the worst case, though, on average it is much faster. In the case of a real metric the lower boundary can be calculated even faster (using linear-time algorithm) and it can be used to determine roughly whether the two signatures are far enough so that they cannot relate to the same object.
-
-
-equalizeHist
-----------------
-Equalizes the histogram of a grayscale image.
-
-.. ocv:function:: void equalizeHist( InputArray src, OutputArray dst )
-
-.. ocv:pyfunction:: cv2.equalizeHist(src[, dst]) -> dst
-
-.. ocv:cfunction:: void cvEqualizeHist( const CvArr* src, CvArr* dst )
-
- :param src: Source 8-bit single channel image.
-
- :param dst: Destination image of the same size and type as ``src`` .
-
-The function equalizes the histogram of the input image using the following algorithm:
-
-#.
- Calculate the histogram
- :math:`H` for ``src`` .
-
-#.
- Normalize the histogram so that the sum of histogram bins is 255.
-
-#.
- Compute the integral of the histogram:
-
- .. math::
-
- H'_i = \sum _{0 \le j < i} H(j)
-
-#.
- Transform the image using
- :math:`H'` as a look-up table:
- :math:`\texttt{dst}(x,y) = H'(\texttt{src}(x,y))`
-
-The algorithm normalizes the brightness and increases the contrast of the image.
-
-
-Extra Histogram Functions (C API)
----------------------------------
-
-The rest of the section describes additional C functions operating on ``CvHistogram``.
-
-CalcBackProjectPatch
---------------------
-Locates a template within an image by using a histogram comparison.
-
-.. ocv:cfunction:: void cvCalcBackProjectPatch( IplImage** images, CvArr* dst, CvSize patch_size, CvHistogram* hist, int method, double factor )
-
- :param images: Source images (though, you may pass CvMat** as well).
-
- :param dst: Destination image.
-
- :param patch_size: Size of the patch slid though the source image.
-
- :param hist: Histogram.
-
- :param method: Comparison method passed to :ocv:cfunc:`CompareHist` (see the function description).
-
- :param factor: Normalization factor for histograms that affects the normalization scale of the destination image. Pass 1 if not sure.
-
-The function calculates the back projection by comparing histograms of the source image patches with the given histogram. The function is similar to :ocv:func:`matchTemplate`, but instead of comparing the raster patch with all its possible positions within the search window, the function ``CalcBackProjectPatch`` compares histograms. See the algorithm diagram below:
-
-.. image:: pics/backprojectpatch.png
-
-
-CalcProbDensity
----------------
-Divides one histogram by another.
-
-.. ocv:cfunction:: void cvCalcProbDensity( const CvHistogram* hist1, const CvHistogram* hist2, CvHistogram* dst_hist, double scale=255 )
-
- :param hist1: First histogram (the divisor).
-
- :param hist2: Second histogram.
-
- :param dst_hist: Destination histogram.
-
- :param scale: Scale factor for the destination histogram.
-
-The function calculates the object probability density from two histograms as:
-
-.. math::
-
- \texttt{disthist} (I)= \forkthree{0}{if $\texttt{hist1}(I)=0$}{\texttt{scale}}{if $\texttt{hist1}(I) \ne 0$ and $\texttt{hist2}(I) > \texttt{hist1}(I)$}{\frac{\texttt{hist2}(I) \cdot \texttt{scale}}{\texttt{hist1}(I)}}{if $\texttt{hist1}(I) \ne 0$ and $\texttt{hist2}(I) \le \texttt{hist1}(I)$}
-
-
-ClearHist
----------
-Clears the histogram.
-
-.. ocv:cfunction:: void cvClearHist( CvHistogram* hist )
-
- :param hist: Histogram.
-
-The function sets all of the histogram bins to 0 in case of a dense histogram and removes all histogram bins in case of a sparse array.
-
-
-CopyHist
---------
-Copies a histogram.
-
-.. ocv:cfunction:: void cvCopyHist( const CvHistogram* src, CvHistogram** dst )
-
- :param src: Source histogram.
-
- :param dst: Pointer to the destination histogram.
-
-The function makes a copy of the histogram. If the second histogram pointer ``*dst`` is NULL, a new histogram of the same size as ``src`` is created. Otherwise, both histograms must have equal types and sizes. Then the function copies the bin values of the source histogram to the destination histogram and sets the same bin value ranges as in ``src``.
-
-.. _createhist:
-
-CreateHist
-----------
-Creates a histogram.
-
-.. ocv:cfunction:: CvHistogram* cvCreateHist( int dims, int* sizes, int type, float** ranges=NULL, int uniform=1 )
-
- :param dims: Number of histogram dimensions.
-
- :param sizes: Array of the histogram dimension sizes.
-
- :param type: Histogram representation format. ``CV_HIST_ARRAY`` means that the histogram data is represented as a multi-dimensional dense array CvMatND. ``CV_HIST_SPARSE`` means that histogram data is represented as a multi-dimensional sparse array ``CvSparseMat``.
-
- :param ranges: Array of ranges for the histogram bins. Its meaning depends on the ``uniform`` parameter value. The ranges are used when the histogram is calculated or backprojected to determine which histogram bin corresponds to which value/tuple of values from the input image(s).
-
- :param uniform: Uniformity flag. If not zero, the histogram has evenly
- spaced bins and for every :math:`0<=i<cDims` ``ranges[i]``
- is an array of two numbers: lower and upper boundaries for the i-th
- histogram dimension.
- The whole range [lower,upper] is then split
- into ``dims[i]`` equal parts to determine the ``i``-th input
- tuple value ranges for every histogram bin. And if ``uniform=0`` ,
- then the ``i``-th element of the ``ranges`` array contains ``dims[i]+1`` elements: :math:`\texttt{lower}_0, \texttt{upper}_0,
- \texttt{lower}_1, \texttt{upper}_1 = \texttt{lower}_2,
- ...
- \texttt{upper}_{dims[i]-1}`
- where :math:`\texttt{lower}_j` and :math:`\texttt{upper}_j`
- are lower and upper
- boundaries of the ``i``-th input tuple value for the ``j``-th
- bin, respectively. In either case, the input values that are beyond
- the specified range for a histogram bin are not counted by :ocv:cfunc:`CalcHist` and filled with 0 by :ocv:cfunc:`CalcBackProject`.
-
-The function creates a histogram of the specified size and returns a pointer to the created histogram. If the array ``ranges`` is 0, the histogram bin ranges must be specified later via the function :ocv:cfunc:`SetHistBinRanges`. Though :ocv:cfunc:`CalcHist` and :ocv:cfunc:`CalcBackProject` may process 8-bit images without setting bin ranges, they assume they are equally spaced in 0 to 255 bins.
-
-
-GetMinMaxHistValue
-------------------
-Finds the minimum and maximum histogram bins.
-
-.. ocv:cfunction:: void cvGetMinMaxHistValue( const CvHistogram* hist, float* min_value, float* max_value, int* min_idx=NULL, int* max_idx=NULL )
-
- :param hist: Histogram.
-
- :param min_value: Pointer to the minimum value of the histogram.
-
- :param max_value: Pointer to the maximum value of the histogram.
-
- :param min_idx: Pointer to the array of coordinates for the minimum.
-
- :param max_idx: Pointer to the array of coordinates for the maximum.
-
-The function finds the minimum and maximum histogram bins and their positions. All of output arguments are optional. Among several extremas with the same value the ones with the minimum index (in the lexicographical order) are returned. In case of several maximums or minimums, the earliest in the lexicographical order (extrema locations) is returned.
-
-
-MakeHistHeaderForArray
-----------------------
-Makes a histogram out of an array.
-
-.. ocv:cfunction:: CvHistogram* cvMakeHistHeaderForArray( int dims, int* sizes, CvHistogram* hist, float* data, float** ranges=NULL, int uniform=1 )
-
- :param dims: Number of the histogram dimensions.
-
- :param sizes: Array of the histogram dimension sizes.
-
- :param hist: Histogram header initialized by the function.
-
- :param data: Array used to store histogram bins.
-
- :param ranges: Histogram bin ranges. See :ocv:cfunc:`CreateHist` for details.
-
- :param uniform: Uniformity flag. See :ocv:cfunc:`CreateHist` for details.
-
-The function initializes the histogram, whose header and bins are allocated by the user. :ocv:cfunc:`ReleaseHist` does not need to be called afterwards. Only dense histograms can be initialized this way. The function returns ``hist``.
-
-NormalizeHist
--------------
-Normalizes the histogram.
-
-.. ocv:cfunction:: void cvNormalizeHist( CvHistogram* hist, double factor )
-
- :param hist: Pointer to the histogram.
-
- :param factor: Normalization factor.
-
-The function normalizes the histogram bins by scaling them so that the sum of the bins becomes equal to ``factor``.
-
-
-ReleaseHist
------------
-Releases the histogram.
-
-.. ocv:cfunction:: void cvReleaseHist( CvHistogram** hist )
-
- :param hist: Double pointer to the released histogram.
-
-The function releases the histogram (header and the data). The pointer to the histogram is cleared by the function. If ``*hist`` pointer is already ``NULL``, the function does nothing.
-
-
-SetHistBinRanges
-----------------
-Sets the bounds of the histogram bins.
-
-.. ocv:cfunction:: void cvSetHistBinRanges( CvHistogram* hist, float** ranges, int uniform=1 )
-
- :param hist: Histogram.
-
- :param ranges: Array of bin ranges arrays. See :ocv:cfunc:`CreateHist` for details.
-
- :param uniform: Uniformity flag. See :ocv:cfunc:`CreateHist` for details.
-
-This is a standalone function for setting bin ranges in the histogram. For a more detailed description of the parameters ``ranges`` and ``uniform``, see the :ocv:cfunc:`CalcHist` function that can initialize the ranges as well. Ranges for the histogram bins must be set before the histogram is calculated or the backproject of the histogram is calculated.
-
-
-ThreshHist
-----------
-Thresholds the histogram.
-
-.. ocv:cfunction:: void cvThreshHist( CvHistogram* hist, double threshold )
-
- :param hist: Pointer to the histogram.
-
- :param threshold: Threshold level.
-
-The function clears histogram bins that are below the specified threshold.
-
-
-.. [RubnerSept98] Y. Rubner. C. Tomasi, L.J. Guibas. *The Earth Mover’s Distance as a Metric for Image Retrieval*. Technical Report STAN-CS-TN-98-86, Department of Computer Science, Stanford University, September 1998.
-.. [Puzicha1997] Puzicha, J., Hofmann, T., and Buhmann, J. *Non-parametric similarity measures for unsupervised texture segmentation and image retrieval.* In Proc. IEEE Conf. Computer Vision and Pattern Recognition, San Juan, Puerto Rico, pp. 267-272, 1997.
+++ /dev/null
-*************************
-imgproc. Image Processing
-*************************
-
-.. highlight:: cpp
-
-.. toctree::
- :maxdepth: 2
-
- filtering
- geometric_transformations
- miscellaneous_transformations
- drawing_functions
- colormaps
- histograms
- structural_analysis_and_shape_descriptors
- motion_analysis_and_object_tracking
- feature_detection
- object_detection
+++ /dev/null
-Miscellaneous Image Transformations
-===================================
-
-.. highlight:: cpp
-
-
-adaptiveThreshold
----------------------
-Applies an adaptive threshold to an array.
-
-.. ocv:function:: void adaptiveThreshold( InputArray src, OutputArray dst, double maxValue, int adaptiveMethod, int thresholdType, int blockSize, double C )
-
-.. ocv:pyfunction:: cv2.adaptiveThreshold(src, maxValue, adaptiveMethod, thresholdType, blockSize, C[, dst]) -> dst
-
-.. ocv:cfunction:: void cvAdaptiveThreshold( const CvArr* src, CvArr* dst, double max_value, int adaptive_method=CV_ADAPTIVE_THRESH_MEAN_C, int threshold_type=CV_THRESH_BINARY, int block_size=3, double param1=5 )
-
- :param src: Source 8-bit single-channel image.
-
- :param dst: Destination image of the same size and the same type as ``src`` .
-
- :param maxValue: Non-zero value assigned to the pixels for which the condition is satisfied. See the details below.
-
- :param adaptiveMethod: Adaptive thresholding algorithm to use, ``ADAPTIVE_THRESH_MEAN_C`` or ``ADAPTIVE_THRESH_GAUSSIAN_C`` . See the details below.
-
- :param thresholdType: Thresholding type that must be either ``THRESH_BINARY`` or ``THRESH_BINARY_INV`` .
-
- :param blockSize: Size of a pixel neighborhood that is used to calculate a threshold value for the pixel: 3, 5, 7, and so on.
-
- :param C: Constant subtracted from the mean or weighted mean (see the details below). Normally, it is positive but may be zero or negative as well.
-
-The function transforms a grayscale image to a binary image according to the formulae:
-
- * **THRESH_BINARY**
-
- .. math::
-
- dst(x,y) = \fork{\texttt{maxValue}}{if $src(x,y) > T(x,y)$}{0}{otherwise}
-
- * **THRESH_BINARY_INV**
-
- .. math::
-
- dst(x,y) = \fork{0}{if $src(x,y) > T(x,y)$}{\texttt{maxValue}}{otherwise}
-
-where
-:math:`T(x,y)` is a threshold calculated individually for each pixel.
-
-*
- For the method ``ADAPTIVE_THRESH_MEAN_C`` , the threshold value
- :math:`T(x,y)` is a mean of the
- :math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood of
- :math:`(x, y)` minus ``C`` .
-
-*
- For the method ``ADAPTIVE_THRESH_GAUSSIAN_C`` , the threshold value
- :math:`T(x, y)` is a weighted sum (cross-correlation with a Gaussian window) of the
- :math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood of
- :math:`(x, y)` minus ``C`` . The default sigma (standard deviation) is used for the specified ``blockSize`` . See
- :ocv:func:`getGaussianKernel` .
-
-The function can process the image in-place.
-
-.. seealso::
-
- :ocv:func:`threshold`,
- :ocv:func:`blur`,
- :ocv:func:`GaussianBlur`
-
-
-
-cvtColor
---------
-Converts an image from one color space to another.
-
-.. ocv:function:: void cvtColor( InputArray src, OutputArray dst, int code, int dstCn=0 )
-
-.. ocv:pyfunction:: cv2.cvtColor(src, code[, dst[, dstCn]]) -> dst
-
-.. ocv:cfunction:: void cvCvtColor( const CvArr* src, CvArr* dst, int code )
-
- :param src: input image: 8-bit unsigned, 16-bit unsigned ( ``CV_16UC...`` ), or single-precision floating-point.
-
- :param dst: output image of the same size and depth as ``src``.
-
- :param code: color space conversion code (see the description below).
-
- :param dstCn: number of channels in the destination image; if the parameter is 0, the number of the channels is derived automatically from ``src`` and ``code`` .
-
-The function converts an input image from one color
-space to another. In case of a transformation to-from RGB color space, the order of the channels should be specified explicitly (RGB or BGR).
-Note that the default color format in OpenCV is often referred to as RGB but it is actually BGR (the bytes are reversed). So the first byte in a standard (24-bit) color image will be an 8-bit Blue component, the second byte will be Green, and the third byte will be Red. The fourth, fifth, and sixth bytes would then be the second pixel (Blue, then Green, then Red), and so on.
-
-The conventional ranges for R, G, and B channel values are:
-
-*
- 0 to 255 for ``CV_8U`` images
-
-*
- 0 to 65535 for ``CV_16U`` images
-
-*
- 0 to 1 for ``CV_32F`` images
-
-In case of linear transformations, the range does not matter.
-But in case of a non-linear transformation, an input RGB image should be normalized to the proper value range to get the correct results, for example, for RGB
-:math:`\rightarrow` L*u*v* transformation. For example, if you have a 32-bit floating-point image directly converted from an 8-bit image without any scaling, then it will have the 0..255 value range instead of 0..1 assumed by the function. So, before calling ``cvtColor`` , you need first to scale the image down: ::
-
- img *= 1./255;
- cvtColor(img, img, COLOR_BGR2Luv);
-
-If you use ``cvtColor`` with 8-bit images, the conversion will have some information lost. For many applications, this will not be noticeable but it is recommended to use 32-bit images in applications that need the full range of colors or that convert an image before an operation and then convert back.
-
-If conversion adds the alpha channel, its value will set to the maximum of corresponding channel range: 255 for ``CV_8U``, 65535 for ``CV_16U``, 1 for ``CV_32F``.
-
-The function can do the following transformations:
-
-*
- RGB :math:`\leftrightarrow` GRAY ( ``COLOR_BGR2GRAY, COLOR_RGB2GRAY, COLOR_GRAY2BGR, COLOR_GRAY2RGB`` )
- Transformations within RGB space like adding/removing the alpha channel, reversing the channel order, conversion to/from 16-bit RGB color (R5:G6:B5 or R5:G5:B5), as well as conversion to/from grayscale using:
-
- .. math::
-
- \text{RGB[A] to Gray:} \quad Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
-
- and
-
- .. math::
-
- \text{Gray to RGB[A]:} \quad R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow \max (ChannelRange)
-
- The conversion from a RGB image to gray is done with:
-
- ::
-
- cvtColor(src, bwsrc, COLOR_RGB2GRAY);
-
- ..
-
- More advanced channel reordering can also be done with
- :ocv:func:`mixChannels` .
-
-*
- RGB
- :math:`\leftrightarrow` CIE XYZ.Rec 709 with D65 white point ( ``COLOR_BGR2XYZ, COLOR_RGB2XYZ, COLOR_XYZ2BGR, COLOR_XYZ2RGB`` ):
-
- .. math::
-
- \begin{bmatrix} X \\ Y \\ Z
- \end{bmatrix} \leftarrow \begin{bmatrix} 0.412453 & 0.357580 & 0.180423 \\ 0.212671 & 0.715160 & 0.072169 \\ 0.019334 & 0.119193 & 0.950227
- \end{bmatrix} \cdot \begin{bmatrix} R \\ G \\ B
- \end{bmatrix}
-
- .. math::
-
- \begin{bmatrix} R \\ G \\ B
- \end{bmatrix} \leftarrow \begin{bmatrix} 3.240479 & -1.53715 & -0.498535 \\ -0.969256 & 1.875991 & 0.041556 \\ 0.055648 & -0.204043 & 1.057311
- \end{bmatrix} \cdot \begin{bmatrix} X \\ Y \\ Z
- \end{bmatrix}
-
- :math:`X`, :math:`Y` and
- :math:`Z` cover the whole value range (in case of floating-point images,
- :math:`Z` may exceed 1).
-
-*
- RGB
- :math:`\leftrightarrow` YCrCb JPEG (or YCC) ( ``COLOR_BGR2YCrCb, COLOR_RGB2YCrCb, COLOR_YCrCb2BGR, COLOR_YCrCb2RGB`` )
-
- .. math::
-
- Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
-
- .. math::
-
- Cr \leftarrow (R-Y) \cdot 0.713 + delta
-
- .. math::
-
- Cb \leftarrow (B-Y) \cdot 0.564 + delta
-
- .. math::
-
- R \leftarrow Y + 1.403 \cdot (Cr - delta)
-
- .. math::
-
- G \leftarrow Y - 0.714 \cdot (Cr - delta) - 0.344 \cdot (Cb - delta)
-
- .. math::
-
- B \leftarrow Y + 1.773 \cdot (Cb - delta)
-
- where
-
- .. math::
-
- delta = \left \{ \begin{array}{l l} 128 & \mbox{for 8-bit images} \\ 32768 & \mbox{for 16-bit images} \\ 0.5 & \mbox{for floating-point images} \end{array} \right .
-
- Y, Cr, and Cb cover the whole value range.
-
-*
- RGB :math:`\leftrightarrow` HSV ( ``COLOR_BGR2HSV, COLOR_RGB2HSV, COLOR_HSV2BGR, COLOR_HSV2RGB`` )
- In case of 8-bit and 16-bit images,
- R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
-
- .. math::
-
- V \leftarrow max(R,G,B)
-
- .. math::
-
- S \leftarrow \fork{\frac{V-min(R,G,B)}{V}}{if $V \neq 0$}{0}{otherwise}
-
- .. math::
-
- H \leftarrow \forkthree{{60(G - B)}/{(V-min(R,G,B))}}{if $V=R$}{{120+60(B - R)}/{(V-min(R,G,B))}}{if $V=G$}{{240+60(R - G)}/{(V-min(R,G,B))}}{if $V=B$}
-
- If
- :math:`H<0` then
- :math:`H \leftarrow H+360` . On output
- :math:`0 \leq V \leq 1`, :math:`0 \leq S \leq 1`, :math:`0 \leq H \leq 360` .
-
- The values are then converted to the destination data type:
-
- * 8-bit images
-
- .. math::
-
- V \leftarrow 255 V, S \leftarrow 255 S, H \leftarrow H/2 \text{(to fit to 0 to 255)}
-
- * 16-bit images (currently not supported)
-
- .. math::
-
- V <- 65535 V, S <- 65535 S, H <- H
-
- * 32-bit images
- H, S, and V are left as is
-
-*
- RGB :math:`\leftrightarrow` HLS ( ``COLOR_BGR2HLS, COLOR_RGB2HLS, COLOR_HLS2BGR, COLOR_HLS2RGB`` ).
- In case of 8-bit and 16-bit images,
- R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
-
- .. math::
-
- V_{max} \leftarrow {max}(R,G,B)
-
- .. math::
-
- V_{min} \leftarrow {min}(R,G,B)
-
- .. math::
-
- L \leftarrow \frac{V_{max} + V_{min}}{2}
-
- .. math::
-
- S \leftarrow \fork { \frac{V_{max} - V_{min}}{V_{max} + V_{min}} }{if $L < 0.5$ }
- { \frac{V_{max} - V_{min}}{2 - (V_{max} + V_{min})} }{if $L \ge 0.5$ }
-
- .. math::
-
- H \leftarrow \forkthree {{60(G - B)}/{S}}{if $V_{max}=R$ }
- {{120+60(B - R)}/{S}}{if $V_{max}=G$ }
- {{240+60(R - G)}/{S}}{if $V_{max}=B$ }
-
- If
- :math:`H<0` then
- :math:`H \leftarrow H+360` . On output
- :math:`0 \leq L \leq 1`, :math:`0 \leq S \leq 1`, :math:`0 \leq H \leq 360` .
-
- The values are then converted to the destination data type:
-
- * 8-bit images
-
- .. math::
-
- V \leftarrow 255 \cdot V, S \leftarrow 255 \cdot S, H \leftarrow H/2 \; \text{(to fit to 0 to 255)}
-
- * 16-bit images (currently not supported)
-
- .. math::
-
- V <- 65535 \cdot V, S <- 65535 \cdot S, H <- H
-
- * 32-bit images
- H, S, V are left as is
-
-*
- RGB :math:`\leftrightarrow` CIE L*a*b* ( ``COLOR_BGR2Lab, COLOR_RGB2Lab, COLOR_Lab2BGR, COLOR_Lab2RGB`` ).
- In case of 8-bit and 16-bit images,
- R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
-
- .. math::
-
- \vecthree{X}{Y}{Z} \leftarrow \vecthreethree{0.412453}{0.357580}{0.180423}{0.212671}{0.715160}{0.072169}{0.019334}{0.119193}{0.950227} \cdot \vecthree{R}{G}{B}
-
- .. math::
-
- X \leftarrow X/X_n, \text{where} X_n = 0.950456
-
- .. math::
-
- Z \leftarrow Z/Z_n, \text{where} Z_n = 1.088754
-
- .. math::
-
- L \leftarrow \fork{116*Y^{1/3}-16}{for $Y>0.008856$}{903.3*Y}{for $Y \le 0.008856$}
-
- .. math::
-
- a \leftarrow 500 (f(X)-f(Y)) + delta
-
- .. math::
-
- b \leftarrow 200 (f(Y)-f(Z)) + delta
-
- where
-
- .. math::
-
- f(t)= \fork{t^{1/3}}{for $t>0.008856$}{7.787 t+16/116}{for $t\leq 0.008856$}
-
- and
-
- .. math::
-
- delta = \fork{128}{for 8-bit images}{0}{for floating-point images}
-
- This outputs
- :math:`0 \leq L \leq 100`, :math:`-127 \leq a \leq 127`, :math:`-127 \leq b \leq 127` . The values are then converted to the destination data type:
-
- * 8-bit images
-
- .. math::
-
- L \leftarrow L*255/100, \; a \leftarrow a + 128, \; b \leftarrow b + 128
-
- * 16-bit images
- (currently not supported)
-
- * 32-bit images
- L, a, and b are left as is
-
-*
- RGB :math:`\leftrightarrow` CIE L*u*v* ( ``COLOR_BGR2Luv, COLOR_RGB2Luv, COLOR_Luv2BGR, COLOR_Luv2RGB`` ).
- In case of 8-bit and 16-bit images,
- R, G, and B are converted to the floating-point format and scaled to fit 0 to 1 range.
-
- .. math::
-
- \vecthree{X}{Y}{Z} \leftarrow \vecthreethree{0.412453}{0.357580}{0.180423}{0.212671}{0.715160}{0.072169}{0.019334}{0.119193}{0.950227} \cdot \vecthree{R}{G}{B}
-
- .. math::
-
- L \leftarrow \fork{116 Y^{1/3}}{for $Y>0.008856$}{903.3 Y}{for $Y\leq 0.008856$}
-
- .. math::
-
- u' \leftarrow 4*X/(X + 15*Y + 3 Z)
-
- .. math::
-
- v' \leftarrow 9*Y/(X + 15*Y + 3 Z)
-
- .. math::
-
- u \leftarrow 13*L*(u' - u_n) \quad \text{where} \quad u_n=0.19793943
-
- .. math::
-
- v \leftarrow 13*L*(v' - v_n) \quad \text{where} \quad v_n=0.46831096
-
- This outputs
- :math:`0 \leq L \leq 100`, :math:`-134 \leq u \leq 220`, :math:`-140 \leq v \leq 122` .
-
- The values are then converted to the destination data type:
-
- * 8-bit images
-
- .. math::
-
- L \leftarrow 255/100 L, \; u \leftarrow 255/354 (u + 134), \; v \leftarrow 255/262 (v + 140)
-
- * 16-bit images
- (currently not supported)
-
- * 32-bit images
- L, u, and v are left as is
-
- The above formulae for converting RGB to/from various color spaces have been taken from multiple sources on the web, primarily from the Charles Poynton site
- http://www.poynton.com/ColorFAQ.html
-
-*
- Bayer :math:`\rightarrow` RGB ( ``COLOR_BayerBG2BGR, COLOR_BayerGB2BGR, COLOR_BayerRG2BGR, COLOR_BayerGR2BGR, COLOR_BayerBG2RGB, COLOR_BayerGB2RGB, COLOR_BayerRG2RGB, COLOR_BayerGR2RGB`` ). The Bayer pattern is widely used in CCD and CMOS cameras. It enables you to get color pictures from a single plane where R,G, and B pixels (sensors of a particular component) are interleaved as follows:
-
- .. image:: pics/bayer.png
-
- The output RGB components of a pixel are interpolated from 1, 2, or
- 4 neighbors of the pixel having the same color. There are several
- modifications of the above pattern that can be achieved by shifting
- the pattern one pixel left and/or one pixel up. The two letters
- :math:`C_1` and
- :math:`C_2` in the conversion constants ``CV_Bayer`` :math:`C_1 C_2` ``2BGR`` and ``CV_Bayer`` :math:`C_1 C_2` ``2RGB`` indicate the particular pattern
- type. These are components from the second row, second and third
- columns, respectively. For example, the above pattern has a very
- popular "BG" type.
-
-
-distanceTransform
------------------
-Calculates the distance to the closest zero pixel for each pixel of the source image.
-
-.. ocv:function:: void distanceTransform( InputArray src, OutputArray dst, int distanceType, int maskSize, int dstType=CV_32F )
-
-.. ocv:function:: void distanceTransform( InputArray src, OutputArray dst, OutputArray labels, int distanceType, int maskSize, int labelType=DIST_LABEL_CCOMP )
-
-.. ocv:pyfunction:: cv2.distanceTransform(src, distanceType, maskSize[, dst]) -> dst
-
-.. ocv:cfunction:: void cvDistTransform( const CvArr* src, CvArr* dst, int distance_type=CV_DIST_L2, int mask_size=3, const float* mask=NULL, CvArr* labels=NULL, int labelType=CV_DIST_LABEL_CCOMP )
-
- :param src: 8-bit, single-channel (binary) source image.
-
- :param dst: Output image with calculated distances. It is a 8-bit or 32-bit floating-point, single-channel image of the same size as ``src`` .
-
- :param distanceType: Type of distance. It can be ``CV_DIST_L1, CV_DIST_L2`` , or ``CV_DIST_C`` .
-
- :param maskSize: Size of the distance transform mask. It can be 3, 5, or ``CV_DIST_MASK_PRECISE`` (the latter option is only supported by the first function). In case of the ``CV_DIST_L1`` or ``CV_DIST_C`` distance type, the parameter is forced to 3 because a :math:`3\times 3` mask gives the same result as :math:`5\times 5` or any larger aperture.
-
- :param dstType: Type of output image. It can be ``CV_8U`` or ``CV_32F``. Type ``CV_8U`` can be used only for the first variant of the function and ``distanceType == CV_DIST_L1``.
-
- :param labels: Optional output 2D array of labels (the discrete Voronoi diagram). It has the type ``CV_32SC1`` and the same size as ``src`` . See the details below.
-
- :param labelType: Type of the label array to build. If ``labelType==DIST_LABEL_CCOMP`` then each connected component of zeros in ``src`` (as well as all the non-zero pixels closest to the connected component) will be assigned the same label. If ``labelType==DIST_LABEL_PIXEL`` then each zero pixel (and all the non-zero pixels closest to it) gets its own label.
-
-The functions ``distanceTransform`` calculate the approximate or precise
-distance from every binary image pixel to the nearest zero pixel.
-For zero image pixels, the distance will obviously be zero.
-
-When ``maskSize == CV_DIST_MASK_PRECISE`` and ``distanceType == CV_DIST_L2`` , the function runs the algorithm described in [Felzenszwalb04]_. This algorithm is parallelized with the TBB library.
-
-In other cases, the algorithm
-[Borgefors86]_
-is used. This means that
-for a pixel the function finds the shortest path to the nearest zero pixel
-consisting of basic shifts: horizontal,
-vertical, diagonal, or knight's move (the latest is available for a
-:math:`5\times 5` mask). The overall distance is calculated as a sum of these
-basic distances. Since the distance function should be symmetric,
-all of the horizontal and vertical shifts must have the same cost (denoted as ``a`` ), all the diagonal shifts must have the
-same cost (denoted as ``b`` ), and all knight's moves must have
-the same cost (denoted as ``c`` ). For the ``CV_DIST_C`` and ``CV_DIST_L1`` types, the distance is calculated precisely,
-whereas for ``CV_DIST_L2`` (Euclidean distance) the distance
-can be calculated only with a relative error (a
-:math:`5\times 5` mask
-gives more accurate results). For ``a``,``b`` , and ``c`` , OpenCV uses the values suggested in the original paper:
-
-.. table::
-
- ============== =================== ======================
- ``CV_DIST_C`` :math:`(3\times 3)` a = 1, b = 1 \
- ============== =================== ======================
- ``CV_DIST_L1`` :math:`(3\times 3)` a = 1, b = 2 \
- ``CV_DIST_L2`` :math:`(3\times 3)` a=0.955, b=1.3693 \
- ``CV_DIST_L2`` :math:`(5\times 5)` a=1, b=1.4, c=2.1969 \
- ============== =================== ======================
-
-Typically, for a fast, coarse distance estimation ``CV_DIST_L2``, a
-:math:`3\times 3` mask is used. For a more accurate distance estimation ``CV_DIST_L2`` , a
-:math:`5\times 5` mask or the precise algorithm is used.
-Note that both the precise and the approximate algorithms are linear on the number of pixels.
-
-The second variant of the function does not only compute the minimum distance for each pixel
-:math:`(x, y)` but also identifies the nearest connected
-component consisting of zero pixels (``labelType==DIST_LABEL_CCOMP``) or the nearest zero pixel (``labelType==DIST_LABEL_PIXEL``). Index of the component/pixel is stored in
-:math:`\texttt{labels}(x, y)` .
-When ``labelType==DIST_LABEL_CCOMP``, the function automatically finds connected components of zero pixels in the input image and marks them with distinct labels. When ``labelType==DIST_LABEL_CCOMP``, the function scans through the input image and marks all the zero pixels with distinct labels.
-
-In this mode, the complexity is still linear.
-That is, the function provides a very fast way to compute the Voronoi diagram for a binary image.
-Currently, the second variant can use only the approximate distance transform algorithm, i.e. ``maskSize=CV_DIST_MASK_PRECISE`` is not supported yet.
-
-.. note::
-
- * An example on using the distance transform can be found at opencv_source_code/samples/cpp/distrans.cpp
-
- * (Python) An example on using the distance transform can be found at opencv_source/samples/python2/distrans.py
-
-floodFill
----------
-Fills a connected component with the given color.
-
-.. ocv:function:: int floodFill( InputOutputArray image, Point seedPoint, Scalar newVal, Rect* rect=0, Scalar loDiff=Scalar(), Scalar upDiff=Scalar(), int flags=4 )
-
-.. ocv:function:: int floodFill( InputOutputArray image, InputOutputArray mask, Point seedPoint, Scalar newVal, Rect* rect=0, Scalar loDiff=Scalar(), Scalar upDiff=Scalar(), int flags=4 )
-
-.. ocv:pyfunction:: cv2.floodFill(image, mask, seedPoint, newVal[, loDiff[, upDiff[, flags]]]) -> retval, image, mask, rect
-
-.. ocv:cfunction:: void cvFloodFill( CvArr* image, CvPoint seed_point, CvScalar new_val, CvScalar lo_diff=cvScalarAll(0), CvScalar up_diff=cvScalarAll(0), CvConnectedComp* comp=NULL, int flags=4, CvArr* mask=NULL )
-
- :param image: Input/output 1- or 3-channel, 8-bit, or floating-point image. It is modified by the function unless the ``FLOODFILL_MASK_ONLY`` flag is set in the second variant of the function. See the details below.
-
- :param mask: Operation mask that should be a single-channel 8-bit image, 2 pixels wider and 2 pixels taller than ``image``. Since this is both an input and output parameter, you must take responsibility of initializing it. Flood-filling cannot go across non-zero pixels in the input mask. For example, an edge detector output can be used as a mask to stop filling at edges. On output, pixels in the mask corresponding to filled pixels in the image are set to 1 or to the a value specified in ``flags`` as described below. It is therefore possible to use the same mask in multiple calls to the function to make sure the filled areas do not overlap.
-
- .. note:: Since the mask is larger than the filled image, a pixel :math:`(x, y)` in ``image`` corresponds to the pixel :math:`(x+1, y+1)` in the ``mask`` .
-
- :param seedPoint: Starting point.
-
- :param newVal: New value of the repainted domain pixels.
-
- :param loDiff: Maximal lower brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component.
-
- :param upDiff: Maximal upper brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component.
-
- :param rect: Optional output parameter set by the function to the minimum bounding rectangle of the repainted domain.
-
- :param flags: Operation flags. The first 8 bits contain a connectivity value. The default value of 4 means that only the four nearest neighbor pixels (those that share an edge) are considered. A connectivity value of 8 means that the eight nearest neighbor pixels (those that share a corner) will be considered. The next 8 bits (8-16) contain a value between 1 and 255 with which to fill the ``mask`` (the default value is 1). For example, ``4 | ( 255 << 8 )`` will consider 4 nearest neighbours and fill the mask with a value of 255. The following additional options occupy higher bits and therefore may be further combined with the connectivity and mask fill values using bit-wise or (``|``):
-
- * **FLOODFILL_FIXED_RANGE** If set, the difference between the current pixel and seed pixel is considered. Otherwise, the difference between neighbor pixels is considered (that is, the range is floating).
-
- * **FLOODFILL_MASK_ONLY** If set, the function does not change the image ( ``newVal`` is ignored), and only fills the mask with the value specified in bits 8-16 of ``flags`` as described above. This option only make sense in function variants that have the ``mask`` parameter.
-
-The functions ``floodFill`` fill a connected component starting from the seed point with the specified color. The connectivity is determined by the color/brightness closeness of the neighbor pixels. The pixel at
-:math:`(x,y)` is considered to belong to the repainted domain if:
-
-*
- .. math::
-
- \texttt{src} (x',y')- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} (x',y')+ \texttt{upDiff}
-
- in case of a grayscale image and floating range
-
-*
-
- .. math::
-
- \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)+ \texttt{upDiff}
-
- in case of a grayscale image and fixed range
-
-*
-
- .. math::
-
- \texttt{src} (x',y')_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} (x',y')_r+ \texttt{upDiff} _r,
-
- .. math::
-
- \texttt{src} (x',y')_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} (x',y')_g+ \texttt{upDiff} _g
-
- and
-
- .. math::
-
- \texttt{src} (x',y')_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} (x',y')_b+ \texttt{upDiff} _b
-
- in case of a color image and floating range
-
-
-*
-
- .. math::
-
- \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_r+ \texttt{upDiff} _r,
-
- .. math::
-
- \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_g+ \texttt{upDiff} _g
-
- and
-
- .. math::
-
- \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_b+ \texttt{upDiff} _b
-
- in case of a color image and fixed range
-
-where
-:math:`src(x',y')` is the value of one of pixel neighbors that is already known to belong to the component. That is, to be added to the connected component, a color/brightness of the pixel should be close enough to:
-
-*
- Color/brightness of one of its neighbors that already belong to the connected component in case of a floating range.
-
-*
- Color/brightness of the seed point in case of a fixed range.
-
-Use these functions to either mark a connected component with the specified color in-place, or build a mask and then extract the contour, or copy the region to another image, and so on.
-
-.. seealso:: :ocv:func:`findContours`
-
-.. note::
-
- * An example using the FloodFill technique can be found at opencv_source_code/samples/cpp/ffilldemo.cpp
-
- * (Python) An example using the FloodFill technique can be found at opencv_source_code/samples/python2/floodfill.cpp
-
-integral
---------
-Calculates the integral of an image.
-
-.. ocv:function:: void integral( InputArray src, OutputArray sum, int sdepth=-1 )
-
-.. ocv:function:: void integral( InputArray src, OutputArray sum, OutputArray sqsum, int sdepth=-1, int sqdepth=-1 )
-
-.. ocv:function:: void integral( InputArray src, OutputArray sum, OutputArray sqsum, OutputArray tilted, int sdepth=-1, int sqdepth=-1 )
-
-.. ocv:pyfunction:: cv2.integral(src[, sum[, sdepth]]) -> sum
-
-.. ocv:pyfunction:: cv2.integral2(src[, sum[, sqsum[, sdepth[, sqdepth]]]]) -> sum, sqsum
-
-.. ocv:pyfunction:: cv2.integral3(src[, sum[, sqsum[, tilted[, sdepth[, sqdepth]]]]]) -> sum, sqsum, tilted
-
-.. ocv:cfunction:: void cvIntegral( const CvArr* image, CvArr* sum, CvArr* sqsum=NULL, CvArr* tilted_sum=NULL )
-
- :param image: input image as :math:`W \times H`, 8-bit or floating-point (32f or 64f).
-
- :param sum: integral image as :math:`(W+1)\times (H+1)` , 32-bit integer or floating-point (32f or 64f).
-
- :param sqsum: integral image for squared pixel values; it is :math:`(W+1)\times (H+1)`, double-precision floating-point (64f) array.
-
- :param tilted: integral for the image rotated by 45 degrees; it is :math:`(W+1)\times (H+1)` array with the same data type as ``sum``.
-
- :param sdepth: desired depth of the integral and the tilted integral images, ``CV_32S``, ``CV_32F``, or ``CV_64F``.
-
- :param sqdepth: desired depth of the integral image of squared pixel values, ``CV_32F`` or ``CV_64F``.
-
-The functions calculate one or more integral images for the source image as follows:
-
-.. math::
-
- \texttt{sum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)
-
-.. math::
-
- \texttt{sqsum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)^2
-
-.. math::
-
- \texttt{tilted} (X,Y) = \sum _{y<Y,abs(x-X+1) \leq Y-y-1} \texttt{image} (x,y)
-
-Using these integral images, you can calculate sum, mean, and standard deviation over a specific up-right or rotated rectangular region of the image in a constant time, for example:
-
-.. math::
-
- \sum _{x_1 \leq x < x_2, \, y_1 \leq y < y_2} \texttt{image} (x,y) = \texttt{sum} (x_2,y_2)- \texttt{sum} (x_1,y_2)- \texttt{sum} (x_2,y_1)+ \texttt{sum} (x_1,y_1)
-
-It makes possible to do a fast blurring or fast block correlation with a variable window size, for example. In case of multi-channel images, sums for each channel are accumulated independently.
-
-As a practical example, the next figure shows the calculation of the integral of a straight rectangle ``Rect(3,3,3,2)`` and of a tilted rectangle ``Rect(5,1,2,3)`` . The selected pixels in the original ``image`` are shown, as well as the relative pixels in the integral images ``sum`` and ``tilted`` .
-
-.. image:: pics/integral.png
-
-
-
-
-
-threshold
----------
-Applies a fixed-level threshold to each array element.
-
-.. ocv:function:: double threshold( InputArray src, OutputArray dst, double thresh, double maxval, int type )
-
-.. ocv:pyfunction:: cv2.threshold(src, thresh, maxval, type[, dst]) -> retval, dst
-
-.. ocv:cfunction:: double cvThreshold( const CvArr* src, CvArr* dst, double threshold, double max_value, int threshold_type )
-
- :param src: input array (single-channel, 8-bit or 32-bit floating point).
-
- :param dst: output array of the same size and type as ``src``.
-
- :param thresh: threshold value.
-
- :param maxval: maximum value to use with the ``THRESH_BINARY`` and ``THRESH_BINARY_INV`` thresholding types.
-
- :param type: thresholding type (see the details below).
-
-The function applies fixed-level thresholding
-to a single-channel array. The function is typically used to get a
-bi-level (binary) image out of a grayscale image (
-:ocv:func:`compare` could
-be also used for this purpose) or for removing a noise, that is, filtering
-out pixels with too small or too large values. There are several
-types of thresholding supported by the function. They are determined by ``type`` :
-
- * **THRESH_BINARY**
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{\texttt{maxval}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
-
- * **THRESH_BINARY_INV**
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{maxval}}{otherwise}
-
- * **THRESH_TRUNC**
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{\texttt{threshold}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
-
- * **THRESH_TOZERO**
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{\texttt{src}(x,y)}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
-
- * **THRESH_TOZERO_INV**
-
- .. math::
-
- \texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
-
-Also, the special values ``THRESH_OTSU`` or ``THRESH_TRIANGLE`` may be combined with
-one of the above values. In these cases, the function determines the optimal threshold
-value using the Otsu's or Triangle algorithm and uses it instead of the specified ``thresh`` .
-The function returns the computed threshold value.
-Currently, the Otsu's and Triangle methods are implemented only for 8-bit images.
-
-
-.. image:: pics/threshold.png
-
-.. seealso::
-
- :ocv:func:`adaptiveThreshold`,
- :ocv:func:`findContours`,
- :ocv:func:`compare`,
- :ocv:func:`min`,
- :ocv:func:`max`
-
-
-watershed
----------
-Performs a marker-based image segmentation using the watershed algorithm.
-
-.. ocv:function:: void watershed( InputArray image, InputOutputArray markers )
-
-.. ocv:cfunction:: void cvWatershed( const CvArr* image, CvArr* markers )
-
-.. ocv:pyfunction:: cv2.watershed(image, markers) -> markers
-
- :param image: Input 8-bit 3-channel image.
-
- :param markers: Input/output 32-bit single-channel image (map) of markers. It should have the same size as ``image`` .
-
-The function implements one of the variants of watershed, non-parametric marker-based segmentation algorithm, described in [Meyer92]_.
-
-Before passing the image to the function, you have to roughly outline the desired regions in the image ``markers`` with positive (``>0``) indices. So, every region is represented as one or more connected components with the pixel values 1, 2, 3, and so on. Such markers can be retrieved from a binary mask using :ocv:func:`findContours` and :ocv:func:`drawContours` (see the ``watershed.cpp`` demo). The markers are "seeds" of the future image regions. All the other pixels in ``markers`` , whose relation to the outlined regions is not known and should be defined by the algorithm, should be set to 0's. In the function output, each pixel in markers is set to a value of the "seed" components or to -1 at boundaries between the regions.
-
-Visual demonstration and usage example of the function can be found in the OpenCV samples directory (see the ``watershed.cpp`` demo).
-
-.. note:: Any two neighbor connected components are not necessarily separated by a watershed boundary (-1's pixels); for example, they can touch each other in the initial marker image passed to the function.
-
-.. seealso:: :ocv:func:`findContours`
-
-.. note::
-
- * An example using the watershed algorithm can be found at opencv_source_code/samples/cpp/watershed.cpp
-
- * (Python) An example using the watershed algorithm can be found at opencv_source_code/samples/python2/watershed.py
-
-grabCut
--------
-Runs the GrabCut algorithm.
-
-.. ocv:function:: void grabCut( InputArray img, InputOutputArray mask, Rect rect, InputOutputArray bgdModel, InputOutputArray fgdModel, int iterCount, int mode=GC_EVAL )
-
-.. ocv:pyfunction:: cv2.grabCut(img, mask, rect, bgdModel, fgdModel, iterCount[, mode]) -> mask, bgdModel, fgdModel
-
- :param img: Input 8-bit 3-channel image.
-
- :param mask: Input/output 8-bit single-channel mask. The mask is initialized by the function when ``mode`` is set to ``GC_INIT_WITH_RECT``. Its elements may have one of following values:
-
- * **GC_BGD** defines an obvious background pixels.
-
- * **GC_FGD** defines an obvious foreground (object) pixel.
-
- * **GC_PR_BGD** defines a possible background pixel.
-
- * **GC_PR_FGD** defines a possible foreground pixel.
-
- :param rect: ROI containing a segmented object. The pixels outside of the ROI are marked as "obvious background". The parameter is only used when ``mode==GC_INIT_WITH_RECT`` .
-
- :param bgdModel: Temporary array for the background model. Do not modify it while you are processing the same image.
-
- :param fgdModel: Temporary arrays for the foreground model. Do not modify it while you are processing the same image.
-
- :param iterCount: Number of iterations the algorithm should make before returning the result. Note that the result can be refined with further calls with ``mode==GC_INIT_WITH_MASK`` or ``mode==GC_EVAL`` .
-
- :param mode: Operation mode that could be one of the following:
-
- * **GC_INIT_WITH_RECT** The function initializes the state and the mask using the provided rectangle. After that it runs ``iterCount`` iterations of the algorithm.
-
- * **GC_INIT_WITH_MASK** The function initializes the state using the provided mask. Note that ``GC_INIT_WITH_RECT`` and ``GC_INIT_WITH_MASK`` can be combined. Then, all the pixels outside of the ROI are automatically initialized with ``GC_BGD`` .
-
- * **GC_EVAL** The value means that the algorithm should just resume.
-
-The function implements the `GrabCut image segmentation algorithm <http://en.wikipedia.org/wiki/GrabCut>`_.
-See the sample ``grabcut.cpp`` to learn how to use the function.
-
-.. [Borgefors86] Borgefors, Gunilla, *Distance transformations in digital images*. Comput. Vision Graph. Image Process. 34 3, pp 344–371 (1986)
-
-.. [Felzenszwalb04] Felzenszwalb, Pedro F. and Huttenlocher, Daniel P. *Distance Transforms of Sampled Functions*, TR2004-1963, TR2004-1963 (2004)
-
-.. [Meyer92] Meyer, F. *Color Image Segmentation*, ICIP92, 1992
-
-
-.. note::
-
- * An example using the GrabCut algorithm can be found at opencv_source_code/samples/cpp/grabcut.cpp
-
- * (Python) An example using the GrabCut algorithm can be found at opencv_source_code/samples/python2/grabcut.py
+++ /dev/null
-Motion Analysis and Object Tracking
-===================================
-
-.. highlight:: cpp
-
-accumulate
---------------
-Adds an image to the accumulator.
-
-.. ocv:function:: void accumulate( InputArray src, InputOutputArray dst, InputArray mask=noArray() )
-
-.. ocv:pyfunction:: cv2.accumulate(src, dst[, mask]) -> dst
-
-.. ocv:cfunction:: void cvAcc( const CvArr* image, CvArr* sum, const CvArr* mask=NULL )
-
- :param src: Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
-
- :param dst: Accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point.
-
- :param mask: Optional operation mask.
-
-The function adds ``src`` or some of its elements to ``dst`` :
-
-.. math::
-
- \texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
-
-The function supports multi-channel images. Each channel is processed independently.
-
-The functions ``accumulate*`` can be used, for example, to collect statistics of a scene background viewed by a still camera and for the further foreground-background segmentation.
-
-.. seealso::
-
- :ocv:func:`accumulateSquare`,
- :ocv:func:`accumulateProduct`,
- :ocv:func:`accumulateWeighted`
-
-
-
-accumulateSquare
---------------------
-Adds the square of a source image to the accumulator.
-
-.. ocv:function:: void accumulateSquare( InputArray src, InputOutputArray dst, InputArray mask=noArray() )
-
-.. ocv:pyfunction:: cv2.accumulateSquare(src, dst[, mask]) -> dst
-
-.. ocv:cfunction:: void cvSquareAcc( const CvArr* image, CvArr* sqsum, const CvArr* mask=NULL )
-
- :param src: Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
-
- :param dst: Accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point.
-
- :param mask: Optional operation mask.
-
-The function adds the input image ``src`` or its selected region, raised to a power of 2, to the accumulator ``dst`` :
-
-.. math::
-
- \texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y)^2 \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
-
-The function supports multi-channel images. Each channel is processed independently.
-
-.. seealso::
-
- :ocv:func:`accumulateSquare`,
- :ocv:func:`accumulateProduct`,
- :ocv:func:`accumulateWeighted`
-
-
-
-accumulateProduct
----------------------
-Adds the per-element product of two input images to the accumulator.
-
-.. ocv:function:: void accumulateProduct( InputArray src1, InputArray src2, InputOutputArray dst, InputArray mask=noArray() )
-
-.. ocv:pyfunction:: cv2.accumulateProduct(src1, src2, dst[, mask]) -> dst
-
-.. ocv:cfunction:: void cvMultiplyAcc( const CvArr* image1, const CvArr* image2, CvArr* acc, const CvArr* mask=NULL )
-
- :param src1: First input image, 1- or 3-channel, 8-bit or 32-bit floating point.
-
- :param src2: Second input image of the same type and the same size as ``src1`` .
-
- :param dst: Accumulator with the same number of channels as input images, 32-bit or 64-bit floating-point.
-
- :param mask: Optional operation mask.
-
-The function adds the product of two images or their selected regions to the accumulator ``dst`` :
-
-.. math::
-
- \texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src1} (x,y) \cdot \texttt{src2} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
-
-The function supports multi-channel images. Each channel is processed independently.
-
-.. seealso::
-
- :ocv:func:`accumulate`,
- :ocv:func:`accumulateSquare`,
- :ocv:func:`accumulateWeighted`
-
-
-
-accumulateWeighted
-----------------------
-Updates a running average.
-
-.. ocv:function:: void accumulateWeighted( InputArray src, InputOutputArray dst, double alpha, InputArray mask=noArray() )
-
-.. ocv:pyfunction:: cv2.accumulateWeighted(src, dst, alpha[, mask]) -> dst
-
-.. ocv:cfunction:: void cvRunningAvg( const CvArr* image, CvArr* acc, double alpha, const CvArr* mask=NULL )
-
- :param src: Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
-
- :param dst: Accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point.
-
- :param alpha: Weight of the input image.
-
- :param mask: Optional operation mask.
-
-The function calculates the weighted sum of the input image ``src`` and the accumulator ``dst`` so that ``dst`` becomes a running average of a frame sequence:
-
-.. math::
-
- \texttt{dst} (x,y) \leftarrow (1- \texttt{alpha} ) \cdot \texttt{dst} (x,y) + \texttt{alpha} \cdot \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
-
-That is, ``alpha`` regulates the update speed (how fast the accumulator "forgets" about earlier images).
-The function supports multi-channel images. Each channel is processed independently.
-
-.. seealso::
-
- :ocv:func:`accumulate`,
- :ocv:func:`accumulateSquare`,
- :ocv:func:`accumulateProduct`
-
-
-
-phaseCorrelate
---------------
-The function is used to detect translational shifts that occur between two images. The operation takes advantage of the Fourier shift theorem for detecting the translational shift in the frequency domain. It can be used for fast image registration as well as motion estimation. For more information please see http://en.wikipedia.org/wiki/Phase\_correlation .
-
-Calculates the cross-power spectrum of two supplied source arrays. The arrays are padded if needed with :ocv:func:`getOptimalDFTSize`.
-
-.. ocv:function:: Point2d phaseCorrelate(InputArray src1, InputArray src2, InputArray window = noArray(), double* response = 0)
-
- :param src1: Source floating point array (CV_32FC1 or CV_64FC1)
- :param src2: Source floating point array (CV_32FC1 or CV_64FC1)
- :param window: Floating point array with windowing coefficients to reduce edge effects (optional).
- :param response: Signal power within the 5x5 centroid around the peak, between 0 and 1 (optional).
-
-Return value: detected phase shift (sub-pixel) between the two arrays.
-
-The function performs the following equations
-
-* First it applies a Hanning window (see http://en.wikipedia.org/wiki/Hann\_function) to each image to remove possible edge effects. This window is cached until the array size changes to speed up processing time.
-
-* Next it computes the forward DFTs of each source array:
-
- .. math::
-
- \mathbf{G}_a = \mathcal{F}\{src_1\}, \; \mathbf{G}_b = \mathcal{F}\{src_2\}
-
- where
- :math:`\mathcal{F}` is the forward DFT.
-
-* It then computes the cross-power spectrum of each frequency domain array:
-
- .. math::
-
- R = \frac{ \mathbf{G}_a \mathbf{G}_b^*}{|\mathbf{G}_a \mathbf{G}_b^*|}
-
-* Next the cross-correlation is converted back into the time domain via the inverse DFT:
-
- .. math::
-
- r = \mathcal{F}^{-1}\{R\}
-
-* Finally, it computes the peak location and computes a 5x5 weighted centroid around the peak to achieve sub-pixel accuracy.
-
- .. math::
-
- (\Delta x, \Delta y) = \texttt{weightedCentroid} \{\arg \max_{(x, y)}\{r\}\}
-
-* If non-zero, the response parameter is computed as the sum of the elements of r within the 5x5 centroid around the peak location. It is normalized to a maximum of 1 (meaning there is a single peak) and will be smaller when there are multiple peaks.
-
-.. seealso::
- :ocv:func:`dft`,
- :ocv:func:`getOptimalDFTSize`,
- :ocv:func:`idft`,
- :ocv:func:`mulSpectrums`
- :ocv:func:`createHanningWindow`
-
-createHanningWindow
--------------------------------
-This function computes a Hanning window coefficients in two dimensions. See http://en.wikipedia.org/wiki/Hann\_function and http://en.wikipedia.org/wiki/Window\_function for more information.
-
-.. ocv:function:: void createHanningWindow(OutputArray dst, Size winSize, int type)
-
- :param dst: Destination array to place Hann coefficients in
- :param winSize: The window size specifications
- :param type: Created array type
-
-An example is shown below: ::
-
- // create hanning window of size 100x100 and type CV_32F
- Mat hann;
- createHanningWindow(hann, Size(100, 100), CV_32F);
-
-.. seealso::
- :ocv:func:`phaseCorrelate`
+++ /dev/null
-Object Detection
-================
-
-.. highlight:: cpp
-
-matchTemplate
------------------
-Compares a template against overlapped image regions.
-
-.. ocv:function:: void matchTemplate( InputArray image, InputArray templ, OutputArray result, int method )
-
-.. ocv:pyfunction:: cv2.matchTemplate(image, templ, method[, result]) -> result
-
-.. ocv:cfunction:: void cvMatchTemplate( const CvArr* image, const CvArr* templ, CvArr* result, int method )
-
- :param image: Image where the search is running. It must be 8-bit or 32-bit floating-point.
-
- :param templ: Searched template. It must be not greater than the source image and have the same data type.
-
- :param result: Map of comparison results. It must be single-channel 32-bit floating-point. If ``image`` is :math:`W \times H` and ``templ`` is :math:`w \times h` , then ``result`` is :math:`(W-w+1) \times (H-h+1)` .
-
- :param method: Parameter specifying the comparison method (see below).
-
-The function slides through ``image`` , compares the
-overlapped patches of size
-:math:`w \times h` against ``templ`` using the specified method and stores the comparison results in ``result`` . Here are the formulae for the available comparison
-methods (
-:math:`I` denotes ``image``, :math:`T` ``template``, :math:`R` ``result`` ). The summation is done over template and/or the
-image patch:
-:math:`x' = 0...w-1, y' = 0...h-1`
-
-* method=CV\_TM\_SQDIFF
-
- .. math::
-
- R(x,y)= \sum _{x',y'} (T(x',y')-I(x+x',y+y'))^2
-
-* method=CV\_TM\_SQDIFF\_NORMED
-
- .. math::
-
- R(x,y)= \frac{\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
-
-* method=CV\_TM\_CCORR
-
- .. math::
-
- R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y'))
-
-* method=CV\_TM\_CCORR\_NORMED
-
- .. math::
-
- R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y'))}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
-
-* method=CV\_TM\_CCOEFF
-
- .. math::
-
- R(x,y)= \sum _{x',y'} (T'(x',y') \cdot I'(x+x',y+y'))
-
- where
-
- .. math::
-
- \begin{array}{l} T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum _{x'',y''} T(x'',y'') \\ I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h) \cdot \sum _{x'',y''} I(x+x'',y+y'') \end{array}
-
-* method=CV\_TM\_CCOEFF\_NORMED
-
- .. math::
-
- R(x,y)= \frac{ \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }{ \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2} }
-
-After the function finishes the comparison, the best matches can be found as global minimums (when ``CV_TM_SQDIFF`` was used) or maximums (when ``CV_TM_CCORR`` or ``CV_TM_CCOEFF`` was used) using the
-:ocv:func:`minMaxLoc` function. In case of a color image, template summation in the numerator and each sum in the denominator is done over all of the channels and separate mean values are used for each channel. That is, the function can take a color template and a color image. The result will still be a single-channel image, which is easier to analyze.
-
-.. note::
-
- * (Python) An example on how to match mouse selected regions in an image can be found at opencv_source_code/samples/python2/mouse_and_match.py
+++ /dev/null
-Structural Analysis and Shape Descriptors
-=========================================
-
-.. highlight:: cpp
-
-moments
------------
-Calculates all of the moments up to the third order of a polygon or rasterized shape.
-
-.. ocv:function:: Moments moments( InputArray array, bool binaryImage=false )
-
-.. ocv:pyfunction:: cv2.moments(array[, binaryImage]) -> retval
-
-.. ocv:cfunction:: void cvMoments( const CvArr* arr, CvMoments* moments, int binary=0 )
-
- :param array: Raster image (single-channel, 8-bit or floating-point 2D array) or an array ( :math:`1 \times N` or :math:`N \times 1` ) of 2D points (``Point`` or ``Point2f`` ).
-
- :param binaryImage: If it is true, all non-zero image pixels are treated as 1's. The parameter is used for images only.
-
- :param moments: Output moments.
-
-The function computes moments, up to the 3rd order, of a vector shape or a rasterized shape. The results are returned in the structure ``Moments`` defined as: ::
-
- class Moments
- {
- public:
- Moments();
- Moments(double m00, double m10, double m01, double m20, double m11,
- double m02, double m30, double m21, double m12, double m03 );
- Moments( const CvMoments& moments );
- operator CvMoments() const;
-
- // spatial moments
- double m00, m10, m01, m20, m11, m02, m30, m21, m12, m03;
- // central moments
- double mu20, mu11, mu02, mu30, mu21, mu12, mu03;
- // central normalized moments
- double nu20, nu11, nu02, nu30, nu21, nu12, nu03;
- }
-
-In case of a raster image, the spatial moments :math:`\texttt{Moments::m}_{ji}` are computed as:
-
-.. math::
-
- \texttt{m} _{ji}= \sum _{x,y} \left ( \texttt{array} (x,y) \cdot x^j \cdot y^i \right )
-
-The central moments
-:math:`\texttt{Moments::mu}_{ji}` are computed as:
-
-.. math::
-
- \texttt{mu} _{ji}= \sum _{x,y} \left ( \texttt{array} (x,y) \cdot (x - \bar{x} )^j \cdot (y - \bar{y} )^i \right )
-
-where
-:math:`(\bar{x}, \bar{y})` is the mass center:
-
-.. math::
-
- \bar{x} = \frac{\texttt{m}_{10}}{\texttt{m}_{00}} , \; \bar{y} = \frac{\texttt{m}_{01}}{\texttt{m}_{00}}
-
-The normalized central moments
-:math:`\texttt{Moments::nu}_{ij}` are computed as:
-
-.. math::
-
- \texttt{nu} _{ji}= \frac{\texttt{mu}_{ji}}{\texttt{m}_{00}^{(i+j)/2+1}} .
-
-.. note::
-
- :math:`\texttt{mu}_{00}=\texttt{m}_{00}`,
- :math:`\texttt{nu}_{00}=1`
- :math:`\texttt{nu}_{10}=\texttt{mu}_{10}=\texttt{mu}_{01}=\texttt{mu}_{10}=0` , hence the values are not stored.
-
-The moments of a contour are defined in the same way but computed using the Green's formula (see http://en.wikipedia.org/wiki/Green_theorem). So, due to a limited raster resolution, the moments computed for a contour are slightly different from the moments computed for the same rasterized contour.
-
-.. note::
-
- Since the contour moments are computed using Green formula, you may get seemingly odd results for contours with self-intersections, e.g. a zero area (``m00``) for butterfly-shaped contours.
-
-.. seealso::
-
- :ocv:func:`contourArea`,
- :ocv:func:`arcLength`
-
-
-
-HuMoments
--------------
-Calculates seven Hu invariants.
-
-.. ocv:function:: void HuMoments( const Moments& m, OutputArray hu )
-
-.. ocv:function:: void HuMoments( const Moments& moments, double hu[7] )
-
-.. ocv:pyfunction:: cv2.HuMoments(m[, hu]) -> hu
-
-.. ocv:cfunction:: void cvGetHuMoments( CvMoments* moments, CvHuMoments* hu_moments )
-
- :param moments: Input moments computed with :ocv:func:`moments` .
- :param hu: Output Hu invariants.
-
-The function calculates seven Hu invariants (introduced in [Hu62]_; see also
-http://en.wikipedia.org/wiki/Image_moment) defined as:
-
-.. math::
-
- \begin{array}{l} hu[0]= \eta _{20}+ \eta _{02} \\ hu[1]=( \eta _{20}- \eta _{02})^{2}+4 \eta _{11}^{2} \\ hu[2]=( \eta _{30}-3 \eta _{12})^{2}+ (3 \eta _{21}- \eta _{03})^{2} \\ hu[3]=( \eta _{30}+ \eta _{12})^{2}+ ( \eta _{21}+ \eta _{03})^{2} \\ hu[4]=( \eta _{30}-3 \eta _{12})( \eta _{30}+ \eta _{12})[( \eta _{30}+ \eta _{12})^{2}-3( \eta _{21}+ \eta _{03})^{2}]+(3 \eta _{21}- \eta _{03})( \eta _{21}+ \eta _{03})[3( \eta _{30}+ \eta _{12})^{2}-( \eta _{21}+ \eta _{03})^{2}] \\ hu[5]=( \eta _{20}- \eta _{02})[( \eta _{30}+ \eta _{12})^{2}- ( \eta _{21}+ \eta _{03})^{2}]+4 \eta _{11}( \eta _{30}+ \eta _{12})( \eta _{21}+ \eta _{03}) \\ hu[6]=(3 \eta _{21}- \eta _{03})( \eta _{21}+ \eta _{03})[3( \eta _{30}+ \eta _{12})^{2}-( \eta _{21}+ \eta _{03})^{2}]-( \eta _{30}-3 \eta _{12})( \eta _{21}+ \eta _{03})[3( \eta _{30}+ \eta _{12})^{2}-( \eta _{21}+ \eta _{03})^{2}] \\ \end{array}
-
-where
-:math:`\eta_{ji}` stands for
-:math:`\texttt{Moments::nu}_{ji}` .
-
-These values are proved to be invariants to the image scale, rotation, and reflection except the seventh one, whose sign is changed by reflection. This invariance is proved with the assumption of infinite image resolution. In case of raster images, the computed Hu invariants for the original and transformed images are a bit different.
-
-.. seealso:: :ocv:func:`matchShapes`
-
-connectedComponents
------------------------
-computes the connected components labeled image of boolean image ``image`` with 4 or 8 way connectivity - returns N, the total number of labels [0, N-1] where 0 represents the background label. ltype specifies the output label image type, an important consideration based on the total number of labels or alternatively the total number of pixels in the source image.
-
-.. ocv:function:: int connectedComponents(InputArray image, OutputArray labels, int connectivity = 8, int ltype=CV_32S)
-
-.. ocv:function:: int connectedComponentsWithStats(InputArray image, OutputArray labels, OutputArray stats, OutputArray centroids, int connectivity = 8, int ltype=CV_32S)
-
- :param image: the image to be labeled
-
- :param labels: destination labeled image
-
- :param connectivity: 8 or 4 for 8-way or 4-way connectivity respectively
-
- :param ltype: output image label type. Currently CV_32S and CV_16U are supported.
-
- :param statsv: statistics output for each label, including the background label, see below for available statistics. Statistics are accessed via statsv(label, COLUMN) where available columns are defined below.
-
- * **CC_STAT_LEFT** The leftmost (x) coordinate which is the inclusive start of the bounding box in the horizontal
- direction.
-
- * **CC_STAT_TOP** The topmost (y) coordinate which is the inclusive start of the bounding box in the vertical
- direction.
-
- * **CC_STAT_WIDTH** The horizontal size of the bounding box
-
- * **CC_STAT_HEIGHT** The vertical size of the bounding box
-
- * **CC_STAT_AREA** The total area (in pixels) of the connected component
-
- :param centroids: floating point centroid (x,y) output for each label, including the background label
-
-
-findContours
-----------------
-Finds contours in a binary image.
-
-.. ocv:function:: void findContours( InputOutputArray image, OutputArrayOfArrays contours, OutputArray hierarchy, int mode, int method, Point offset=Point())
-
-.. ocv:function:: void findContours( InputOutputArray image, OutputArrayOfArrays contours, int mode, int method, Point offset=Point())
-
-.. ocv:pyfunction:: cv2.findContours(image, mode, method[, contours[, hierarchy[, offset]]]) -> image, contours, hierarchy
-
-.. ocv:cfunction:: int cvFindContours( CvArr* image, CvMemStorage* storage, CvSeq** first_contour, int header_size=sizeof(CvContour), int mode=CV_RETR_LIST, int method=CV_CHAIN_APPROX_SIMPLE, CvPoint offset=cvPoint(0,0) )
-
- :param image: Source, an 8-bit single-channel image. Non-zero pixels are treated as 1's. Zero pixels remain 0's, so the image is treated as ``binary`` . You can use :ocv:func:`compare` , :ocv:func:`inRange` , :ocv:func:`threshold` , :ocv:func:`adaptiveThreshold` , :ocv:func:`Canny` , and others to create a binary image out of a grayscale or color one. The function modifies the ``image`` while extracting the contours. If mode equals to ``CV_RETR_CCOMP`` or ``CV_RETR_FLOODFILL``, the input can also be a 32-bit integer image of labels (``CV_32SC1``).
-
- :param contours: Detected contours. Each contour is stored as a vector of points.
-
- :param hierarchy: Optional output vector, containing information about the image topology. It has as many elements as the number of contours. For each i-th contour ``contours[i]`` , the elements ``hierarchy[i][0]`` , ``hiearchy[i][1]`` , ``hiearchy[i][2]`` , and ``hiearchy[i][3]`` are set to 0-based indices in ``contours`` of the next and previous contours at the same hierarchical level, the first child contour and the parent contour, respectively. If for the contour ``i`` there are no next, previous, parent, or nested contours, the corresponding elements of ``hierarchy[i]`` will be negative.
-
- :param mode: Contour retrieval mode (if you use Python see also a note below).
-
- * **CV_RETR_EXTERNAL** retrieves only the extreme outer contours. It sets ``hierarchy[i][2]=hierarchy[i][3]=-1`` for all the contours.
-
- * **CV_RETR_LIST** retrieves all of the contours without establishing any hierarchical relationships.
-
- * **CV_RETR_CCOMP** retrieves all of the contours and organizes them into a two-level hierarchy. At the top level, there are external boundaries of the components. At the second level, there are boundaries of the holes. If there is another contour inside a hole of a connected component, it is still put at the top level.
-
- * **CV_RETR_TREE** retrieves all of the contours and reconstructs a full hierarchy of nested contours. This full hierarchy is built and shown in the OpenCV ``contours.c`` demo.
-
- :param method: Contour approximation method (if you use Python see also a note below).
-
- * **CV_CHAIN_APPROX_NONE** stores absolutely all the contour points. That is, any 2 subsequent points ``(x1,y1)`` and ``(x2,y2)`` of the contour will be either horizontal, vertical or diagonal neighbors, that is, ``max(abs(x1-x2),abs(y2-y1))==1``.
-
- * **CV_CHAIN_APPROX_SIMPLE** compresses horizontal, vertical, and diagonal segments and leaves only their end points. For example, an up-right rectangular contour is encoded with 4 points.
-
- * **CV_CHAIN_APPROX_TC89_L1,CV_CHAIN_APPROX_TC89_KCOS** applies one of the flavors of the Teh-Chin chain approximation algorithm. See [TehChin89]_ for details.
-
- :param offset: Optional offset by which every contour point is shifted. This is useful if the contours are extracted from the image ROI and then they should be analyzed in the whole image context.
-
-The function retrieves contours from the binary image using the algorithm
-[Suzuki85]_. The contours are a useful tool for shape analysis and object detection and recognition. See ``squares.c`` in the OpenCV sample directory.
-
-.. note:: Source ``image`` is modified by this function. Also, the function does not take into account 1-pixel border of the image (it's filled with 0's and used for neighbor analysis in the algorithm), therefore the contours touching the image border will be clipped.
-
-.. note:: If you use the new Python interface then the ``CV_`` prefix has to be omitted in contour retrieval mode and contour approximation method parameters (for example, use ``cv2.RETR_LIST`` and ``cv2.CHAIN_APPROX_NONE`` parameters). If you use the old Python interface then these parameters have the ``CV_`` prefix (for example, use ``cv.CV_RETR_LIST`` and ``cv.CV_CHAIN_APPROX_NONE``).
-
-.. note::
-
- * An example using the findContour functionality can be found at opencv_source_code/samples/cpp/contours2.cpp
- * An example using findContours to clean up a background segmentation result at opencv_source_code/samples/cpp/segment_objects.cpp
-
- * (Python) An example using the findContour functionality can be found at opencv_source/samples/python2/contours.py
- * (Python) An example of detecting squares in an image can be found at opencv_source/samples/python2/squares.py
-
-
-approxPolyDP
-----------------
-Approximates a polygonal curve(s) with the specified precision.
-
-.. ocv:function:: void approxPolyDP( InputArray curve, OutputArray approxCurve, double epsilon, bool closed )
-
-.. ocv:pyfunction:: cv2.approxPolyDP(curve, epsilon, closed[, approxCurve]) -> approxCurve
-
-.. ocv:cfunction:: CvSeq* cvApproxPoly( const void* src_seq, int header_size, CvMemStorage* storage, int method, double eps, int recursive=0 )
-
- :param curve: Input vector of a 2D point stored in:
-
- * ``std::vector`` or ``Mat`` (C++ interface)
-
- * ``Nx2`` numpy array (Python interface)
-
- * ``CvSeq`` or `` ``CvMat`` (C interface)
-
- :param approxCurve: Result of the approximation. The type should match the type of the input curve. In case of C interface the approximated curve is stored in the memory storage and pointer to it is returned.
-
- :param epsilon: Parameter specifying the approximation accuracy. This is the maximum distance between the original curve and its approximation.
-
- :param closed: If true, the approximated curve is closed (its first and last vertices are connected). Otherwise, it is not closed.
-
- :param header_size: Header size of the approximated curve. Normally, ``sizeof(CvContour)`` is used.
-
- :param storage: Memory storage where the approximated curve is stored.
-
- :param method: Contour approximation algorithm. Only ``CV_POLY_APPROX_DP`` is supported.
-
- :param recursive: Recursion flag. If it is non-zero and ``curve`` is ``CvSeq*``, the function ``cvApproxPoly`` approximates all the contours accessible from ``curve`` by ``h_next`` and ``v_next`` links.
-
-The functions ``approxPolyDP`` approximate a curve or a polygon with another curve/polygon with less vertices so that the distance between them is less or equal to the specified precision. It uses the Douglas-Peucker algorithm
-http://en.wikipedia.org/wiki/Ramer-Douglas-Peucker_algorithm
-
-See https://github.com/Itseez/opencv/tree/master/samples/cpp/contours2.cpp for the function usage model.
-
-
-ApproxChains
--------------
-Approximates Freeman chain(s) with a polygonal curve.
-
-.. ocv:cfunction:: CvSeq* cvApproxChains( CvSeq* src_seq, CvMemStorage* storage, int method=CV_CHAIN_APPROX_SIMPLE, double parameter=0, int minimal_perimeter=0, int recursive=0 )
-
- :param src_seq: Pointer to the approximated Freeman chain that can refer to other chains.
-
- :param storage: Storage location for the resulting polylines.
-
- :param method: Approximation method (see the description of the function :ocv:cfunc:`FindContours` ).
-
- :param parameter: Method parameter (not used now).
-
- :param minimal_perimeter: Approximates only those contours whose perimeters are not less than ``minimal_perimeter`` . Other chains are removed from the resulting structure.
-
- :param recursive: Recursion flag. If it is non-zero, the function approximates all chains that can be obtained from ``chain`` by using the ``h_next`` or ``v_next`` links. Otherwise, the single input chain is approximated.
-
-This is a standalone contour approximation routine, not represented in the new interface. When :ocv:cfunc:`FindContours` retrieves contours as Freeman chains, it calls the function to get approximated contours, represented as polygons.
-
-
-arcLength
--------------
-Calculates a contour perimeter or a curve length.
-
-.. ocv:function:: double arcLength( InputArray curve, bool closed )
-
-.. ocv:pyfunction:: cv2.arcLength(curve, closed) -> retval
-
-.. ocv:cfunction:: double cvArcLength( const void* curve, CvSlice slice=CV_WHOLE_SEQ, int is_closed=-1 )
-
- :param curve: Input vector of 2D points, stored in ``std::vector`` or ``Mat``.
-
- :param closed: Flag indicating whether the curve is closed or not.
-
-The function computes a curve length or a closed contour perimeter.
-
-
-
-boundingRect
-----------------
-Calculates the up-right bounding rectangle of a point set.
-
-.. ocv:function:: Rect boundingRect( InputArray points )
-
-.. ocv:pyfunction:: cv2.boundingRect(points) -> retval
-
-.. ocv:cfunction:: CvRect cvBoundingRect( CvArr* points, int update=0 )
-
- :param points: Input 2D point set, stored in ``std::vector`` or ``Mat``.
-
-The function calculates and returns the minimal up-right bounding rectangle for the specified point set.
-
-
-contourArea
----------------
-Calculates a contour area.
-
-.. ocv:function:: double contourArea( InputArray contour, bool oriented=false )
-
-.. ocv:pyfunction:: cv2.contourArea(contour[, oriented]) -> retval
-
-.. ocv:cfunction:: double cvContourArea( const CvArr* contour, CvSlice slice=CV_WHOLE_SEQ, int oriented=0 )
-
- :param contour: Input vector of 2D points (contour vertices), stored in ``std::vector`` or ``Mat``.
-
- :param oriented: Oriented area flag. If it is true, the function returns a signed area value, depending on the contour orientation (clockwise or counter-clockwise). Using this feature you can determine orientation of a contour by taking the sign of an area. By default, the parameter is ``false``, which means that the absolute value is returned.
-
-The function computes a contour area. Similarly to
-:ocv:func:`moments` , the area is computed using the Green formula. Thus, the returned area and the number of non-zero pixels, if you draw the contour using
-:ocv:func:`drawContours` or
-:ocv:func:`fillPoly` , can be different.
-Also, the function will most certainly give a wrong results for contours with self-intersections.
-
-Example: ::
-
- vector<Point> contour;
- contour.push_back(Point2f(0, 0));
- contour.push_back(Point2f(10, 0));
- contour.push_back(Point2f(10, 10));
- contour.push_back(Point2f(5, 4));
-
- double area0 = contourArea(contour);
- vector<Point> approx;
- approxPolyDP(contour, approx, 5, true);
- double area1 = contourArea(approx);
-
- cout << "area0 =" << area0 << endl <<
- "area1 =" << area1 << endl <<
- "approx poly vertices" << approx.size() << endl;
-
-
-
-convexHull
---------------
-Finds the convex hull of a point set.
-
-.. ocv:function:: void convexHull( InputArray points, OutputArray hull, bool clockwise=false, bool returnPoints=true )
-
-.. ocv:pyfunction:: cv2.convexHull(points[, hull[, clockwise[, returnPoints]]]) -> hull
-
-.. ocv:cfunction:: CvSeq* cvConvexHull2( const CvArr* input, void* hull_storage=NULL, int orientation=CV_CLOCKWISE, int return_points=0 )
-
- :param points: Input 2D point set, stored in ``std::vector`` or ``Mat``.
-
- :param hull: Output convex hull. It is either an integer vector of indices or vector of points. In the first case, the ``hull`` elements are 0-based indices of the convex hull points in the original array (since the set of convex hull points is a subset of the original point set). In the second case, ``hull`` elements are the convex hull points themselves.
-
- :param hull_storage: Output memory storage in the old API (``cvConvexHull2`` returns a sequence containing the convex hull points or their indices).
-
- :param clockwise: Orientation flag. If it is true, the output convex hull is oriented clockwise. Otherwise, it is oriented counter-clockwise. The assumed coordinate system has its X axis pointing to the right, and its Y axis pointing upwards.
-
- :param orientation: Convex hull orientation parameter in the old API, ``CV_CLOCKWISE`` or ``CV_COUNTERCLOCKWISE``.
-
- :param returnPoints: Operation flag. In case of a matrix, when the flag is true, the function returns convex hull points. Otherwise, it returns indices of the convex hull points. When the output array is ``std::vector``, the flag is ignored, and the output depends on the type of the vector: ``std::vector<int>`` implies ``returnPoints=true``, ``std::vector<Point>`` implies ``returnPoints=false``.
-
-The functions find the convex hull of a 2D point set using the Sklansky's algorithm
-[Sklansky82]_
-that has
-*O(N logN)* complexity in the current implementation. See the OpenCV sample ``convexhull.cpp`` that demonstrates the usage of different function variants.
-
-.. note::
-
- * An example using the convexHull functionality can be found at opencv_source_code/samples/cpp/convexhull.cpp
-
-
-convexityDefects
-----------------
-Finds the convexity defects of a contour.
-
-.. ocv:function:: void convexityDefects( InputArray contour, InputArray convexhull, OutputArray convexityDefects )
-
-.. ocv:pyfunction:: cv2.convexityDefects(contour, convexhull[, convexityDefects]) -> convexityDefects
-
-.. ocv:cfunction:: CvSeq* cvConvexityDefects( const CvArr* contour, const CvArr* convexhull, CvMemStorage* storage=NULL )
-
- :param contour: Input contour.
-
- :param convexhull: Convex hull obtained using :ocv:func:`convexHull` that should contain indices of the contour points that make the hull.
-
- :param convexityDefects: The output vector of convexity defects. In C++ and the new Python/Java interface each convexity defect is represented as 4-element integer vector (a.k.a. ``cv::Vec4i``): ``(start_index, end_index, farthest_pt_index, fixpt_depth)``, where indices are 0-based indices in the original contour of the convexity defect beginning, end and the farthest point, and ``fixpt_depth`` is fixed-point approximation (with 8 fractional bits) of the distance between the farthest contour point and the hull. That is, to get the floating-point value of the depth will be ``fixpt_depth/256.0``. In C interface convexity defect is represented by ``CvConvexityDefect`` structure - see below.
-
- :param storage: Container for the output sequence of convexity defects. If it is NULL, the contour or hull (in that order) storage is used.
-
-The function finds all convexity defects of the input contour and returns a sequence of the ``CvConvexityDefect`` structures, where ``CvConvexityDetect`` is defined as: ::
-
- struct CvConvexityDefect
- {
- CvPoint* start; // point of the contour where the defect begins
- CvPoint* end; // point of the contour where the defect ends
- CvPoint* depth_point; // the farthest from the convex hull point within the defect
- float depth; // distance between the farthest point and the convex hull
- };
-
-The figure below displays convexity defects of a hand contour:
-
-.. image:: pics/defects.png
-
-fitEllipse
---------------
-Fits an ellipse around a set of 2D points.
-
-.. ocv:function:: RotatedRect fitEllipse( InputArray points )
-
-.. ocv:pyfunction:: cv2.fitEllipse(points) -> retval
-
-.. ocv:cfunction:: CvBox2D cvFitEllipse2( const CvArr* points )
-
- :param points: Input 2D point set, stored in:
-
- * ``std::vector<>`` or ``Mat`` (C++ interface)
-
- * ``CvSeq*`` or ``CvMat*`` (C interface)
-
- * Nx2 numpy array (Python interface)
-
-The function calculates the ellipse that fits (in a least-squares sense) a set of 2D points best of all. It returns the rotated rectangle in which the ellipse is inscribed. The algorithm [Fitzgibbon95]_ is used.
-Developer should keep in mind that it is possible that the returned ellipse/rotatedRect data contains negative indices, due to the data points being close to the border of the containing Mat element.
-
-.. note::
-
- * An example using the fitEllipse technique can be found at opencv_source_code/samples/cpp/fitellipse.cpp
-
-
-fitLine
------------
-Fits a line to a 2D or 3D point set.
-
-.. ocv:function:: void fitLine( InputArray points, OutputArray line, int distType, double param, double reps, double aeps )
-
-.. ocv:pyfunction:: cv2.fitLine(points, distType, param, reps, aeps[, line]) -> line
-
-.. ocv:cfunction:: void cvFitLine( const CvArr* points, int dist_type, double param, double reps, double aeps, float* line )
-
- :param points: Input vector of 2D or 3D points, stored in ``std::vector<>`` or ``Mat``.
-
- :param line: Output line parameters. In case of 2D fitting, it should be a vector of 4 elements (like ``Vec4f``) - ``(vx, vy, x0, y0)``, where ``(vx, vy)`` is a normalized vector collinear to the line and ``(x0, y0)`` is a point on the line. In case of 3D fitting, it should be a vector of 6 elements (like ``Vec6f``) - ``(vx, vy, vz, x0, y0, z0)``, where ``(vx, vy, vz)`` is a normalized vector collinear to the line and ``(x0, y0, z0)`` is a point on the line.
-
- :param distType: Distance used by the M-estimator (see the discussion below).
-
- :param param: Numerical parameter ( ``C`` ) for some types of distances. If it is 0, an optimal value is chosen.
-
- :param reps: Sufficient accuracy for the radius (distance between the coordinate origin and the line).
-
- :param aeps: Sufficient accuracy for the angle. 0.01 would be a good default value for ``reps`` and ``aeps``.
-
-The function ``fitLine`` fits a line to a 2D or 3D point set by minimizing
-:math:`\sum_i \rho(r_i)` where
-:math:`r_i` is a distance between the
-:math:`i^{th}` point, the line and
-:math:`\rho(r)` is a distance function, one of the following:
-
-* distType=CV\_DIST\_L2
-
- .. math::
-
- \rho (r) = r^2/2 \quad \text{(the simplest and the fastest least-squares method)}
-
-* distType=CV\_DIST\_L1
-
- .. math::
-
- \rho (r) = r
-
-* distType=CV\_DIST\_L12
-
- .. math::
-
- \rho (r) = 2 \cdot ( \sqrt{1 + \frac{r^2}{2}} - 1)
-
-* distType=CV\_DIST\_FAIR
-
- .. math::
-
- \rho \left (r \right ) = C^2 \cdot \left ( \frac{r}{C} - \log{\left(1 + \frac{r}{C}\right)} \right ) \quad \text{where} \quad C=1.3998
-
-* distType=CV\_DIST\_WELSCH
-
- .. math::
-
- \rho \left (r \right ) = \frac{C^2}{2} \cdot \left ( 1 - \exp{\left(-\left(\frac{r}{C}\right)^2\right)} \right ) \quad \text{where} \quad C=2.9846
-
-* distType=CV\_DIST\_HUBER
-
- .. math::
-
- \rho (r) = \fork{r^2/2}{if $r < C$}{C \cdot (r-C/2)}{otherwise} \quad \text{where} \quad C=1.345
-
-The algorithm is based on the M-estimator (
-http://en.wikipedia.org/wiki/M-estimator
-) technique that iteratively fits the line using the weighted least-squares algorithm. After each iteration the weights
-:math:`w_i` are adjusted to be inversely proportional to
-:math:`\rho(r_i)` .
-
-.. Sample code:
-
- * (Python) An example of robust line fitting can be found at opencv_source_code/samples/python2/fitline.py
-
-
-isContourConvex
--------------------
-Tests a contour convexity.
-
-.. ocv:function:: bool isContourConvex( InputArray contour )
-
-.. ocv:pyfunction:: cv2.isContourConvex(contour) -> retval
-
-.. ocv:cfunction:: int cvCheckContourConvexity( const CvArr* contour )
-
- :param contour: Input vector of 2D points, stored in:
-
- * ``std::vector<>`` or ``Mat`` (C++ interface)
-
- * ``CvSeq*`` or ``CvMat*`` (C interface)
-
- * Nx2 numpy array (Python interface)
-
-The function tests whether the input contour is convex or not. The contour must be simple, that is, without self-intersections. Otherwise, the function output is undefined.
-
-
-
-minAreaRect
----------------
-Finds a rotated rectangle of the minimum area enclosing the input 2D point set.
-
-.. ocv:function:: RotatedRect minAreaRect( InputArray points )
-
-.. ocv:pyfunction:: cv2.minAreaRect(points) -> retval
-
-.. ocv:cfunction:: CvBox2D cvMinAreaRect2( const CvArr* points, CvMemStorage* storage=NULL )
-
- :param points: Input vector of 2D points, stored in:
-
- * ``std::vector<>`` or ``Mat`` (C++ interface)
-
- * ``CvSeq*`` or ``CvMat*`` (C interface)
-
- * Nx2 numpy array (Python interface)
-
-The function calculates and returns the minimum-area bounding rectangle (possibly rotated) for a specified point set. See the OpenCV sample ``minarea.cpp`` .
-Developer should keep in mind that the returned rotatedRect can contain negative indices when data is close the the containing Mat element boundary.
-
-
-boxPoints
------------
-Finds the four vertices of a rotated rect. Useful to draw the rotated rectangle.
-
-.. ocv:function:: void boxPoints(RotatedRect box, OutputArray points)
-
-.. ocv:pyfunction:: cv2.boxPoints(box[, points]) -> points
-
-.. ocv:cfunction:: void cvBoxPoints( CvBox2D box, CvPoint2D32f pt[4] )
-
- :param box: The input rotated rectangle. It may be the output of .. ocv:function:: minAreaRect.
-
- :param points: The output array of four vertices of rectangles.
-
-The function finds the four vertices of a rotated rectangle. This function is useful to draw the rectangle. In C++, instead of using this function, you can directly use box.points() method. Please visit the `tutorial on bounding rectangle <http://docs.opencv.org/doc/tutorials/imgproc/shapedescriptors/bounding_rects_circles/bounding_rects_circles.html#bounding-rects-circles>`_ for more information.
-
-
-
-minEnclosingTriangle
-----------------------
-Finds a triangle of minimum area enclosing a 2D point set and returns its area.
-
-.. ocv:function:: double minEnclosingTriangle( InputArray points, OutputArray triangle )
-
-.. ocv:pyfunction:: cv2.minEnclosingTriangle(points[, triangle]) -> retval, triangle
-
- :param points: Input vector of 2D points with depth ``CV_32S`` or ``CV_32F``, stored in:
-
- * ``std::vector<>`` or ``Mat`` (C++ interface)
-
- * Nx2 numpy array (Python interface)
-
- :param triangle: Output vector of three 2D points defining the vertices of the triangle. The depth of the OutputArray must be ``CV_32F``.
-
-The function finds a triangle of minimum area enclosing the given set of 2D points and returns its area. The output for a given 2D point set is shown in the image below. 2D points are depicted in *red* and the enclosing triangle in *yellow*.
-
-.. image:: pics/minenclosingtriangle.png
- :height: 250px
- :width: 250px
- :alt: Sample output of the minimum enclosing triangle function
-
-The implementation of the algorithm is based on O'Rourke's [ORourke86]_ and Klee and Laskowski's [KleeLaskowski85]_ papers. O'Rourke provides a
-:math:`\theta(n)`
-algorithm for finding the minimal enclosing triangle of a 2D convex polygon with ``n`` vertices. Since the :ocv:func:`minEnclosingTriangle` function takes a 2D point set as input an additional preprocessing step of computing the convex hull of the 2D point set is required. The complexity of the :ocv:func:`convexHull` function is
-:math:`O(n log(n))` which is higher than
-:math:`\theta(n)`.
-Thus the overall complexity of the function is
-:math:`O(n log(n))`.
-
-.. note:: See ``opencv_source/samples/cpp/minarea.cpp`` for a usage example.
-
-
-
-minEnclosingCircle
-----------------------
-Finds a circle of the minimum area enclosing a 2D point set.
-
-.. ocv:function:: void minEnclosingCircle( InputArray points, Point2f& center, float& radius )
-
-.. ocv:pyfunction:: cv2.minEnclosingCircle(points) -> center, radius
-
-.. ocv:cfunction:: int cvMinEnclosingCircle( const CvArr* points, CvPoint2D32f* center, float* radius )
-
- :param points: Input vector of 2D points, stored in:
-
- * ``std::vector<>`` or ``Mat`` (C++ interface)
-
- * ``CvSeq*`` or ``CvMat*`` (C interface)
-
- * Nx2 numpy array (Python interface)
-
- :param center: Output center of the circle.
-
- :param radius: Output radius of the circle.
-
-The function finds the minimal enclosing circle of a 2D point set using an iterative algorithm. See the OpenCV sample ``minarea.cpp`` .
-
-
-
-matchShapes
----------------
-Compares two shapes.
-
-.. ocv:function:: double matchShapes( InputArray contour1, InputArray contour2, int method, double parameter )
-
-.. ocv:pyfunction:: cv2.matchShapes(contour1, contour2, method, parameter) -> retval
-
-.. ocv:cfunction:: double cvMatchShapes( const void* object1, const void* object2, int method, double parameter=0 )
-
- :param object1: First contour or grayscale image.
-
- :param object2: Second contour or grayscale image.
-
- :param method: Comparison method: ``CV_CONTOURS_MATCH_I1`` , \ ``CV_CONTOURS_MATCH_I2`` \
- or ``CV_CONTOURS_MATCH_I3`` (see the details below).
-
- :param parameter: Method-specific parameter (not supported now).
-
-The function compares two shapes. All three implemented methods use the Hu invariants (see
-:ocv:func:`HuMoments` ) as follows (
-:math:`A` denotes ``object1``,:math:`B` denotes ``object2`` ):
-
-* method=CV_CONTOURS_MATCH_I1
-
- .. math::
-
- I_1(A,B) = \sum _{i=1...7} \left | \frac{1}{m^A_i} - \frac{1}{m^B_i} \right |
-
-* method=CV_CONTOURS_MATCH_I2
-
- .. math::
-
- I_2(A,B) = \sum _{i=1...7} \left | m^A_i - m^B_i \right |
-
-* method=CV_CONTOURS_MATCH_I3
-
- .. math::
-
- I_3(A,B) = \max _{i=1...7} \frac{ \left| m^A_i - m^B_i \right| }{ \left| m^A_i \right| }
-
-where
-
-.. math::
-
- \begin{array}{l} m^A_i = \mathrm{sign} (h^A_i) \cdot \log{h^A_i} \\ m^B_i = \mathrm{sign} (h^B_i) \cdot \log{h^B_i} \end{array}
-
-and
-:math:`h^A_i, h^B_i` are the Hu moments of
-:math:`A` and
-:math:`B` , respectively.
-
-
-
-pointPolygonTest
---------------------
-Performs a point-in-contour test.
-
-.. ocv:function:: double pointPolygonTest( InputArray contour, Point2f pt, bool measureDist )
-
-.. ocv:pyfunction:: cv2.pointPolygonTest(contour, pt, measureDist) -> retval
-
-.. ocv:cfunction:: double cvPointPolygonTest( const CvArr* contour, CvPoint2D32f pt, int measure_dist )
-
- :param contour: Input contour.
-
- :param pt: Point tested against the contour.
-
- :param measureDist: If true, the function estimates the signed distance from the point to the nearest contour edge. Otherwise, the function only checks if the point is inside a contour or not.
-
-The function determines whether the
-point is inside a contour, outside, or lies on an edge (or coincides
-with a vertex). It returns positive (inside), negative (outside), or zero (on an edge) value,
-correspondingly. When ``measureDist=false`` , the return value
-is +1, -1, and 0, respectively. Otherwise, the return value
-is a signed distance between the point and the nearest contour
-edge.
-
-See below a sample output of the function where each image pixel is tested against the contour.
-
-.. image:: pics/pointpolygon.png
-
-.. [Fitzgibbon95] Andrew W. Fitzgibbon, R.B.Fisher. *A Buyer's Guide to Conic Fitting*. Proc.5th British Machine Vision Conference, Birmingham, pp. 513-522, 1995.
-
-.. [Hu62] M. Hu. *Visual Pattern Recognition by Moment Invariants*, IRE Transactions on Information Theory, 8:2, pp. 179-187, 1962.
-
-.. [KleeLaskowski85] Klee, V. and Laskowski, M.C., *Finding the smallest triangles containing a given convex polygon*, Journal of Algorithms, vol. 6, no. 3, pp. 359-375 (1985)
-
-.. [ORourke86] O’Rourke, J., Aggarwal, A., Maddila, S., and Baldwin, M., *An optimal algorithm for finding minimal enclosing triangles*, Journal of Algorithms, vol. 7, no. 2, pp. 258-269 (1986)
-
-.. [Sklansky82] Sklansky, J., *Finding the Convex Hull of a Simple Polygon*. PRL 1 $number, pp 79-83 (1982)
-
-.. [Suzuki85] Suzuki, S. and Abe, K., *Topological Structural Analysis of Digitized Binary Images by Border Following*. CVGIP 30 1, pp 32-46 (1985)
-
-.. [TehChin89] Teh, C.H. and Chin, R.T., *On the Detection of Dominant Points on Digital Curve*. PAMI 11 8, pp 859-872 (1989)
-
-
-
-rotatedRectangleIntersection
--------------------------------
-Finds out if there is any intersection between two rotated rectangles. If there is then the vertices of the interesecting region are returned as well.
-
-.. ocv:function:: int rotatedRectangleIntersection( const RotatedRect& rect1, const RotatedRect& rect2, OutputArray intersectingRegion )
-.. ocv:pyfunction:: cv2.rotatedRectangleIntersection( rect1, rect2 ) -> retval, intersectingRegion
-
- :param rect1: First rectangle
-
- :param rect2: Second rectangle
-
- :param intersectingRegion: The output array of the verticies of the intersecting region. It returns at most 8 vertices. Stored as ``std::vector<cv::Point2f>`` or ``cv::Mat`` as Mx1 of type CV_32FC2.
-
- :param pointCount: The number of vertices.
-
-The following values are returned by the function:
-
- * INTERSECT_NONE=0 - No intersection
-
- * INTERSECT_PARTIAL=1 - There is a partial intersection
-
- * INTERSECT_FULL=2 - One of the rectangle is fully enclosed in the other
-
-Below are some examples of intersection configurations. The hatched pattern indicates the intersecting region and the red vertices are returned by the function.
-
-.. image:: pics/intersection.png
+++ /dev/null
-.. _Boosting:
-
-Boosting
-========
-
-.. highlight:: cpp
-
-A common machine learning task is supervised learning. In supervised learning, the goal is to learn the functional relationship
-:math:`F: y = F(x)` between the input
-:math:`x` and the output
-:math:`y` . Predicting the qualitative output is called *classification*, while predicting the quantitative output is called *regression*.
-
-Boosting is a powerful learning concept that provides a solution to the supervised classification learning task. It combines the performance of many "weak" classifiers to produce a powerful committee [HTF01]_. A weak classifier is only required to be better than chance, and thus can be very simple and computationally inexpensive. However, many of them smartly combine results to a strong classifier that often outperforms most "monolithic" strong classifiers such as SVMs and Neural Networks.
-
-Decision trees are the most popular weak classifiers used in boosting schemes. Often the simplest decision trees with only a single split node per tree (called ``stumps`` ) are sufficient.
-
-The boosted model is based on
-:math:`N` training examples
-:math:`{(x_i,y_i)}1N` with
-:math:`x_i \in{R^K}` and
-:math:`y_i \in{-1, +1}` .
-:math:`x_i` is a
-:math:`K` -component vector. Each component encodes a feature relevant to the learning task at hand. The desired two-class output is encoded as -1 and +1.
-
-Different variants of boosting are known as Discrete Adaboost, Real AdaBoost, LogitBoost, and Gentle AdaBoost [FHT98]_. All of them are very similar in their overall structure. Therefore, this chapter focuses only on the standard two-class Discrete AdaBoost algorithm, outlined below. Initially the same weight is assigned to each sample (step 2). Then, a weak classifier
-:math:`f_{m(x)}` is trained on the weighted training data (step 3a). Its weighted training error and scaling factor
-:math:`c_m` is computed (step 3b). The weights are increased for training samples that have been misclassified (step 3c). All weights are then normalized, and the process of finding the next weak classifier continues for another
-:math:`M` -1 times. The final classifier
-:math:`F(x)` is the sign of the weighted sum over the individual weak classifiers (step 4).
-
-**Two-class Discrete AdaBoost Algorithm**
-
-#.
- Set
- :math:`N` examples
- :math:`{(x_i,y_i)}1N` with
- :math:`x_i \in{R^K}, y_i \in{-1, +1}` .
-
-#.
- Assign weights as
- :math:`w_i = 1/N, i = 1,...,N` .
-
-#.
- Repeat for :math:`m = 1,2,...,M` :
-
- 3.1. Fit the classifier :math:`f_m(x) \in{-1,1}`, using weights :math:`w_i` on the training data.
-
- 3.2. Compute :math:`err_m = E_w [1_{(y \neq f_m(x))}], c_m = log((1 - err_m)/err_m)` .
-
- 3.3. Set :math:`w_i \Leftarrow w_i exp[c_m 1_{(y_i \neq f_m(x_i))}], i = 1,2,...,N,` and renormalize so that :math:`\Sigma i w_i = 1` .
-
-
-#. Classify new samples *x* using the formula: :math:`\textrm{sign} (\Sigma m = 1M c_m f_m(x))` .
-
-
-.. note:: Similar to the classical boosting methods, the current implementation supports two-class classifiers only. For ``M > 2`` classes, there is the **AdaBoost.MH** algorithm (described in [FHT98]_) that reduces the problem to the two-class problem, yet with a much larger training set.
-
-To reduce computation time for boosted models without substantially losing accuracy, the influence trimming technique can be employed. As the training algorithm proceeds and the number of trees in the ensemble is increased, a larger number of the training samples are classified correctly and with increasing confidence, thereby those samples receive smaller weights on the subsequent iterations. Examples with a very low relative weight have a small impact on the weak classifier training. Thus, such examples may be excluded during the weak classifier training without having much effect on the induced classifier. This process is controlled with the ``weight_trim_rate`` parameter. Only examples with the summary fraction ``weight_trim_rate`` of the total weight mass are used in the weak classifier training. Note that the weights for
-**all**
-training examples are recomputed at each training iteration. Examples deleted at a particular iteration may be used again for learning some of the weak classifiers further [FHT98]_.
-
-.. [HTF01] Hastie, T., Tibshirani, R., Friedman, J. H. *The Elements of Statistical Learning: Data Mining, Inference, and Prediction. Springer Series in Statistics*. 2001.
-
-.. [FHT98] Friedman, J. H., Hastie, T. and Tibshirani, R. Additive Logistic Regression: a Statistical View of Boosting. Technical Report, Dept. of Statistics*, Stanford University, 1998.
-
-Boost::Params
--------------
-.. ocv:struct:: Boost::Params : public DTree::Params
-
- Boosting training parameters.
-
-The structure is derived from ``DTrees::Params`` but not all of the decision tree parameters are supported. In particular, cross-validation is not supported.
-
-All parameters are public. You can initialize them by a constructor and then override some of them directly if you want.
-
-Boost::Params::Params
-----------------------------
-The constructors.
-
-.. ocv:function:: Boost::Params::Params()
-
-.. ocv:function:: Boost::Params::Params( int boostType, int weakCount, double weightTrimRate, int maxDepth, bool useSurrogates, const Mat& priors )
-
- :param boost_type: Type of the boosting algorithm. Possible values are:
-
- * **Boost::DISCRETE** Discrete AdaBoost.
- * **Boost::REAL** Real AdaBoost. It is a technique that utilizes confidence-rated predictions and works well with categorical data.
- * **Boost::LOGIT** LogitBoost. It can produce good regression fits.
- * **Boost::GENTLE** Gentle AdaBoost. It puts less weight on outlier data points and for that reason is often good with regression data.
-
- Gentle AdaBoost and Real AdaBoost are often the preferable choices.
-
- :param weak_count: The number of weak classifiers.
-
- :param weight_trim_rate: A threshold between 0 and 1 used to save computational time. Samples with summary weight :math:`\leq 1 - weight\_trim\_rate` do not participate in the *next* iteration of training. Set this parameter to 0 to turn off this functionality.
-
-See ``DTrees::Params`` for description of other parameters.
-
-Default parameters are:
-
-::
-
- Boost::Params::Params()
- {
- boostType = Boost::REAL;
- weakCount = 100;
- weightTrimRate = 0.95;
- CVFolds = 0;
- maxDepth = 1;
- }
-
-Boost
--------
-.. ocv:class:: Boost : public DTrees
-
-Boosted tree classifier derived from ``DTrees``
-
-Boost::create
-----------------
-Creates the empty model
-
-.. ocv:function:: Ptr<Boost> Boost::create(const Params& params=Params())
-
-Use ``StatModel::train`` to train the model, ``StatModel::train<Boost>(traindata, params)`` to create and train the model, ``StatModel::load<Boost>(filename)`` to load the pre-trained model.
-
-Boost::getBParams
------------------
-Returns the boosting parameters
-
-.. ocv:function:: Params Boost::getBParams() const
-
-The method returns the training parameters.
-
-Boost::setBParams
------------------
-Sets the boosting parameters
-
-.. ocv:function:: void Boost::setBParams( const Params& p )
-
- :param p: Training parameters of type Boost::Params.
-
-The method sets the training parameters.
-
-Prediction with Boost
----------------------
-
-StatModel::predict(samples, results, flags) should be used. Pass ``flags=StatModel::RAW_OUTPUT`` to get the raw sum from Boost classifier.
+++ /dev/null
-Decision Trees
-==============
-
-The ML classes discussed in this section implement Classification and Regression Tree algorithms described in [Breiman84]_.
-
-The class ``cv::ml::DTrees`` represents a single decision tree or a collection of decision trees. It's also a base class for ``RTrees`` and ``Boost``.
-
-A decision tree is a binary tree (tree where each non-leaf node has two child nodes). It can be used either for classification or for regression. For classification, each tree leaf is marked with a class label; multiple leaves may have the same label. For regression, a constant is also assigned to each tree leaf, so the approximation function is piecewise constant.
-
-Predicting with Decision Trees
-------------------------------
-
-To reach a leaf node and to obtain a response for the input feature
-vector, the prediction procedure starts with the root node. From each
-non-leaf node the procedure goes to the left (selects the left
-child node as the next observed node) or to the right based on the
-value of a certain variable whose index is stored in the observed
-node. The following variables are possible:
-
-*
- **Ordered variables.** The variable value is compared with a threshold that is also stored in the node. If the value is less than the threshold, the procedure goes to the left. Otherwise, it goes to the right. For example, if the weight is less than 1 kilogram, the procedure goes to the left, else to the right.
-*
- **Categorical variables.** A discrete variable value is tested to see whether it belongs to a certain subset of values (also stored in the node) from a limited set of values the variable could take. If it does, the procedure goes to the left. Otherwise, it goes to the right. For example, if the color is green or red, go to the left, else to the right.
-
-So, in each node, a pair of entities (``variable_index`` , ``decision_rule
-(threshold/subset)`` ) is used. This pair is called a *split* (split on
-the variable ``variable_index`` ). Once a leaf node is reached, the value
-assigned to this node is used as the output of the prediction procedure.
-
-Sometimes, certain features of the input vector are missed (for example, in the darkness it is difficult to determine the object color), and the prediction procedure may get stuck in the certain node (in the mentioned example, if the node is split by color). To avoid such situations, decision trees use so-called *surrogate splits*. That is, in addition to the best "primary" split, every tree node may also be split to one or more other variables with nearly the same results.
-
-Training Decision Trees
------------------------
-
-The tree is built recursively, starting from the root node. All training data (feature vectors and responses) is used to split the root node. In each node the optimum decision rule (the best "primary" split) is found based on some criteria. In machine learning, ``gini`` "purity" criteria are used for classification, and sum of squared errors is used for regression. Then, if necessary, the surrogate splits are found. They resemble the results of the primary split on the training data. All the data is divided using the primary and the surrogate splits (like it is done in the prediction procedure) between the left and the right child node. Then, the procedure recursively splits both left and right nodes. At each node the recursive procedure may stop (that is, stop splitting the node further) in one of the following cases:
-
-* Depth of the constructed tree branch has reached the specified maximum value.
-
-* Number of training samples in the node is less than the specified threshold when it is not statistically representative to split the node further.
-
-* All the samples in the node belong to the same class or, in case of regression, the variation is too small.
-
-* The best found split does not give any noticeable improvement compared to a random choice.
-
-When the tree is built, it may be pruned using a cross-validation procedure, if necessary. That is, some branches of the tree that may lead to the model overfitting are cut off. Normally, this procedure is only applied to standalone decision trees. Usually tree ensembles build trees that are small enough and use their own protection schemes against overfitting.
-
-Variable Importance
--------------------
-
-Besides the prediction that is an obvious use of decision trees, the tree can be also used for various data analyses. One of the key properties of the constructed decision tree algorithms is an ability to compute the importance (relative decisive power) of each variable. For example, in a spam filter that uses a set of words occurred in the message as a feature vector, the variable importance rating can be used to determine the most "spam-indicating" words and thus help keep the dictionary size reasonable.
-
-Importance of each variable is computed over all the splits on this variable in the tree, primary and surrogate ones. Thus, to compute variable importance correctly, the surrogate splits must be enabled in the training parameters, even if there is no missing data.
-
-
-DTrees::Split
--------------
-.. ocv:class:: DTrees::Split
-
- The class represents split in a decision tree. It has public members:
-
- .. ocv:member:: int varIdx
-
- Index of variable on which the split is created.
-
- .. ocv:member:: bool inversed
-
- If true, then the inverse split rule is used (i.e. left and right branches are exchanged in the rule expressions below).
-
- .. ocv:member:: float quality
-
- The split quality, a positive number. It is used to choose the best split.
-
- .. ocv:member:: int next
-
- Index of the next split in the list of splits for the node
-
- .. ocv:member:: float c
-
- The threshold value in case of split on an ordered variable. The rule is: ::
-
- if var_value < c
- then next_node<-left
- else next_node<-right
-
- .. ocv:member:: int subsetOfs
-
- Offset of the bitset used by the split on a categorical variable. The rule is: ::
-
- if bitset[var_value] == 1
- then next_node <- left
- else next_node <- right
-
-DTrees::Node
-------------
-.. ocv:class:: DTrees::Node
-
- The class represents a decision tree node. It has public members:
-
- .. ocv:member:: double value
-
- Value at the node: a class label in case of classification or estimated function value in case of regression.
-
- .. ocv:member:: int classIdx
-
- Class index normalized to 0..class_count-1 range and assigned to the node. It is used internally in classification trees and tree ensembles.
-
- .. ocv:member:: int parent
-
- Index of the parent node
-
- .. ocv:member:: int left
-
- Index of the left child node
-
- .. ocv:member:: int right
-
- Index of right child node.
-
- .. ocv:member:: int defaultDir
-
- Default direction where to go (-1: left or +1: right). It helps in the case of missing values.
-
- .. ocv:member:: int split
-
- Index of the first split
-
-DTrees::Params
----------------
-.. ocv:class:: DTrees::Params
-
-The structure contains all the decision tree training parameters. You can initialize it by default constructor and then override any parameters directly before training, or the structure may be fully initialized using the advanced variant of the constructor.
-
-DTrees::Params::Params
-----------------------------
-The constructors
-
-.. ocv:function:: DTrees::Params::Params()
-
-.. ocv:function:: DTrees::Params::Params( int maxDepth, int minSampleCount, double regressionAccuracy, bool useSurrogates, int maxCategories, int CVFolds, bool use1SERule, bool truncatePrunedTree, const Mat& priors )
-
- :param maxDepth: The maximum possible depth of the tree. That is the training algorithms attempts to split a node while its depth is less than ``maxDepth``. The root node has zero depth. The actual depth may be smaller if the other termination criteria are met (see the outline of the training procedure in the beginning of the section), and/or if the tree is pruned.
-
- :param minSampleCount: If the number of samples in a node is less than this parameter then the node will not be split.
-
- :param regressionAccuracy: Termination criteria for regression trees. If all absolute differences between an estimated value in a node and values of train samples in this node are less than this parameter then the node will not be split further.
-
- :param useSurrogates: If true then surrogate splits will be built. These splits allow to work with missing data and compute variable importance correctly. .. note:: currently it's not implemented.
-
- :param maxCategories: Cluster possible values of a categorical variable into ``K<=maxCategories`` clusters to find a suboptimal split. If a discrete variable, on which the training procedure tries to make a split, takes more than ``maxCategories`` values, the precise best subset estimation may take a very long time because the algorithm is exponential. Instead, many decision trees engines (including our implementation) try to find sub-optimal split in this case by clustering all the samples into ``maxCategories`` clusters that is some categories are merged together. The clustering is applied only in ``n > 2``-class classification problems for categorical variables with ``N > max_categories`` possible values. In case of regression and 2-class classification the optimal split can be found efficiently without employing clustering, thus the parameter is not used in these cases.
-
- :param CVFolds: If ``CVFolds > 1`` then algorithms prunes the built decision tree using ``K``-fold cross-validation procedure where ``K`` is equal to ``CVFolds``.
-
- :param use1SERule: If true then a pruning will be harsher. This will make a tree more compact and more resistant to the training data noise but a bit less accurate.
-
- :param truncatePrunedTree: If true then pruned branches are physically removed from the tree. Otherwise they are retained and it is possible to get results from the original unpruned (or pruned less aggressively) tree.
-
- :param priors: The array of a priori class probabilities, sorted by the class label value. The parameter can be used to tune the decision tree preferences toward a certain class. For example, if you want to detect some rare anomaly occurrence, the training base will likely contain much more normal cases than anomalies, so a very good classification performance will be achieved just by considering every case as normal. To avoid this, the priors can be specified, where the anomaly probability is artificially increased (up to 0.5 or even greater), so the weight of the misclassified anomalies becomes much bigger, and the tree is adjusted properly. You can also think about this parameter as weights of prediction categories which determine relative weights that you give to misclassification. That is, if the weight of the first category is 1 and the weight of the second category is 10, then each mistake in predicting the second category is equivalent to making 10 mistakes in predicting the first category.
-
-The default constructor initializes all the parameters with the default values tuned for the standalone classification tree:
-
-::
-
- DTrees::Params::Params()
- {
- maxDepth = INT_MAX;
- minSampleCount = 10;
- regressionAccuracy = 0.01f;
- useSurrogates = false;
- maxCategories = 10;
- CVFolds = 10;
- use1SERule = true;
- truncatePrunedTree = true;
- priors = Mat();
- }
-
-
-DTrees
-------
-
-.. ocv:class:: DTrees : public StatModel
-
-The class represents a single decision tree or a collection of decision trees. The current public interface of the class allows user to train only a single decision tree, however the class is capable of storing multiple decision trees and using them for prediction (by summing responses or using a voting schemes), and the derived from DTrees classes (such as ``RTrees`` and ``Boost``) use this capability to implement decision tree ensembles.
-
-DTrees::create
-----------------
-Creates the empty model
-
-.. ocv:function:: Ptr<DTrees> DTrees::create(const Params& params=Params())
-
-The static method creates empty decision tree with the specified parameters. It should be then trained using ``train`` method (see ``StatModel::train``). Alternatively, you can load the model from file using ``StatModel::load<DTrees>(filename)``.
-
-DTrees::getDParams
-------------------
-Returns the training parameters
-
-.. ocv:function:: Params DTrees::getDParams() const
-
-The method returns the training parameters.
-
-DTrees::setDParams
--------------------
-Sets the training parameters
-
-.. ocv:function:: void DTrees::setDParams( const Params& p )
-
- :param p: Training parameters of type DTrees::Params.
-
-The method sets the training parameters.
-
-
-DTrees::getRoots
--------------------
-Returns indices of root nodes
-
-.. ocv:function:: std::vector<int>& DTrees::getRoots() const
-
-DTrees::getNodes
--------------------
-Returns all the nodes
-
-.. ocv:function:: std::vector<Node>& DTrees::getNodes() const
-
-all the node indices, mentioned above (left, right, parent, root indices) are indices in the returned vector
-
-DTrees::getSplits
--------------------
-Returns all the splits
-
-.. ocv:function:: std::vector<Split>& DTrees::getSplits() const
-
-all the split indices, mentioned above (split, next etc.) are indices in the returned vector
-
-DTrees::getSubsets
--------------------
-Returns all the bitsets for categorical splits
-
-.. ocv:function:: std::vector<int>& DTrees::getSubsets() const
-
-``Split::subsetOfs`` is an offset in the returned vector
-
-.. [Breiman84] Breiman, L., Friedman, J. Olshen, R. and Stone, C. (1984), *Classification and Regression Trees*, Wadsworth.
+++ /dev/null
-
-.. _ML_Expectation Maximization:
-
-
-Expectation Maximization
-========================
-
-.. highlight:: cpp
-
-The Expectation Maximization(EM) algorithm estimates the parameters of the multivariate probability density function in the form of a Gaussian mixture distribution with a specified number of mixtures.
-
-Consider the set of the N feature vectors
-{ :math:`x_1, x_2,...,x_{N}` } from a d-dimensional Euclidean space drawn from a Gaussian mixture:
-
-.. math::
-
- p(x;a_k,S_k, \pi _k) = \sum _{k=1}^{m} \pi _kp_k(x), \quad \pi _k \geq 0, \quad \sum _{k=1}^{m} \pi _k=1,
-
-.. math::
-
- p_k(x)= \varphi (x;a_k,S_k)= \frac{1}{(2\pi)^{d/2}\mid{S_k}\mid^{1/2}} exp \left \{ - \frac{1}{2} (x-a_k)^TS_k^{-1}(x-a_k) \right \} ,
-
-where
-:math:`m` is the number of mixtures,
-:math:`p_k` is the normal distribution
-density with the mean
-:math:`a_k` and covariance matrix
-:math:`S_k`,
-:math:`\pi_k` is the weight of the k-th mixture. Given the number of mixtures
-:math:`M` and the samples
-:math:`x_i`,
-:math:`i=1..N` the algorithm finds the
-maximum-likelihood estimates (MLE) of all the mixture parameters,
-that is,
-:math:`a_k`,
-:math:`S_k` and
-:math:`\pi_k` :
-
-.. math::
-
- L(x, \theta )=logp(x, \theta )= \sum _{i=1}^{N}log \left ( \sum _{k=1}^{m} \pi _kp_k(x) \right ) \to \max _{ \theta \in \Theta },
-
-.. math::
-
- \Theta = \left \{ (a_k,S_k, \pi _k): a_k \in \mathbbm{R} ^d,S_k=S_k^T>0,S_k \in \mathbbm{R} ^{d \times d}, \pi _k \geq 0, \sum _{k=1}^{m} \pi _k=1 \right \} .
-
-The EM algorithm is an iterative procedure. Each iteration includes
-two steps. At the first step (Expectation step or E-step), you find a
-probability
-:math:`p_{i,k}` (denoted
-:math:`\alpha_{i,k}` in the formula below) of
-sample ``i`` to belong to mixture ``k`` using the currently
-available mixture parameter estimates:
-
-.. math::
-
- \alpha _{ki} = \frac{\pi_k\varphi(x;a_k,S_k)}{\sum\limits_{j=1}^{m}\pi_j\varphi(x;a_j,S_j)} .
-
-At the second step (Maximization step or M-step), the mixture parameter estimates are refined using the computed probabilities:
-
-.. math::
-
- \pi _k= \frac{1}{N} \sum _{i=1}^{N} \alpha _{ki}, \quad a_k= \frac{\sum\limits_{i=1}^{N}\alpha_{ki}x_i}{\sum\limits_{i=1}^{N}\alpha_{ki}} , \quad S_k= \frac{\sum\limits_{i=1}^{N}\alpha_{ki}(x_i-a_k)(x_i-a_k)^T}{\sum\limits_{i=1}^{N}\alpha_{ki}}
-
-Alternatively, the algorithm may start with the M-step when the initial values for
-:math:`p_{i,k}` can be provided. Another alternative when
-:math:`p_{i,k}` are unknown is to use a simpler clustering algorithm to pre-cluster the input samples and thus obtain initial
-:math:`p_{i,k}` . Often (including machine learning) the
-``k-means`` algorithm is used for that purpose.
-
-One of the main problems of the EM algorithm is a large number
-of parameters to estimate. The majority of the parameters reside in
-covariance matrices, which are
-:math:`d \times d` elements each
-where
-:math:`d` is the feature space dimensionality. However, in
-many practical problems, the covariance matrices are close to diagonal
-or even to
-:math:`\mu_k*I` , where
-:math:`I` is an identity matrix and
-:math:`\mu_k` is a mixture-dependent "scale" parameter. So, a robust computation
-scheme could start with harder constraints on the covariance
-matrices and then use the estimated parameters as an input for a less
-constrained optimization problem (often a diagonal covariance matrix is
-already a good enough approximation).
-
-**References:**
-
-*
- Bilmes98 J. A. Bilmes. *A Gentle Tutorial of the EM Algorithm and its Application to Parameter Estimation for Gaussian Mixture and Hidden Markov Models*. Technical Report TR-97-021, International Computer Science Institute and Computer Science Division, University of California at Berkeley, April 1998.
-
-EM
---
-.. ocv:class:: EM : public StatModel
-
-The class implements the EM algorithm as described in the beginning of this section.
-
-EM::Params
-----------
-.. ocv:class:: EM::Params
-
-The class describes EM training parameters.
-
-EM::Params::Params
-------------------
-The constructor
-
-.. ocv:function:: EM::Params::Params( int nclusters=DEFAULT_NCLUSTERS, int covMatType=EM::COV_MAT_DIAGONAL,const TermCriteria& termCrit=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, EM::DEFAULT_MAX_ITERS, 1e-6))
-
- :param nclusters: The number of mixture components in the Gaussian mixture model. Default value of the parameter is ``EM::DEFAULT_NCLUSTERS=5``. Some of EM implementation could determine the optimal number of mixtures within a specified value range, but that is not the case in ML yet.
-
- :param covMatType: Constraint on covariance matrices which defines type of matrices. Possible values are:
-
- * **EM::COV_MAT_SPHERICAL** A scaled identity matrix :math:`\mu_k * I`. There is the only parameter :math:`\mu_k` to be estimated for each matrix. The option may be used in special cases, when the constraint is relevant, or as a first step in the optimization (for example in case when the data is preprocessed with PCA). The results of such preliminary estimation may be passed again to the optimization procedure, this time with ``covMatType=EM::COV_MAT_DIAGONAL``.
-
- * **EM::COV_MAT_DIAGONAL** A diagonal matrix with positive diagonal elements. The number of free parameters is ``d`` for each matrix. This is most commonly used option yielding good estimation results.
-
- * **EM::COV_MAT_GENERIC** A symmetric positively defined matrix. The number of free parameters in each matrix is about :math:`d^2/2`. It is not recommended to use this option, unless there is pretty accurate initial estimation of the parameters and/or a huge number of training samples.
-
- :param termCrit: The termination criteria of the EM algorithm. The EM algorithm can be terminated by the number of iterations ``termCrit.maxCount`` (number of M-steps) or when relative change of likelihood logarithm is less than ``termCrit.epsilon``. Default maximum number of iterations is ``EM::DEFAULT_MAX_ITERS=100``.
-
-
-EM::create
-----------
-Creates empty EM model
-
-.. ocv:function:: Ptr<EM> EM::create(const Params& params=Params())
-
- :param params: EM parameters
-
-The model should be trained then using ``StatModel::train(traindata, flags)`` method. Alternatively, you can use one of the ``EM::train*`` methods or load it from file using ``StatModel::load<EM>(filename)``.
-
-EM::train
----------
-Static methods that estimate the Gaussian mixture parameters from a samples set
-
-.. ocv:function:: Ptr<EM> EM::train(InputArray samples, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray(), const Params& params=Params())
-
-.. ocv:function:: bool EM::train_startWithE(InputArray samples, InputArray means0, InputArray covs0=noArray(), InputArray weights0=noArray(), OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray(), const Params& params=Params())
-
-.. ocv:function:: bool EM::train_startWithM(InputArray samples, InputArray probs0, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray(), const Params& params=Params())
-
- :param samples: Samples from which the Gaussian mixture model will be estimated. It should be a one-channel matrix, each row of which is a sample. If the matrix does not have ``CV_64F`` type it will be converted to the inner matrix of such type for the further computing.
-
- :param means0: Initial means :math:`a_k` of mixture components. It is a one-channel matrix of :math:`nclusters \times dims` size. If the matrix does not have ``CV_64F`` type it will be converted to the inner matrix of such type for the further computing.
-
- :param covs0: The vector of initial covariance matrices :math:`S_k` of mixture components. Each of covariance matrices is a one-channel matrix of :math:`dims \times dims` size. If the matrices do not have ``CV_64F`` type they will be converted to the inner matrices of such type for the further computing.
-
- :param weights0: Initial weights :math:`\pi_k` of mixture components. It should be a one-channel floating-point matrix with :math:`1 \times nclusters` or :math:`nclusters \times 1` size.
-
- :param probs0: Initial probabilities :math:`p_{i,k}` of sample :math:`i` to belong to mixture component :math:`k`. It is a one-channel floating-point matrix of :math:`nsamples \times nclusters` size.
-
- :param logLikelihoods: The optional output matrix that contains a likelihood logarithm value for each sample. It has :math:`nsamples \times 1` size and ``CV_64FC1`` type.
-
- :param labels: The optional output "class label" for each sample: :math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (indices of the most probable mixture component for each sample). It has :math:`nsamples \times 1` size and ``CV_32SC1`` type.
-
- :param probs: The optional output matrix that contains posterior probabilities of each Gaussian mixture component given the each sample. It has :math:`nsamples \times nclusters` size and ``CV_64FC1`` type.
-
- :param params: The Gaussian mixture params, see ``EM::Params`` description above.
-
-Three versions of training method differ in the initialization of Gaussian mixture model parameters and start step:
-
-* **train** - Starts with Expectation step. Initial values of the model parameters will be estimated by the k-means algorithm.
-
-* **trainE** - Starts with Expectation step. You need to provide initial means :math:`a_k` of mixture components. Optionally you can pass initial weights :math:`\pi_k` and covariance matrices :math:`S_k` of mixture components.
-
-* **trainM** - Starts with Maximization step. You need to provide initial probabilities :math:`p_{i,k}` to use this option.
-
-The methods return ``true`` if the Gaussian mixture model was trained successfully, otherwise it returns ``false``.
-
-Unlike many of the ML models, EM is an unsupervised learning algorithm and it does not take responses (class labels or function values) as input. Instead, it computes the
-*Maximum Likelihood Estimate* of the Gaussian mixture parameters from an input sample set, stores all the parameters inside the structure:
-:math:`p_{i,k}` in ``probs``,
-:math:`a_k` in ``means`` ,
-:math:`S_k` in ``covs[k]``,
-:math:`\pi_k` in ``weights`` , and optionally computes the output "class label" for each sample:
-:math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (indices of the most probable mixture component for each sample).
-
-The trained model can be used further for prediction, just like any other classifier. The trained model is similar to the
-``NormalBayesClassifier``.
-
-EM::predict2
-------------
-Returns a likelihood logarithm value and an index of the most probable mixture component for the given sample.
-
-.. ocv:function:: Vec2d EM::predict2(InputArray sample, OutputArray probs=noArray()) const
-
- :param sample: A sample for classification. It should be a one-channel matrix of :math:`1 \times dims` or :math:`dims \times 1` size.
-
- :param probs: Optional output matrix that contains posterior probabilities of each component given the sample. It has :math:`1 \times nclusters` size and ``CV_64FC1`` type.
-
-The method returns a two-element ``double`` vector. Zero element is a likelihood logarithm value for the sample. First element is an index of the most probable mixture component for the given sample.
-
-
-EM::getMeans
-------------
-Returns the cluster centers (means of the Gaussian mixture)
-
-.. ocv:function:: Mat EM::getMeans() const
-
-Returns matrix with the number of rows equal to the number of mixtures and number of columns equal to the space dimensionality.
-
-
-EM::getWeights
---------------
-Returns weights of the mixtures
-
-.. ocv:function:: Mat EM::getWeights() const
-
-Returns vector with the number of elements equal to the number of mixtures.
-
-
-EM::getCovs
---------------
-Returns covariation matrices
-
-.. ocv:function:: void EM::getCovs(std::vector<Mat>& covs) const
-
-Returns vector of covariation matrices. Number of matrices is the number of gaussian mixtures, each matrix is a square floating-point matrix NxN, where N is the space dimensionality.
+++ /dev/null
-K-Nearest Neighbors
-===================
-
-.. highlight:: cpp
-
-The algorithm caches all training samples and predicts the response for a new sample by analyzing a certain number (**K**) of the nearest neighbors of the sample using voting, calculating weighted sum, and so on. The method is sometimes referred to as "learning by example" because for prediction it looks for the feature vector with a known response that is closest to the given vector.
-
-KNearest
-----------
-.. ocv:class:: KNearest : public StatModel
-
-The class implements K-Nearest Neighbors model as described in the beginning of this section.
-
-.. note::
-
- * (Python) An example of digit recognition using KNearest can be found at opencv_source/samples/python2/digits.py
- * (Python) An example of grid search digit recognition using KNearest can be found at opencv_source/samples/python2/digits_adjust.py
- * (Python) An example of video digit recognition using KNearest can be found at opencv_source/samples/python2/digits_video.py
-
-KNearest::create
-----------------------
-Creates the empty model
-
-.. ocv:function:: Ptr<KNearest> KNearest::create(const Params& params=Params())
-
- :param params: The model parameters: default number of neighbors to use in predict method (in ``KNearest::findNearest`` this number must be passed explicitly) and the flag on whether classification or regression model should be trained.
-
-The static method creates empty KNearest classifier. It should be then trained using ``train`` method (see ``StatModel::train``). Alternatively, you can load boost model from file using ``StatModel::load<KNearest>(filename)``.
-
-
-KNearest::findNearest
-------------------------
-Finds the neighbors and predicts responses for input vectors.
-
-.. ocv:function:: float KNearest::findNearest( InputArray samples, int k, OutputArray results, OutputArray neighborResponses=noArray(), OutputArray dist=noArray() ) const
-
- :param samples: Input samples stored by rows. It is a single-precision floating-point matrix of ``<number_of_samples> * k`` size.
-
- :param k: Number of used nearest neighbors. Should be greater than 1.
-
- :param results: Vector with results of prediction (regression or classification) for each input sample. It is a single-precision floating-point vector with ``<number_of_samples>`` elements.
-
- :param neighborResponses: Optional output values for corresponding neighbors. It is a single-precision floating-point matrix of ``<number_of_samples> * k`` size.
-
- :param dist: Optional output distances from the input vectors to the corresponding neighbors. It is a single-precision floating-point matrix of ``<number_of_samples> * k`` size.
-
-For each input vector (a row of the matrix ``samples``), the method finds the ``k`` nearest neighbors. In case of regression, the predicted result is a mean value of the particular vector's neighbor responses. In case of classification, the class is determined by voting.
-
-For each input vector, the neighbors are sorted by their distances to the vector.
-
-In case of C++ interface you can use output pointers to empty matrices and the function will allocate memory itself.
-
-If only a single input vector is passed, all output matrices are optional and the predicted value is returned by the method.
-
-The function is parallelized with the TBB library.
-
-KNearest::getDefaultK
----------------------
-Returns the default number of neighbors
-
-.. ocv:function:: int KNearest::getDefaultK() const
-
-The function returns the default number of neighbors that is used in a simpler ``predict`` method, not ``findNearest``.
-
-KNearest::setDefaultK
----------------------
-Returns the default number of neighbors
-
-.. ocv:function:: void KNearest::setDefaultK(int k)
-
-The function sets the default number of neighbors that is used in a simpler ``predict`` method, not ``findNearest``.
+++ /dev/null
-Logistic Regression
-===================
-
-.. highlight:: cpp
-
-ML implements logistic regression, which is a probabilistic classification technique. Logistic Regression is a binary classification algorithm which is closely related to Support Vector Machines (SVM).
-Like SVM, Logistic Regression can be extended to work on multi-class classification problems like digit recognition (i.e. recognizing digitis like 0,1 2, 3,... from the given images).
-This version of Logistic Regression supports both binary and multi-class classifications (for multi-class it creates a multiple 2-class classifiers).
-In order to train the logistic regression classifier, Batch Gradient Descent and Mini-Batch Gradient Descent algorithms are used (see [BatchDesWiki]_).
-Logistic Regression is a discriminative classifier (see [LogRegTomMitch]_ for more details). Logistic Regression is implemented as a C++ class in ``LogisticRegression``.
-
-
-In Logistic Regression, we try to optimize the training paramater
-:math:`\theta`
-such that the hypothesis
-:math:`0 \leq h_\theta(x) \leq 1` is acheived.
-We have
-:math:`h_\theta(x) = g(h_\theta(x))`
-and
-:math:`g(z) = \frac{1}{1+e^{-z}}`
-as the logistic or sigmoid function.
-The term "Logistic" in Logistic Regression refers to this function.
-For given data of a binary classification problem of classes 0 and 1,
-one can determine that the given data instance belongs to class 1 if
-:math:`h_\theta(x) \geq 0.5`
-or class 0 if
-:math:`h_\theta(x) < 0.5`
-.
-
-In Logistic Regression, choosing the right parameters is of utmost importance for reducing the training error and ensuring high training accuracy.
-``LogisticRegression::Params`` is the structure that defines parameters that are required to train a Logistic Regression classifier.
-The learning rate is determined by ``LogisticRegression::Params.alpha``. It determines how faster we approach the solution.
-It is a positive real number. Optimization algorithms like Batch Gradient Descent and Mini-Batch Gradient Descent are supported in ``LogisticRegression``.
-It is important that we mention the number of iterations these optimization algorithms have to run.
-The number of iterations are mentioned by ``LogisticRegression::Params.num_iters``.
-The number of iterations can be thought as number of steps taken and learning rate specifies if it is a long step or a short step. These two parameters define how fast we arrive at a possible solution.
-In order to compensate for overfitting regularization is performed, which can be enabled by setting ``LogisticRegression::Params.regularized`` to a positive integer (greater than zero).
-One can specify what kind of regularization has to be performed by setting ``LogisticRegression::Params.norm`` to ``LogisticRegression::REG_L1`` or ``LogisticRegression::REG_L2`` values.
-``LogisticRegression`` provides a choice of 2 training methods with Batch Gradient Descent or the Mini-Batch Gradient Descent. To specify this, set ``LogisticRegression::Params.train_method`` to either ``LogisticRegression::BATCH`` or ``LogisticRegression::MINI_BATCH``.
-If ``LogisticRegression::Params`` is set to ``LogisticRegression::MINI_BATCH``, the size of the mini batch has to be to a postive integer using ``LogisticRegression::Params.mini_batch_size``.
-
-A sample set of training parameters for the Logistic Regression classifier can be initialized as follows:
-
-::
-
- LogisticRegression::Params params;
- params.alpha = 0.5;
- params.num_iters = 10000;
- params.norm = LogisticRegression::REG_L2;
- params.regularized = 1;
- params.train_method = LogisticRegression::MINI_BATCH;
- params.mini_batch_size = 10;
-
-**References:**
-
-.. [LogRegWiki] http://en.wikipedia.org/wiki/Logistic_regression. Wikipedia article about the Logistic Regression algorithm.
-
-.. [RenMalik2003] Learning a Classification Model for Segmentation. Proc. CVPR, Nice, France (2003).
-
-.. [LogRegTomMitch] http://www.cs.cmu.edu/~tom/NewChapters.html. "Generative and Discriminative Classifiers: Naive Bayes and Logistic Regression" in Machine Learning, Tom Mitchell.
-
-.. [BatchDesWiki] http://en.wikipedia.org/wiki/Gradient_descent_optimization. Wikipedia article about Gradient Descent based optimization.
-
-LogisticRegression::Params
---------------------------
-.. ocv:struct:: LogisticRegression::Params
-
- Parameters of the Logistic Regression training algorithm. You can initialize the structure using a constructor or declaring the variable and initializing the the individual parameters.
-
- The training parameters for Logistic Regression:
-
- .. ocv:member:: double alpha
-
- The learning rate of the optimization algorithm. The higher the value, faster the rate and vice versa. If the value is too high, the learning algorithm may overshoot the optimal parameters and result in lower training accuracy. If the value is too low, the learning algorithm converges towards the optimal parameters very slowly. The value must a be a positive real number. You can experiment with different values with small increments as in 0.0001, 0.0003, 0.001, 0.003, 0.01, 0.03, 0.1, 0.3, ... and select the learning rate with less training error.
-
- .. ocv:member:: int num_iters
-
- The number of iterations required for the learing algorithm (Gradient Descent or Mini Batch Gradient Descent). It has to be a positive integer. You can try different number of iterations like in 100, 1000, 2000, 3000, 5000, 10000, .. so on.
-
- .. ocv:member:: int norm
-
- The type of normalization applied. It takes value ``LogisticRegression::L1`` or ``LogisticRegression::L2``.
-
- .. ocv:member:: int regularized
-
- It should be set to postive integer (greater than zero) in order to enable regularization.
-
- .. ocv:member:: int train_method
-
- The kind of training method used to train the classifier. It should be set to either ``LogisticRegression::BATCH`` or ``LogisticRegression::MINI_BATCH``.
-
- .. ocv:member:: int mini_batch_size
-
- If the training method is set to LogisticRegression::MINI_BATCH, it has to be set to positive integer. It can range from 1 to number of training samples.
-
- .. ocv:member:: cv::TermCriteria term_crit
-
- Sets termination criteria for training algorithm.
-
-LogisticRegression::Params::Params
-----------------------------------
-The constructors
-
-.. ocv:function:: LogisticRegression::Params::Params(double learning_rate = 0.001, int iters = 1000, int method = LogisticRegression::BATCH, int normlization = LogisticRegression::REG_L2, int reg = 1, int batch_size = 1)
-
- :param learning_rate: Specifies the learning rate.
-
- :param iters: Specifies the number of iterations.
-
- :param train_method: Specifies the kind of training method used. It should be set to either ``LogisticRegression::BATCH`` or ``LogisticRegression::MINI_BATCH``. If using ``LogisticRegression::MINI_BATCH``, set ``LogisticRegression::Params.mini_batch_size`` to a positive integer.
-
- :param normalization: Specifies the kind of regularization to be applied. ``LogisticRegression::REG_L1`` or ``LogisticRegression::REG_L2`` (L1 norm or L2 norm). To use this, set ``LogisticRegression::Params.regularized`` to a integer greater than zero.
-
- :param reg: To enable or disable regularization. Set to positive integer (greater than zero) to enable and to 0 to disable.
-
- :param mini_batch_size: Specifies the number of training samples taken in each step of Mini-Batch Gradient Descent. Will only be used if using ``LogisticRegression::MINI_BATCH`` training algorithm. It has to take values less than the total number of training samples.
-
-By initializing this structure, one can set all the parameters required for Logistic Regression classifier.
-
-LogisticRegression
-------------------
-
-.. ocv:class:: LogisticRegression : public StatModel
-
-Implements Logistic Regression classifier.
-
-LogisticRegression::create
---------------------------
-Creates empty model.
-
-.. ocv:function:: Ptr<LogisticRegression> LogisticRegression::create( const Params& params = Params() )
-
- :param params: The training parameters for the classifier of type ``LogisticRegression::Params``.
-
-Creates Logistic Regression model with parameters given.
-
-LogisticRegression::train
--------------------------
-Trains the Logistic Regression classifier and returns true if successful.
-
-.. ocv:function:: bool LogisticRegression::train( const Ptr<TrainData>& trainData, int flags=0 )
-
- :param trainData: Instance of ml::TrainData class holding learning data.
-
- :param flags: Not used.
-
-LogisticRegression::predict
----------------------------
-Predicts responses for input samples and returns a float type.
-
-.. ocv:function:: void LogisticRegression::predict( InputArray samples, OutputArray results=noArray(), int flags=0 ) const
-
- :param samples: The input data for the prediction algorithm. Matrix [m x n], where each row contains variables (features) of one object being classified. Should have data type ``CV_32F``.
-
- :param results: Predicted labels as a column matrix of type ``CV_32S``.
-
- :param flags: Not used.
-
-
-LogisticRegression::get_learnt_thetas
--------------------------------------
-This function returns the trained paramters arranged across rows. For a two class classifcation problem, it returns a row matrix.
-
-.. ocv:function:: Mat LogisticRegression::get_learnt_thetas() const
-
-It returns learnt paramters of the Logistic Regression as a matrix of type ``CV_32F``.
-
-LogisticRegression::read
-------------------------
-This function reads the trained LogisticRegression clasifier from disk.
-
-.. ocv:function:: void LogisticRegression::read(const FileNode& fn)
-
-LogisticRegression::write
--------------------------
-This function writes the trained LogisticRegression clasifier to disk.
-
-.. ocv:function:: void LogisticRegression::write(FileStorage& fs) const
+++ /dev/null
-********************
-ml. Machine Learning
-********************
-
-The Machine Learning Library (MLL) is a set of classes and functions for statistical classification, regression, and clustering of data.
-
-Most of the classification and regression algorithms are implemented as C++ classes. As the algorithms have different sets of features (like an ability to handle missing measurements or categorical input variables), there is a little common ground between the classes. This common ground is defined by the class `CvStatModel` that all the other ML classes are derived from.
-
-.. toctree::
- :maxdepth: 2
-
- statistical_models
- normal_bayes_classifier
- k_nearest_neighbors
- support_vector_machines
- decision_trees
- boosting
- random_trees
- expectation_maximization
- neural_networks
- logistic_regression
- mldata
+++ /dev/null
-Training Data
-===================
-
-.. highlight:: cpp
-
-In machine learning algorithms there is notion of training data. Training data includes several components:
-
-* A set of training samples. Each training sample is a vector of values (in Computer Vision it's sometimes referred to as feature vector). Usually all the vectors have the same number of components (features); OpenCV ml module assumes that. Each feature can be ordered (i.e. its values are floating-point numbers that can be compared with each other and strictly ordered, i.e. sorted) or categorical (i.e. its value belongs to a fixed set of values that can be integers, strings etc.).
-
-* Optional set of responses corresponding to the samples. Training data with no responses is used in unsupervised learning algorithms that learn structure of the supplied data based on distances between different samples. Training data with responses is used in supervised learning algorithms, which learn the function mapping samples to responses. Usually the responses are scalar values, ordered (when we deal with regression problem) or categorical (when we deal with classification problem; in this case the responses are often called "labels"). Some algorithms, most noticeably Neural networks, can handle not only scalar, but also multi-dimensional or vector responses.
-
-* Another optional component is the mask of missing measurements. Most algorithms require all the components in all the training samples be valid, but some other algorithms, such as decision tress, can handle the cases of missing measurements.
-
-* In the case of classification problem user may want to give different weights to different classes. This is useful, for example, when
- * user wants to shift prediction accuracy towards lower false-alarm rate or higher hit-rate.
- * user wants to compensate for significantly different amounts of training samples from different classes.
-
-* In addition to that, each training sample may be given a weight, if user wants the algorithm to pay special attention to certain training samples and adjust the training model accordingly.
-
-* Also, user may wish not to use the whole training data at once, but rather use parts of it, e.g. to do parameter optimization via cross-validation procedure.
-
-As you can see, training data can have rather complex structure; besides, it may be very big and/or not entirely available, so there is need to make abstraction for this concept. In OpenCV ml there is ``cv::ml::TrainData`` class for that.
-
-TrainData
----------
-.. ocv:class:: TrainData
-
-Class encapsulating training data. Please note that the class only specifies the interface of training data, but not implementation. All the statistical model classes in ml take Ptr<TrainData>. In other words, you can create your own class derived from ``TrainData`` and supply smart pointer to the instance of this class into ``StatModel::train``.
-
-TrainData::loadFromCSV
-----------------------
-Reads the dataset from a .csv file and returns the ready-to-use training data.
-
-.. ocv:function:: Ptr<TrainData> loadFromCSV(const String& filename, int headerLineCount, int responseStartIdx=-1, int responseEndIdx=-1, const String& varTypeSpec=String(), char delimiter=',', char missch='?')
-
- :param filename: The input file name
-
- :param headerLineCount: The number of lines in the beginning to skip; besides the header, the function also skips empty lines and lines staring with '#'
-
- :param responseStartIdx: Index of the first output variable. If -1, the function considers the last variable as the response
-
- :param responseEndIdx: Index of the last output variable + 1. If -1, then there is single response variable at ``responseStartIdx``.
-
- :param varTypeSpec: The optional text string that specifies the variables' types. It has the format ``ord[n1-n2,n3,n4-n5,...]cat[n6,n7-n8,...]``. That is, variables from n1 to n2 (inclusive range), n3, n4 to n5 ... are considered ordered and n6, n7 to n8 ... are considered as categorical. The range [n1..n2] + [n3] + [n4..n5] + ... + [n6] + [n7..n8] should cover all the variables. If varTypeSpec is not specified, then algorithm uses the following rules:
- 1. all input variables are considered ordered by default. If some column contains has non-numerical values, e.g. 'apple', 'pear', 'apple', 'apple', 'mango', the corresponding variable is considered categorical.
- 2. if there are several output variables, they are all considered as ordered. Error is reported when non-numerical values are used.
- 3. if there is a single output variable, then if its values are non-numerical or are all integers, then it's considered categorical. Otherwise, it's considered ordered.
-
- :param delimiter: The character used to separate values in each line.
-
- :param missch: The character used to specify missing measurements. It should not be a digit. Although it's a non-numerical value, it surely does not affect the decision of whether the variable ordered or categorical.
-
-TrainData::create
------------------
-Creates training data from in-memory arrays.
-
-.. ocv:function:: Ptr<TrainData> create(InputArray samples, int layout, InputArray responses, InputArray varIdx=noArray(), InputArray sampleIdx=noArray(), InputArray sampleWeights=noArray(), InputArray varType=noArray())
-
- :param samples: matrix of samples. It should have ``CV_32F`` type.
-
- :param layout: it's either ``ROW_SAMPLE``, which means that each training sample is a row of ``samples``, or ``COL_SAMPLE``, which means that each training sample occupies a column of ``samples``.
-
- :param responses: matrix of responses. If the responses are scalar, they should be stored as a single row or as a single column. The matrix should have type ``CV_32F`` or ``CV_32S`` (in the former case the responses are considered as ordered by default; in the latter case - as categorical)
-
- :param varIdx: vector specifying which variables to use for training. It can be an integer vector (``CV_32S``) containing 0-based variable indices or byte vector (``CV_8U``) containing a mask of active variables.
-
- :param sampleIdx: vector specifying which samples to use for training. It can be an integer vector (``CV_32S``) containing 0-based sample indices or byte vector (``CV_8U``) containing a mask of training samples.
-
- :param sampleWeights: optional vector with weights for each sample. It should have ``CV_32F`` type.
-
- :param varType: optional vector of type ``CV_8U`` and size <number_of_variables_in_samples> + <number_of_variables_in_responses>, containing types of each input and output variable. The ordered variables are denoted by value ``VAR_ORDERED``, and categorical - by ``VAR_CATEGORICAL``.
-
-
-TrainData::getTrainSamples
---------------------------
-Returns matrix of train samples
-
-.. ocv:function:: Mat TrainData::getTrainSamples(int layout=ROW_SAMPLE, bool compressSamples=true, bool compressVars=true) const
-
- :param layout: The requested layout. If it's different from the initial one, the matrix is transposed.
-
- :param compressSamples: if true, the function returns only the training samples (specified by sampleIdx)
-
- :param compressVars: if true, the function returns the shorter training samples, containing only the active variables.
-
-In current implementation the function tries to avoid physical data copying and returns the matrix stored inside TrainData (unless the transposition or compression is needed).
-
-
-TrainData::getTrainResponses
-----------------------------
-Returns the vector of responses
-
-.. ocv:function:: Mat TrainData::getTrainResponses() const
-
-The function returns ordered or the original categorical responses. Usually it's used in regression algorithms.
-
-
-TrainData::getClassLabels
-----------------------------
-Returns the vector of class labels
-
-.. ocv:function:: Mat TrainData::getClassLabels() const
-
-The function returns vector of unique labels occurred in the responses.
-
-
-TrainData::getTrainNormCatResponses
------------------------------------
-Returns the vector of normalized categorical responses
-
-.. ocv:function:: Mat TrainData::getTrainNormCatResponses() const
-
-The function returns vector of responses. Each response is integer from 0 to <number of classes>-1. The actual label value can be retrieved then from the class label vector, see ``TrainData::getClassLabels``.
-
-TrainData::setTrainTestSplitRatio
------------------------------------
-Splits the training data into the training and test parts
-
-.. ocv:function:: void TrainData::setTrainTestSplitRatio(double ratio, bool shuffle=true)
-
-The function selects a subset of specified relative size and then returns it as the training set. If the function is not called, all the data is used for training. Please, note that for each of ``TrainData::getTrain*`` there is corresponding ``TrainData::getTest*``, so that the test subset can be retrieved and processed as well.
-
-
-Other methods
--------------
-The class includes many other methods that can be used to access normalized categorical input variables, access training data by parts, so that does not have to fit into the memory etc.
+++ /dev/null
-Neural Networks
-===============
-
-.. highlight:: cpp
-
-ML implements feed-forward artificial neural networks or, more particularly, multi-layer perceptrons (MLP), the most commonly used type of neural networks. MLP consists of the input layer, output layer, and one or more hidden layers. Each layer of MLP includes one or more neurons directionally linked with the neurons from the previous and the next layer. The example below represents a 3-layer perceptron with three inputs, two outputs, and the hidden layer including five neurons:
-
-.. image:: pics/mlp.png
-
-All the neurons in MLP are similar. Each of them has several input links (it takes the output values from several neurons in the previous layer as input) and several output links (it passes the response to several neurons in the next layer). The values retrieved from the previous layer are summed up with certain weights, individual for each neuron, plus the bias term. The sum is transformed using the activation function
-:math:`f` that may be also different for different neurons.
-
-.. image:: pics/neuron_model.png
-
-In other words, given the outputs
-:math:`x_j` of the layer
-:math:`n` , the outputs
-:math:`y_i` of the layer
-:math:`n+1` are computed as:
-
-.. math::
-
- u_i = \sum _j (w^{n+1}_{i,j}*x_j) + w^{n+1}_{i,bias}
-
-.. math::
-
- y_i = f(u_i)
-
-Different activation functions may be used. ML implements three standard functions:
-
-*
- Identity function ( ``ANN_MLP::IDENTITY`` ):
- :math:`f(x)=x`
-*
- Symmetrical sigmoid ( ``ANN_MLP::SIGMOID_SYM`` ):
- :math:`f(x)=\beta*(1-e^{-\alpha x})/(1+e^{-\alpha x}` ), which is the default choice for MLP. The standard sigmoid with
- :math:`\beta =1, \alpha =1` is shown below:
-
- .. image:: pics/sigmoid_bipolar.png
-
-*
- Gaussian function ( ``ANN_MLP::GAUSSIAN`` ):
- :math:`f(x)=\beta e^{-\alpha x*x}` , which is not completely supported at the moment.
-
-In ML, all the neurons have the same activation functions, with the same free parameters (
-:math:`\alpha, \beta` ) that are specified by user and are not altered by the training algorithms.
-
-So, the whole trained network works as follows:
-
-#. Take the feature vector as input. The vector size is equal to the size of the input layer.
-
-#. Pass values as input to the first hidden layer.
-
-#. Compute outputs of the hidden layer using the weights and the activation functions.
-
-#. Pass outputs further downstream until you compute the output layer.
-
-So, to compute the network, you need to know all the
-weights
-:math:`w^{n+1)}_{i,j}` . The weights are computed by the training
-algorithm. The algorithm takes a training set, multiple input vectors
-with the corresponding output vectors, and iteratively adjusts the
-weights to enable the network to give the desired response to the
-provided input vectors.
-
-The larger the network size (the number of hidden layers and their sizes) is,
-the more the potential network flexibility is. The error on the
-training set could be made arbitrarily small. But at the same time the
-learned network also "learns" the noise present in the training set,
-so the error on the test set usually starts increasing after the network
-size reaches a limit. Besides, the larger networks are trained much
-longer than the smaller ones, so it is reasonable to pre-process the data,
-using
-:ocv:funcx:`PCA::operator()` or similar technique, and train a smaller network
-on only essential features.
-
-Another MLP feature is an inability to handle categorical
-data as is. However, there is a workaround. If a certain feature in the
-input or output (in case of ``n`` -class classifier for
-:math:`n>2` ) layer is categorical and can take
-:math:`M>2` different values, it makes sense to represent it as a binary tuple of ``M`` elements, where the ``i`` -th element is 1 if and only if the
-feature is equal to the ``i`` -th value out of ``M`` possible. It
-increases the size of the input/output layer but speeds up the
-training algorithm convergence and at the same time enables "fuzzy" values
-of such variables, that is, a tuple of probabilities instead of a fixed value.
-
-ML implements two algorithms for training MLP's. The first algorithm is a classical
-random sequential back-propagation algorithm.
-The second (default) one is a batch RPROP algorithm.
-
-.. [BackPropWikipedia] http://en.wikipedia.org/wiki/Backpropagation. Wikipedia article about the back-propagation algorithm.
-
-.. [LeCun98] Y. LeCun, L. Bottou, G.B. Orr and K.-R. Muller, *Efficient backprop*, in Neural Networks---Tricks of the Trade, Springer Lecture Notes in Computer Sciences 1524, pp.5-50, 1998.
-
-.. [RPROP93] M. Riedmiller and H. Braun, *A Direct Adaptive Method for Faster Backpropagation Learning: The RPROP Algorithm*, Proc. ICNN, San Francisco (1993).
-
-
-ANN_MLP::Params
----------------------
-.. ocv:class:: ANN_MLP::Params
-
- Parameters of the MLP and of the training algorithm. You can initialize the structure by a constructor or the individual parameters can be adjusted after the structure is created.
-
- The network structure:
-
- .. ocv:member:: Mat layerSizes
-
- The number of elements in each layer of network. The very first element specifies the number of elements in the input layer. The last element - number of elements in the output layer.
-
- .. ocv:member:: int activateFunc
-
- The activation function. Currently the only fully supported activation function is ``ANN_MLP::SIGMOID_SYM``.
-
- .. ocv:member:: double fparam1
-
- The first parameter of activation function, 0 by default.
-
- .. ocv:member:: double fparam2
-
- The second parameter of the activation function, 0 by default.
-
- .. note::
-
- If you are using the default ``ANN_MLP::SIGMOID_SYM`` activation function with the default parameter values fparam1=0 and fparam2=0 then the function used is y = 1.7159*tanh(2/3 * x), so the output will range from [-1.7159, 1.7159], instead of [0,1].
-
- The back-propagation algorithm parameters:
-
- .. ocv:member:: double bpDWScale
-
- Strength of the weight gradient term. The recommended value is about 0.1.
-
- .. ocv:member:: double bpMomentScale
-
- Strength of the momentum term (the difference between weights on the 2 previous iterations). This parameter provides some inertia to smooth the random fluctuations of the weights. It can vary from 0 (the feature is disabled) to 1 and beyond. The value 0.1 or so is good enough
-
- The RPROP algorithm parameters (see [RPROP93]_ for details):
-
- .. ocv:member:: double prDW0
-
- Initial value :math:`\Delta_0` of update-values :math:`\Delta_{ij}`.
-
- .. ocv:member:: double rpDWPlus
-
- Increase factor :math:`\eta^+`. It must be >1.
-
- .. ocv:member:: double rpDWMinus
-
- Decrease factor :math:`\eta^-`. It must be <1.
-
- .. ocv:member:: double rpDWMin
-
- Update-values lower limit :math:`\Delta_{min}`. It must be positive.
-
- .. ocv:member:: double rpDWMax
-
- Update-values upper limit :math:`\Delta_{max}`. It must be >1.
-
-
-ANN_MLP::Params::Params
---------------------------------------------
-Construct the parameter structure
-
-.. ocv:function:: ANN_MLP::Params()
-
-.. ocv:function:: ANN_MLP::Params::Params( const Mat& layerSizes, int activateFunc, double fparam1, double fparam2, TermCriteria termCrit, int trainMethod, double param1, double param2=0 )
-
- :param layerSizes: Integer vector specifying the number of neurons in each layer including the input and output layers.
-
- :param activateFunc: Parameter specifying the activation function for each neuron: one of ``ANN_MLP::IDENTITY``, ``ANN_MLP::SIGMOID_SYM``, and ``ANN_MLP::GAUSSIAN``.
-
- :param fparam1: The first parameter of the activation function, :math:`\alpha`. See the formulas in the introduction section.
-
- :param fparam2: The second parameter of the activation function, :math:`\beta`. See the formulas in the introduction section.
-
- :param termCrit: Termination criteria of the training algorithm. You can specify the maximum number of iterations (``maxCount``) and/or how much the error could change between the iterations to make the algorithm continue (``epsilon``).
-
- :param train_method: Training method of the MLP. Possible values are:
-
- * **ANN_MLP_TrainParams::BACKPROP** The back-propagation algorithm.
-
- * **ANN_MLP_TrainParams::RPROP** The RPROP algorithm.
-
- :param param1: Parameter of the training method. It is ``rp_dw0`` for ``RPROP`` and ``bp_dw_scale`` for ``BACKPROP``.
-
- :param param2: Parameter of the training method. It is ``rp_dw_min`` for ``RPROP`` and ``bp_moment_scale`` for ``BACKPROP``.
-
-By default the RPROP algorithm is used:
-
-::
-
- ANN_MLP_TrainParams::ANN_MLP_TrainParams()
- {
- layerSizes = Mat();
- activateFun = SIGMOID_SYM;
- fparam1 = fparam2 = 0;
- term_crit = TermCriteria( TermCriteria::MAX_ITER + TermCriteria::EPS, 1000, 0.01 );
- train_method = RPROP;
- bpDWScale = bpMomentScale = 0.1;
- rpDW0 = 0.1; rpDWPlus = 1.2; rpDWMinus = 0.5;
- rpDWMin = FLT_EPSILON; rpDWMax = 50.;
- }
-
-ANN_MLP
----------
-.. ocv:class:: ANN_MLP : public StatModel
-
-MLP model.
-
-Unlike many other models in ML that are constructed and trained at once, in the MLP model these steps are separated. First, a network with the specified topology is created using the non-default constructor or the method :ocv:func:`ANN_MLP::create`. All the weights are set to zeros. Then, the network is trained using a set of input and output vectors. The training procedure can be repeated more than once, that is, the weights can be adjusted based on the new training data.
-
-
-ANN_MLP::create
---------------------
-Creates empty model
-
-.. ocv:function:: Ptr<ANN_MLP> ANN_MLP::create(const Params& params=Params())
-
-Use ``StatModel::train`` to train the model, ``StatModel::train<ANN_MLP>(traindata, params)`` to create and train the model, ``StatModel::load<ANN_MLP>(filename)`` to load the pre-trained model. Note that the train method has optional flags, and the following flags are handled by ``ANN_MLP``:
-
- * **UPDATE_WEIGHTS** Algorithm updates the network weights, rather than computes them from scratch. In the latter case the weights are initialized using the Nguyen-Widrow algorithm.
-
- * **NO_INPUT_SCALE** Algorithm does not normalize the input vectors. If this flag is not set, the training algorithm normalizes each input feature independently, shifting its mean value to 0 and making the standard deviation equal to 1. If the network is assumed to be updated frequently, the new training data could be much different from original one. In this case, you should take care of proper normalization.
-
- * **NO_OUTPUT_SCALE** Algorithm does not normalize the output vectors. If the flag is not set, the training algorithm normalizes each output feature independently, by transforming it to the certain range depending on the used activation function.
-
-
-ANN_MLP::setParams
--------------------
-Sets the new network parameters
-
-.. ocv:function:: void ANN_MLP::setParams(const Params& params)
-
- :param params: The new parameters
-
-The existing network, if any, will be destroyed and new empty one will be created. It should be re-trained after that.
-
-ANN_MLP::getParams
--------------------
-Retrieves the current network parameters
-
-.. ocv:function:: Params ANN_MLP::getParams() const
+++ /dev/null
-.. _Bayes Classifier:
-
-Normal Bayes Classifier
-=======================
-
-.. highlight:: cpp
-
-This simple classification model assumes that feature vectors from each class are normally distributed (though, not necessarily independently distributed). So, the whole data distribution function is assumed to be a Gaussian mixture, one component per class. Using the training data the algorithm estimates mean vectors and covariance matrices for every class, and then it uses them for prediction.
-
-.. [Fukunaga90] K. Fukunaga. *Introduction to Statistical Pattern Recognition*. second ed., New York: Academic Press, 1990.
-
-NormalBayesClassifier
------------------------
-.. ocv:class:: NormalBayesClassifier : public StatModel
-
-Bayes classifier for normally distributed data.
-
-NormalBayesClassifier::create
------------------------------
-Creates empty model
-
-.. ocv:function:: Ptr<NormalBayesClassifier> NormalBayesClassifier::create(const NormalBayesClassifier::Params& params=Params())
-
- :param params: The model parameters. There is none so far, the structure is used as a placeholder for possible extensions.
-
-Use ``StatModel::train`` to train the model, ``StatModel::train<NormalBayesClassifier>(traindata, params)`` to create and train the model, ``StatModel::load<NormalBayesClassifier>(filename)`` to load the pre-trained model.
-
-NormalBayesClassifier::predictProb
-----------------------------------
-Predicts the response for sample(s).
-
-.. ocv:function:: float NormalBayesClassifier::predictProb( InputArray inputs, OutputArray outputs, OutputArray outputProbs, int flags=0 ) const
-
-The method estimates the most probable classes for input vectors. Input vectors (one or more) are stored as rows of the matrix ``inputs``. In case of multiple input vectors, there should be one output vector ``outputs``. The predicted class for a single input vector is returned by the method. The vector ``outputProbs`` contains the output probabilities corresponding to each element of ``result``.
+++ /dev/null
-.. _Random Trees:
-
-Random Trees
-============
-
-.. highlight:: cpp
-
-Random trees have been introduced by Leo Breiman and Adele Cutler:
-http://www.stat.berkeley.edu/users/breiman/RandomForests/
-. The algorithm can deal with both classification and regression problems. Random trees is a collection (ensemble) of tree predictors that is called
-*forest*
-further in this section (the term has been also introduced by L. Breiman). The classification works as follows: the random trees classifier takes the input feature vector, classifies it with every tree in the forest, and outputs the class label that received the majority of "votes". In case of a regression, the classifier response is the average of the responses over all the trees in the forest.
-
-All the trees are trained with the same parameters but on different training sets. These sets are generated from the original training set using the bootstrap procedure: for each training set, you randomly select the same number of vectors as in the original set ( ``=N`` ). The vectors are chosen with replacement. That is, some vectors will occur more than once and some will be absent. At each node of each trained tree, not all the variables are used to find the best split, but a random subset of them. With each node a new subset is generated. However, its size is fixed for all the nodes and all the trees. It is a training parameter set to
-:math:`\sqrt{number\_of\_variables}` by default. None of the built trees are pruned.
-
-In random trees there is no need for any accuracy estimation procedures, such as cross-validation or bootstrap, or a separate test set to get an estimate of the training error. The error is estimated internally during the training. When the training set for the current tree is drawn by sampling with replacement, some vectors are left out (so-called
-*oob (out-of-bag) data*
-). The size of oob data is about ``N/3`` . The classification error is estimated by using this oob-data as follows:
-
-#.
- Get a prediction for each vector, which is oob relative to the i-th tree, using the very i-th tree.
-
-#.
- After all the trees have been trained, for each vector that has ever been oob, find the class-*winner* for it (the class that has got the majority of votes in the trees where the vector was oob) and compare it to the ground-truth response.
-
-#.
- Compute the classification error estimate as a ratio of the number of misclassified oob vectors to all the vectors in the original data. In case of regression, the oob-error is computed as the squared error for oob vectors difference divided by the total number of vectors.
-
-
-For the random trees usage example, please, see letter_recog.cpp sample in OpenCV distribution.
-
-**References:**
-
- * *Machine Learning*, Wald I, July 2002. http://stat-www.berkeley.edu/users/breiman/wald2002-1.pdf
-
- * *Looking Inside the Black Box*, Wald II, July 2002. http://stat-www.berkeley.edu/users/breiman/wald2002-2.pdf
-
- * *Software for the Masses*, Wald III, July 2002. http://stat-www.berkeley.edu/users/breiman/wald2002-3.pdf
-
- * And other articles from the web site http://www.stat.berkeley.edu/users/breiman/RandomForests/cc_home.htm
-
-RTrees::Params
---------------
-.. ocv:struct:: RTrees::Params : public DTrees::Params
-
- Training parameters of random trees.
-
-The set of training parameters for the forest is a superset of the training parameters for a single tree. However, random trees do not need all the functionality/features of decision trees. Most noticeably, the trees are not pruned, so the cross-validation parameters are not used.
-
-
-RTrees::Params::Params
------------------------
-The constructors
-
-.. ocv:function:: RTrees::Params::Params()
-
-.. ocv:function:: RTrees::Params::Params( int maxDepth, int minSampleCount, double regressionAccuracy, bool useSurrogates, int maxCategories, const Mat& priors, bool calcVarImportance, int nactiveVars, TermCriteria termCrit )
-
- :param maxDepth: the depth of the tree. A low value will likely underfit and conversely a high value will likely overfit. The optimal value can be obtained using cross validation or other suitable methods.
-
- :param minSampleCount: minimum samples required at a leaf node for it to be split. A reasonable value is a small percentage of the total data e.g. 1%.
-
- :param maxCategories: Cluster possible values of a categorical variable into ``K <= maxCategories`` clusters to find a suboptimal split. If a discrete variable, on which the training procedure tries to make a split, takes more than ``max_categories`` values, the precise best subset estimation may take a very long time because the algorithm is exponential. Instead, many decision trees engines (including ML) try to find sub-optimal split in this case by clustering all the samples into ``maxCategories`` clusters that is some categories are merged together. The clustering is applied only in ``n``>2-class classification problems for categorical variables with ``N > max_categories`` possible values. In case of regression and 2-class classification the optimal split can be found efficiently without employing clustering, thus the parameter is not used in these cases.
-
- :param calcVarImportance: If true then variable importance will be calculated and then it can be retrieved by ``RTrees::getVarImportance``.
-
- :param nactiveVars: The size of the randomly selected subset of features at each tree node and that are used to find the best split(s). If you set it to 0 then the size will be set to the square root of the total number of features.
-
- :param termCrit: The termination criteria that specifies when the training algorithm stops - either when the specified number of trees is trained and added to the ensemble or when sufficient accuracy (measured as OOB error) is achieved. Typically the more trees you have the better the accuracy. However, the improvement in accuracy generally diminishes and asymptotes pass a certain number of trees. Also to keep in mind, the number of tree increases the prediction time linearly.
-
-The default constructor sets all parameters to default values which are different from default values of ``DTrees::Params``:
-
-::
-
- RTrees::Params::Params() : DTrees::Params( 5, 10, 0, false, 10, 0, false, false, Mat() ),
- calcVarImportance(false), nactiveVars(0)
- {
- termCrit = cvTermCriteria( TermCriteria::MAX_ITERS + TermCriteria::EPS, 50, 0.1 );
- }
-
-
-RTrees
---------
-.. ocv:class:: RTrees : public DTrees
-
- The class implements the random forest predictor as described in the beginning of this section.
-
-RTrees::create
----------------
-Creates the empty model
-
-.. ocv:function:: bool RTrees::create(const RTrees::Params& params=Params())
-
-Use ``StatModel::train`` to train the model, ``StatModel::train<RTrees>(traindata, params)`` to create and train the model, ``StatModel::load<RTrees>(filename)`` to load the pre-trained model.
-
-RTrees::getVarImportance
-----------------------------
-Returns the variable importance array.
-
-.. ocv:function:: Mat RTrees::getVarImportance() const
-
-The method returns the variable importance vector, computed at the training stage when ``RTParams::calcVarImportance`` is set to true. If this flag was set to false, the empty matrix is returned.
+++ /dev/null
-Statistical Models
-==================
-
-.. highlight:: cpp
-
-.. index:: StatModel
-
-StatModel
------------
-.. ocv:class:: StatModel
-
-Base class for statistical models in OpenCV ML.
-
-
-StatModel::train
-------------------------
-Trains the statistical model
-
-.. ocv:function:: bool StatModel::train( const Ptr<TrainData>& trainData, int flags=0 )
-
-.. ocv:function:: bool StatModel::train( InputArray samples, int layout, InputArray responses )
-
-.. ocv:function:: Ptr<_Tp> StatModel::train(const Ptr<TrainData>& data, const _Tp::Params& p, int flags=0 )
-
-.. ocv:function:: Ptr<_Tp> StatModel::train(InputArray samples, int layout, InputArray responses, const _Tp::Params& p, int flags=0 )
-
- :param trainData: training data that can be loaded from file using ``TrainData::loadFromCSV`` or created with ``TrainData::create``.
-
- :param samples: training samples
-
- :param layout: ``ROW_SAMPLE`` (training samples are the matrix rows) or ``COL_SAMPLE`` (training samples are the matrix columns)
-
- :param responses: vector of responses associated with the training samples.
-
- :param p: the stat model parameters.
-
- :param flags: optional flags, depending on the model. Some of the models can be updated with the new training samples, not completely overwritten (such as ``NormalBayesClassifier`` or ``ANN_MLP``).
-
-There are 2 instance methods and 2 static (class) template methods. The first two train the already created model (the very first method must be overwritten in the derived classes). And the latter two variants are convenience methods that construct empty model and then call its train method.
-
-
-StatModel::isTrained
------------------------------
-Returns true if the model is trained
-
-.. ocv:function:: bool StatModel::isTrained()
-
-The method must be overwritten in the derived classes.
-
-StatModel::isClassifier
------------------------------
-Returns true if the model is classifier
-
-.. ocv:function:: bool StatModel::isClassifier()
-
-The method must be overwritten in the derived classes.
-
-StatModel::getVarCount
------------------------------
-Returns the number of variables in training samples
-
-.. ocv:function:: int StatModel::getVarCount()
-
-The method must be overwritten in the derived classes.
-
-StatModel::predict
-------------------
-Predicts response(s) for the provided sample(s)
-
-.. ocv:function:: float StatModel::predict( InputArray samples, OutputArray results=noArray(), int flags=0 ) const
-
- :param samples: The input samples, floating-point matrix
-
- :param results: The optional output matrix of results.
-
- :param flags: The optional flags, model-dependent. Some models, such as ``Boost``, ``SVM`` recognize ``StatModel::RAW_OUTPUT`` flag, which makes the method return the raw results (the sum), not the class label.
-
-
-StatModel::calcError
--------------------------
-Computes error on the training or test dataset
-
-.. ocv:function:: float StatModel::calcError( const Ptr<TrainData>& data, bool test, OutputArray resp ) const
-
- :param data: the training data
-
- :param test: if true, the error is computed over the test subset of the data, otherwise it's computed over the training subset of the data. Please note that if you loaded a completely different dataset to evaluate already trained classifier, you will probably want not to set the test subset at all with ``TrainData::setTrainTestSplitRatio`` and specify ``test=false``, so that the error is computed for the whole new set. Yes, this sounds a bit confusing.
-
- :param resp: the optional output responses.
-
-The method uses ``StatModel::predict`` to compute the error. For regression models the error is computed as RMS, for classifiers - as a percent of missclassified samples (0%-100%).
-
-
-StatModel::save
------------------
-Saves the model to a file.
-
-.. ocv:function:: void StatModel::save( const String& filename )
-
-In order to make this method work, the derived class must overwrite ``Algorithm::write(FileStorage& fs)``.
-
-StatModel::load
------------------
-Loads model from the file
-
-.. ocv:function:: Ptr<_Tp> StatModel::load( const String& filename )
-
-This is static template method of StatModel. It's usage is following (in the case of SVM): ::
-
- Ptr<SVM> svm = StatModel::load<SVM>("my_svm_model.xml");
-
-In order to make this method work, the derived class must overwrite ``Algorithm::read(const FileNode& fn)``.
+++ /dev/null
-Support Vector Machines
-=======================
-
-.. highlight:: cpp
-
-Originally, support vector machines (SVM) was a technique for building an optimal binary (2-class) classifier. Later the technique was extended to regression and clustering problems. SVM is a partial case of kernel-based methods. It maps feature vectors into a higher-dimensional space using a kernel function and builds an optimal linear discriminating function in this space or an optimal hyper-plane that fits into the training data. In case of SVM, the kernel is not defined explicitly. Instead, a distance between any 2 points in the hyper-space needs to be defined.
-
-The solution is optimal, which means that the margin between the separating hyper-plane and the nearest feature vectors from both classes (in case of 2-class classifier) is maximal. The feature vectors that are the closest to the hyper-plane are called *support vectors*, which means that the position of other vectors does not affect the hyper-plane (the decision function).
-
-SVM implementation in OpenCV is based on [LibSVM]_.
-
-.. [Burges98] C. Burges. *A tutorial on support vector machines for pattern recognition*, Knowledge Discovery and Data Mining 2(2), 1998 (available online at http://citeseer.ist.psu.edu/burges98tutorial.html)
-
-.. [LibSVM] C.-C. Chang and C.-J. Lin. *LIBSVM: a library for support vector machines*, ACM Transactions on Intelligent Systems and Technology, 2:27:1--27:27, 2011. (http://www.csie.ntu.edu.tw/~cjlin/papers/libsvm.pdf)
-
-
-ParamGrid
------------
-.. ocv:class:: ParamGrid
-
- The structure represents the logarithmic grid range of statmodel parameters. It is used for optimizing statmodel accuracy by varying model parameters, the accuracy estimate being computed by cross-validation.
-
- .. ocv:member:: double ParamGrid::minVal
-
- Minimum value of the statmodel parameter.
-
- .. ocv:member:: double ParamGrid::maxVal
-
- Maximum value of the statmodel parameter.
-
- .. ocv:member:: double ParamGrid::logStep
-
- Logarithmic step for iterating the statmodel parameter.
-
-The grid determines the following iteration sequence of the statmodel parameter values:
-
-.. math::
-
- (minVal, minVal*step, minVal*{step}^2, \dots, minVal*{logStep}^n),
-
-where :math:`n` is the maximal index satisfying
-
-.. math::
-
- \texttt{minVal} * \texttt{logStep} ^n < \texttt{maxVal}
-
-The grid is logarithmic, so ``logStep`` must always be greater then 1.
-
-ParamGrid::ParamGrid
-------------------------
-The constructors.
-
-.. ocv:function:: ParamGrid::ParamGrid()
-
-.. ocv:function:: ParamGrid::ParamGrid( double minVal, double maxVal, double logStep )
-
-The full constructor initializes corresponding members. The default constructor creates a dummy grid:
-
-::
-
- ParamGrid::ParamGrid()
- {
- minVal = maxVal = 0;
- logStep = 1;
- }
-
-
-SVM::Params
------------
-.. ocv:class:: SVM::Params
-
-SVM training parameters.
-
-The structure must be initialized and passed to the training method of :ocv:class:`SVM`.
-
-SVM::Params::Params
-------------------------
-The constructors
-
-.. ocv:function:: SVM::Params::Params()
-
-.. ocv:function:: SVM::Params::Params( int svmType, int kernelType, double degree, double gamma, double coef0, double Cvalue, double nu, double p, const Mat& classWeights, TermCriteria termCrit )
-
- :param svmType: Type of a SVM formulation. Possible values are:
-
- * **SVM::C_SVC** C-Support Vector Classification. ``n``-class classification (``n`` :math:`\geq` 2), allows imperfect separation of classes with penalty multiplier ``C`` for outliers.
-
- * **SVM::NU_SVC** :math:`\nu`-Support Vector Classification. ``n``-class classification with possible imperfect separation. Parameter :math:`\nu` (in the range 0..1, the larger the value, the smoother the decision boundary) is used instead of ``C``.
-
- * **SVM::ONE_CLASS** Distribution Estimation (One-class SVM). All the training data are from the same class, SVM builds a boundary that separates the class from the rest of the feature space.
-
- * **SVM::EPS_SVR** :math:`\epsilon`-Support Vector Regression. The distance between feature vectors from the training set and the fitting hyper-plane must be less than ``p``. For outliers the penalty multiplier ``C`` is used.
-
- * **SVM::NU_SVR** :math:`\nu`-Support Vector Regression. :math:`\nu` is used instead of ``p``.
-
- See [LibSVM]_ for details.
-
- :param kernelType: Type of a SVM kernel. Possible values are:
-
- * **SVM::LINEAR** Linear kernel. No mapping is done, linear discrimination (or regression) is done in the original feature space. It is the fastest option. :math:`K(x_i, x_j) = x_i^T x_j`.
-
- * **SVM::POLY** Polynomial kernel: :math:`K(x_i, x_j) = (\gamma x_i^T x_j + coef0)^{degree}, \gamma > 0`.
-
- * **SVM::RBF** Radial basis function (RBF), a good choice in most cases. :math:`K(x_i, x_j) = e^{-\gamma ||x_i - x_j||^2}, \gamma > 0`.
-
- * **SVM::SIGMOID** Sigmoid kernel: :math:`K(x_i, x_j) = \tanh(\gamma x_i^T x_j + coef0)`.
-
- * **SVM::CHI2** Exponential Chi2 kernel, similar to the RBF kernel: :math:`K(x_i, x_j) = e^{-\gamma \chi^2(x_i,x_j)}, \chi^2(x_i,x_j) = (x_i-x_j)^2/(x_i+x_j), \gamma > 0`.
-
- * **SVM::INTER** Histogram intersection kernel. A fast kernel. :math:`K(x_i, x_j) = min(x_i,x_j)`.
-
- :param degree: Parameter ``degree`` of a kernel function (POLY).
-
- :param gamma: Parameter :math:`\gamma` of a kernel function (POLY / RBF / SIGMOID / CHI2).
-
- :param coef0: Parameter ``coef0`` of a kernel function (POLY / SIGMOID).
-
- :param Cvalue: Parameter ``C`` of a SVM optimization problem (C_SVC / EPS_SVR / NU_SVR).
-
- :param nu: Parameter :math:`\nu` of a SVM optimization problem (NU_SVC / ONE_CLASS / NU_SVR).
-
- :param p: Parameter :math:`\epsilon` of a SVM optimization problem (EPS_SVR).
-
- :param classWeights: Optional weights in the C_SVC problem , assigned to particular classes. They are multiplied by ``C`` so the parameter ``C`` of class ``#i`` becomes ``classWeights(i) * C``. Thus these weights affect the misclassification penalty for different classes. The larger weight, the larger penalty on misclassification of data from the corresponding class.
-
- :param termCrit: Termination criteria of the iterative SVM training procedure which solves a partial case of constrained quadratic optimization problem. You can specify tolerance and/or the maximum number of iterations.
-
-The default constructor initialize the structure with following values:
-
-::
-
- SVMParams::SVMParams() :
- svmType(SVM::C_SVC), kernelType(SVM::RBF), degree(0),
- gamma(1), coef0(0), C(1), nu(0), p(0), classWeights(0)
- {
- termCrit = TermCriteria( TermCriteria::MAX_ITER+TermCriteria::EPS, 1000, FLT_EPSILON );
- }
-
-A comparison of different kernels on the following 2D test case with four classes. Four C_SVC SVMs have been trained (one against rest) with auto_train. Evaluation on three different kernels (CHI2, INTER, RBF). The color depicts the class with max score. Bright means max-score > 0, dark means max-score < 0.
-
-.. image:: pics/SVM_Comparison.png
-
-
-SVM
------
-.. ocv:class:: SVM : public StatModel
-
-Support Vector Machines.
-
-.. note::
-
- * (Python) An example of digit recognition using SVM can be found at opencv_source/samples/python2/digits.py
- * (Python) An example of grid search digit recognition using SVM can be found at opencv_source/samples/python2/digits_adjust.py
- * (Python) An example of video digit recognition using SVM can be found at opencv_source/samples/python2/digits_video.py
-
-SVM::create
-------------
-Creates empty model
-
-.. ocv:function:: Ptr<SVM> SVM::create(const Params& p=Params(), const Ptr<Kernel>& customKernel=Ptr<Kernel>())
-
- :param p: SVM parameters
- :param customKernel: the optional custom kernel to use. It must implement ``SVM::Kernel`` interface.
-
-Use ``StatModel::train`` to train the model, ``StatModel::train<RTrees>(traindata, params)`` to create and train the model, ``StatModel::load<RTrees>(filename)`` to load the pre-trained model. Since SVM has several parameters, you may want to find the best parameters for your problem. It can be done with ``SVM::trainAuto``.
-
-
-SVM::trainAuto
------------------
-Trains an SVM with optimal parameters.
-
-.. ocv:function:: bool SVM::trainAuto( const Ptr<TrainData>& data, int kFold = 10, ParamGrid Cgrid = SVM::getDefaultGrid(SVM::C), ParamGrid gammaGrid = SVM::getDefaultGrid(SVM::GAMMA), ParamGrid pGrid = SVM::getDefaultGrid(SVM::P), ParamGrid nuGrid = SVM::getDefaultGrid(SVM::NU), ParamGrid coeffGrid = SVM::getDefaultGrid(SVM::COEF), ParamGrid degreeGrid = SVM::getDefaultGrid(SVM::DEGREE), bool balanced=false)
-
- :param data: the training data that can be constructed using ``TrainData::create`` or ``TrainData::loadFromCSV``.
-
- :param kFold: Cross-validation parameter. The training set is divided into ``kFold`` subsets. One subset is used to test the model, the others form the train set. So, the SVM algorithm is executed ``kFold`` times.
-
- :param \*Grid: Iteration grid for the corresponding SVM parameter.
-
- :param balanced: If ``true`` and the problem is 2-class classification then the method creates more balanced cross-validation subsets that is proportions between classes in subsets are close to such proportion in the whole train dataset.
-
-The method trains the SVM model automatically by choosing the optimal
-parameters ``C``, ``gamma``, ``p``, ``nu``, ``coef0``, ``degree`` from
-``SVM::Params``. Parameters are considered optimal
-when the cross-validation estimate of the test set error
-is minimal.
-
-If there is no need to optimize a parameter, the corresponding grid step should be set to any value less than or equal to 1. For example, to avoid optimization in ``gamma``, set ``gammaGrid.step = 0``, ``gammaGrid.minVal``, ``gamma_grid.maxVal`` as arbitrary numbers. In this case, the value ``params.gamma`` is taken for ``gamma``.
-
-And, finally, if the optimization in a parameter is required but
-the corresponding grid is unknown, you may call the function :ocv:func:`SVM::getDefaulltGrid`. To generate a grid, for example, for ``gamma``, call ``SVM::getDefaulltGrid(SVM::GAMMA)``.
-
-This function works for the classification
-(``params.svmType=SVM::C_SVC`` or ``params.svmType=SVM::NU_SVC``)
-as well as for the regression
-(``params.svmType=SVM::EPS_SVR`` or ``params.svmType=SVM::NU_SVR``). If ``params.svmType=SVM::ONE_CLASS``, no optimization is made and the usual SVM with parameters specified in ``params`` is executed.
-
-
-SVM::getDefaulltGrid
------------------------
-Generates a grid for SVM parameters.
-
-.. ocv:function:: ParamGrid SVM::getDefaulltGrid( int param_id )
-
- :param param_id: SVM parameters IDs that must be one of the following:
-
- * **SVM::C**
-
- * **SVM::GAMMA**
-
- * **SVM::P**
-
- * **SVM::NU**
-
- * **SVM::COEF**
-
- * **SVM::DEGREE**
-
- The grid is generated for the parameter with this ID.
-
-The function generates a grid for the specified parameter of the SVM algorithm. The grid may be passed to the function :ocv:func:`SVM::trainAuto`.
-
-SVM::getParams
------------------
-Returns the current SVM parameters.
-
-.. ocv:function:: SVM::Params SVM::getParams() const
-
-This function may be used to get the optimal parameters obtained while automatically training ``SVM::trainAuto``.
-
-SVM::getSupportVectors
---------------------------
-Retrieves all the support vectors
-
-.. ocv:function:: Mat SVM::getSupportVectors() const
-
-The method returns all the support vector as floating-point matrix, where support vectors are stored as matrix rows.
-
-SVM::getDecisionFunction
---------------------------
-Retrieves the decision function
-
-.. ocv:function:: double SVM::getDecisionFunction(int i, OutputArray alpha, OutputArray svidx) const
-
- :param i: the index of the decision function. If the problem solved is regression, 1-class or 2-class classification, then there will be just one decision function and the index should always be 0. Otherwise, in the case of N-class classification, there will be N*(N-1)/2 decision functions.
-
- :param alpha: the optional output vector for weights, corresponding to different support vectors. In the case of linear SVM all the alpha's will be 1's.
-
- :param svidx: the optional output vector of indices of support vectors within the matrix of support vectors (which can be retrieved by ``SVM::getSupportVectors``). In the case of linear SVM each decision function consists of a single "compressed" support vector.
-
-The method returns ``rho`` parameter of the decision function, a scalar subtracted from the weighted sum of kernel responses.
-
-Prediction with SVM
---------------------
-
-StatModel::predict(samples, results, flags) should be used. Pass ``flags=StatModel::RAW_OUTPUT`` to get the raw response from SVM (in the case of regression, 1-class or 2-class classification problem).
+++ /dev/null
-Cascade Classification
-======================
-
-.. highlight:: cpp
-
-Haar Feature-based Cascade Classifier for Object Detection
-----------------------------------------------------------
-
-The object detector described below has been initially proposed by Paul Viola [Viola01]_ and improved by Rainer Lienhart [Lienhart02]_.
-
-First, a classifier (namely a *cascade of boosted classifiers working with haar-like features*) is trained with a few hundred sample views of a particular object (i.e., a face or a car), called positive examples, that are scaled to the same size (say, 20x20), and negative examples - arbitrary images of the same size.
-
-After a classifier is trained, it can be applied to a region of interest (of the same size as used during the training) in an input image. The classifier outputs a "1" if the region is likely to show the object (i.e., face/car), and "0" otherwise. To search for the object in the whole image one can move the search window across the image and check every location using the classifier. The classifier is designed so that it can be easily "resized" in order to be able to find the objects of interest at different sizes, which is more efficient than resizing the image itself. So, to find an object of an unknown size in the image the scan procedure should be done several times at different scales.
-
-The word "cascade" in the classifier name means that the resultant classifier consists of several simpler classifiers (*stages*) that are applied subsequently to a region of interest until at some stage the candidate is rejected or all the stages are passed. The word "boosted" means that the classifiers at every stage of the cascade are complex themselves and they are built out of basic classifiers using one of four different ``boosting`` techniques (weighted voting). Currently Discrete Adaboost, Real Adaboost, Gentle Adaboost and Logitboost are supported. The basic classifiers are decision-tree classifiers with at least 2 leaves. Haar-like features are the input to the basic classifiers, and are calculated as described below. The current algorithm uses the following Haar-like features:
-
-
-.. image:: pics/haarfeatures.png
-
-
-The feature used in a particular classifier is specified by its shape (1a, 2b etc.), position within the region of interest and the scale (this scale is not the same as the scale used at the detection stage, though these two scales are multiplied). For example, in the case of the third line feature (2c) the response is calculated as the difference between the sum of image pixels under the rectangle covering the whole feature (including the two white stripes and the black stripe in the middle) and the sum of the image pixels under the black stripe multiplied by 3 in order to compensate for the differences in the size of areas. The sums of pixel values over a rectangular regions are calculated rapidly using integral images (see below and the :ocv:func:`integral` description).
-
-To see the object detector at work, have a look at the facedetect demo:
-https://github.com/Itseez/opencv/tree/master/samples/cpp/dbt_face_detection.cpp
-
-The following reference is for the detection part only. There is a separate application called ``opencv_traincascade`` that can train a cascade of boosted classifiers from a set of samples.
-
-.. note:: In the new C++ interface it is also possible to use LBP (local binary pattern) features in addition to Haar-like features.
-
-.. [Viola01] Paul Viola and Michael J. Jones. Rapid Object Detection using a Boosted Cascade of Simple Features. IEEE CVPR, 2001. The paper is available online at http://research.microsoft.com/en-us/um/people/viola/Pubs/Detect/violaJones_CVPR2001.pdf
-
-.. [Lienhart02] Rainer Lienhart and Jochen Maydt. An Extended Set of Haar-like Features for Rapid Object Detection. IEEE ICIP 2002, Vol. 1, pp. 900-903, Sep. 2002. This paper, as well as the extended technical report, can be retrieved at http://www.multimedia-computing.de/mediawiki//images/5/52/MRL-TR-May02-revised-Dec02.pdf
-
-
-CascadeClassifier
------------------
-.. ocv:class:: CascadeClassifier
-
-Cascade classifier class for object detection.
-
-CascadeClassifier::CascadeClassifier
-----------------------------------------
-Loads a classifier from a file.
-
-.. ocv:function:: CascadeClassifier::CascadeClassifier(const String& filename)
-
-.. ocv:pyfunction:: cv2.CascadeClassifier([filename]) -> <CascadeClassifier object>
-
- :param filename: Name of the file from which the classifier is loaded.
-
-
-
-CascadeClassifier::empty
-----------------------------
-Checks whether the classifier has been loaded.
-
-.. ocv:function:: bool CascadeClassifier::empty() const
-
-
-.. ocv:pyfunction:: cv2.CascadeClassifier.empty() -> retval
-
-CascadeClassifier::load
----------------------------
-Loads a classifier from a file.
-
-.. ocv:function:: bool CascadeClassifier::load(const String& filename)
-
-.. ocv:pyfunction:: cv2.CascadeClassifier.load(filename) -> retval
-
- :param filename: Name of the file from which the classifier is loaded. The file may contain an old HAAR classifier trained by the haartraining application or a new cascade classifier trained by the traincascade application.
-
-
-
-CascadeClassifier::read
----------------------------
-Reads a classifier from a FileStorage node.
-
-.. ocv:function:: bool CascadeClassifier::read(const FileNode& node)
-
-.. note:: The file may contain a new cascade classifier (trained traincascade application) only.
-
-
-CascadeClassifier::detectMultiScale
----------------------------------------
-Detects objects of different sizes in the input image. The detected objects are returned as a list of rectangles.
-
-.. ocv:function:: void CascadeClassifier::detectMultiScale( InputArray image, vector<Rect>& objects, double scaleFactor=1.1, int minNeighbors=3, int flags=0, Size minSize=Size(), Size maxSize=Size())
-.. ocv:function:: void CascadeClassifier::detectMultiScale( InputArray image, vector<Rect>& objects, vector<int>& numDetections, double scaleFactor=1.1, int minNeighbors=3, int flags=0, Size minSize=Size(), Size maxSize=Size())
-.. ocv:function:: void CascadeClassifier::detectMultiScale( InputArray image, std::vector<Rect>& objects, std::vector<int>& rejectLevels, std::vector<double>& levelWeights, double scaleFactor = 1.1, int minNeighbors = 3, int flags = 0, Size minSize = Size(), Size maxSize = Size(), bool outputRejectLevels = false )
-
-.. ocv:pyfunction:: cv2.CascadeClassifier.detectMultiScale(image[, scaleFactor[, minNeighbors[, flags[, minSize[, maxSize]]]]]) -> objects
-.. ocv:pyfunction:: cv2.CascadeClassifier.detectMultiScale2(image[, scaleFactor[, minNeighbors[, flags[, minSize[, maxSize]]]]]) -> objects, numDetections
-.. ocv:pyfunction:: cv2.CascadeClassifier.detectMultiScale3(image[, scaleFactor[, minNeighbors[, flags[, minSize[, maxSize[, outputRejectLevels]]]]]]) -> objects, rejectLevels, levelWeights
-
-.. ocv:cfunction:: CvSeq* cvHaarDetectObjects( const CvArr* image, CvHaarClassifierCascade* cascade, CvMemStorage* storage, double scale_factor=1.1, int min_neighbors=3, int flags=0, CvSize min_size=cvSize(0,0), CvSize max_size=cvSize(0,0) )
-
- :param cascade: Haar classifier cascade (OpenCV 1.x API only). It can be loaded from XML or YAML file using :ocv:cfunc:`Load`. When the cascade is not needed anymore, release it using ``cvReleaseHaarClassifierCascade(&cascade)``.
-
- :param image: Matrix of the type ``CV_8U`` containing an image where objects are detected.
-
- :param objects: Vector of rectangles where each rectangle contains the detected object, the rectangles may be partially outside the original image.
-
- :param numDetections: Vector of detection numbers for the corresponding objects. An object's number of detections is the number of neighboring positively classified rectangles that were joined together to form the object.
-
- :param scaleFactor: Parameter specifying how much the image size is reduced at each image scale.
-
- :param minNeighbors: Parameter specifying how many neighbors each candidate rectangle should have to retain it.
-
- :param flags: Parameter with the same meaning for an old cascade as in the function ``cvHaarDetectObjects``. It is not used for a new cascade.
-
- :param minSize: Minimum possible object size. Objects smaller than that are ignored.
-
- :param maxSize: Maximum possible object size. Objects larger than that are ignored.
-
- :param outputRejectLevels: Boolean. If ``True``, it returns the rejectLevels and levelWeights. Default value is ``False``.
-
-The function is parallelized with the TBB library.
-
-.. note::
-
- * (Python) A face detection example using cascade classifiers can be found at opencv_source_code/samples/python2/facedetect.py
-
-
-groupRectangles
--------------------
-Groups the object candidate rectangles.
-
-.. ocv:function:: void groupRectangles(vector<Rect>& rectList, int groupThreshold, double eps=0.2)
-.. ocv:function:: void groupRectangles(vector<Rect>& rectList, vector<int>& weights, int groupThreshold, double eps=0.2)
-
-.. ocv:pyfunction:: cv2.groupRectangles(rectList, groupThreshold[, eps]) -> rectList, weights
-
-
- :param rectList: Input/output vector of rectangles. Output vector includes retained and grouped rectangles. (The Python list is not modified in place.)
-
- :param groupThreshold: Minimum possible number of rectangles minus 1. The threshold is used in a group of rectangles to retain it.
-
- :param eps: Relative difference between sides of the rectangles to merge them into a group.
-
-The function is a wrapper for the generic function
-:ocv:func:`partition` . It clusters all the input rectangles using the rectangle equivalence criteria that combines rectangles with similar sizes and similar locations. The similarity is defined by ``eps``. When ``eps=0`` , no clustering is done at all. If
-:math:`\texttt{eps}\rightarrow +\inf` , all the rectangles are put in one cluster. Then, the small clusters containing less than or equal to ``groupThreshold`` rectangles are rejected. In each other cluster, the average rectangle is computed and put into the output rectangle list.
+++ /dev/null
-***************************
-objdetect. Object Detection
-***************************
-
-.. highlight:: cpp
-
-.. toctree::
- :maxdepth: 2
-
- cascade_classification
+++ /dev/null
-Seamless Cloning
-================
-
-.. highlight:: cpp
-
-seamlessClone
--------------
-Image editing tasks concern either global changes (color/intensity corrections, filters, deformations) or local changes concerned to a selection.
-Here we are interested in achieving local changes, ones that are restricted to a region manually selected (ROI), in a seamless and effortless manner.
-The extent of the changes ranges from slight distortions to complete replacement by novel content [PM03]_.
-
-.. ocv:function:: void seamlessClone( InputArray src, InputArray dst, InputArray mask, Point p, OutputArray blend, int flags)
-
- :param src: Input 8-bit 3-channel image.
-
- :param dst: Input 8-bit 3-channel image.
-
- :param mask: Input 8-bit 1 or 3-channel image.
-
- :param p: Point in dst image where object is placed.
-
- :param result: Output image with the same size and type as ``dst``.
-
- :param flags: Cloning method that could be one of the following:
-
- * **NORMAL_CLONE** The power of the method is fully expressed when inserting objects with complex outlines into a new background
-
- * **MIXED_CLONE** The classic method, color-based selection and alpha masking might be time consuming and often leaves an undesirable halo. Seamless cloning, even averaged with the original image, is not effective. Mixed seamless cloning based on a loose selection proves effective.
-
- * **FEATURE_EXCHANGE** Feature exchange allows the user to easily replace certain features of one object by alternative features.
-
-
-
-colorChange
------------
-Given an original color image, two differently colored versions of this image can be mixed seamlessly.
-
-.. ocv:function:: void colorChange( InputArray src, InputArray mask, OutputArray dst, float red_mul = 1.0f, float green_mul = 1.0f, float blue_mul = 1.0f)
-
- :param src: Input 8-bit 3-channel image.
-
- :param mask: Input 8-bit 1 or 3-channel image.
-
- :param dst: Output image with the same size and type as ``src`` .
-
- :param red_mul: R-channel multiply factor.
-
- :param green_mul: G-channel multiply factor.
-
- :param blue_mul: B-channel multiply factor.
-
-Multiplication factor is between .5 to 2.5.
-
-
-illuminationChange
-------------------
-Applying an appropriate non-linear transformation to the gradient field inside the selection and then integrating back with a Poisson
-solver, modifies locally the apparent illumination of an image.
-
-.. ocv:function:: void illuminationChange(InputArray src, InputArray mask, OutputArray dst, float alpha = 0.2f, float beta = 0.4f)
-
- :param src: Input 8-bit 3-channel image.
-
- :param mask: Input 8-bit 1 or 3-channel image.
-
- :param dst: Output image with the same size and type as ``src``.
-
- :param alpha: Value ranges between 0-2.
-
- :param beta: Value ranges between 0-2.
-
-This is useful to highlight under-exposed foreground objects or to reduce specular reflections.
-
-textureFlattening
------------------
-By retaining only the gradients at edge locations, before integrating with the Poisson solver, one washes out the texture of the selected
-region, giving its contents a flat aspect. Here Canny Edge Detector is used.
-
-.. ocv:function:: void textureFlattening(InputArray src, InputArray mask, OutputArray dst, double low_threshold=30 , double high_threshold=45, int kernel_size=3)
-
- :param src: Input 8-bit 3-channel image.
-
- :param mask: Input 8-bit 1 or 3-channel image.
-
- :param dst: Output image with the same size and type as ``src``.
-
- :param low_threshold: Range from 0 to 100.
-
- :param high_threshold: Value > 100.
-
- :param kernel_size: The size of the Sobel kernel to be used.
-
-**NOTE:**
-
-The algorithm assumes that the color of the source image is close to that of the destination. This assumption means that when the colors don't match, the source image color gets tinted toward the color of the destination image.
-
-.. [PM03] Patrick Perez, Michel Gangnet, Andrew Blake, "Poisson image editing", ACM Transactions on Graphics (SIGGRAPH), 2003.
+++ /dev/null
-Decolorization
-==============
-
-.. highlight:: cpp
-
-decolor
--------
-
-Transforms a color image to a grayscale image. It is a basic tool in digital printing, stylized black-and-white photograph rendering, and in many single channel image processing applications [CL12]_.
-
-.. ocv:function:: void decolor( InputArray src, OutputArray grayscale, OutputArray color_boost )
-
- :param src: Input 8-bit 3-channel image.
-
- :param grayscale: Output 8-bit 1-channel image.
-
- :param color_boost: Output 8-bit 3-channel image.
-
-This function is to be applied on color images.
-
-.. [CL12] Cewu Lu, Li Xu, Jiaya Jia, "Contrast Preserving Decolorization", IEEE International Conference on Computational Photography (ICCP), 2012.
+++ /dev/null
-Denoising
-==========
-
-.. highlight:: cpp
-
-fastNlMeansDenoising
---------------------
-Perform image denoising using Non-local Means Denoising algorithm http://www.ipol.im/pub/algo/bcm_non_local_means_denoising/
-with several computational optimizations. Noise expected to be a gaussian white noise
-
-.. ocv:function:: void fastNlMeansDenoising( InputArray src, OutputArray dst, float h=3, int templateWindowSize=7, int searchWindowSize=21 )
-
-.. ocv:pyfunction:: cv2.fastNlMeansDenoising(src[, dst[, h[, templateWindowSize[, searchWindowSize]]]]) -> dst
-
- :param src: Input 8-bit 1-channel, 2-channel or 3-channel image.
-
- :param dst: Output image with the same size and type as ``src`` .
-
- :param templateWindowSize: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-
- :param searchWindowSize: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater denoising time. Recommended value 21 pixels
-
- :param h: Parameter regulating filter strength. Big h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
-
-This function expected to be applied to grayscale images. For colored images look at ``fastNlMeansDenoisingColored``.
-Advanced usage of this functions can be manual denoising of colored image in different colorspaces.
-Such approach is used in ``fastNlMeansDenoisingColored`` by converting image to CIELAB colorspace and then separately denoise L and AB components with different h parameter.
-
-fastNlMeansDenoisingColored
----------------------------
-Modification of ``fastNlMeansDenoising`` function for colored images
-
-.. ocv:function:: void fastNlMeansDenoisingColored( InputArray src, OutputArray dst, float h=3, float hColor=3, int templateWindowSize=7, int searchWindowSize=21 )
-
-.. ocv:pyfunction:: cv2.fastNlMeansDenoisingColored(src[, dst[, h[, hColor[, templateWindowSize[, searchWindowSize]]]]]) -> dst
-
- :param src: Input 8-bit 3-channel image.
-
- :param dst: Output image with the same size and type as ``src`` .
-
- :param templateWindowSize: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-
- :param searchWindowSize: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater denoising time. Recommended value 21 pixels
-
- :param h: Parameter regulating filter strength for luminance component. Bigger h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
-
- :param hForColorComponents: The same as h but for color components. For most images value equals 10 will be enought to remove colored noise and do not distort colors
-
-The function converts image to CIELAB colorspace and then separately denoise L and AB components with given h parameters using ``fastNlMeansDenoising`` function.
-
-fastNlMeansDenoisingMulti
--------------------------
-Modification of ``fastNlMeansDenoising`` function for images sequence where consequtive images have been captured in small period of time. For example video. This version of the function is for grayscale images or for manual manipulation with colorspaces.
-For more details see http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.131.6394
-
-.. ocv:function:: void fastNlMeansDenoisingMulti( InputArrayOfArrays srcImgs, OutputArray dst, int imgToDenoiseIndex, int temporalWindowSize, float h=3, int templateWindowSize=7, int searchWindowSize=21 )
-
-.. ocv:pyfunction:: cv2.fastNlMeansDenoisingMulti(srcImgs, imgToDenoiseIndex, temporalWindowSize[, dst[, h[, templateWindowSize[, searchWindowSize]]]]) -> dst
-
- :param srcImgs: Input 8-bit 1-channel, 2-channel or 3-channel images sequence. All images should have the same type and size.
-
- :param imgToDenoiseIndex: Target image to denoise index in ``srcImgs`` sequence
-
- :param temporalWindowSize: Number of surrounding images to use for target image denoising. Should be odd. Images from ``imgToDenoiseIndex - temporalWindowSize / 2`` to ``imgToDenoiseIndex - temporalWindowSize / 2`` from ``srcImgs`` will be used to denoise ``srcImgs[imgToDenoiseIndex]`` image.
-
- :param dst: Output image with the same size and type as ``srcImgs`` images.
-
- :param templateWindowSize: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-
- :param searchWindowSize: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater denoising time. Recommended value 21 pixels
-
- :param h: Parameter regulating filter strength for luminance component. Bigger h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
-
-fastNlMeansDenoisingColoredMulti
---------------------------------
-Modification of ``fastNlMeansDenoisingMulti`` function for colored images sequences
-
-.. ocv:function:: void fastNlMeansDenoisingColoredMulti( InputArrayOfArrays srcImgs, OutputArray dst, int imgToDenoiseIndex, int temporalWindowSize, float h=3, float hColor=3, int templateWindowSize=7, int searchWindowSize=21 )
-
-.. ocv:pyfunction:: cv2.fastNlMeansDenoisingColoredMulti(srcImgs, imgToDenoiseIndex, temporalWindowSize[, dst[, h[, hColor[, templateWindowSize[, searchWindowSize]]]]]) -> dst
-
- :param srcImgs: Input 8-bit 3-channel images sequence. All images should have the same type and size.
-
- :param imgToDenoiseIndex: Target image to denoise index in ``srcImgs`` sequence
-
- :param temporalWindowSize: Number of surrounding images to use for target image denoising. Should be odd. Images from ``imgToDenoiseIndex - temporalWindowSize / 2`` to ``imgToDenoiseIndex - temporalWindowSize / 2`` from ``srcImgs`` will be used to denoise ``srcImgs[imgToDenoiseIndex]`` image.
-
- :param dst: Output image with the same size and type as ``srcImgs`` images.
-
- :param templateWindowSize: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-
- :param searchWindowSize: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater denoising time. Recommended value 21 pixels
-
- :param h: Parameter regulating filter strength for luminance component. Bigger h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise.
-
- :param hForColorComponents: The same as h but for color components.
-
-The function converts images to CIELAB colorspace and then separately denoise L and AB components with given h parameters using ``fastNlMeansDenoisingMulti`` function.
-
-
-
-cuda::nonLocalMeans
--------------------
-Performs pure non local means denoising without any simplification, and thus it is not fast.
-
-.. ocv:function:: void cuda::nonLocalMeans(const GpuMat& src, GpuMat& dst, float h, int search_window = 21, int block_size = 7, int borderMode = BORDER_DEFAULT, Stream& s = Stream::Null())
-
- :param src: Source image. Supports only CV_8UC1, CV_8UC2 and CV_8UC3.
-
- :param dst: Destination image.
-
- :param h: Filter sigma regulating filter strength for color.
-
- :param search_window: Size of search window.
-
- :param block_size: Size of block used for computing weights.
-
- :param borderMode: Border type. See :ocv:func:`borderInterpolate` for details. ``BORDER_REFLECT101`` , ``BORDER_REPLICATE`` , ``BORDER_CONSTANT`` , ``BORDER_REFLECT`` and ``BORDER_WRAP`` are supported for now.
-
- :param stream: Stream for the asynchronous version.
-
-.. seealso::
-
- :ocv:func:`fastNlMeansDenoising`
-
-
-
-cuda::FastNonLocalMeansDenoising
---------------------------------
-.. ocv:class:: cuda::FastNonLocalMeansDenoising
-
- ::
-
- class FastNonLocalMeansDenoising
- {
- public:
- //! Simple method, recommended for grayscale images (though it supports multichannel images)
- void simpleMethod(const GpuMat& src, GpuMat& dst, float h, int search_window = 21, int block_size = 7, Stream& s = Stream::Null())
- //! Processes luminance and color components separatelly
- void labMethod(const GpuMat& src, GpuMat& dst, float h_luminance, float h_color, int search_window = 21, int block_size = 7, Stream& s = Stream::Null())
- };
-
-The class implements fast approximate Non Local Means Denoising algorithm.
-
-
-
-cuda::FastNonLocalMeansDenoising::simpleMethod()
-------------------------------------------------
-Perform image denoising using Non-local Means Denoising algorithm http://www.ipol.im/pub/algo/bcm_non_local_means_denoising with several computational optimizations. Noise expected to be a gaussian white noise
-
-.. ocv:function:: void cuda::FastNonLocalMeansDenoising::simpleMethod(const GpuMat& src, GpuMat& dst, float h, int search_window = 21, int block_size = 7, Stream& s = Stream::Null())
-
- :param src: Input 8-bit 1-channel, 2-channel or 3-channel image.
-
- :param dst: Output image with the same size and type as ``src`` .
-
- :param h: Parameter regulating filter strength. Big h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
-
- :param search_window: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater search_window - greater denoising time. Recommended value 21 pixels
-
- :param block_size: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-
- :param stream: Stream for the asynchronous invocations.
-
-This function expected to be applied to grayscale images. For colored images look at ``FastNonLocalMeansDenoising::labMethod``.
-
-.. seealso::
-
- :ocv:func:`fastNlMeansDenoising`
-
-
-
-cuda::FastNonLocalMeansDenoising::labMethod()
----------------------------------------------
-Modification of ``FastNonLocalMeansDenoising::simpleMethod`` for color images
-
-.. ocv:function:: void cuda::FastNonLocalMeansDenoising::labMethod(const GpuMat& src, GpuMat& dst, float h_luminance, float h_color, int search_window = 21, int block_size = 7, Stream& s = Stream::Null())
-
- :param src: Input 8-bit 3-channel image.
-
- :param dst: Output image with the same size and type as ``src`` .
-
- :param h_luminance: Parameter regulating filter strength. Big h value perfectly removes noise but also removes image details, smaller h value preserves details but also preserves some noise
-
- :param float: The same as h but for color components. For most images value equals 10 will be enought to remove colored noise and do not distort colors
-
- :param search_window: Size in pixels of the window that is used to compute weighted average for given pixel. Should be odd. Affect performance linearly: greater search_window - greater denoising time. Recommended value 21 pixels
-
- :param block_size: Size in pixels of the template patch that is used to compute weights. Should be odd. Recommended value 7 pixels
-
- :param stream: Stream for the asynchronous invocations.
-
-The function converts image to CIELAB colorspace and then separately denoise L and AB components with given h parameters using ``FastNonLocalMeansDenoising::simpleMethod`` function.
-
-.. seealso::
-
- :ocv:func:`fastNlMeansDenoisingColored`
-
-
-denoise_TVL1
----------------------------------
-
-Primal-dual algorithm is an algorithm for solving special types of variational
-problems (that is, finding a function to minimize some functional).
-As the image denoising, in particular, may be seen as the variational
-problem, primal-dual algorithm then can be used to perform denoising and this
-is exactly what is implemented.
-
-It should be noted, that this implementation was taken from the July 2013 blog entry [Mordvintsev]_, which also contained
-(slightly more general) ready-to-use
-source code on Python. Subsequently, that code was rewritten on C++ with the usage of openCV by Vadim Pisarevsky
-at the end of July 2013 and finally it was slightly adapted by later authors.
-
-Although the thorough discussion and justification
-of the algorithm involved may be found in [ChambolleEtAl]_, it might make sense to skim over it here, following [Mordvintsev]_. To
-begin with, we consider the 1-byte gray-level images as the functions from the rectangular domain of pixels
-(it may be seen as set :math:`\left\{(x,y)\in\mathbb{N}\times\mathbb{N}\mid 1\leq x\leq n,\;1\leq y\leq m\right\}`
-for some :math:`m,\;n\in\mathbb{N}`) into :math:`\{0,1,\dots,255\}`. We shall denote the noised images as :math:`f_i` and with this
-view, given some image :math:`x` of the same size, we may measure how bad it is by the formula
-
-.. math::
- \left\|\left\|\nabla x\right\|\right\| + \lambda\sum_i\left\|\left\|x-f_i\right\|\right\|
-
-:math:`\|\|\cdot\|\|` here denotes :math:`L_2`-norm and as you see, the first addend states that we want our image to be smooth
-(ideally, having zero gradient, thus being constant) and the second states that we want our result to be close to the observations we've got.
-If we treat :math:`x` as a function, this is exactly the functional what we seek to minimize and here the Primal-Dual algorithm comes
-into play.
-
-.. ocv:function:: void denoise_TVL1(const std::vector<Mat>& observations,Mat& result, double lambda, int niters)
-
- :param observations: This array should contain one or more noised versions of the image that is to be restored.
-
- :param result: Here the denoised image will be stored. There is no need to do pre-allocation of storage space, as it will be automatically allocated, if necessary.
-
- :param lambda: Corresponds to :math:`\lambda` in the formulas above. As it is enlarged, the smooth (blurred) images are treated more favorably than detailed (but maybe more noised) ones. Roughly speaking, as it becomes smaller, the result will be more blur but more sever outliers will be removed.
-
- :param niters: Number of iterations that the algorithm will run. Of course, as more iterations as better, but it is hard to quantitatively refine this statement, so just use the default and increase it if the results are poor.
-
-
-.. [ChambolleEtAl] A. Chambolle, V. Caselles, M. Novaga, D. Cremers and T. Pock, An Introduction to Total Variation for Image Analysis, http://hal.archives-ouvertes.fr/docs/00/43/75/81/PDF/preprint.pdf (pdf)
-
-.. [Mordvintsev] Alexander Mordvintsev, ROF and TV-L1 denoising with Primal-Dual algorithm, http://znah.net/rof-and-tv-l1-denoising-with-primal-dual-algorithm.html (blog entry)
+++ /dev/null
-HDR imaging
-=============
-
-.. highlight:: cpp
-
-This section describes high dynamic range imaging algorithms namely tonemapping, exposure alignment, camera calibration with multiple exposures and exposure fusion.
-
-Tonemap
----------------------------
-.. ocv:class:: Tonemap : public Algorithm
-
-Base class for tonemapping algorithms - tools that are used to map HDR image to 8-bit range.
-
-Tonemap::process
----------------------------
-Tonemaps image
-
-.. ocv:function:: void Tonemap::process(InputArray src, OutputArray dst)
-
- :param src: source image - 32-bit 3-channel Mat
- :param dst: destination image - 32-bit 3-channel Mat with values in [0, 1] range
-
-createTonemap
----------------------------
-Creates simple linear mapper with gamma correction
-
-.. ocv:function:: Ptr<Tonemap> createTonemap(float gamma = 1.0f)
-
- :param gamma: positive value for gamma correction. Gamma value of 1.0 implies no correction, gamma equal to 2.2f is suitable for most displays.
-
- Generally gamma > 1 brightens the image and gamma < 1 darkens it.
-
-TonemapDrago
----------------------------
-.. ocv:class:: TonemapDrago : public Tonemap
-
-Adaptive logarithmic mapping is a fast global tonemapping algorithm that scales the image in logarithmic domain.
-
-Since it's a global operator the same function is applied to all the pixels, it is controlled by the bias parameter.
-
-Optional saturation enhancement is possible as described in [FL02]_.
-
-For more information see [DM03]_.
-
-createTonemapDrago
----------------------------
-Creates TonemapDrago object
-
-.. ocv:function:: Ptr<TonemapDrago> createTonemapDrago(float gamma = 1.0f, float saturation = 1.0f, float bias = 0.85f)
-
- :param gamma: gamma value for gamma correction. See :ocv:func:`createTonemap`
-
- :param saturation: positive saturation enhancement value. 1.0 preserves saturation, values greater than 1 increase saturation and values less than 1 decrease it.
-
- :param bias: value for bias function in [0, 1] range. Values from 0.7 to 0.9 usually give best results, default value is 0.85.
-
-TonemapDurand
----------------------------
-.. ocv:class:: TonemapDurand : public Tonemap
-
-This algorithm decomposes image into two layers: base layer and detail layer using bilateral filter and compresses contrast of the base layer thus preserving all the details.
-
-This implementation uses regular bilateral filter from opencv.
-
-Saturation enhancement is possible as in ocv:class:`TonemapDrago`.
-
-For more information see [DD02]_.
-
-createTonemapDurand
----------------------------
-Creates TonemapDurand object
-
-.. ocv:function:: Ptr<TonemapDurand> createTonemapDurand(float gamma = 1.0f, float contrast = 4.0f, float saturation = 1.0f, float sigma_space = 2.0f, float sigma_color = 2.0f)
-
- :param gamma: gamma value for gamma correction. See :ocv:func:`createTonemap`
-
- :param contrast: resulting contrast on logarithmic scale, i. e. log(max / min), where max and min are maximum and minimum luminance values of the resulting image.
-
- :param saturation: saturation enhancement value. See :ocv:func:`createTonemapDrago`
-
- :param sigma_space: bilateral filter sigma in color space
-
- :param sigma_color: bilateral filter sigma in coordinate space
-
-TonemapReinhard
----------------------------
-.. ocv:class:: TonemapReinhard : public Tonemap
-
-This is a global tonemapping operator that models human visual system.
-
-Mapping function is controlled by adaptation parameter, that is computed using light adaptation and color adaptation.
-
-For more information see [RD05]_.
-
-createTonemapReinhard
----------------------------
-Creates TonemapReinhard object
-
-.. ocv:function:: Ptr<TonemapReinhard> createTonemapReinhard(float gamma = 1.0f, float intensity = 0.0f, float light_adapt = 1.0f, float color_adapt = 0.0f)
-
- :param gamma: gamma value for gamma correction. See :ocv:func:`createTonemap`
-
- :param intensity: result intensity in [-8, 8] range. Greater intensity produces brighter results.
-
- :param light_adapt: light adaptation in [0, 1] range. If 1 adaptation is based only on pixel value, if 0 it's global, otherwise it's a weighted mean of this two cases.
-
- :param color_adapt: chromatic adaptation in [0, 1] range. If 1 channels are treated independently, if 0 adaptation level is the same for each channel.
-
-TonemapMantiuk
----------------------------
-.. ocv:class:: TonemapMantiuk : public Tonemap
-
-This algorithm transforms image to contrast using gradients on all levels of gaussian pyramid, transforms contrast values to HVS response and scales the response.
-After this the image is reconstructed from new contrast values.
-
-For more information see [MM06]_.
-
-createTonemapMantiuk
----------------------------
-Creates TonemapMantiuk object
-
-.. ocv:function:: Ptr<TonemapMantiuk> createTonemapMantiuk(float gamma = 1.0f, float scale = 0.7f, float saturation = 1.0f)
-
- :param gamma: gamma value for gamma correction. See :ocv:func:`createTonemap`
-
- :param scale: contrast scale factor. HVS response is multiplied by this parameter, thus compressing dynamic range. Values from 0.6 to 0.9 produce best results.
-
- :param saturation: saturation enhancement value. See :ocv:func:`createTonemapDrago`
-
-AlignExposures
----------------------------
-.. ocv:class:: AlignExposures : public Algorithm
-
-The base class for algorithms that align images of the same scene with different exposures
-
-AlignExposures::process
----------------------------
-Aligns images
-
-.. ocv:function:: void AlignExposures::process(InputArrayOfArrays src, std::vector<Mat>& dst, InputArray times, InputArray response)
-
- :param src: vector of input images
-
- :param dst: vector of aligned images
-
- :param times: vector of exposure time values for each image
-
- :param response: 256x1 matrix with inverse camera response function for each pixel value, it should have the same number of channels as images.
-
-AlignMTB
----------------------------
-.. ocv:class:: AlignMTB : public AlignExposures
-
-This algorithm converts images to median threshold bitmaps (1 for pixels brighter than median luminance and 0 otherwise) and than aligns the resulting bitmaps using bit operations.
-
-It is invariant to exposure, so exposure values and camera response are not necessary.
-
-In this implementation new image regions are filled with zeros.
-
-For more information see [GW03]_.
-
-AlignMTB::process
----------------------------
-Short version of process, that doesn't take extra arguments.
-
-.. ocv:function:: void AlignMTB::process(InputArrayOfArrays src, std::vector<Mat>& dst)
-
- :param src: vector of input images
-
- :param dst: vector of aligned images
-
-AlignMTB::calculateShift
----------------------------
-Calculates shift between two images, i. e. how to shift the second image to correspond it with the first.
-
-.. ocv:function:: Point AlignMTB::calculateShift(InputArray img0, InputArray img1)
-
- :param img0: first image
-
- :param img1: second image
-
-AlignMTB::shiftMat
----------------------------
-Helper function, that shift Mat filling new regions with zeros.
-
-.. ocv:function:: void AlignMTB::shiftMat(InputArray src, OutputArray dst, const Point shift)
-
- :param src: input image
-
- :param dst: result image
-
- :param shift: shift value
-
-AlignMTB::computeBitmaps
----------------------------
-Computes median threshold and exclude bitmaps of given image.
-
-.. ocv:function:: void AlignMTB::computeBitmaps(InputArray img, OutputArray tb, OutputArray eb)
-
- :param img: input image
-
- :param tb: median threshold bitmap
-
- :param eb: exclude bitmap
-
-createAlignMTB
----------------------------
-Creates AlignMTB object
-
-.. ocv:function:: Ptr<AlignMTB> createAlignMTB(int max_bits = 6, int exclude_range = 4, bool cut = true)
-
- :param max_bits: logarithm to the base 2 of maximal shift in each dimension. Values of 5 and 6 are usually good enough (31 and 63 pixels shift respectively).
-
- :param exclude_range: range for exclusion bitmap that is constructed to suppress noise around the median value.
-
- :param cut: if true cuts images, otherwise fills the new regions with zeros.
-
-CalibrateCRF
----------------------------
-.. ocv:class:: CalibrateCRF : public Algorithm
-
-The base class for camera response calibration algorithms.
-
-CalibrateCRF::process
----------------------------
-Recovers inverse camera response.
-
-.. ocv:function:: void CalibrateCRF::process(InputArrayOfArrays src, OutputArray dst, InputArray times)
-
- :param src: vector of input images
-
- :param dst: 256x1 matrix with inverse camera response function
-
- :param times: vector of exposure time values for each image
-
-CalibrateDebevec
----------------------------
-.. ocv:class:: CalibrateDebevec : public CalibrateCRF
-
-Inverse camera response function is extracted for each brightness value by minimizing an objective function as linear system.
-Objective function is constructed using pixel values on the same position in all images, extra term is added to make the result smoother.
-
-For more information see [DM97]_.
-
-createCalibrateDebevec
----------------------------
-Creates CalibrateDebevec object
-
-.. ocv:function:: createCalibrateDebevec(int samples = 70, float lambda = 10.0f, bool random = false)
-
- :param samples: number of pixel locations to use
-
- :param lambda: smoothness term weight. Greater values produce smoother results, but can alter the response.
-
- :param random: if true sample pixel locations are chosen at random, otherwise the form a rectangular grid.
-
-CalibrateRobertson
----------------------------
-.. ocv:class:: CalibrateRobertson : public CalibrateCRF
-
-Inverse camera response function is extracted for each brightness value by minimizing an objective function as linear system.
-This algorithm uses all image pixels.
-
-For more information see [RB99]_.
-
-createCalibrateRobertson
----------------------------
-Creates CalibrateRobertson object
-
-.. ocv:function:: createCalibrateRobertson(int max_iter = 30, float threshold = 0.01f)
-
- :param max_iter: maximal number of Gauss-Seidel solver iterations.
-
- :param threshold: target difference between results of two successive steps of the minimization.
-
-MergeExposures
----------------------------
-.. ocv:class:: MergeExposures : public Algorithm
-
-The base class algorithms that can merge exposure sequence to a single image.
-
-MergeExposures::process
----------------------------
-Merges images.
-
-.. ocv:function:: void MergeExposures::process(InputArrayOfArrays src, OutputArray dst, InputArray times, InputArray response)
-
- :param src: vector of input images
-
- :param dst: result image
-
- :param times: vector of exposure time values for each image
-
- :param response: 256x1 matrix with inverse camera response function for each pixel value, it should have the same number of channels as images.
-
-MergeDebevec
----------------------------
-.. ocv:class:: MergeDebevec : public MergeExposures
-
-The resulting HDR image is calculated as weighted average of the exposures considering exposure values and camera response.
-
-For more information see [DM97]_.
-
-createMergeDebevec
----------------------------
-Creates MergeDebevec object
-
-.. ocv:function:: Ptr<MergeDebevec> createMergeDebevec()
-
-MergeMertens
----------------------------
-.. ocv:class:: MergeMertens : public MergeExposures
-
-Pixels are weighted using contrast, saturation and well-exposedness measures, than images are combined using laplacian pyramids.
-
-The resulting image weight is constructed as weighted average of contrast, saturation and well-exposedness measures.
-
-The resulting image doesn't require tonemapping and can be converted to 8-bit image by multiplying by 255, but it's recommended to apply gamma correction and/or linear tonemapping.
-
-For more information see [MK07]_.
-
-MergeMertens::process
----------------------------
-Short version of process, that doesn't take extra arguments.
-
-.. ocv:function:: void MergeMertens::process(InputArrayOfArrays src, OutputArray dst)
-
- :param src: vector of input images
-
- :param dst: result image
-
-createMergeMertens
----------------------------
-Creates MergeMertens object
-
-.. ocv:function:: Ptr<MergeMertens> createMergeMertens(float contrast_weight = 1.0f, float saturation_weight = 1.0f, float exposure_weight = 0.0f)
-
- :param contrast_weight: contrast measure weight. See :ocv:class:`MergeMertens`.
-
- :param saturation_weight: saturation measure weight
-
- :param exposure_weight: well-exposedness measure weight
-
-MergeRobertson
----------------------------
-.. ocv:class:: MergeRobertson : public MergeExposures
-
-The resulting HDR image is calculated as weighted average of the exposures considering exposure values and camera response.
-
-For more information see [RB99]_.
-
-createMergeRobertson
----------------------------
-Creates MergeRobertson object
-
-.. ocv:function:: Ptr<MergeRobertson> createMergeRobertson()
-
-References
----------------------------
-
-.. [DM03] F. Drago, K. Myszkowski, T. Annen, N. Chiba, "Adaptive Logarithmic Mapping For Displaying High Contrast Scenes", Computer Graphics Forum, 2003, 22, 419 - 426.
-
-.. [FL02] R. Fattal, D. Lischinski, M. Werman, "Gradient Domain High Dynamic Range Compression", Proceedings OF ACM SIGGRAPH, 2002, 249 - 256.
-
-.. [DD02] F. Durand and Julie Dorsey, "Fast Bilateral Filtering for the Display of High-Dynamic-Range Images", ACM Transactions on Graphics, 2002, 21, 3, 257 - 266.
-
-.. [RD05] E. Reinhard, K. Devlin, "Dynamic Range Reduction Inspired by Photoreceptor Physiology", IEEE Transactions on Visualization and Computer Graphics, 2005, 11, 13 - 24.
-
-.. [MM06] R. Mantiuk, K. Myszkowski, H.-P. Seidel, "Perceptual Framework for Contrast Processing of High Dynamic Range Images", ACM Transactions on Applied Perception, 2006, 3, 3, 286 - 308.
-
-.. [GW03] G. Ward, "Fast, Robust Image Registration for Compositing High Dynamic Range Photographs from Handheld Exposures", Journal of Graphics Tools, 2003, 8, 17 - 30.
-
-.. [DM97] P. Debevec, J. Malik, "Recovering High Dynamic Range Radiance Maps from Photographs", Proceedings OF ACM SIGGRAPH, 1997, 369 - 378.
-
-.. [MK07] T. Mertens, J. Kautz, F. Van Reeth, "Exposure Fusion", Proceedings of the 15th Pacific Conference on Computer Graphics and Applications, 2007, 382 - 390.
-
-.. [RB99] M. Robertson , S. Borman , R. Stevenson , "Dynamic range improvement through multiple exposures ", Proceedings of the Int. Conf. on Image Processing , 1999, 159 - 163.
+++ /dev/null
-Inpainting
-==========
-
-.. highlight:: cpp
-
-inpaint
------------
-Restores the selected region in an image using the region neighborhood.
-
-.. ocv:function:: void inpaint( InputArray src, InputArray inpaintMask, OutputArray dst, double inpaintRadius, int flags )
-
-.. ocv:pyfunction:: cv2.inpaint(src, inpaintMask, inpaintRadius, flags[, dst]) -> dst
-
-.. ocv:cfunction:: void cvInpaint( const CvArr* src, const CvArr* inpaint_mask, CvArr* dst, double inpaintRange, int flags )
-
- :param src: Input 8-bit 1-channel or 3-channel image.
-
- :param inpaintMask: Inpainting mask, 8-bit 1-channel image. Non-zero pixels indicate the area that needs to be inpainted.
-
- :param dst: Output image with the same size and type as ``src`` .
-
- :param inpaintRadius: Radius of a circular neighborhood of each point inpainted that is considered by the algorithm.
-
- :param flags: Inpainting method that could be one of the following:
-
- * **INPAINT_NS** Navier-Stokes based method [Navier01]
-
- * **INPAINT_TELEA** Method by Alexandru Telea [Telea04]_.
-
-The function reconstructs the selected image area from the pixel near the area boundary. The function may be used to remove dust and scratches from a scanned photo, or to remove undesirable objects from still images or video. See
-http://en.wikipedia.org/wiki/Inpainting
-for more details.
-
-.. note::
-
- * An example using the inpainting technique can be found at opencv_source_code/samples/cpp/inpaint.cpp
-
- * (Python) An example using the inpainting technique can be found at opencv_source_code/samples/python2/inpaint.py
-
-
-.. [Telea04] Telea, Alexandru. "An image inpainting technique based on the fast marching method." Journal of graphics tools 9, no. 1 (2004): 23-34.
-
-.. [Navier01] Bertalmio, Marcelo, Andrea L. Bertozzi, and Guillermo Sapiro. "Navier-stokes, fluid dynamics, and image and video inpainting." In Computer Vision and Pattern Recognition, 2001. CVPR 2001. Proceedings of the 2001 IEEE Computer Society Conference on, vol. 1, pp. I-355. IEEE, 2001.
+++ /dev/null
-Non-Photorealistic Rendering
-============================
-
-.. highlight:: cpp
-
-edgePreservingFilter
---------------------
-
-Filtering is the fundamental operation in image and video processing. Edge-preserving smoothing filters are used in many different applications [EM11]_.
-
-.. ocv:function:: void edgePreservingFilter(InputArray src, OutputArray dst, int flags = 1, float sigma_s = 60, float sigma_r = 0.4f)
-
- :param src: Input 8-bit 3-channel image.
-
- :param dst: Output 8-bit 3-channel image.
-
- :param flags: Edge preserving filters:
-
- * **RECURS_FILTER** = 1
-
- * **NORMCONV_FILTER** = 2
-
- :param sigma_s: Range between 0 to 200.
-
- :param sigma_r: Range between 0 to 1.
-
-
-detailEnhance
--------------
-This filter enhances the details of a particular image.
-
-.. ocv:function:: void detailEnhance(InputArray src, OutputArray dst, float sigma_s = 10, float sigma_r = 0.15f)
-
- :param src: Input 8-bit 3-channel image.
-
- :param dst: Output image with the same size and type as ``src``.
-
- :param sigma_s: Range between 0 to 200.
-
- :param sigma_r: Range between 0 to 1.
-
-
-pencilSketch
-------------
-Pencil-like non-photorealistic line drawing
-
-.. ocv:function:: void pencilSketch(InputArray src, OutputArray dst1, OutputArray dst2, float sigma_s = 60, float sigma_r = 0.07f, float shade_factor = 0.02f)
-
- :param src: Input 8-bit 3-channel image.
-
- :param dst1: Output 8-bit 1-channel image.
-
- :param dst2: Output image with the same size and type as ``src``.
-
- :param sigma_s: Range between 0 to 200.
-
- :param sigma_r: Range between 0 to 1.
-
- :param shade_factor: Range between 0 to 0.1.
-
-
-stylization
------------
-Stylization aims to produce digital imagery with a wide variety of effects not focused on photorealism. Edge-aware filters are ideal for stylization, as they can abstract regions of low contrast while preserving, or enhancing, high-contrast features.
-
-.. ocv:function:: void stylization(InputArray src, OutputArray dst, float sigma_s = 60, float sigma_r = 0.45f)
-
- :param src: Input 8-bit 3-channel image.
-
- :param dst: Output image with the same size and type as ``src``.
-
- :param sigma_s: Range between 0 to 200.
-
- :param sigma_r: Range between 0 to 1.
-
-.. [EM11] Eduardo S. L. Gastal, Manuel M. Oliveira, "Domain transform for edge-aware image and video processing", ACM Trans. Graph. 30(4): 69, 2011.
+++ /dev/null
-********************************
-photo. Computational Photography
-********************************
-
-.. highlight:: cpp
-
-.. toctree::
- :maxdepth: 2
-
- inpainting
- denoising
- hdr_imaging
- decolor
- cloning
- npr
+++ /dev/null
-############################
-OpenCV API Reference
-############################
-
-.. toctree::
- :maxdepth: 2
-
- core/doc/intro.rst
-@OPENCV_REFMAN_TOC@
+++ /dev/null
-EMD-L1
-======
-Computes the "minimal work" distance between two weighted point configurations base on the papers "EMD-L1: An efficient and Robust Algorithm
-for comparing histogram-based descriptors", by Haibin Ling and Kazunori Okuda; and "The Earth Mover's Distance is the Mallows Distance:
-Some Insights from Statistics", by Elizaveta Levina and Peter Bickel.
-
-.. ocv:function:: float EMDL1( InputArray signature1, InputArray signature2 )
-
- :param signature1: First signature, a single column floating-point matrix. Each row is the value of the histogram in each bin.
-
- :param signature2: Second signature of the same format and size as ``signature1``.
+++ /dev/null
-Cost Matrix for Histograms Common Interface
-===========================================
-
-.. highlight:: cpp
-
-A common interface is defined to ease the implementation of some algorithms pipelines, such
-as the Shape Context Matching Algorithm. A common class is defined, so any object that implements
-a Cost Matrix builder inherits the
-:ocv:class:`HistogramCostExtractor` interface.
-
-HistogramCostExtractor
-----------------------
-.. ocv:class:: HistogramCostExtractor : public Algorithm
-
-Abstract base class for histogram cost algorithms. ::
-
- class CV_EXPORTS_W HistogramCostExtractor : public Algorithm
- {
- public:
- CV_WRAP virtual void buildCostMatrix(InputArray descriptors1, InputArray descriptors2, OutputArray costMatrix) = 0;
-
- CV_WRAP virtual void setNDummies(int nDummies) = 0;
- CV_WRAP virtual int getNDummies() const = 0;
-
- CV_WRAP virtual void setDefaultCost(float defaultCost) = 0;
- CV_WRAP virtual float getDefaultCost() const = 0;
- };
-
-NormHistogramCostExtractor
---------------------------
-.. ocv:class:: NormHistogramCostExtractor : public HistogramCostExtractor
-
-A norm based cost extraction. ::
-
- class CV_EXPORTS_W NormHistogramCostExtractor : public HistogramCostExtractor
- {
- public:
- CV_WRAP virtual void setNormFlag(int flag) = 0;
- CV_WRAP virtual int getNormFlag() const = 0;
- };
-
- CV_EXPORTS_W Ptr<HistogramCostExtractor>
- createNormHistogramCostExtractor(int flag=cv::DIST_L2, int nDummies=25, float defaultCost=0.2);
-
-EMDHistogramCostExtractor
--------------------------
-.. ocv:class:: EMDHistogramCostExtractor : public HistogramCostExtractor
-
-An EMD based cost extraction. ::
-
- class CV_EXPORTS_W EMDHistogramCostExtractor : public HistogramCostExtractor
- {
- public:
- CV_WRAP virtual void setNormFlag(int flag) = 0;
- CV_WRAP virtual int getNormFlag() const = 0;
- };
-
- CV_EXPORTS_W Ptr<HistogramCostExtractor>
- createEMDHistogramCostExtractor(int flag=cv::DIST_L2, int nDummies=25, float defaultCost=0.2);
-
-ChiHistogramCostExtractor
--------------------------
-.. ocv:class:: ChiHistogramCostExtractor : public HistogramCostExtractor
-
-An Chi based cost extraction. ::
-
- class CV_EXPORTS_W ChiHistogramCostExtractor : public HistogramCostExtractor
- {};
-
- CV_EXPORTS_W Ptr<HistogramCostExtractor> createChiHistogramCostExtractor(int nDummies=25, float defaultCost=0.2);
-
-EMDL1HistogramCostExtractor
----------------------------
-.. ocv:class:: EMDL1HistogramCostExtractor : public HistogramCostExtractor
-
-An EMD-L1 based cost extraction. ::
-
- class CV_EXPORTS_W EMDL1HistogramCostExtractor : public HistogramCostExtractor
- {};
-
- CV_EXPORTS_W Ptr<HistogramCostExtractor>
- createEMDL1HistogramCostExtractor(int nDummies=25, float defaultCost=0.2);
+++ /dev/null
-**********************************
-shape. Shape Distance and Matching
-**********************************
-
-The module contains algorithms that embed a notion of shape distance.
-These algorithms may be used for shape matching and retrieval, or shape
-comparison.
-
-.. toctree::
- :maxdepth: 2
-
- shape_distances
- shape_transformers
- histogram_cost_matrix
- emdL1
+++ /dev/null
-Shape Distance and Common Interfaces
-====================================
-
-.. highlight:: cpp
-
-Shape Distance algorithms in OpenCV are derivated from a common interface that allows you to
-switch between them in a practical way for solving the same problem with different methods.
-Thus, all objects that implement shape distance measures inherit the
-:ocv:class:`ShapeDistanceExtractor` interface.
-
-
-ShapeDistanceExtractor
-----------------------
-.. ocv:class:: ShapeDistanceExtractor : public Algorithm
-
-Abstract base class for shape distance algorithms. ::
-
- class CV_EXPORTS_W ShapeDistanceExtractor : public Algorithm
- {
- public:
- CV_WRAP virtual float computeDistance(InputArray contour1, InputArray contour2) = 0;
- };
-
-ShapeDistanceExtractor::computeDistance
----------------------------------------
-Compute the shape distance between two shapes defined by its contours.
-
-.. ocv:function:: float ShapeDistanceExtractor::computeDistance( InputArray contour1, InputArray contour2 )
-
- :param contour1: Contour defining first shape.
-
- :param contour2: Contour defining second shape.
-
-ShapeContextDistanceExtractor
------------------------------
-.. ocv:class:: ShapeContextDistanceExtractor : public ShapeDistanceExtractor
-
-Implementation of the Shape Context descriptor and matching algorithm proposed by Belongie et al. in
-"Shape Matching and Object Recognition Using Shape Contexts" (PAMI 2002).
-This implementation is packaged in a generic scheme, in order to allow you the implementation of the
-common variations of the original pipeline. ::
-
- class CV_EXPORTS_W ShapeContextDistanceExtractor : public ShapeDistanceExtractor
- {
- public:
- CV_WRAP virtual void setAngularBins(int nAngularBins) = 0;
- CV_WRAP virtual int getAngularBins() const = 0;
-
- CV_WRAP virtual void setRadialBins(int nRadialBins) = 0;
- CV_WRAP virtual int getRadialBins() const = 0;
-
- CV_WRAP virtual void setInnerRadius(float innerRadius) = 0;
- CV_WRAP virtual float getInnerRadius() const = 0;
-
- CV_WRAP virtual void setOuterRadius(float outerRadius) = 0;
- CV_WRAP virtual float getOuterRadius() const = 0;
-
- CV_WRAP virtual void setRotationInvariant(bool rotationInvariant) = 0;
- CV_WRAP virtual bool getRotationInvariant() const = 0;
-
- CV_WRAP virtual void setShapeContextWeight(float shapeContextWeight) = 0;
- CV_WRAP virtual float getShapeContextWeight() const = 0;
-
- CV_WRAP virtual void setImageAppearanceWeight(float imageAppearanceWeight) = 0;
- CV_WRAP virtual float getImageAppearanceWeight() const = 0;
-
- CV_WRAP virtual void setBendingEnergyWeight(float bendingEnergyWeight) = 0;
- CV_WRAP virtual float getBendingEnergyWeight() const = 0;
-
- CV_WRAP virtual void setImages(InputArray image1, InputArray image2) = 0;
- CV_WRAP virtual void getImages(OutputArray image1, OutputArray image2) const = 0;
-
- CV_WRAP virtual void setIterations(int iterations) = 0;
- CV_WRAP virtual int getIterations() const = 0;
-
- CV_WRAP virtual void setCostExtractor(Ptr<HistogramCostExtractor> comparer) = 0;
- CV_WRAP virtual Ptr<HistogramCostExtractor> getCostExtractor() const = 0;
-
- CV_WRAP virtual void setTransformAlgorithm(Ptr<ShapeTransformer> transformer) = 0;
- CV_WRAP virtual Ptr<ShapeTransformer> getTransformAlgorithm() const = 0;
- };
-
- /* Complete constructor */
- CV_EXPORTS_W Ptr<ShapeContextDistanceExtractor>
- createShapeContextDistanceExtractor(int nAngularBins=12, int nRadialBins=4,
- float innerRadius=0.2, float outerRadius=2, int iterations=3,
- const Ptr<HistogramCostExtractor> &comparer = createChiHistogramCostExtractor(),
- const Ptr<ShapeTransformer> &transformer = createThinPlateSplineShapeTransformer());
-
-ShapeContextDistanceExtractor::setAngularBins
----------------------------------------------
-Establish the number of angular bins for the Shape Context Descriptor used in the shape matching pipeline.
-
-.. ocv:function:: void setAngularBins( int nAngularBins )
-
- :param nAngularBins: The number of angular bins in the shape context descriptor.
-
-ShapeContextDistanceExtractor::setRadialBins
---------------------------------------------
-Establish the number of radial bins for the Shape Context Descriptor used in the shape matching pipeline.
-
-.. ocv:function:: void setRadialBins( int nRadialBins )
-
- :param nRadialBins: The number of radial bins in the shape context descriptor.
-
-ShapeContextDistanceExtractor::setInnerRadius
----------------------------------------------
-Set the inner radius of the shape context descriptor.
-
-.. ocv:function:: void setInnerRadius(float innerRadius)
-
- :param innerRadius: The value of the inner radius.
-
-ShapeContextDistanceExtractor::setOuterRadius
----------------------------------------------
-Set the outer radius of the shape context descriptor.
-
-.. ocv:function:: void setOuterRadius(float outerRadius)
-
- :param outerRadius: The value of the outer radius.
-
-ShapeContextDistanceExtractor::setShapeContextWeight
-----------------------------------------------------
-Set the weight of the shape context distance in the final value of the shape distance.
-The shape context distance between two shapes is defined as the symmetric sum of shape
-context matching costs over best matching points.
-The final value of the shape distance is a user-defined linear combination of the shape
-context distance, an image appearance distance, and a bending energy.
-
-.. ocv:function:: void setShapeContextWeight( float shapeContextWeight )
-
- :param shapeContextWeight: The weight of the shape context distance in the final distance value.
-
-ShapeContextDistanceExtractor::setImageAppearanceWeight
--------------------------------------------------------
-Set the weight of the Image Appearance cost in the final value of the shape distance.
-The image appearance cost is defined as the sum of squared brightness differences in
-Gaussian windows around corresponding image points.
-The final value of the shape distance is a user-defined linear combination of the shape
-context distance, an image appearance distance, and a bending energy.
-If this value is set to a number different from 0, is mandatory to set the images that
-correspond to each shape.
-
-.. ocv:function:: void setImageAppearanceWeight( float imageAppearanceWeight )
-
- :param imageAppearanceWeight: The weight of the appearance cost in the final distance value.
-
-ShapeContextDistanceExtractor::setBendingEnergyWeight
------------------------------------------------------
-Set the weight of the Bending Energy in the final value of the shape distance.
-The bending energy definition depends on what transformation is being used to align the
-shapes.
-The final value of the shape distance is a user-defined linear combination of the shape
-context distance, an image appearance distance, and a bending energy.
-
-.. ocv:function:: void setBendingEnergyWeight( float bendingEnergyWeight )
-
- :param bendingEnergyWeight: The weight of the Bending Energy in the final distance value.
-
-ShapeContextDistanceExtractor::setImages
-----------------------------------------
-Set the images that correspond to each shape. This images are used in the calculation of the
-Image Appearance cost.
-
-.. ocv:function:: void setImages( InputArray image1, InputArray image2 )
-
- :param image1: Image corresponding to the shape defined by ``contours1``.
-
- :param image2: Image corresponding to the shape defined by ``contours2``.
-
-ShapeContextDistanceExtractor::setCostExtractor
------------------------------------------------
-Set the algorithm used for building the shape context descriptor cost matrix.
-
-.. ocv:function:: void setCostExtractor( Ptr<HistogramCostExtractor> comparer )
-
- :param comparer: Smart pointer to a HistogramCostExtractor, an algorithm that defines the cost matrix between descriptors.
-
-ShapeContextDistanceExtractor::setStdDev
-----------------------------------------
-Set the value of the standard deviation for the Gaussian window for the image appearance cost.
-
-.. ocv:function:: void setStdDev( float sigma )
-
- :param sigma: Standard Deviation.
-
-ShapeContextDistanceExtractor::setTransformAlgorithm
-----------------------------------------------------
-Set the algorithm used for aligning the shapes.
-
-.. ocv:function:: void setTransformAlgorithm( Ptr<ShapeTransformer> transformer )
-
- :param comparer: Smart pointer to a ShapeTransformer, an algorithm that defines the aligning transformation.
-
-HausdorffDistanceExtractor
---------------------------
-.. ocv:class:: HausdorffDistanceExtractor : public ShapeDistanceExtractor
-
-A simple Hausdorff distance measure between shapes defined by contours,
-according to the paper "Comparing Images using the Hausdorff distance." by
-D.P. Huttenlocher, G.A. Klanderman, and W.J. Rucklidge. (PAMI 1993). ::
-
- class CV_EXPORTS_W HausdorffDistanceExtractor : public ShapeDistanceExtractor
- {
- public:
- CV_WRAP virtual void setDistanceFlag(int distanceFlag) = 0;
- CV_WRAP virtual int getDistanceFlag() const = 0;
-
- CV_WRAP virtual void setRankProportion(float rankProportion) = 0;
- CV_WRAP virtual float getRankProportion() const = 0;
- };
-
- /* Constructor */
- CV_EXPORTS_W Ptr<HausdorffDistanceExtractor> createHausdorffDistanceExtractor(int distanceFlag=cv::NORM_L2, float rankProp=0.6);
-
-HausdorffDistanceExtractor::setDistanceFlag
--------------------------------------------
-Set the norm used to compute the Hausdorff value between two shapes. It can be L1 or L2 norm.
-
-.. ocv:function:: void setDistanceFlag( int distanceFlag )
-
- :param distanceFlag: Flag indicating which norm is used to compute the Hausdorff distance (NORM_L1, NORM_L2).
-
-HausdorffDistanceExtractor::setRankProportion
----------------------------------------------
-This method sets the rank proportion (or fractional value) that establish the Kth ranked value of the
-partial Hausdorff distance. Experimentally had been shown that 0.6 is a good value to compare shapes.
-
-.. ocv:function:: void setRankProportion( float rankProportion )
-
- :param rankProportion: fractional value (between 0 and 1).
+++ /dev/null
-Shape Transformers and Interfaces
-=================================
-
-.. highlight:: cpp
-
-A virtual interface that ease the use of transforming algorithms in some pipelines, such as
-the Shape Context Matching Algorithm. Thus, all objects that implement shape transformation
-techniques inherit the
-:ocv:class:`ShapeTransformer` interface.
-
-ShapeTransformer
-----------------
-.. ocv:class:: ShapeTransformer : public Algorithm
-
-Abstract base class for shape transformation algorithms. ::
-
- class CV_EXPORTS_W ShapeTransformer : public Algorithm
- {
- public:
- CV_WRAP virtual void estimateTransformation(InputArray transformingShape, InputArray targetShape,
- std::vector<DMatch>& matches) = 0;
-
- CV_WRAP virtual float applyTransformation(InputArray input, OutputArray output=noArray()) = 0;
-
- CV_WRAP virtual void warpImage(InputArray transformingImage, OutputArray output,
- int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT,
- const Scalar& borderValue=Scalar()) const = 0;
- };
-
-ShapeTransformer::estimateTransformation
-----------------------------------------
-Estimate the transformation parameters of the current transformer algorithm, based on point matches.
-
-.. ocv:function:: void estimateTransformation( InputArray transformingShape, InputArray targetShape, std::vector<DMatch>& matches )
-
- :param transformingShape: Contour defining first shape.
-
- :param targetShape: Contour defining second shape (Target).
-
- :param matches: Standard vector of Matches between points.
-
-ShapeTransformer::applyTransformation
--------------------------------------
-Apply a transformation, given a pre-estimated transformation parameters.
-
-.. ocv:function:: float applyTransformation( InputArray input, OutputArray output=noArray() )
-
- :param input: Contour (set of points) to apply the transformation.
-
- :param output: Output contour.
-
-ShapeTransformer::warpImage
----------------------------
-Apply a transformation, given a pre-estimated transformation parameters, to an Image.
-
-.. ocv:function:: void warpImage( InputArray transformingImage, OutputArray output, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar& borderValue=Scalar() )
-
- :param transformingImage: Input image.
-
- :param output: Output image.
-
- :param flags: Image interpolation method.
-
- :param borderMode: border style.
-
- :param borderValue: border value.
-
-ThinPlateSplineShapeTransformer
--------------------------------
-.. ocv:class:: ThinPlateSplineShapeTransformer : public Algorithm
-
-Definition of the transformation ocupied in the paper "Principal Warps: Thin-Plate Splines and Decomposition
-of Deformations", by F.L. Bookstein (PAMI 1989). ::
-
- class CV_EXPORTS_W ThinPlateSplineShapeTransformer : public ShapeTransformer
- {
- public:
- CV_WRAP virtual void setRegularizationParameter(double beta) = 0;
- CV_WRAP virtual double getRegularizationParameter() const = 0;
- };
-
- /* Complete constructor */
- CV_EXPORTS_W Ptr<ThinPlateSplineShapeTransformer>
- createThinPlateSplineShapeTransformer(double regularizationParameter=0);
-
-ThinPlateSplineShapeTransformer::setRegularizationParameter
------------------------------------------------------------
-Set the regularization parameter for relaxing the exact interpolation requirements of the TPS algorithm.
-
-.. ocv:function:: void setRegularizationParameter( double beta )
-
- :param beta: value of the regularization parameter.
-
-AffineTransformer
------------------
-.. ocv:class:: AffineTransformer : public Algorithm
-
-Wrapper class for the OpenCV Affine Transformation algorithm. ::
-
- class CV_EXPORTS_W AffineTransformer : public ShapeTransformer
- {
- public:
- CV_WRAP virtual void setFullAffine(bool fullAffine) = 0;
- CV_WRAP virtual bool getFullAffine() const = 0;
- };
-
- /* Complete constructor */
- CV_EXPORTS_W Ptr<AffineTransformer> createAffineTransformer(bool fullAffine);
+++ /dev/null
-Autocalibration
-===============
-
-.. highlight:: cpp
-
-detail::focalsFromHomography
-----------------------------
-Tries to estimate focal lengths from the given homography under the assumption that the camera undergoes rotations around its centre only.
-
-.. ocv:function:: void detail::focalsFromHomography(const Mat &H, double &f0, double &f1, bool &f0_ok, bool &f1_ok)
-
- :param H: Homography.
-
- :param f0: Estimated focal length along X axis.
-
- :param f1: Estimated focal length along Y axis.
-
- :param f0_ok: True, if f0 was estimated successfully, false otherwise.
-
- :param f1_ok: True, if f1 was estimated successfully, false otherwise.
-
-detail::estimateFocal
----------------------
-Estimates focal lengths for each given camera.
-
-.. ocv:function:: void detail::estimateFocal(const std::vector<ImageFeatures> &features, const std::vector<MatchesInfo> &pairwise_matches, std::vector<double> &focals)
-
- :param features: Features of images.
-
- :param pairwise_matches: Matches between all image pairs.
-
- :param focals: Estimated focal lengths for each camera.
+++ /dev/null
-Image Blenders
-==============
-
-.. highlight:: cpp
-
-detail::Blender
----------------
-.. ocv:class:: detail::Blender
-
-Base class for all blenders. ::
-
- class CV_EXPORTS Blender
- {
- public:
- virtual ~Blender() {}
-
- enum { NO, FEATHER, MULTI_BAND };
- static Ptr<Blender> createDefault(int type, bool try_gpu = false);
-
- void prepare(const std::vector<Point> &corners, const std::vector<Size> &sizes);
- virtual void prepare(Rect dst_roi);
- virtual void feed(const Mat &img, const Mat &mask, Point tl);
- virtual void blend(Mat &dst, Mat &dst_mask);
-
- protected:
- Mat dst_, dst_mask_;
- Rect dst_roi_;
- };
-
-detail::Blender::prepare
-------------------------
-
-Prepares the blender for blending.
-
-.. ocv:function:: void detail::Blender::prepare(const std::vector<Point> &corners, const std::vector<Size> &sizes)
-
- :param corners: Source images top-left corners
-
- :param sizes: Source image sizes
-
-detail::Blender::feed
----------------------
-
-Processes the image.
-
-.. ocv:function:: void detail::Blender::feed(InputArray img, InputArray mask, Point tl)
-
- :param img: Source image
-
- :param mask: Source image mask
-
- :param tl: Source image top-left corners
-
-detail::Blender::blend
-----------------------
-
-Blends and returns the final pano.
-
-.. ocv:function:: void detail::Blender::blend(InputOutputArray dst, InputOutputArray dst_mask)
-
- :param dst: Final pano
-
- :param dst_mask: Final pano mask
-
-detail::FeatherBlender
-----------------------
-.. ocv:class:: detail::FeatherBlender : public detail::Blender
-
-Simple blender which mixes images at its borders. ::
-
- class CV_EXPORTS FeatherBlender : public Blender
- {
- public:
- FeatherBlender(float sharpness = 0.02f) { setSharpness(sharpness); }
-
- float sharpness() const { return sharpness_; }
- void setSharpness(float val) { sharpness_ = val; }
-
- void prepare(Rect dst_roi);
- void feed(const Mat &img, const Mat &mask, Point tl);
- void blend(Mat &dst, Mat &dst_mask);
-
- // Creates weight maps for fixed set of source images by their masks and top-left corners.
- // Final image can be obtained by simple weighting of the source images.
- Rect createWeightMaps(const std::vector<Mat> &masks, const std::vector<Point> &corners,
- std::vector<Mat> &weight_maps);
-
- private:
- /* hidden */
- };
-
-.. seealso:: :ocv:class:`detail::Blender`
-
-detail::MultiBandBlender
-------------------------
-.. ocv:class:: detail::MultiBandBlender : public detail::Blender
-
-Blender which uses multi-band blending algorithm (see [BA83]_). ::
-
- class CV_EXPORTS MultiBandBlender : public Blender
- {
- public:
- MultiBandBlender(int try_gpu = false, int num_bands = 5);
- int numBands() const { return actual_num_bands_; }
- void setNumBands(int val) { actual_num_bands_ = val; }
-
- void prepare(Rect dst_roi);
- void feed(const Mat &img, const Mat &mask, Point tl);
- void blend(Mat &dst, Mat &dst_mask);
-
- private:
- /* hidden */
- };
-
-.. seealso:: :ocv:class:`detail::Blender`
+++ /dev/null
-Camera
-======
-
-.. highlight:: cpp
-
-detail::CameraParams
---------------------
-.. ocv:struct:: detail::CameraParams
-
-Describes camera parameters.
-
-.. note:: Translation is assumed to be zero during the whole stitching pipeline.
-
-::
-
- struct CV_EXPORTS CameraParams
- {
- CameraParams();
- CameraParams(const CameraParams& other);
- const CameraParams& operator =(const CameraParams& other);
- Mat K() const;
-
- double focal; // Focal length
- double aspect; // Aspect ratio
- double ppx; // Principal point X
- double ppy; // Principal point Y
- Mat R; // Rotation
- Mat t; // Translation
- };
+++ /dev/null
-Exposure Compensation
-=====================
-
-.. highlight:: cpp
-
-detail::ExposureCompensator
-----------------------------
-.. ocv:class:: detail::ExposureCompensator
-
-Base class for all exposure compensators. ::
-
- class CV_EXPORTS ExposureCompensator
- {
- public:
- virtual ~ExposureCompensator() {}
-
- enum { NO, GAIN, GAIN_BLOCKS };
- static Ptr<ExposureCompensator> createDefault(int type);
-
- void feed(const std::vector<Point> &corners, const std::vector<Mat> &images,
- const std::vector<Mat> &masks);
- virtual void feed(const std::vector<Point> &corners, const std::vector<Mat> &images,
- const std::vector<std::pair<Mat,uchar> > &masks) = 0;
- virtual void apply(int index, Point corner, Mat &image, const Mat &mask) = 0;
- };
-
-detail::ExposureCompensator::feed
-----------------------------------
-
-.. ocv:function:: void detail::ExposureCompensator::feed(const std::vector<Point> &corners, const std::vector<UMat> &images, const std::vector<UMat> &masks)
-
-.. ocv:function:: void detail::ExposureCompensator::feed(const std::vector<Point> &corners, const std::vector<UMat> &images, const std::vector<std::pair<UMat,uchar> > &masks)
-
- :param corners: Source image top-left corners
-
- :param images: Source images
-
- :param masks: Image masks to update (second value in pair specifies the value which should be used to detect where image is)
-
-detil::ExposureCompensator::apply
-----------------------------------
-
-Compensate exposure in the specified image.
-
-.. ocv:function:: void detail::ExposureCompensator::apply(int index, Point corner, InputOutputArray image, InputArray mask)
-
- :param index: Image index
-
- :param corner: Image top-left corner
-
- :param image: Image to process
-
- :param mask: Image mask
-
-detail::NoExposureCompensator
------------------------------
-.. ocv:class:: detail::NoExposureCompensator : public detail::ExposureCompensator
-
-Stub exposure compensator which does nothing. ::
-
- class CV_EXPORTS NoExposureCompensator : public ExposureCompensator
- {
- public:
- void feed(const std::vector<Point> &/*corners*/, const std::vector<Mat> &/*images*/,
- const std::vector<std::pair<Mat,uchar> > &/*masks*/) { }
- void apply(int /*index*/, Point /*corner*/, Mat &/*image*/, const Mat &/*mask*/) { }
- };
-
-.. seealso:: :ocv:class:`detail::ExposureCompensator`
-
-detail::GainCompensator
------------------------
-.. ocv:class:: detail::GainCompensator : public detail::ExposureCompensator
-
-Exposure compensator which tries to remove exposure related artifacts by adjusting image intensities, see [BL07]_ and [WJ10]_ for details. ::
-
- class CV_EXPORTS GainCompensator : public ExposureCompensator
- {
- public:
- void feed(const std::vector<Point> &corners, const std::vector<Mat> &images,
- const std::vector<std::pair<Mat,uchar> > &masks);
- void apply(int index, Point corner, Mat &image, const Mat &mask);
- std::vector<double> gains() const;
-
- private:
- /* hidden */
- };
-
-.. seealso:: :ocv:class:`detail::ExposureCompensator`
-
-detail::BlocksGainCompensator
------------------------------
-.. ocv:class:: detail::BlocksGainCompensator : public detail::ExposureCompensator
-
-Exposure compensator which tries to remove exposure related artifacts by adjusting image block intensities, see [UES01]_ for details. ::
-
- class CV_EXPORTS BlocksGainCompensator : public ExposureCompensator
- {
- public:
- BlocksGainCompensator(int bl_width = 32, int bl_height = 32)
- : bl_width_(bl_width), bl_height_(bl_height) {}
- void feed(const std::vector<Point> &corners, const std::vector<Mat> &images,
- const std::vector<std::pair<Mat,uchar> > &masks);
- void apply(int index, Point corner, Mat &image, const Mat &mask);
-
- private:
- /* hidden */
- };
-
-.. seealso:: :ocv:class:`detail::ExposureCompensator`
+++ /dev/null
-High Level Functionality
-========================
-
-.. highlight:: cpp
-
-Stitcher
---------
-.. ocv:class:: Stitcher
-
-High level image stitcher. It's possible to use this class without being aware of the entire stitching pipeline. However, to be able to achieve higher stitching stability and quality of the final images at least being familiar with the theory is recommended (see :ref:`stitching-pipeline`). ::
-
- class CV_EXPORTS Stitcher
- {
- public:
- enum { ORIG_RESOL = -1 };
- enum Status { OK, ERR_NEED_MORE_IMGS };
-
- // Creates stitcher with default parameters
- static Stitcher createDefault(bool try_use_gpu = false);
-
- Status estimateTransform(InputArray images);
- Status estimateTransform(InputArray images, const std::vector<std::vector<Rect> > &rois);
-
- Status composePanorama(OutputArray pano);
- Status composePanorama(InputArray images, OutputArray pano);
-
- Status stitch(InputArray images, OutputArray pano);
- Status stitch(InputArray images, const std::vector<std::vector<Rect> > &rois, OutputArray pano);
-
- double registrationResol() const { return registr_resol_; }
- void setRegistrationResol(double resol_mpx) { registr_resol_ = resol_mpx; }
-
- double seamEstimationResol() const { return seam_est_resol_; }
- void setSeamEstimationResol(double resol_mpx) { seam_est_resol_ = resol_mpx; }
-
- double compositingResol() const { return compose_resol_; }
- void setCompositingResol(double resol_mpx) { compose_resol_ = resol_mpx; }
-
- double panoConfidenceThresh() const { return conf_thresh_; }
- void setPanoConfidenceThresh(double conf_thresh) { conf_thresh_ = conf_thresh; }
-
- bool waveCorrection() const { return do_wave_correct_; }
- void setWaveCorrection(bool flag) { do_wave_correct_ = flag; }
-
- detail::WaveCorrectKind waveCorrectKind() const { return wave_correct_kind_; }
- void setWaveCorrectKind(detail::WaveCorrectKind kind) { wave_correct_kind_ = kind; }
-
- Ptr<detail::FeaturesFinder> featuresFinder() { return features_finder_; }
- const Ptr<detail::FeaturesFinder> featuresFinder() const { return features_finder_; }
- void setFeaturesFinder(Ptr<detail::FeaturesFinder> features_finder)
- { features_finder_ = features_finder; }
-
- Ptr<detail::FeaturesMatcher> featuresMatcher() { return features_matcher_; }
- const Ptr<detail::FeaturesMatcher> featuresMatcher() const { return features_matcher_; }
- void setFeaturesMatcher(Ptr<detail::FeaturesMatcher> features_matcher)
- { features_matcher_ = features_matcher; }
-
- const cv::Mat& matchingMask() const { return matching_mask_; }
- void setMatchingMask(const cv::Mat &mask)
- {
- CV_Assert(mask.type() == CV_8U && mask.cols == mask.rows);
- matching_mask_ = mask.clone();
- }
-
- Ptr<detail::BundleAdjusterBase> bundleAdjuster() { return bundle_adjuster_; }
- const Ptr<detail::BundleAdjusterBase> bundleAdjuster() const { return bundle_adjuster_; }
- void setBundleAdjuster(Ptr<detail::BundleAdjusterBase> bundle_adjuster)
- { bundle_adjuster_ = bundle_adjuster; }
-
- Ptr<WarperCreator> warper() { return warper_; }
- const Ptr<WarperCreator> warper() const { return warper_; }
- void setWarper(Ptr<WarperCreator> warper) { warper_ = warper; }
-
- Ptr<detail::ExposureCompensator> exposureCompensator() { return exposure_comp_; }
- const Ptr<detail::ExposureCompensator> exposureCompensator() const { return exposure_comp_; }
- void setExposureCompensator(Ptr<detail::ExposureCompensator> exposure_comp)
- { exposure_comp_ = exposure_comp; }
-
- Ptr<detail::SeamFinder> seamFinder() { return seam_finder_; }
- const Ptr<detail::SeamFinder> seamFinder() const { return seam_finder_; }
- void setSeamFinder(Ptr<detail::SeamFinder> seam_finder) { seam_finder_ = seam_finder; }
-
- Ptr<detail::Blender> blender() { return blender_; }
- const Ptr<detail::Blender> blender() const { return blender_; }
- void setBlender(Ptr<detail::Blender> blender) { blender_ = blender; }
-
- private:
- /* hidden */
- };
-
-.. note::
-
- * A basic example on image stitching can be found at opencv_source_code/samples/cpp/stitching.cpp
- * A detailed example on image stitching can be found at opencv_source_code/samples/cpp/stitching_detailed.cpp
-
-Stitcher::createDefault
------------------------
-Creates a stitcher with the default parameters.
-
-.. ocv:function:: Stitcher Stitcher::createDefault(bool try_use_gpu = false)
-
- :param try_use_gpu: Flag indicating whether GPU should be used whenever it's possible.
-
- :return: Stitcher class instance.
-
-Stitcher::estimateTransform
----------------------------
-
-These functions try to match the given images and to estimate rotations of each camera.
-
-.. note:: Use the functions only if you're aware of the stitching pipeline, otherwise use :ocv:func:`Stitcher::stitch`.
-
-.. ocv:function:: Status Stitcher::estimateTransform(InputArrayOfArrays images)
-
-.. ocv:function:: Status Stitcher::estimateTransform(InputArrayOfArrays images, const std::vector<std::vector<Rect> > &rois)
-
- :param images: Input images.
-
- :param rois: Region of interest rectangles.
-
- :return: Status code.
-
-Stitcher::composePanorama
--------------------------
-
-These functions try to compose the given images (or images stored internally from the other function calls) into the final pano under the assumption that the image transformations were estimated before.
-
-.. note:: Use the functions only if you're aware of the stitching pipeline, otherwise use :ocv:func:`Stitcher::stitch`.
-
-.. ocv:function:: Status Stitcher::composePanorama(OutputArray pano)
-
-.. ocv:function:: Status Stitcher::composePanorama(InputArrayOfArrays images, OutputArray pano)
-
- :param images: Input images.
-
- :param pano: Final pano.
-
- :return: Status code.
-
-Stitcher::stitch
-----------------
-
-These functions try to stitch the given images.
-
-.. ocv:function:: Status Stitcher::stitch(InputArrayOfArrays images, OutputArray pano)
-
-.. ocv:function:: Status Stitcher::stitch(InputArrayOfArrays images, const std::vector<std::vector<Rect> > &rois, OutputArray pano)
-
- :param images: Input images.
-
- :param rois: Region of interest rectangles.
-
- :param pano: Final pano.
-
- :return: Status code.
-
-WarperCreator
--------------
-.. ocv:class:: WarperCreator
-
-Image warper factories base class. ::
-
- class WarperCreator
- {
- public:
- virtual ~WarperCreator() {}
- virtual Ptr<detail::RotationWarper> create(float scale) const = 0;
- };
-
-PlaneWarper
------------
-.. ocv:class:: PlaneWarper : public WarperCreator
-
-Plane warper factory class. ::
-
- class PlaneWarper : public WarperCreator
- {
- public:
- Ptr<detail::RotationWarper> create(float scale) const { return new detail::PlaneWarper(scale); }
- };
-
-.. seealso:: :ocv:class:`detail::PlaneWarper`
-
-CylindricalWarper
------------------
-.. ocv:class:: CylindricalWarper : public WarperCreator
-
-Cylindrical warper factory class. ::
-
- class CylindricalWarper: public WarperCreator
- {
- public:
- Ptr<detail::RotationWarper> create(float scale) const { return new detail::CylindricalWarper(scale); }
- };
-
-.. seealso:: :ocv:class:`detail::CylindricalWarper`
-
-SphericalWarper
----------------
-.. ocv:class:: SphericalWarper : public WarperCreator
-
-Spherical warper factory class. ::
-
- class SphericalWarper: public WarperCreator
- {
- public:
- Ptr<detail::RotationWarper> create(float scale) const { return new detail::SphericalWarper(scale); }
- };
-
-.. seealso:: :ocv:class:`detail::SphericalWarper`
+++ /dev/null
-.. _stitching-pipeline:
-
-Stitching Pipeline
-==================
-
-This figure illustrates the stitching module pipeline implemented in the :ocv:class:`Stitcher` class. Using that class it's possible to configure/remove some steps, i.e. adjust the stitching pipeline according to the particular needs. All building blocks from the pipeline are available in the ``detail`` namespace, one can combine and use them separately.
-
-The implemented stitching pipeline is very similar to the one proposed in [BL07]_.
-
-.. image:: StitchingPipeline.jpg
-
-References
-==========
-
-.. [BL07] M. Brown and D. Lowe. Automatic Panoramic Image Stitching using Invariant Features. International Journal of Computer Vision, 74(1), pages 59-73, 2007.
-
-.. [RS10] Richard Szeliski. Computer Vision: Algorithms and Applications. Springer, New York, 2010.
-
-.. [RS04] Richard Szeliski. Image alignment and stitching: A tutorial. Technical Report MSR-TR-2004-92, Microsoft Research, December 2004.
-
-.. [SS00] Heung-Yeung Shum and Richard Szeliski. Construction of panoramic mosaics with global and local alignment. International Journal of Computer Vision, 36(2):101-130, February 2000. Erratum published July 2002, 48(2):151-152.
-
-.. [V03] Vivek Kwatra, Arno Schödl, Irfan Essa, Greg Turk and Aaron Bobick. Graphcut Textures: Image and Video Synthesis Using Graph Cuts. To appear in Proc. ACM Transactions on Graphics, SIGGRAPH 2003.
-
-.. [UES01] M. Uyttendaele, A. Eden, and R. Szeliski. Eliminating ghosting and exposure artifacts in image mosaics. In Proc. CVPR’01, volume 2, pages 509–516, 2001
-
-.. [WJ10] Wei Xu and Jane Mulligan. Performance evaluation of color correction approaches for automatic multiview image and video stitching. In Intl. Conf on Computer Vision and Pattern Recognition (CVPR10), San Francisco, CA, 2010
-
-.. [BA83] Burt, P., and Adelson, E. H., A Multiresolution Spline with Application to Image Mosaics. ACM Transactions on Graphics, 2(4):217-236, 1983.
+++ /dev/null
-Features Finding and Images Matching
-====================================
-
-.. highlight:: cpp
-
-detail::ImageFeatures
------------------------
-.. ocv:struct:: detail::ImageFeatures
-
-Structure containing image keypoints and descriptors. ::
-
- struct CV_EXPORTS ImageFeatures
- {
- int img_idx;
- Size img_size;
- std::vector<KeyPoint> keypoints;
- Mat descriptors;
- };
-
-detail::FeaturesFinder
-----------------------
-.. ocv:class:: detail::FeaturesFinder
-
-Feature finders base class. ::
-
- class CV_EXPORTS FeaturesFinder
- {
- public:
- virtual ~FeaturesFinder() {}
- void operator ()(const Mat &image, ImageFeatures &features);
- void operator ()(const Mat &image, ImageFeatures &features, const std::vector<cv::Rect> &rois);
- virtual void collectGarbage() {}
-
- protected:
- virtual void find(const Mat &image, ImageFeatures &features) = 0;
- };
-
-detail::FeaturesFinder::operator()
-----------------------------------
-
-Finds features in the given image.
-
-.. ocv:function:: void detail::FeaturesFinder::operator ()(InputArray image, ImageFeatures &features)
-
-.. ocv:function:: void detail::FeaturesFinder::operator ()(InputArray image, ImageFeatures &features, const std::vector<cv::Rect> &rois)
-
- :param image: Source image
-
- :param features: Found features
-
- :param rois: Regions of interest
-
-.. seealso:: :ocv:struct:`detail::ImageFeatures`, :ocv:class:`Rect_`
-
-detail::FeaturesFinder::collectGarbage
---------------------------------------
-
-Frees unused memory allocated before if there is any.
-
-.. ocv:function:: void detail::FeaturesFinder::collectGarbage()
-
-detail::FeaturesFinder::find
-----------------------------
-
-This method must implement features finding logic in order to make the wrappers `detail::FeaturesFinder::operator()`_ work.
-
-.. ocv:function:: void detail::FeaturesFinder::find(InputArray image, ImageFeatures &features)
-
- :param image: Source image
-
- :param features: Found features
-
-.. seealso:: :ocv:struct:`detail::ImageFeatures`
-
-detail::SurfFeaturesFinder
---------------------------
-.. ocv:class:: detail::SurfFeaturesFinder : public detail::FeaturesFinder
-
-SURF features finder. ::
-
- class CV_EXPORTS SurfFeaturesFinder : public FeaturesFinder
- {
- public:
- SurfFeaturesFinder(double hess_thresh = 300., int num_octaves = 3, int num_layers = 4,
- int num_octaves_descr = /*4*/3, int num_layers_descr = /*2*/4);
-
- private:
- /* hidden */
- };
-
-.. seealso:: :ocv:class:`detail::FeaturesFinder`, ``SURF``
-
-detail::OrbFeaturesFinder
--------------------------
-.. ocv:class:: detail::OrbFeaturesFinder : public detail::FeaturesFinder
-
-ORB features finder. ::
-
- class CV_EXPORTS OrbFeaturesFinder : public FeaturesFinder
- {
- public:
- OrbFeaturesFinder(Size _grid_size = Size(3,1), size_t n_features = 1500,
- const ORB::CommonParams &detector_params = ORB::CommonParams(1.3f, 5));
-
- private:
- /* hidden */
- };
-
-.. seealso:: :ocv:class:`detail::FeaturesFinder`, :ocv:class:`ORB`
-
-detail::MatchesInfo
--------------------
-.. ocv:struct:: detail::MatchesInfo
-
-Structure containing information about matches between two images. It's assumed that there is a homography between those images. ::
-
- struct CV_EXPORTS MatchesInfo
- {
- MatchesInfo();
- MatchesInfo(const MatchesInfo &other);
- const MatchesInfo& operator =(const MatchesInfo &other);
-
- int src_img_idx, dst_img_idx; // Images indices (optional)
- std::vector<DMatch> matches;
- std::vector<uchar> inliers_mask; // Geometrically consistent matches mask
- int num_inliers; // Number of geometrically consistent matches
- Mat H; // Estimated homography
- double confidence; // Confidence two images are from the same panorama
- };
-
-detail::FeaturesMatcher
------------------------
-.. ocv:class:: detail::FeaturesMatcher
-
-Feature matchers base class. ::
-
- class CV_EXPORTS FeaturesMatcher
- {
- public:
- virtual ~FeaturesMatcher() {}
-
- void operator ()(const ImageFeatures &features1, const ImageFeatures &features2,
- MatchesInfo& matches_info) { match(features1, features2, matches_info); }
-
- void operator ()(const std::vector<ImageFeatures> &features, std::vector<MatchesInfo> &pairwise_matches,
- const Mat &mask = cv::Mat());
-
- bool isThreadSafe() const { return is_thread_safe_; }
-
- virtual void collectGarbage() {}
-
- protected:
- FeaturesMatcher(bool is_thread_safe = false) : is_thread_safe_(is_thread_safe) {}
-
- virtual void match(const ImageFeatures &features1, const ImageFeatures &features2,
- MatchesInfo& matches_info) = 0;
-
- bool is_thread_safe_;
- };
-
-detail::FeaturesMatcher::operator()
------------------------------------
-
-Performs images matching.
-
-.. ocv:function:: void detail::FeaturesMatcher::operator ()(const ImageFeatures &features1, const ImageFeatures &features2, MatchesInfo& matches_info)
-
- :param features1: First image features
-
- :param features2: Second image features
-
- :param matches_info: Found matches
-
-.. ocv:function:: void detail::FeaturesMatcher::operator ()( const std::vector<ImageFeatures> & features, std::vector<MatchesInfo> & pairwise_matches, const UMat & mask=UMat() )
-
- :param features: Features of the source images
-
- :param pairwise_matches: Found pairwise matches
-
- :param mask: Mask indicating which image pairs must be matched
-
-The function is parallelized with the TBB library.
-
-.. seealso:: :ocv:struct:`detail::MatchesInfo`
-
-detail::FeaturesMatcher::isThreadSafe
--------------------------------------
-
-.. ocv:function:: bool detail::FeaturesMatcher::isThreadSafe() const
-
- :return: True, if it's possible to use the same matcher instance in parallel, false otherwise
-
-detail::FeaturesMatcher::collectGarbage
----------------------------------------
-
-Frees unused memory allocated before if there is any.
-
-.. ocv:function:: void detail::FeaturesMatcher::collectGarbage()
-
-detail::FeaturesMatcher::match
-------------------------------
-
-This method must implement matching logic in order to make the wrappers `detail::FeaturesMatcher::operator()`_ work.
-
-.. ocv:function:: void detail::FeaturesMatcher::match(const ImageFeatures &features1, const ImageFeatures &features2, MatchesInfo& matches_info)
-
- :param features1: first image features
-
- :param features2: second image features
-
- :param matches_info: found matches
-
-detail::BestOf2NearestMatcher
------------------------------
-.. ocv:class:: detail::BestOf2NearestMatcher : public detail::FeaturesMatcher
-
-Features matcher which finds two best matches for each feature and leaves the best one only if the ratio between descriptor distances is greater than the threshold ``match_conf``. ::
-
- class CV_EXPORTS BestOf2NearestMatcher : public FeaturesMatcher
- {
- public:
- BestOf2NearestMatcher(bool try_use_gpu = false, float match_conf = 0.65f,
- int num_matches_thresh1 = 6, int num_matches_thresh2 = 6);
-
- void collectGarbage();
-
- protected:
- void match(const ImageFeatures &features1, const ImageFeatures &features2, MatchesInfo &matches_info);
-
- int num_matches_thresh1_;
- int num_matches_thresh2_;
- Ptr<FeaturesMatcher> impl_;
- };
-
-.. seealso:: :ocv:class:`detail::FeaturesMatcher`
-
-detail::BestOf2NearestMatcher::BestOf2NearestMatcher
-----------------------------------------------------
-
-Constructs a "best of 2 nearest" matcher.
-
-.. ocv:function:: detail::BestOf2NearestMatcher::BestOf2NearestMatcher(bool try_use_gpu = false, float match_conf = 0.3f, int num_matches_thresh1 = 6, int num_matches_thresh2 = 6)
-
- :param try_use_gpu: Should try to use GPU or not
-
- :param match_conf: Match distances ration threshold
-
- :param num_matches_thresh1: Minimum number of matches required for the 2D projective transform estimation used in the inliers classification step
-
- :param num_matches_thresh2: Minimum number of matches required for the 2D projective transform re-estimation on inliers
+++ /dev/null
-Rotation Estimation
-===================
-
-.. highlight:: cpp
-
-detail::Estimator
------------------
-.. ocv:class:: detail::Estimator
-
-Rotation estimator base class. It takes features of all images, pairwise matches between all images and estimates rotations of all cameras.
-
-.. note:: The coordinate system origin is implementation-dependent, but you can always normalize the rotations in respect to the first camera, for instance.
-
-::
-
- class CV_EXPORTS Estimator
- {
- public:
- virtual ~Estimator() {}
-
- bool operator ()(const std::vector<ImageFeatures> &features, const std::vector<MatchesInfo> &pairwise_matches,
- std::vector<CameraParams> &cameras);
-
- protected:
- virtual bool estimate(const std::vector<ImageFeatures> &features, const std::vector<MatchesInfo> &pairwise_matches,
- std::vector<CameraParams> &cameras) = 0;
- };
-
-detail::Estimator::operator()
------------------------------
-
-Estimates camera parameters.
-
-.. ocv:function:: bool detail::Estimator::operator ()(const std::vector<ImageFeatures> &features, const std::vector<MatchesInfo> &pairwise_matches, std::vector<CameraParams> &cameras)
-
- :param features: Features of images
-
- :param pairwise_matches: Pairwise matches of images
-
- :param cameras: Estimated camera parameters
-
- :return: True in case of success, false otherwise
-
-detail::Estimator::estimate
----------------------------
-
-This method must implement camera parameters estimation logic in order to make the wrapper `detail::Estimator::operator()`_ work.
-
-.. ocv:function:: bool detail::Estimator::estimate(const std::vector<ImageFeatures> &features, const std::vector<MatchesInfo> &pairwise_matches, std::vector<CameraParams> &cameras)
-
- :param features: Features of images
-
- :param pairwise_matches: Pairwise matches of images
-
- :param cameras: Estimated camera parameters
-
- :return: True in case of success, false otherwise
-
-detail::HomographyBasedEstimator
---------------------------------
-.. ocv:class:: detail::HomographyBasedEstimator : public detail::Estimator
-
-Homography based rotation estimator. ::
-
- class CV_EXPORTS HomographyBasedEstimator : public Estimator
- {
- public:
- HomographyBasedEstimator(bool is_focals_estimated = false)
- : is_focals_estimated_(is_focals_estimated) {}
-
- private:
- /* hidden */
- };
-
-detail::BundleAdjusterBase
---------------------------
-.. ocv:class:: detail::BundleAdjusterBase : public detail::Estimator
-
-Base class for all camera parameters refinement methods. ::
-
- class CV_EXPORTS BundleAdjusterBase : public Estimator
- {
- public:
- const Mat refinementMask() const { return refinement_mask_.clone(); }
- void setRefinementMask(const Mat &mask)
- {
- CV_Assert(mask.type() == CV_8U && mask.size() == Size(3, 3));
- refinement_mask_ = mask.clone();
- }
-
- double confThresh() const { return conf_thresh_; }
- void setConfThresh(double conf_thresh) { conf_thresh_ = conf_thresh; }
-
- CvTermCriteria termCriteria() { return term_criteria_; }
- void setTermCriteria(const CvTermCriteria& term_criteria) { term_criteria_ = term_criteria; }
-
- protected:
- BundleAdjusterBase(int num_params_per_cam, int num_errs_per_measurement)
- : num_params_per_cam_(num_params_per_cam),
- num_errs_per_measurement_(num_errs_per_measurement)
- {
- setRefinementMask(Mat::ones(3, 3, CV_8U));
- setConfThresh(1.);
- setTermCriteria(cvTermCriteria(CV_TERMCRIT_EPS + CV_TERMCRIT_ITER, 1000, DBL_EPSILON));
- }
-
- // Runs bundle adjustment
- virtual void estimate(const std::vector<ImageFeatures> &features,
- const std::vector<MatchesInfo> &pairwise_matches,
- std::vector<CameraParams> &cameras);
-
- virtual void setUpInitialCameraParams(const std::vector<CameraParams> &cameras) = 0;
- virtual void obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const = 0;
- virtual void calcError(Mat &err) = 0;
- virtual void calcJacobian(Mat &jac) = 0;
-
- // 3x3 8U mask, where 0 means don't refine respective parameter, != 0 means refine
- Mat refinement_mask_;
-
- int num_images_;
- int total_num_matches_;
-
- int num_params_per_cam_;
- int num_errs_per_measurement_;
-
- const ImageFeatures *features_;
- const MatchesInfo *pairwise_matches_;
-
- // Threshold to filter out poorly matched image pairs
- double conf_thresh_;
-
- //Levenberg–Marquardt algorithm termination criteria
- CvTermCriteria term_criteria_;
-
- // Camera parameters matrix (CV_64F)
- Mat cam_params_;
-
- // Connected images pairs
- std::vector<std::pair<int,int> > edges_;
- };
-
-.. seealso:: :ocv:class:`detail::Estimator`
-
-detail::BundleAdjusterBase::BundleAdjusterBase
-----------------------------------------------
-
-Construct a bundle adjuster base instance.
-
-.. ocv:function:: detail::BundleAdjusterBase::BundleAdjusterBase(int num_params_per_cam, int num_errs_per_measurement)
-
- :param num_params_per_cam: Number of parameters per camera
-
- :param num_errs_per_measurement: Number of error terms (components) per match
-
-detail::BundleAdjusterBase::setUpInitialCameraParams
-----------------------------------------------------
-
-Sets initial camera parameter to refine.
-
-.. ocv:function:: void detail::BundleAdjusterBase::setUpInitialCameraParams(const std::vector<CameraParams> &cameras)
-
- :param cameras: Camera parameters
-
-detail::BundleAdjusterBase::calcError
--------------------------------------
-
-Calculates error vector.
-
-.. ocv:function:: void detail::BundleAdjusterBase::calcError(Mat &err)
-
- :param err: Error column-vector of length ``total_num_matches * num_errs_per_measurement``
-
-detail::BundleAdjusterBase::calcJacobian
-----------------------------------------
-
-Calculates the cost function jacobian.
-
-.. ocv:function:: void detail::BundleAdjusterBase::calcJacobian(Mat &jac)
-
- :param jac: Jacobian matrix of dimensions ``(total_num_matches * num_errs_per_measurement) x (num_images * num_params_per_cam)``
-
-detail::BundleAdjusterBase::obtainRefinedCameraParams
------------------------------------------------------
-
-Gets the refined camera parameters.
-
-.. ocv:function:: void detail::BundleAdjusterBase::obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const
-
- :param cameras: Refined camera parameters
-
-detail::BundleAdjusterReproj
-----------------------------
-.. ocv:class:: detail::BundleAdjusterReproj : public detail::BundleAdjusterBase
-
-Implementation of the camera parameters refinement algorithm which minimizes sum of the reprojection error squares. ::
-
- class CV_EXPORTS BundleAdjusterReproj : public BundleAdjusterBase
- {
- public:
- BundleAdjusterReproj() : BundleAdjusterBase(7, 2) {}
-
- private:
- /* hidden */
- };
-
-.. seealso:: :ocv:class:`detail::BundleAdjusterBase`, :ocv:class:`detail::Estimator`
-
-detail::BundleAdjusterRay
--------------------------
-.. ocv:class:: detail::BundleAdjusterRay : public detail::BundleAdjusterBase
-
-Implementation of the camera parameters refinement algorithm which minimizes sum of the distances between the rays passing through the camera center and a feature. ::
-
- class CV_EXPORTS BundleAdjusterRay : public BundleAdjusterBase
- {
- public:
- BundleAdjusterRay() : BundleAdjusterBase(4, 3) {}
-
- private:
- /* hidden */
- };
-
-.. seealso:: :ocv:class:`detail::BundleAdjusterBase`
-
-detail::WaveCorrectKind
------------------------
-Wave correction kind.
-
-.. ocv:enum:: detail::WaveCorrectKind
-
- .. ocv:emember:: WAVE_CORRECT_HORIZ
- .. ocv:emember:: WAVE_CORRECT_VERT
-
-
-detail::waveCorrect
--------------------
-Tries to make panorama more horizontal (or vertical).
-
-.. ocv:function:: void detail::waveCorrect(std::vector<Mat> &rmats, WaveCorrectKind kind)
-
- :param rmats: Camera rotation matrices.
-
- :param kind: Correction kind, see :ocv:enum:`detail::WaveCorrectKind`.
+++ /dev/null
-Seam Estimation
-===============
-
-.. highlight:: cpp
-
-detail::SeamFinder
-------------------
-.. ocv:class:: detail::SeamFinder
-
-Base class for a seam estimator. ::
-
- class CV_EXPORTS SeamFinder
- {
- public:
- virtual ~SeamFinder() {}
- virtual void find(const std::vector<Mat> &src, const std::vector<Point> &corners,
- std::vector<Mat> &masks) = 0;
- };
-
-detail::SeamFinder::find
-------------------------
-
-Estimates seams.
-
-.. ocv:function:: void detail::SeamFinder::find(const std::vector<UMat> &src, const std::vector<Point> &corners, std::vector<UMat> &masks)
-
- :param src: Source images
-
- :param corners: Source image top-left corners
-
- :param masks: Source image masks to update
-
-
-detail::NoSeamFinder
---------------------
-.. ocv:class:: detail::NoSeamFinder : public detail::SeamFinder
-
-Stub seam estimator which does nothing. ::
-
- class CV_EXPORTS NoSeamFinder : public SeamFinder
- {
- public:
- void find(const std::vector<Mat>&, const std::vector<Point>&, std::vector<Mat>&) {}
- };
-
-.. seealso:: :ocv:class:`detail::SeamFinder`
-
-detail::PairwiseSeamFinder
---------------------------
-.. ocv:class:: detail::PairwiseSeamFinder : public detail::SeamFinder
-
-Base class for all pairwise seam estimators. ::
-
- class CV_EXPORTS PairwiseSeamFinder : public SeamFinder
- {
- public:
- virtual void find(const std::vector<Mat> &src, const std::vector<Point> &corners,
- std::vector<Mat> &masks);
-
- protected:
- void run();
- virtual void findInPair(size_t first, size_t second, Rect roi) = 0;
-
- std::vector<Mat> images_;
- std::vector<Size> sizes_;
- std::vector<Point> corners_;
- std::vector<Mat> masks_;
- };
-
-.. seealso:: :ocv:class:`detail::SeamFinder`
-
-detail::PairwiseSeamFinder::findInPair
---------------------------------------
-
-Resolves masks intersection of two specified images in the given ROI.
-
-.. ocv:function:: void detail::PairwiseSeamFinder::findInPair(size_t first, size_t second, Rect roi)
-
- :param first: First image index
-
- :param second: Second image index
-
- :param roi: Region of interest
-
-detail::VoronoiSeamFinder
--------------------------
-.. ocv:class:: detail::VoronoiSeamFinder : public detail::PairwiseSeamFinder
-
-Voronoi diagram-based seam estimator. ::
-
- class CV_EXPORTS VoronoiSeamFinder : public PairwiseSeamFinder
- {
- public:
- virtual void find(const std::vector<Size> &size, const std::vector<Point> &corners,
- std::vector<Mat> &masks);
- private:
- void findInPair(size_t first, size_t second, Rect roi);
- };
-
-.. seealso:: :ocv:class:`detail::PairwiseSeamFinder`
-
-detail::GraphCutSeamFinderBase
-------------------------------
-.. ocv:class:: detail::GraphCutSeamFinderBase
-
-Base class for all minimum graph-cut-based seam estimators. ::
-
- class CV_EXPORTS GraphCutSeamFinderBase
- {
- public:
- enum { COST_COLOR, COST_COLOR_GRAD };
- };
-
-detail::GraphCutSeamFinder
---------------------------
-.. ocv:class:: detail::GraphCutSeamFinder : public detail::GraphCutSeamFinderBase, public detail::SeamFinder
-
-Minimum graph cut-based seam estimator. See details in [V03]_. ::
-
- class CV_EXPORTS GraphCutSeamFinder : public GraphCutSeamFinderBase, public SeamFinder
- {
- public:
- GraphCutSeamFinder(int cost_type = COST_COLOR_GRAD, float terminal_cost = 10000.f,
- float bad_region_penalty = 1000.f);
-
- void find(const std::vector<Mat> &src, const std::vector<Point> &corners,
- std::vector<Mat> &masks);
-
- private:
- /* hidden */
- };
-
-.. seealso::
- :ocv:class:`detail::GraphCutSeamFinderBase`,
- :ocv:class:`detail::SeamFinder`
+++ /dev/null
-***************************
-stitching. Images stitching
-***************************
-
-.. toctree::
- :maxdepth: 2
-
- introduction
- high_level
- camera
- matching
- motion_estimation
- autocalib
- warpers
- seam_estimation
- exposure_compensation
- blenders
+++ /dev/null
-Images Warping
-==============
-
-.. highlight:: cpp
-
-detail::RotationWarper
-----------------------
-.. ocv:class:: detail::RotationWarper
-
-Rotation-only model image warper interface. ::
-
- class CV_EXPORTS RotationWarper
- {
- public:
- virtual ~RotationWarper() {}
-
- virtual Point2f warpPoint(const Point2f &pt, InputArray K, InputArray R) = 0;
-
- virtual Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap) = 0;
-
- virtual Point warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
- OutputArray dst) = 0;
-
- virtual void warpBackward(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
- Size dst_size, OutputArray dst) = 0;
-
- virtual Rect warpRoi(Size src_size, InputArray K, InputArray R) = 0;
- };
-
-detail::RotationWarper::warpPoint
----------------------------------
-
-Projects the image point.
-
-.. ocv:function:: Point2f detail::RotationWarper::warpPoint(const Point2f &pt, InputArray K, InputArray R)
-
- :param pt: Source point
-
- :param K: Camera intrinsic parameters
-
- :param R: Camera rotation matrix
-
- :return: Projected point
-
-detail::RotationWarper::buildMaps
----------------------------------
-
-Builds the projection maps according to the given camera data.
-
-.. ocv:function:: Rect detail::RotationWarper::buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap)
-
- :param src_size: Source image size
-
- :param K: Camera intrinsic parameters
-
- :param R: Camera rotation matrix
-
- :param xmap: Projection map for the x axis
-
- :param ymap: Projection map for the y axis
-
- :return: Projected image minimum bounding box
-
-detail::RotationWarper::warp
-----------------------------
-
-Projects the image.
-
-.. ocv:function:: Point detail::RotationWarper::warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode, OutputArray dst)
-
- :param src: Source image
-
- :param K: Camera intrinsic parameters
-
- :param R: Camera rotation matrix
-
- :param interp_mode: Interpolation mode
-
- :param border_mode: Border extrapolation mode
-
- :param dst: Projected image
-
- :return: Project image top-left corner
-
-detail::RotationWarper::warpBackward
-------------------------------------
-
-Projects the image backward.
-
-.. ocv:function:: void detail::RotationWarper::warpBackward(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode, Size dst_size, OutputArray dst)
-
- :param src: Projected image
-
- :param K: Camera intrinsic parameters
-
- :param R: Camera rotation matrix
-
- :param interp_mode: Interpolation mode
-
- :param border_mode: Border extrapolation mode
-
- :param dst_size: Backward-projected image size
-
- :param dst: Backward-projected image
-
-detail::RotationWarper::warpRoi
--------------------------------
-
-.. ocv:function:: Rect detail::RotationWarper::warpRoi(Size src_size, InputArray K, InputArray R)
-
- :param src_size: Source image bounding box
-
- :param K: Camera intrinsic parameters
-
- :param R: Camera rotation matrix
-
- :return: Projected image minimum bounding box
-
-detail::ProjectorBase
----------------------
-.. ocv:struct:: detail::ProjectorBase
-
-Base class for warping logic implementation. ::
-
- struct CV_EXPORTS ProjectorBase
- {
- void setCameraParams(InputArray K = Mat::eye(3, 3, CV_32F),
- InputArray R = Mat::eye(3, 3, CV_32F),
- InputArray T = Mat::zeros(3, 1, CV_32F));
-
- float scale;
- float k[9];
- float rinv[9];
- float r_kinv[9];
- float k_rinv[9];
- float t[3];
- };
-
-detail::RotationWarperBase
---------------------------
-.. ocv:class:: detail::RotationWarperBase
-
-Base class for rotation-based warper using a `detail::ProjectorBase`_ derived class. ::
-
- template <class P>
- class CV_EXPORTS RotationWarperBase : public RotationWarper
- {
- public:
- Point2f warpPoint(const Point2f &pt, InputArray K, InputArray R);
-
- Rect buildMaps(Size src_size, InputArray K, InputArray R, OutputArray xmap, OutputArray ymap);
-
- Point warp(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
- OutputArray dst);
-
- void warpBackward(InputArray src, InputArray K, InputArray R, int interp_mode, int border_mode,
- Size dst_size, OutputArray dst);
-
- Rect warpRoi(Size src_size, InputArray K, InputArray R);
-
- protected:
-
- // Detects ROI of the destination image. It's correct for any projection.
- virtual void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br);
-
- // Detects ROI of the destination image by walking over image border.
- // Correctness for any projection isn't guaranteed.
- void detectResultRoiByBorder(Size src_size, Point &dst_tl, Point &dst_br);
-
- P projector_;
- };
-
-detail::PlaneWarper
--------------------
-.. ocv:class:: detail::PlaneWarper : public detail::RotationWarperBase<PlaneProjector>
-
-Warper that maps an image onto the z = 1 plane. ::
-
- class CV_EXPORTS PlaneWarper : public RotationWarperBase<PlaneProjector>
- {
- public:
- PlaneWarper(float scale = 1.f) { projector_.scale = scale; }
-
- void setScale(float scale) { projector_.scale = scale; }
-
- Point2f warpPoint(const Point2f &pt, InputArray K, InputArray R, InputArray T);
-
- Rect buildMaps(Size src_size, InputArray K, InputArray R, InputArray T, OutputArray xmap, OutputArray ymap);
-
- Point warp(InputArray src, InputArray K, InputArray R, InputArray T, int interp_mode, int border_mode,
- OutputArray dst);
-
- Rect warpRoi(Size src_size, InputArray K, InputArray R, InputArray T);
-
- protected:
- void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br);
- };
-
-.. seealso:: :ocv:class:`detail::RotationWarper`
-
-detail::PlaneWarper::PlaneWarper
---------------------------------
-
-Construct an instance of the plane warper class.
-
-.. ocv:function:: void detail::PlaneWarper::PlaneWarper(float scale = 1.f)
-
- :param scale: Projected image scale multiplier
-
-detail::SphericalWarper
------------------------
-.. ocv:class:: detail::SphericalWarper : public detail::RotationWarperBase<SphericalProjector>
-
-Warper that maps an image onto the unit sphere located at the origin. ::
-
- class CV_EXPORTS SphericalWarper : public RotationWarperBase<SphericalProjector>
- {
- public:
- SphericalWarper(float scale) { projector_.scale = scale; }
-
- protected:
- void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br);
- };
-
-.. seealso:: :ocv:class:`detail::RotationWarper`
-
-detail::SphericalWarper::SphericalWarper
-----------------------------------------
-
-Construct an instance of the spherical warper class.
-
-.. ocv:function:: void detail::SphericalWarper::SphericalWarper(float scale)
-
- :param scale: Projected image scale multiplier
-
-detail::CylindricalWarper
--------------------------
-.. ocv:class:: detail::CylindricalWarper : public detail::RotationWarperBase<CylindricalProjector>
-
-Warper that maps an image onto the x*x + z*z = 1 cylinder. ::
-
- class CV_EXPORTS CylindricalWarper : public RotationWarperBase<CylindricalProjector>
- {
- public:
- CylindricalWarper(float scale) { projector_.scale = scale; }
-
- protected:
- void detectResultRoi(Size src_size, Point &dst_tl, Point &dst_br)
- {
- RotationWarperBase<CylindricalProjector>::detectResultRoiByBorder(src_size, dst_tl, dst_br);
- }
- };
-
-.. seealso:: :ocv:class:`detail::RotationWarper`
-
-detail::CylindricalWarper::CylindricalWarper
---------------------------------------------
-
-Construct an instance of the cylindrical warper class.
-
-.. ocv:function:: void detail::CylindricalWarper::CylindricalWarper(float scale)
-
- :param scale: Projected image scale multiplier
+++ /dev/null
-Super Resolution
-================
-
-.. highlight:: cpp
-
-The Super Resolution module contains a set of functions and classes that can be used to solve the problem of resolution enhancement. There are a few methods implemented, most of them are descibed in the papers [Farsiu03]_ and [Mitzel09]_.
-
-
-
-superres::SuperResolution
--------------------------
-Base class for Super Resolution algorithms.
-
-.. ocv:class:: superres::SuperResolution : public Algorithm, public superres::FrameSource
-
-The class is only used to define the common interface for the whole family of Super Resolution algorithms.
-
-
-
-superres::SuperResolution::setInput
------------------------------------
-Set input frame source for Super Resolution algorithm.
-
-.. ocv:function:: void superres::SuperResolution::setInput(const Ptr<FrameSource>& frameSource)
-
- :param frameSource: Input frame source
-
-
-
-superres::SuperResolution::nextFrame
-------------------------------------
-Process next frame from input and return output result.
-
-.. ocv:function:: void superres::SuperResolution::nextFrame(OutputArray frame)
-
- :param frame: Output result
-
-
-
-superres::SuperResolution::collectGarbage
------------------------------------------
-Clear all inner buffers.
-
-.. ocv:function:: void superres::SuperResolution::collectGarbage()
-
-
-
-superres::createSuperResolution_BTVL1
--------------------------------------
-Create Bilateral TV-L1 Super Resolution.
-
-.. ocv:function:: Ptr<SuperResolution> superres::createSuperResolution_BTVL1()
-
-.. ocv:function:: Ptr<SuperResolution> superres::createSuperResolution_BTVL1_CUDA()
-
-This class implements Super Resolution algorithm described in the papers [Farsiu03]_ and [Mitzel09]_ .
-
-Here are important members of the class that control the algorithm, which you can set after constructing the class instance:
-
- * **int scale** Scale factor.
-
- * **int iterations** Iteration count.
-
- * **double tau** Asymptotic value of steepest descent method.
-
- * **double lambda** Weight parameter to balance data term and smoothness term.
-
- * **double alpha** Parameter of spacial distribution in Bilateral-TV.
-
- * **int btvKernelSize** Kernel size of Bilateral-TV filter.
-
- * **int blurKernelSize** Gaussian blur kernel size.
-
- * **double blurSigma** Gaussian blur sigma.
-
- * **int temporalAreaRadius** Radius of the temporal search area.
-
- * **Ptr<DenseOpticalFlowExt> opticalFlow** Dense optical flow algorithm.
-
-
-
-.. [Farsiu03] S. Farsiu, D. Robinson, M. Elad, P. Milanfar. Fast and robust Super-Resolution. Proc 2003 IEEE Int Conf on Image Process, pp. 291–294, 2003.
-
-.. [Mitzel09] D. Mitzel, T. Pock, T. Schoenemann, D. Cremers. Video super resolution using duality based TV-L1 optical flow. DAGM, 2009.
+++ /dev/null
-**************************
-superres. Super Resolution
-**************************
-
-.. toctree::
- :maxdepth: 2
-
- super_resolution
+++ /dev/null
-Motion Analysis and Object Tracking
-===================================
-
-.. highlight:: cpp
-
-
-calcOpticalFlowPyrLK
-------------------------
-Calculates an optical flow for a sparse feature set using the iterative Lucas-Kanade method with pyramids.
-
-.. ocv:function:: void calcOpticalFlowPyrLK( InputArray prevImg, InputArray nextImg, InputArray prevPts, InputOutputArray nextPts, OutputArray status, OutputArray err, Size winSize=Size(21,21), int maxLevel=3, TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, 0.01), int flags=0, double minEigThreshold=1e-4 )
-
-.. ocv:pyfunction:: cv2.calcOpticalFlowPyrLK(prevImg, nextImg, prevPts, nextPts[, status[, err[, winSize[, maxLevel[, criteria[, flags[, minEigThreshold]]]]]]]) -> nextPts, status, err
-
-.. ocv:cfunction:: void cvCalcOpticalFlowPyrLK( const CvArr* prev, const CvArr* curr, CvArr* prev_pyr, CvArr* curr_pyr, const CvPoint2D32f* prev_features, CvPoint2D32f* curr_features, int count, CvSize win_size, int level, char* status, float* track_error, CvTermCriteria criteria, int flags )
-
- :param prevImg: first 8-bit input image or pyramid constructed by :ocv:func:`buildOpticalFlowPyramid`.
-
- :param nextImg: second input image or pyramid of the same size and the same type as ``prevImg``.
-
- :param prevPts: vector of 2D points for which the flow needs to be found; point coordinates must be single-precision floating-point numbers.
-
- :param nextPts: output vector of 2D points (with single-precision floating-point coordinates) containing the calculated new positions of input features in the second image; when ``OPTFLOW_USE_INITIAL_FLOW`` flag is passed, the vector must have the same size as in the input.
-
- :param status: output status vector (of unsigned chars); each element of the vector is set to 1 if the flow for the corresponding features has been found, otherwise, it is set to 0.
-
- :param err: output vector of errors; each element of the vector is set to an error for the corresponding feature, type of the error measure can be set in ``flags`` parameter; if the flow wasn't found then the error is not defined (use the ``status`` parameter to find such cases).
-
- :param winSize: size of the search window at each pyramid level.
-
- :param maxLevel: 0-based maximal pyramid level number; if set to 0, pyramids are not used (single level), if set to 1, two levels are used, and so on; if pyramids are passed to input then algorithm will use as many levels as pyramids have but no more than ``maxLevel``.
-
- :param criteria: parameter, specifying the termination criteria of the iterative search algorithm (after the specified maximum number of iterations ``criteria.maxCount`` or when the search window moves by less than ``criteria.epsilon``.
-
- :param flags: operation flags:
-
- * **OPTFLOW_USE_INITIAL_FLOW** uses initial estimations, stored in ``nextPts``; if the flag is not set, then ``prevPts`` is copied to ``nextPts`` and is considered the initial estimate.
- * **OPTFLOW_LK_GET_MIN_EIGENVALS** use minimum eigen values as an error measure (see ``minEigThreshold`` description); if the flag is not set, then L1 distance between patches around the original and a moved point, divided by number of pixels in a window, is used as a error measure.
-
- :param minEigThreshold: the algorithm calculates the minimum eigen value of a 2x2 normal matrix of optical flow equations (this matrix is called a spatial gradient matrix in [Bouguet00]_), divided by number of pixels in a window; if this value is less than ``minEigThreshold``, then a corresponding feature is filtered out and its flow is not processed, so it allows to remove bad points and get a performance boost.
-
-The function implements a sparse iterative version of the Lucas-Kanade optical flow in pyramids. See [Bouguet00]_. The function is parallelized with the TBB library.
-
-.. note::
-
- * An example using the Lucas-Kanade optical flow algorithm can be found at opencv_source_code/samples/cpp/lkdemo.cpp
-
- * (Python) An example using the Lucas-Kanade optical flow algorithm can be found at opencv_source_code/samples/python2/lk_track.py
- * (Python) An example using the Lucas-Kanade tracker for homography matching can be found at opencv_source_code/samples/python2/lk_homography.py
-
-buildOpticalFlowPyramid
------------------------
-Constructs the image pyramid which can be passed to :ocv:func:`calcOpticalFlowPyrLK`.
-
-.. ocv:function:: int buildOpticalFlowPyramid(InputArray img, OutputArrayOfArrays pyramid, Size winSize, int maxLevel, bool withDerivatives = true, int pyrBorder = BORDER_REFLECT_101, int derivBorder = BORDER_CONSTANT, bool tryReuseInputImage = true)
-
-.. ocv:pyfunction:: cv2.buildOpticalFlowPyramid(img, winSize, maxLevel[, pyramid[, withDerivatives[, pyrBorder[, derivBorder[, tryReuseInputImage]]]]]) -> retval, pyramid
-
- :param img: 8-bit input image.
-
- :param pyramid: output pyramid.
-
- :param winSize: window size of optical flow algorithm. Must be not less than ``winSize`` argument of :ocv:func:`calcOpticalFlowPyrLK`. It is needed to calculate required padding for pyramid levels.
-
- :param maxLevel: 0-based maximal pyramid level number.
-
- :param withDerivatives: set to precompute gradients for the every pyramid level. If pyramid is constructed without the gradients then :ocv:func:`calcOpticalFlowPyrLK` will calculate them internally.
-
- :param pyrBorder: the border mode for pyramid layers.
-
- :param derivBorder: the border mode for gradients.
-
- :param tryReuseInputImage: put ROI of input image into the pyramid if possible. You can pass ``false`` to force data copying.
-
- :return: number of levels in constructed pyramid. Can be less than ``maxLevel``.
-
-
-calcOpticalFlowFarneback
-----------------------------
-Computes a dense optical flow using the Gunnar Farneback's algorithm.
-
-.. ocv:function:: void calcOpticalFlowFarneback( InputArray prev, InputArray next, InputOutputArray flow, double pyr_scale, int levels, int winsize, int iterations, int poly_n, double poly_sigma, int flags )
-
-.. ocv:cfunction:: void cvCalcOpticalFlowFarneback( const CvArr* prev, const CvArr* next, CvArr* flow, double pyr_scale, int levels, int winsize, int iterations, int poly_n, double poly_sigma, int flags )
-
-.. ocv:pyfunction:: cv2.calcOpticalFlowFarneback(prev, next, flow, pyr_scale, levels, winsize, iterations, poly_n, poly_sigma, flags) -> flow
-
- :param prev: first 8-bit single-channel input image.
-
- :param next: second input image of the same size and the same type as ``prev``.
-
- :param flow: computed flow image that has the same size as ``prev`` and type ``CV_32FC2``.
-
- :param pyr_scale: parameter, specifying the image scale (<1) to build pyramids for each image; ``pyr_scale=0.5`` means a classical pyramid, where each next layer is twice smaller than the previous one.
-
- :param levels: number of pyramid layers including the initial image; ``levels=1`` means that no extra layers are created and only the original images are used.
-
- :param winsize: averaging window size; larger values increase the algorithm robustness to image noise and give more chances for fast motion detection, but yield more blurred motion field.
-
- :param iterations: number of iterations the algorithm does at each pyramid level.
-
- :param poly_n: size of the pixel neighborhood used to find polynomial expansion in each pixel; larger values mean that the image will be approximated with smoother surfaces, yielding more robust algorithm and more blurred motion field, typically ``poly_n`` =5 or 7.
-
- :param poly_sigma: standard deviation of the Gaussian that is used to smooth derivatives used as a basis for the polynomial expansion; for ``poly_n=5``, you can set ``poly_sigma=1.1``, for ``poly_n=7``, a good value would be ``poly_sigma=1.5``.
-
- :param flags: operation flags that can be a combination of the following:
-
- * **OPTFLOW_USE_INITIAL_FLOW** uses the input ``flow`` as an initial flow approximation.
-
- * **OPTFLOW_FARNEBACK_GAUSSIAN** uses the Gaussian :math:`\texttt{winsize}\times\texttt{winsize}` filter instead of a box filter of the same size for optical flow estimation; usually, this option gives z more accurate flow than with a box filter, at the cost of lower speed; normally, ``winsize`` for a Gaussian window should be set to a larger value to achieve the same level of robustness.
-
-The function finds an optical flow for each ``prev`` pixel using the [Farneback2003]_ algorithm so that
-
-.. math::
-
- \texttt{prev} (y,x) \sim \texttt{next} ( y + \texttt{flow} (y,x)[1], x + \texttt{flow} (y,x)[0])
-
-.. note::
-
- * An example using the optical flow algorithm described by Gunnar Farneback can be found at opencv_source_code/samples/cpp/fback.cpp
-
- * (Python) An example using the optical flow algorithm described by Gunnar Farneback can be found at opencv_source_code/samples/python2/opt_flow.py
-
-estimateRigidTransform
---------------------------
-Computes an optimal affine transformation between two 2D point sets.
-
-.. ocv:function:: Mat estimateRigidTransform( InputArray src, InputArray dst, bool fullAffine )
-
-.. ocv:pyfunction:: cv2.estimateRigidTransform(src, dst, fullAffine) -> retval
-
- :param src: First input 2D point set stored in ``std::vector`` or ``Mat``, or an image stored in ``Mat``.
-
- :param dst: Second input 2D point set of the same size and the same type as ``A``, or another image.
-
- :param fullAffine: If true, the function finds an optimal affine transformation with no additional restrictions (6 degrees of freedom). Otherwise, the class of transformations to choose from is limited to combinations of translation, rotation, and uniform scaling (5 degrees of freedom).
-
-The function finds an optimal affine transform *[A|b]* (a ``2 x 3`` floating-point matrix) that approximates best the affine transformation between:
-
- *
- Two point sets
- *
- Two raster images. In this case, the function first finds some features in the ``src`` image and finds the corresponding features in ``dst`` image. After that, the problem is reduced to the first case.
-
-In case of point sets, the problem is formulated as follows: you need to find a 2x2 matrix *A* and 2x1 vector *b* so that:
-
- .. math::
-
- [A^*|b^*] = arg \min _{[A|b]} \sum _i \| \texttt{dst}[i] - A { \texttt{src}[i]}^T - b \| ^2
-
- where ``src[i]`` and ``dst[i]`` are the i-th points in ``src`` and ``dst``, respectively
-
- :math:`[A|b]` can be either arbitrary (when ``fullAffine=true`` ) or have a form of
-
- .. math::
-
- \begin{bmatrix} a_{11} & a_{12} & b_1 \\ -a_{12} & a_{11} & b_2 \end{bmatrix}
-
- when ``fullAffine=false`` .
-
-.. seealso::
-
- :ocv:func:`getAffineTransform`,
- :ocv:func:`getPerspectiveTransform`,
- :ocv:func:`findHomography`
-
-findTransformECC
-------------------------
-Finds the geometric transform (warp) between two images in terms of the ECC criterion [EP08]_.
-
-.. ocv:function:: double findTransformECC( InputArray templateImage, InputArray inputImage, InputOutputArray warpMatrix, int motionType=MOTION_AFFINE, TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 50, 0.001))
-
-.. ocv:pyfunction:: cv2.findTransformECC(templateImage, inputImage, warpMatrix[, motionType[, criteria]]) -> retval, warpMatrix
-
- :param templateImage: single-channel template image; ``CV_8U`` or ``CV_32F`` array.
-
- :param inputImage: single-channel input image which should be warped with the final ``warpMatrix`` in order to provide an image similar to ``templateImage``, same type as ``temlateImage``.
-
- :param warpMatrix: floating-point :math:`2\times 3` or :math:`3\times 3` mapping matrix (warp).
-
- :param motionType: parameter, specifying the type of motion:
-
- * **MOTION_TRANSLATION** sets a translational motion model; ``warpMatrix`` is :math:`2\times 3` with the first :math:`2\times 2` part being the unity matrix and the rest two parameters being estimated.
-
- * **MOTION_EUCLIDEAN** sets a Euclidean (rigid) transformation as motion model; three parameters are estimated; ``warpMatrix`` is :math:`2\times 3`.
-
- * **MOTION_AFFINE** sets an affine motion model (DEFAULT); six parameters are estimated; ``warpMatrix`` is :math:`2\times 3`.
-
- * **MOTION_HOMOGRAPHY** sets a homography as a motion model; eight parameters are estimated;``warpMatrix`` is :math:`3\times 3`.
-
- :param criteria: parameter, specifying the termination criteria of the ECC algorithm; ``criteria.epsilon`` defines the threshold of the increment in the correlation coefficient between two iterations (a negative ``criteria.epsilon`` makes ``criteria.maxcount`` the only termination criterion). Default values are shown in the declaration above.
-
-
-The function estimates the optimum transformation (``warpMatrix``) with respect to ECC criterion ([EP08]_), that is
-
-.. math::
-
- \texttt{warpMatrix} = \texttt{warpMatrix} = \arg\max_{W} \texttt{ECC}(\texttt{templateImage}(x,y),\texttt{inputImage}(x',y'))
-
-where
-
-.. math::
-
- \begin{bmatrix} x' \\ y' \end{bmatrix} = W \cdot \begin{bmatrix} x \\ y \\ 1 \end{bmatrix}
-
-(the equation holds with homogeneous coordinates for homography). It returns the final enhanced correlation coefficient, that is the correlation coefficient between the template image and the final warped input image. When a :math:`3\times 3` matrix is given with ``motionType`` =0, 1 or 2, the third row is ignored.
-
-
-Unlike :ocv:func:`findHomography` and :ocv:func:`estimateRigidTransform`, the function :ocv:func:`findTransformECC` implements an area-based alignment that builds on intensity similarities. In essence, the function updates the initial transformation that roughly aligns the images. If this information is missing, the identity warp (unity matrix) should be given as input. Note that if images undergo strong displacements/rotations, an initial transformation that roughly aligns the images is necessary (e.g., a simple euclidean/similarity transform that allows for the images showing the same image content approximately). Use inverse warping in the second image to take an image close to the first one, i.e. use the flag ``WARP_INVERSE_MAP`` with :ocv:func:`warpAffine` or :ocv:func:`warpPerspective`. See also the OpenCV sample ``image_alignment.cpp`` that demonstrates the use of the function. Note that the function throws an exception if algorithm does not converges.
-
-.. seealso::
-
- :ocv:func:`estimateRigidTransform`,
- :ocv:func:`findHomography`
-
-
-CamShift
---------
-Finds an object center, size, and orientation.
-
-.. ocv:function:: RotatedRect CamShift( InputArray probImage, Rect& window, TermCriteria criteria )
-
-.. ocv:pyfunction:: cv2.CamShift(probImage, window, criteria) -> retval, window
-
-.. ocv:cfunction:: int cvCamShift( const CvArr* prob_image, CvRect window, CvTermCriteria criteria, CvConnectedComp* comp, CvBox2D* box=NULL )
-
- :param probImage: Back projection of the object histogram. See :ocv:func:`calcBackProject` .
-
- :param window: Initial search window.
-
- :param criteria: Stop criteria for the underlying :ocv:func:`meanShift` .
-
- :returns: (in old interfaces) Number of iterations CAMSHIFT took to converge
-
-The function implements the CAMSHIFT object tracking algorithm
-[Bradski98]_.
-First, it finds an object center using
-:ocv:func:`meanShift` and then adjusts the window size and finds the optimal rotation. The function returns the rotated rectangle structure that includes the object position, size, and orientation. The next position of the search window can be obtained with ``RotatedRect::boundingRect()`` .
-
-See the OpenCV sample ``camshiftdemo.c`` that tracks colored objects.
-
-.. note::
-
- * (Python) A sample explaining the camshift tracking algorithm can be found at opencv_source_code/samples/python2/camshift.py
-
-meanShift
----------
-Finds an object on a back projection image.
-
-.. ocv:function:: int meanShift( InputArray probImage, Rect& window, TermCriteria criteria )
-
-.. ocv:pyfunction:: cv2.meanShift(probImage, window, criteria) -> retval, window
-
-.. ocv:cfunction:: int cvMeanShift( const CvArr* prob_image, CvRect window, CvTermCriteria criteria, CvConnectedComp* comp )
-
- :param probImage: Back projection of the object histogram. See :ocv:func:`calcBackProject` for details.
-
- :param window: Initial search window.
-
- :param criteria: Stop criteria for the iterative search algorithm.
-
- :returns: Number of iterations CAMSHIFT took to converge.
-
-The function implements the iterative object search algorithm. It takes the input back projection of an object and the initial position. The mass center in ``window`` of the back projection image is computed and the search window center shifts to the mass center. The procedure is repeated until the specified number of iterations ``criteria.maxCount`` is done or until the window center shifts by less than ``criteria.epsilon`` . The algorithm is used inside
-:ocv:func:`CamShift` and, unlike
-:ocv:func:`CamShift` , the search window size or orientation do not change during the search. You can simply pass the output of
-:ocv:func:`calcBackProject` to this function. But better results can be obtained if you pre-filter the back projection and remove the noise. For example, you can do this by retrieving connected components with
-:ocv:func:`findContours` , throwing away contours with small area (
-:ocv:func:`contourArea` ), and rendering the remaining contours with
-:ocv:func:`drawContours` .
-
-.. note::
-
- * A mean-shift tracking sample can be found at opencv_source_code/samples/cpp/camshiftdemo.cpp
-
-KalmanFilter
-------------
-.. ocv:class:: KalmanFilter
-
- Kalman filter class.
-
-The class implements a standard Kalman filter
-http://en.wikipedia.org/wiki/Kalman_filter, [Welch95]_. However, you can modify ``transitionMatrix``, ``controlMatrix``, and ``measurementMatrix`` to get an extended Kalman filter functionality. See the OpenCV sample ``kalman.cpp`` .
-
-.. note::
-
- * An example using the standard Kalman filter can be found at opencv_source_code/samples/cpp/kalman.cpp
-
-
-KalmanFilter::KalmanFilter
---------------------------
-The constructors.
-
-.. ocv:function:: KalmanFilter::KalmanFilter()
-
-.. ocv:function:: KalmanFilter::KalmanFilter(int dynamParams, int measureParams, int controlParams=0, int type=CV_32F)
-
-.. ocv:pyfunction:: cv2.KalmanFilter([dynamParams, measureParams[, controlParams[, type]]]) -> <KalmanFilter object>
-
-.. ocv:cfunction:: CvKalman* cvCreateKalman( int dynam_params, int measure_params, int control_params=0 )
-
- The full constructor.
-
- :param dynamParams: Dimensionality of the state.
-
- :param measureParams: Dimensionality of the measurement.
-
- :param controlParams: Dimensionality of the control vector.
-
- :param type: Type of the created matrices that should be ``CV_32F`` or ``CV_64F``.
-
-.. note:: In C API when ``CvKalman* kalmanFilter`` structure is not needed anymore, it should be released with ``cvReleaseKalman(&kalmanFilter)``
-
-KalmanFilter::init
-------------------
-Re-initializes Kalman filter. The previous content is destroyed.
-
-.. ocv:function:: void KalmanFilter::init(int dynamParams, int measureParams, int controlParams=0, int type=CV_32F)
-
- :param dynamParams: Dimensionalityensionality of the state.
-
- :param measureParams: Dimensionality of the measurement.
-
- :param controlParams: Dimensionality of the control vector.
-
- :param type: Type of the created matrices that should be ``CV_32F`` or ``CV_64F``.
-
-
-KalmanFilter::predict
----------------------
-Computes a predicted state.
-
-.. ocv:function:: const Mat& KalmanFilter::predict(const Mat& control=Mat())
-
-.. ocv:pyfunction:: cv2.KalmanFilter.predict([control]) -> retval
-
-.. ocv:cfunction:: const CvMat* cvKalmanPredict( CvKalman* kalman, const CvMat* control=NULL)
-
- :param control: The optional input control
-
-
-KalmanFilter::correct
----------------------
-Updates the predicted state from the measurement.
-
-.. ocv:function:: const Mat& KalmanFilter::correct(const Mat& measurement)
-
-.. ocv:pyfunction:: cv2.KalmanFilter.correct(measurement) -> retval
-
-.. ocv:cfunction:: const CvMat* cvKalmanCorrect( CvKalman* kalman, const CvMat* measurement )
-
- :param measurement: The measured system parameters
-
-
-BackgroundSubtractor
---------------------
-
-.. ocv:class:: BackgroundSubtractor : public Algorithm
-
-Base class for background/foreground segmentation. ::
-
- class BackgroundSubtractor : public Algorithm
- {
- public:
- virtual ~BackgroundSubtractor();
- virtual void apply(InputArray image, OutputArray fgmask, double learningRate=0);
- virtual void getBackgroundImage(OutputArray backgroundImage) const;
- };
-
-
-The class is only used to define the common interface for the whole family of background/foreground segmentation algorithms.
-
-
-BackgroundSubtractor::apply
---------------------------------
-Computes a foreground mask.
-
-.. ocv:function:: void BackgroundSubtractor::apply(InputArray image, OutputArray fgmask, double learningRate=-1)
-
-.. ocv:pyfunction:: cv2.BackgroundSubtractor.apply(image[, fgmask[, learningRate]]) -> fgmask
-
- :param image: Next video frame.
-
- :param fgmask: The output foreground mask as an 8-bit binary image.
-
- :param learningRate: The value between 0 and 1 that indicates how fast the background model is learnt. Negative parameter value makes the algorithm to use some automatically chosen learning rate. 0 means that the background model is not updated at all, 1 means that the background model is completely reinitialized from the last frame.
-
-BackgroundSubtractor::getBackgroundImage
-----------------------------------------
-Computes a background image.
-
-.. ocv:function:: void BackgroundSubtractor::getBackgroundImage(OutputArray backgroundImage) const
-
- :param backgroundImage: The output background image.
-
-.. note:: Sometimes the background image can be very blurry, as it contain the average background statistics.
-
-BackgroundSubtractorMOG
------------------------
-
-.. ocv:class:: BackgroundSubtractorMOG : public BackgroundSubtractor
-
-Gaussian Mixture-based Background/Foreground Segmentation Algorithm.
-
-The class implements the algorithm described in [KB2001]_.
-
-
-createBackgroundSubtractorMOG
-------------------------------------------------
-Creates mixture-of-gaussian background subtractor
-
-.. ocv:function:: Ptr<BackgroundSubtractorMOG> createBackgroundSubtractorMOG(int history=200, int nmixtures=5, double backgroundRatio=0.7, double noiseSigma=0)
-
-.. ocv:pyfunction:: cv2.createBackgroundSubtractorMOG([history[, nmixtures[, backgroundRatio[, noiseSigma]]]]) -> retval
-
- :param history: Length of the history.
-
- :param nmixtures: Number of Gaussian mixtures.
-
- :param backgroundRatio: Background ratio.
-
- :param noiseSigma: Noise strength (standard deviation of the brightness or each color channel). 0 means some automatic value.
-
-
-BackgroundSubtractorMOG2
-------------------------
-Gaussian Mixture-based Background/Foreground Segmentation Algorithm.
-
-.. ocv:class:: BackgroundSubtractorMOG2 : public BackgroundSubtractor
-
-The class implements the Gaussian mixture model background subtraction described in [Zivkovic2004]_ and [Zivkovic2006]_ .
-
-
-createBackgroundSubtractorMOG2
---------------------------------------------------
-Creates MOG2 Background Subtractor
-
-.. ocv:function:: Ptr<BackgroundSubtractorMOG2> createBackgroundSubtractorMOG2( int history=500, double varThreshold=16, bool detectShadows=true )
-
- :param history: Length of the history.
-
- :param varThreshold: Threshold on the squared Mahalanobis distance between the pixel and the model to decide whether a pixel is well described by the background model. This parameter does not affect the background update.
-
- :param detectShadows: If true, the algorithm will detect shadows and mark them. It decreases the speed a bit, so if you do not need this feature, set the parameter to false.
-
-
-BackgroundSubtractorMOG2::getHistory
---------------------------------------
-Returns the number of last frames that affect the background model
-
-.. ocv:function:: int BackgroundSubtractorMOG2::getHistory() const
-
-
-BackgroundSubtractorMOG2::setHistory
---------------------------------------
-Sets the number of last frames that affect the background model
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setHistory(int history)
-
-
-BackgroundSubtractorMOG2::getNMixtures
---------------------------------------
-Returns the number of gaussian components in the background model
-
-.. ocv:function:: int BackgroundSubtractorMOG2::getNMixtures() const
-
-
-BackgroundSubtractorMOG2::setNMixtures
---------------------------------------
-Sets the number of gaussian components in the background model. The model needs to be reinitalized to reserve memory.
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setNMixtures(int nmixtures)
-
-
-BackgroundSubtractorMOG2::getBackgroundRatio
----------------------------------------------
-Returns the "background ratio" parameter of the algorithm
-
-.. ocv:function:: double BackgroundSubtractorMOG2::getBackgroundRatio() const
-
-If a foreground pixel keeps semi-constant value for about ``backgroundRatio*history`` frames, it's considered background and added to the model as a center of a new component. It corresponds to ``TB`` parameter in the paper.
-
-BackgroundSubtractorMOG2::setBackgroundRatio
----------------------------------------------
-Sets the "background ratio" parameter of the algorithm
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setBackgroundRatio(double ratio)
-
-BackgroundSubtractorMOG2::getVarThreshold
----------------------------------------------
-Returns the variance threshold for the pixel-model match
-
-.. ocv:function:: double BackgroundSubtractorMOG2::getVarThreshold() const
-
-The main threshold on the squared Mahalanobis distance to decide if the sample is well described by the background model or not. Related to Cthr from the paper.
-
-BackgroundSubtractorMOG2::setVarThreshold
----------------------------------------------
-Sets the variance threshold for the pixel-model match
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setVarThreshold(double varThreshold)
-
-BackgroundSubtractorMOG2::getVarThresholdGen
----------------------------------------------
-Returns the variance threshold for the pixel-model match used for new mixture component generation
-
-.. ocv:function:: double BackgroundSubtractorMOG2::getVarThresholdGen() const
-
-Threshold for the squared Mahalanobis distance that helps decide when a sample is close to the existing components (corresponds to ``Tg`` in the paper). If a pixel is not close to any component, it is considered foreground or added as a new component. ``3 sigma => Tg=3*3=9`` is default. A smaller ``Tg`` value generates more components. A higher ``Tg`` value may result in a small number of components but they can grow too large.
-
-BackgroundSubtractorMOG2::setVarThresholdGen
----------------------------------------------
-Sets the variance threshold for the pixel-model match used for new mixture component generation
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setVarThresholdGen(double varThresholdGen)
-
-BackgroundSubtractorMOG2::getVarInit
----------------------------------------------
-Returns the initial variance of each gaussian component
-
-.. ocv:function:: double BackgroundSubtractorMOG2::getVarInit() const
-
-BackgroundSubtractorMOG2::setVarInit
----------------------------------------------
-Sets the initial variance of each gaussian component
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setVarInit(double varInit)
-
-
-BackgroundSubtractorMOG2::getComplexityReductionThreshold
-----------------------------------------------------------
-Returns the complexity reduction threshold
-
-.. ocv:function:: double BackgroundSubtractorMOG2::getComplexityReductionThreshold() const
-
-This parameter defines the number of samples needed to accept to prove the component exists. ``CT=0.05`` is a default value for all the samples. By setting ``CT=0`` you get an algorithm very similar to the standard Stauffer&Grimson algorithm.
-
-BackgroundSubtractorMOG2::setComplexityReductionThreshold
-----------------------------------------------------------
-Sets the complexity reduction threshold
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setComplexityReductionThreshold(double ct)
-
-
-BackgroundSubtractorMOG2::getDetectShadows
----------------------------------------------
-Returns the shadow detection flag
-
-.. ocv:function:: bool BackgroundSubtractorMOG2::getDetectShadows() const
-
-If true, the algorithm detects shadows and marks them. See createBackgroundSubtractorMOG2 for details.
-
-BackgroundSubtractorMOG2::setDetectShadows
----------------------------------------------
-Enables or disables shadow detection
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setDetectShadows(bool detectShadows)
-
-BackgroundSubtractorMOG2::getShadowValue
----------------------------------------------
-Returns the shadow value
-
-.. ocv:function:: int BackgroundSubtractorMOG2::getShadowValue() const
-
-Shadow value is the value used to mark shadows in the foreground mask. Default value is 127. Value 0 in the mask always means background, 255 means foreground.
-
-BackgroundSubtractorMOG2::setShadowValue
----------------------------------------------
-Sets the shadow value
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setShadowValue(int value)
-
-BackgroundSubtractorMOG2::getShadowThreshold
----------------------------------------------
-Returns the shadow threshold
-
-.. ocv:function:: double BackgroundSubtractorMOG2::getShadowThreshold() const
-
-A shadow is detected if pixel is a darker version of the background. The shadow threshold (``Tau`` in the paper) is a threshold defining how much darker the shadow can be. ``Tau= 0.5`` means that if a pixel is more than twice darker then it is not shadow. See Prati, Mikic, Trivedi and Cucchiarra, *Detecting Moving Shadows...*, IEEE PAMI,2003.
-
-BackgroundSubtractorMOG2::setShadowThreshold
----------------------------------------------
-Sets the shadow threshold
-
-.. ocv:function:: void BackgroundSubtractorMOG2::setShadowThreshold(double threshold)
-
-
-BackgroundSubtractorKNN
-------------------------
-K-nearest neigbours - based Background/Foreground Segmentation Algorithm.
-
-.. ocv:class:: BackgroundSubtractorKNN : public BackgroundSubtractor
-
-The class implements the K-nearest neigbours background subtraction described in [Zivkovic2006]_ . Very efficient if number of foreground pixels is low.
-
-
-createBackgroundSubtractorKNN
---------------------------------------------------
-Creates KNN Background Subtractor
-
-.. ocv:function:: Ptr<BackgroundSubtractorKNN> createBackgroundSubtractorKNN( int history=500, double dist2Threshold=400.0, bool detectShadows=true )
-
- :param history: Length of the history.
-
- :param dist2Threshold: Threshold on the squared distance between the pixel and the sample to decide whether a pixel is close to that sample. This parameter does not affect the background update.
-
- :param detectShadows: If true, the algorithm will detect shadows and mark them. It decreases the speed a bit, so if you do not need this feature, set the parameter to false.
-
-
-BackgroundSubtractorKNN::getHistory
---------------------------------------
-Returns the number of last frames that affect the background model
-
-.. ocv:function:: int BackgroundSubtractorKNN::getHistory() const
-
-
-BackgroundSubtractorKNN::setHistory
---------------------------------------
-Sets the number of last frames that affect the background model
-
-.. ocv:function:: void BackgroundSubtractorKNN::setHistory(int history)
-
-
-BackgroundSubtractorKNN::getNSamples
---------------------------------------
-Returns the number of data samples in the background model
-
-.. ocv:function:: int BackgroundSubtractorKNN::getNSamples() const
-
-
-BackgroundSubtractorKNN::setNSamples
---------------------------------------
-Sets the number of data samples in the background model. The model needs to be reinitalized to reserve memory.
-
-.. ocv:function:: void BackgroundSubtractorKNN::setNSamples(int _nN)
-
-
-BackgroundSubtractorKNN::getDist2Threshold
----------------------------------------------
-Returns the threshold on the squared distance between the pixel and the sample
-
-.. ocv:function:: double BackgroundSubtractorKNN::getDist2Threshold() const
-
-The threshold on the squared distance between the pixel and the sample to decide whether a pixel is close to a data sample.
-
-BackgroundSubtractorKNN::setDist2Threshold
----------------------------------------------
-Sets the threshold on the squared distance
-
-.. ocv:function:: void BackgroundSubtractorKNN::setDist2Threshold(double _dist2Threshold)
-
-BackgroundSubtractorKNN::getkNNSamples
----------------------------------------------
-Returns the number of neighbours, the k in the kNN. K is the number of samples that need to be within dist2Threshold in order to decide that that pixel is matching the kNN background model.
-
-.. ocv:function:: int BackgroundSubtractorKNN::getkNNSamples() const
-
-BackgroundSubtractorKNN::setkNNSamples
----------------------------------------------
-Sets the k in the kNN. How many nearest neigbours need to match.
-
-.. ocv:function:: void BackgroundSubtractorKNN::setkNNSamples(int _nkNN)
-
-
-BackgroundSubtractorKNN::getDetectShadows
----------------------------------------------
-Returns the shadow detection flag
-
-.. ocv:function:: bool BackgroundSubtractorKNN::getDetectShadows() const
-
-If true, the algorithm detects shadows and marks them. See createBackgroundSubtractorKNN for details.
-
-BackgroundSubtractorKNN::setDetectShadows
----------------------------------------------
-Enables or disables shadow detection
-
-.. ocv:function:: void BackgroundSubtractorKNN::setDetectShadows(bool detectShadows)
-
-BackgroundSubtractorKNN::getShadowValue
----------------------------------------------
-Returns the shadow value
-
-.. ocv:function:: int BackgroundSubtractorKNN::getShadowValue() const
-
-Shadow value is the value used to mark shadows in the foreground mask. Default value is 127. Value 0 in the mask always means background, 255 means foreground.
-
-BackgroundSubtractorKNN::setShadowValue
----------------------------------------------
-Sets the shadow value
-
-.. ocv:function:: void BackgroundSubtractorKNN::setShadowValue(int value)
-
-BackgroundSubtractorKNN::getShadowThreshold
----------------------------------------------
-Returns the shadow threshold
-
-.. ocv:function:: double BackgroundSubtractorKNN::getShadowThreshold() const
-
-A shadow is detected if pixel is a darker version of the background. The shadow threshold (``Tau`` in the paper) is a threshold defining how much darker the shadow can be. ``Tau= 0.5`` means that if a pixel is more than twice darker then it is not shadow. See Prati, Mikic, Trivedi and Cucchiarra, *Detecting Moving Shadows...*, IEEE PAMI,2003.
-
-BackgroundSubtractorKNN::setShadowThreshold
----------------------------------------------
-Sets the shadow threshold
-
-.. ocv:function:: void BackgroundSubtractorKNN::setShadowThreshold(double threshold)
-
-
-BackgroundSubtractorGMG
-------------------------
-Background Subtractor module based on the algorithm given in [Gold2012]_.
-
-.. ocv:class:: BackgroundSubtractorGMG : public BackgroundSubtractor
-
-
-createBackgroundSubtractorGMG
------------------------------------
-Creates a GMG Background Subtractor
-
-.. ocv:function:: Ptr<BackgroundSubtractorGMG> createBackgroundSubtractorGMG(int initializationFrames=120, double decisionThreshold=0.8)
-
-.. ocv:pyfunction:: cv2.createBackgroundSubtractorGMG([, initializationFrames[, decisionThreshold]]) -> retval
-
- :param initializationFrames: number of frames used to initialize the background models.
-
- :param decisionThreshold: Threshold value, above which it is marked foreground, else background.
-
-
-BackgroundSubtractorGMG::getNumFrames
----------------------------------------
-Returns the number of frames used to initialize background model.
-
-.. ocv:function:: int BackgroundSubtractorGMG::getNumFrames() const
-
-
-BackgroundSubtractorGMG::setNumFrames
----------------------------------------
-Sets the number of frames used to initialize background model.
-
-.. ocv:function:: void BackgroundSubtractorGMG::setNumFrames(int nframes)
-
-
-BackgroundSubtractorGMG::getDefaultLearningRate
---------------------------------------------------
-Returns the learning rate of the algorithm. It lies between 0.0 and 1.0. It determines how quickly features are "forgotten" from histograms.
-
-.. ocv:function:: double BackgroundSubtractorGMG::getDefaultLearningRate() const
-
-
-BackgroundSubtractorGMG::setDefaultLearningRate
---------------------------------------------------
-Sets the learning rate of the algorithm.
-
-.. ocv:function:: void BackgroundSubtractorGMG::setDefaultLearningRate(double lr)
-
-
-BackgroundSubtractorGMG::getDecisionThreshold
---------------------------------------------------
-Returns the value of decision threshold. Decision value is the value above which pixel is determined to be FG.
-
-.. ocv:function:: double BackgroundSubtractorGMG::getDecisionThreshold() const
-
-
-BackgroundSubtractorGMG::setDecisionThreshold
---------------------------------------------------
-Sets the value of decision threshold.
-
-.. ocv:function:: void BackgroundSubtractorGMG::setDecisionThreshold(double thresh)
-
-
-BackgroundSubtractorGMG::getMaxFeatures
---------------------------------------------------
-Returns total number of distinct colors to maintain in histogram.
-
-.. ocv:function:: int BackgroundSubtractorGMG::getMaxFeatures() const
-
-
-BackgroundSubtractorGMG::setMaxFeatures
---------------------------------------------------
-Sets total number of distinct colors to maintain in histogram.
-
-.. ocv:function:: void BackgroundSubtractorGMG::setMaxFeatures(int maxFeatures)
-
-
-BackgroundSubtractorGMG::getQuantizationLevels
---------------------------------------------------
-Returns the parameter used for quantization of color-space. It is the number of discrete levels in each channel to be used in histograms.
-
-.. ocv:function:: int BackgroundSubtractorGMG::getQuantizationLevels() const
-
-
-BackgroundSubtractorGMG::setQuantizationLevels
---------------------------------------------------
-Sets the parameter used for quantization of color-space
-
-.. ocv:function:: void BackgroundSubtractorGMG::setQuantizationLevels(int nlevels)
-
-
-BackgroundSubtractorGMG::getSmoothingRadius
---------------------------------------------------
-Returns the kernel radius used for morphological operations
-
-.. ocv:function:: int BackgroundSubtractorGMG::getSmoothingRadius() const
-
-
-BackgroundSubtractorGMG::setSmoothingRadius
---------------------------------------------------
-Sets the kernel radius used for morphological operations
-
-.. ocv:function:: void BackgroundSubtractorGMG::setSmoothingRadius(int radius)
-
-
-BackgroundSubtractorGMG::getUpdateBackgroundModel
---------------------------------------------------
-Returns the status of background model update
-
-.. ocv:function:: bool BackgroundSubtractorGMG::getUpdateBackgroundModel() const
-
-
-BackgroundSubtractorGMG::setUpdateBackgroundModel
---------------------------------------------------
-Sets the status of background model update
-
-.. ocv:function:: void BackgroundSubtractorGMG::setUpdateBackgroundModel(bool update)
-
-
-BackgroundSubtractorGMG::getMinVal
---------------------------------------------------
-Returns the minimum value taken on by pixels in image sequence. Usually 0.
-
-.. ocv:function:: double BackgroundSubtractorGMG::getMinVal() const
-
-
-BackgroundSubtractorGMG::setMinVal
---------------------------------------------------
-Sets the minimum value taken on by pixels in image sequence.
-
-.. ocv:function:: void BackgroundSubtractorGMG::setMinVal(double val)
-
-
-BackgroundSubtractorGMG::getMaxVal
---------------------------------------------------
-Returns the maximum value taken on by pixels in image sequence. e.g. 1.0 or 255.
-
-.. ocv:function:: double BackgroundSubtractorGMG::getMaxVal() const
-
-
-BackgroundSubtractorGMG::setMaxVal
---------------------------------------------------
-Sets the maximum value taken on by pixels in image sequence.
-
-.. ocv:function:: void BackgroundSubtractorGMG::setMaxVal(double val)
-
-
-BackgroundSubtractorGMG::getBackgroundPrior
---------------------------------------------------
-Returns the prior probability that each individual pixel is a background pixel.
-
-.. ocv:function:: double BackgroundSubtractorGMG::getBackgroundPrior() const
-
-
-BackgroundSubtractorGMG::setBackgroundPrior
---------------------------------------------------
-Sets the prior probability that each individual pixel is a background pixel.
-
-.. ocv:function:: void BackgroundSubtractorGMG::setBackgroundPrior(double bgprior)
-
-
-createOptFlow_DualTVL1
-----------------------
-"Dual TV L1" Optical Flow Algorithm.
-
-.. ocv:function:: Ptr<DenseOpticalFlow> createOptFlow_DualTVL1()
-
-
- The class implements the "Dual TV L1" optical flow algorithm described in [Zach2007]_ and [Javier2012]_ .
-
- Here are important members of the class that control the algorithm, which you can set after constructing the class instance:
-
- .. ocv:member:: double tau
-
- Time step of the numerical scheme.
-
- .. ocv:member:: double lambda
-
- Weight parameter for the data term, attachment parameter. This is the most relevant parameter, which determines the smoothness of the output. The smaller this parameter is, the smoother the solutions we obtain. It depends on the range of motions of the images, so its value should be adapted to each image sequence.
-
- .. ocv:member:: double theta
-
- Weight parameter for (u - v)^2, tightness parameter. It serves as a link between the attachment and the regularization terms. In theory, it should have a small value in order to maintain both parts in correspondence. The method is stable for a large range of values of this parameter.
-
- .. ocv:member:: int nscales
-
- Number of scales used to create the pyramid of images.
-
- .. ocv:member:: int warps
-
- Number of warpings per scale. Represents the number of times that I1(x+u0) and grad( I1(x+u0) ) are computed per scale. This is a parameter that assures the stability of the method. It also affects the running time, so it is a compromise between speed and accuracy.
-
- .. ocv:member:: double epsilon
-
- Stopping criterion threshold used in the numerical scheme, which is a trade-off between precision and running time. A small value will yield more accurate solutions at the expense of a slower convergence.
-
- .. ocv:member:: int iterations
-
- Stopping criterion iterations number used in the numerical scheme.
-
-
-DenseOpticalFlow::calc
---------------------------
-Calculates an optical flow.
-
-.. ocv:function:: void DenseOpticalFlow::calc(InputArray I0, InputArray I1, InputOutputArray flow)
-
- :param I0: first 8-bit single-channel input image.
-
- :param I1: second input image of the same size and the same type as ``I0`` .
-
- :param flow: computed flow image that has the same size as ``I0`` and type ``CV_32FC2`` .
-
-
-
-DenseOpticalFlow::collectGarbage
---------------------------------
-Releases all inner buffers.
-
-.. ocv:function:: void DenseOpticalFlow::collectGarbage()
-
-
-
-.. [Bouguet00] Jean-Yves Bouguet. Pyramidal Implementation of the Lucas Kanade Feature Tracker.
-
-.. [Bradski98] Bradski, G.R. "Computer Vision Face Tracking for Use in a Perceptual User Interface", Intel, 1998
-
-.. [EP08] Evangelidis, G.D. and Psarakis E.Z. "Parametric Image Alignment using Enhanced Correlation Coefficient Maximization", IEEE Transactions on PAMI, vol. 32, no. 10, 2008
-
-.. [Farneback2003] Gunnar Farneback, Two-frame motion estimation based on polynomial expansion, Lecture Notes in Computer Science, 2003, (2749), , 363-370.
-
-.. [Horn81] Berthold K.P. Horn and Brian G. Schunck. Determining Optical Flow. Artificial Intelligence, 17, pp. 185-203, 1981.
-
-.. [KB2001] P. KadewTraKuPong and R. Bowden. "An improved adaptive background mixture model for real-time tracking with shadow detection", Proc. 2nd European Workshop on Advanced Video-Based Surveillance Systems, 2001: http://personal.ee.surrey.ac.uk/Personal/R.Bowden/publications/avbs01/avbs01.pdf
-
-.. [Javier2012] Javier Sanchez, Enric Meinhardt-Llopis and Gabriele Facciolo. "TV-L1 Optical Flow Estimation".
-
-.. [Lucas81] Lucas, B., and Kanade, T. An Iterative Image Registration Technique with an Application to Stereo Vision, Proc. of 7th International Joint Conference on Artificial Intelligence (IJCAI), pp. 674-679.
-
-.. [Welch95] Greg Welch and Gary Bishop "An Introduction to the Kalman Filter", 1995
-
-.. [Zach2007] C. Zach, T. Pock and H. Bischof. "A Duality Based Approach for Realtime TV-L1 Optical Flow", In Proceedings of Pattern Recognition (DAGM), Heidelberg, Germany, pp. 214-223, 2007
-
-.. [Zivkovic2004] Z. Zivkovic. "Improved adaptive Gausian mixture model for background subtraction", International Conference Pattern Recognition, UK, August, 2004, http://www.zoranz.net/Publications/zivkovic2004ICPR.pdf. The code is very fast and performs also shadow detection. Number of Gausssian components is adapted per pixel.
-
-.. [Zivkovic2006] Z.Zivkovic, F. van der Heijden. "Efficient Adaptive Density Estimation per Image Pixel for the Task of Background Subtraction", Pattern Recognition Letters, vol. 27, no. 7, pages 773-780, 2006.
-
-.. [Gold2012] Andrew B. Godbehere, Akihiro Matsukawa, Ken Goldberg, "Visual Tracking of Human Visitors under Variable-Lighting Conditions for a Responsive Audio Art Installation", American Control Conference, Montreal, June 2012.
+++ /dev/null
-*********************
-video. Video Analysis
-*********************
-
-.. toctree::
- :maxdepth: 2
-
- motion_analysis_and_object_tracking
+++ /dev/null
-Reading and Writing Video
-=========================
-
-.. highlight:: cpp
-
-
-VideoCapture
-------------
-.. ocv:class:: VideoCapture
-
-Class for video capturing from video files, image sequences or cameras.
-The class provides C++ API for capturing video from cameras or for reading video files and image sequences. Here is how the class can be used: ::
-
- #include "opencv2/opencv.hpp"
-
- using namespace cv;
-
- int main(int, char**)
- {
- VideoCapture cap(0); // open the default camera
- if(!cap.isOpened()) // check if we succeeded
- return -1;
-
- Mat edges;
- namedWindow("edges",1);
- for(;;)
- {
- Mat frame;
- cap >> frame; // get a new frame from camera
- cvtColor(frame, edges, COLOR_BGR2GRAY);
- GaussianBlur(edges, edges, Size(7,7), 1.5, 1.5);
- Canny(edges, edges, 0, 30, 3);
- imshow("edges", edges);
- if(waitKey(30) >= 0) break;
- }
- // the camera will be deinitialized automatically in VideoCapture destructor
- return 0;
- }
-
-
-.. note:: In C API the black-box structure ``CvCapture`` is used instead of ``VideoCapture``.
-
-.. note::
-
- * A basic sample on using the VideoCapture interface can be found at opencv_source_code/samples/cpp/starter_video.cpp
- * Another basic video processing sample can be found at opencv_source_code/samples/cpp/video_dmtx.cpp
-
- * (Python) A basic sample on using the VideoCapture interface can be found at opencv_source_code/samples/python2/video.py
- * (Python) Another basic video processing sample can be found at opencv_source_code/samples/python2/video_dmtx.py
- * (Python) A multi threaded video processing sample can be found at opencv_source_code/samples/python2/video_threaded.py
-
-
-VideoCapture::VideoCapture
-------------------------------
-VideoCapture constructors.
-
-.. ocv:function:: VideoCapture::VideoCapture()
-
-.. ocv:function:: VideoCapture::VideoCapture(const String& filename)
-
-.. ocv:function:: VideoCapture::VideoCapture(int device)
-
-.. ocv:pyfunction:: cv2.VideoCapture() -> <VideoCapture object>
-.. ocv:pyfunction:: cv2.VideoCapture(filename) -> <VideoCapture object>
-.. ocv:pyfunction:: cv2.VideoCapture(device) -> <VideoCapture object>
-
-.. ocv:cfunction:: CvCapture* cvCaptureFromCAM( int device )
-.. ocv:cfunction:: CvCapture* cvCaptureFromFile( const char* filename )
-
- :param filename: name of the opened video file (eg. video.avi) or image sequence (eg. img_%02d.jpg, which will read samples like img_00.jpg, img_01.jpg, img_02.jpg, ...)
-
- :param device: id of the opened video capturing device (i.e. a camera index). If there is a single camera connected, just pass 0.
-
-.. note:: In C API, when you finished working with video, release ``CvCapture`` structure with ``cvReleaseCapture()``, or use ``Ptr<CvCapture>`` that calls ``cvReleaseCapture()`` automatically in the destructor.
-
-
-VideoCapture::open
----------------------
-Open video file or a capturing device for video capturing
-
-.. ocv:function:: bool VideoCapture::open(const String& filename)
-.. ocv:function:: bool VideoCapture::open(int device)
-
-.. ocv:pyfunction:: cv2.VideoCapture.open(filename) -> retval
-.. ocv:pyfunction:: cv2.VideoCapture.open(device) -> retval
-
- :param filename: name of the opened video file (eg. video.avi) or image sequence (eg. img_%02d.jpg, which will read samples like img_00.jpg, img_01.jpg, img_02.jpg, ...)
-
- :param device: id of the opened video capturing device (i.e. a camera index).
-
-The methods first call :ocv:func:`VideoCapture::release` to close the already opened file or camera.
-
-
-VideoCapture::isOpened
-----------------------
-Returns true if video capturing has been initialized already.
-
-.. ocv:function:: bool VideoCapture::isOpened()
-
-.. ocv:pyfunction:: cv2.VideoCapture.isOpened() -> retval
-
-If the previous call to ``VideoCapture`` constructor or ``VideoCapture::open`` succeeded, the method returns true.
-
-VideoCapture::release
----------------------
-Closes video file or capturing device.
-
-.. ocv:function:: void VideoCapture::release()
-
-.. ocv:pyfunction:: cv2.VideoCapture.release() -> None
-
-.. ocv:cfunction:: void cvReleaseCapture(CvCapture** capture)
-
-The methods are automatically called by subsequent :ocv:func:`VideoCapture::open` and by ``VideoCapture`` destructor.
-
-The C function also deallocates memory and clears ``*capture`` pointer.
-
-
-VideoCapture::grab
----------------------
-Grabs the next frame from video file or capturing device.
-
-.. ocv:function:: bool VideoCapture::grab()
-
-.. ocv:pyfunction:: cv2.VideoCapture.grab() -> retval
-
-.. ocv:cfunction:: int cvGrabFrame(CvCapture* capture)
-
-The methods/functions grab the next frame from video file or camera and return true (non-zero) in the case of success.
-
-The primary use of the function is in multi-camera environments, especially when the cameras do not have hardware synchronization. That is, you call ``VideoCapture::grab()`` for each camera and after that call the slower method ``VideoCapture::retrieve()`` to decode and get frame from each camera. This way the overhead on demosaicing or motion jpeg decompression etc. is eliminated and the retrieved frames from different cameras will be closer in time.
-
-Also, when a connected camera is multi-head (for example, a stereo camera or a Kinect device), the correct way of retrieving data from it is to call `VideoCapture::grab` first and then call :ocv:func:`VideoCapture::retrieve` one or more times with different values of the ``channel`` parameter. See https://github.com/Itseez/opencv/tree/master/samples/cpp/openni_capture.cpp
-
-
-VideoCapture::retrieve
-----------------------
-Decodes and returns the grabbed video frame.
-
-.. ocv:function:: bool VideoCapture::retrieve( OutputArray image, int flag=0 )
-
-.. ocv:pyfunction:: cv2.VideoCapture.retrieve([image[, flag]]) -> retval, image
-
-.. ocv:cfunction:: IplImage* cvRetrieveFrame( CvCapture* capture, int streamIdx=0 )
-
-The methods/functions decode and return the just grabbed frame. If no frames has been grabbed (camera has been disconnected, or there are no more frames in video file), the methods return false and the functions return NULL pointer.
-
-.. note:: OpenCV 1.x functions ``cvRetrieveFrame`` and ``cv.RetrieveFrame`` return image stored inside the video capturing structure. It is not allowed to modify or release the image! You can copy the frame using :ocv:cfunc:`cvCloneImage` and then do whatever you want with the copy.
-
-
-VideoCapture::read
-----------------------
-Grabs, decodes and returns the next video frame.
-
-.. ocv:function:: VideoCapture& VideoCapture::operator >> (Mat& image)
-
-.. ocv:function:: VideoCapture& VideoCapture::operator >> (UMat& image)
-
-.. ocv:function:: bool VideoCapture::read(OutputArray image)
-
-.. ocv:pyfunction:: cv2.VideoCapture.read([image]) -> retval, image
-
-.. ocv:cfunction:: IplImage* cvQueryFrame(CvCapture* capture)
-
-The methods/functions combine :ocv:func:`VideoCapture::grab` and :ocv:func:`VideoCapture::retrieve` in one call. This is the most convenient method for reading video files or capturing data from decode and return the just grabbed frame. If no frames has been grabbed (camera has been disconnected, or there are no more frames in video file), the methods return false and the functions return NULL pointer.
-
-.. note:: OpenCV 1.x functions ``cvRetrieveFrame`` and ``cv.RetrieveFrame`` return image stored inside the video capturing structure. It is not allowed to modify or release the image! You can copy the frame using :ocv:cfunc:`cvCloneImage` and then do whatever you want with the copy.
-
-
-VideoCapture::get
----------------------
-Returns the specified ``VideoCapture`` property
-
-.. ocv:function:: double VideoCapture::get(int propId)
-
-.. ocv:pyfunction:: cv2.VideoCapture.get(propId) -> retval
-
-.. ocv:cfunction:: double cvGetCaptureProperty( CvCapture* capture, int property_id )
-
- :param propId: Property identifier. It can be one of the following:
-
- * **CV_CAP_PROP_POS_MSEC** Current position of the video file in milliseconds or video capture timestamp.
-
- * **CV_CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next.
-
- * **CV_CAP_PROP_POS_AVI_RATIO** Relative position of the video file: 0 - start of the film, 1 - end of the film.
-
- * **CV_CAP_PROP_FRAME_WIDTH** Width of the frames in the video stream.
-
- * **CV_CAP_PROP_FRAME_HEIGHT** Height of the frames in the video stream.
-
- * **CV_CAP_PROP_FPS** Frame rate.
-
- * **CV_CAP_PROP_FOURCC** 4-character code of codec.
-
- * **CV_CAP_PROP_FRAME_COUNT** Number of frames in the video file.
-
- * **CV_CAP_PROP_FORMAT** Format of the Mat objects returned by ``retrieve()`` .
-
- * **CV_CAP_PROP_MODE** Backend-specific value indicating the current capture mode.
-
- * **CV_CAP_PROP_BRIGHTNESS** Brightness of the image (only for cameras).
-
- * **CV_CAP_PROP_CONTRAST** Contrast of the image (only for cameras).
-
- * **CV_CAP_PROP_SATURATION** Saturation of the image (only for cameras).
-
- * **CV_CAP_PROP_HUE** Hue of the image (only for cameras).
-
- * **CV_CAP_PROP_GAIN** Gain of the image (only for cameras).
-
- * **CV_CAP_PROP_EXPOSURE** Exposure (only for cameras).
-
- * **CV_CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted to RGB.
-
- * **CV_CAP_PROP_WHITE_BALANCE** Currently not supported
-
- * **CV_CAP_PROP_RECTIFICATION** Rectification flag for stereo cameras (note: only supported by DC1394 v 2.x backend currently)
-
-
-**Note**: When querying a property that is not supported by the backend used by the ``VideoCapture`` class, value 0 is returned.
-
-VideoCapture::set
----------------------
-Sets a property in the ``VideoCapture``.
-
-.. ocv:function:: bool VideoCapture::set( int propId, double value )
-
-.. ocv:pyfunction:: cv2.VideoCapture.set(propId, value) -> retval
-
-.. ocv:cfunction:: int cvSetCaptureProperty( CvCapture* capture, int property_id, double value )
-
- :param propId: Property identifier. It can be one of the following:
-
- * **CV_CAP_PROP_POS_MSEC** Current position of the video file in milliseconds.
-
- * **CV_CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next.
-
- * **CV_CAP_PROP_POS_AVI_RATIO** Relative position of the video file: 0 - start of the film, 1 - end of the film.
-
- * **CV_CAP_PROP_FRAME_WIDTH** Width of the frames in the video stream.
-
- * **CV_CAP_PROP_FRAME_HEIGHT** Height of the frames in the video stream.
-
- * **CV_CAP_PROP_FPS** Frame rate.
-
- * **CV_CAP_PROP_FOURCC** 4-character code of codec.
-
- * **CV_CAP_PROP_FRAME_COUNT** Number of frames in the video file.
-
- * **CV_CAP_PROP_FORMAT** Format of the Mat objects returned by ``retrieve()`` .
-
- * **CV_CAP_PROP_MODE** Backend-specific value indicating the current capture mode.
-
- * **CV_CAP_PROP_BRIGHTNESS** Brightness of the image (only for cameras).
-
- * **CV_CAP_PROP_CONTRAST** Contrast of the image (only for cameras).
-
- * **CV_CAP_PROP_SATURATION** Saturation of the image (only for cameras).
-
- * **CV_CAP_PROP_HUE** Hue of the image (only for cameras).
-
- * **CV_CAP_PROP_GAIN** Gain of the image (only for cameras).
-
- * **CV_CAP_PROP_EXPOSURE** Exposure (only for cameras).
-
- * **CV_CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted to RGB.
-
- * **CV_CAP_PROP_WHITE_BALANCE** Currently unsupported
-
- * **CV_CAP_PROP_RECTIFICATION** Rectification flag for stereo cameras (note: only supported by DC1394 v 2.x backend currently)
-
- :param value: Value of the property.
-
-
-
-VideoWriter
------------
-.. ocv:class:: VideoWriter
-
-Video writer class.
-
-
-
-VideoWriter::VideoWriter
-------------------------
-VideoWriter constructors
-
-.. ocv:function:: VideoWriter::VideoWriter()
-
-.. ocv:function:: VideoWriter::VideoWriter(const String& filename, int fourcc, double fps, Size frameSize, bool isColor=true)
-
-.. ocv:pyfunction:: cv2.VideoWriter([filename, fourcc, fps, frameSize[, isColor]]) -> <VideoWriter object>
-
-.. ocv:cfunction:: CvVideoWriter* cvCreateVideoWriter( const char* filename, int fourcc, double fps, CvSize frame_size, int is_color=1 )
-
-.. ocv:pyfunction:: cv2.VideoWriter.isOpened() -> retval
-.. ocv:pyfunction:: cv2.VideoWriter.open(filename, fourcc, fps, frameSize[, isColor]) -> retval
-.. ocv:pyfunction:: cv2.VideoWriter.write(image) -> None
-
- :param filename: Name of the output video file.
-
- :param fourcc: 4-character code of codec used to compress the frames. For example, ``VideoWriter::fourcc('P','I','M','1')`` is a MPEG-1 codec, ``VideoWriter::fourcc('M','J','P','G')`` is a motion-jpeg codec etc. List of codes can be obtained at `Video Codecs by FOURCC <http://www.fourcc.org/codecs.php>`_ page.
-
- :param fps: Framerate of the created video stream.
-
- :param frameSize: Size of the video frames.
-
- :param isColor: If it is not zero, the encoder will expect and encode color frames, otherwise it will work with grayscale frames (the flag is currently supported on Windows only).
-
-The constructors/functions initialize video writers. On Linux FFMPEG is used to write videos; on Windows FFMPEG or VFW is used; on MacOSX QTKit is used.
-
-
-
-ReleaseVideoWriter
-------------------
-Releases the AVI writer.
-
-.. ocv:cfunction:: void cvReleaseVideoWriter( CvVideoWriter** writer )
-
-The function should be called after you finished using ``CvVideoWriter`` opened with :ocv:cfunc:`CreateVideoWriter`.
-
-
-VideoWriter::open
------------------
-Initializes or reinitializes video writer.
-
-.. ocv:function:: bool VideoWriter::open(const String& filename, int fourcc, double fps, Size frameSize, bool isColor=true)
-
-.. ocv:pyfunction:: cv2.VideoWriter.open(filename, fourcc, fps, frameSize[, isColor]) -> retval
-
-The method opens video writer. Parameters are the same as in the constructor :ocv:func:`VideoWriter::VideoWriter`.
-
-
-VideoWriter::isOpened
----------------------
-Returns true if video writer has been successfully initialized.
-
-.. ocv:function:: bool VideoWriter::isOpened()
-
-.. ocv:pyfunction:: cv2.VideoWriter.isOpened() -> retval
-
-
-VideoWriter::write
-------------------
-Writes the next video frame
-
-.. ocv:function:: VideoWriter& VideoWriter::operator << (const Mat& image)
-
-.. ocv:function:: void VideoWriter::write(const Mat& image)
-
-.. ocv:pyfunction:: cv2.VideoWriter.write(image) -> None
-
-.. ocv:cfunction:: int cvWriteFrame( CvVideoWriter* writer, const IplImage* image )
-
- :param writer: Video writer structure (OpenCV 1.x API)
-
- :param image: The written frame
-
-The functions/methods write the specified image to video file. It must have the same size as has been specified when opening the video writer.
-
-
-VideoWriter::fourcc
--------------------
-Concatenates 4 chars to a fourcc code
-
-.. ocv:function:: static int VideoWriter::fourcc(char c1, char c2, char c3, char c4)
-
-.. ocv:pyfunction:: cv2.VideoWriter_fourcc(c1, c2, c3, c4) -> retval
-
-This static method constructs the fourcc code of the codec to be used in the constructor :ocv:func:`VideoWriter::VideoWriter` or :ocv:func:`VideoWriter::open`.
+++ /dev/null
-*******************
-videoio. Media I/O
-*******************
-
-videoio provides easy interface to:
-
-* Read video from camera or file and write video to a file.
-
-.. toctree::
- :maxdepth: 2
-
- reading_and_writing_video
+++ /dev/null
-Fast Marching Method
-====================
-
-.. highlight:: cpp
-
-The Fast Marching Method [T04]_ is used in of the video stabilization routines to do motion and color inpainting. The method is implemented is a flexible way and it's made public for other users.
-
-videostab::FastMarchingMethod
------------------------------
-
-.. ocv:class:: videostab::FastMarchingMethod
-
-Describes the Fast Marching Method implementation.
-
-::
-
- class CV_EXPORTS FastMarchingMethod
- {
- public:
- FastMarchingMethod();
-
- template <typename Inpaint>
- Inpaint run(const Mat &mask, Inpaint inpaint);
-
- Mat distanceMap() const;
- };
-
-
-videostab::FastMarchingMethod::FastMarchingMethod
--------------------------------------------------
-
-Constructor.
-
-.. ocv:function:: videostab::FastMarchingMethod::FastMarchingMethod()
-
-
-videostab::FastMarchingMethod::run
-----------------------------------
-
-Template method that runs the Fast Marching Method.
-
-.. ocv:function:: template<typename Inpaint> Inpaint videostab::FastMarchingMethod::run(const Mat &mask, Inpaint inpaint)
-
- :param mask: Image mask. ``0`` value indicates that the pixel value must be inpainted, ``255`` indicates that the pixel value is known, other values aren't acceptable.
-
- :param inpaint: Inpainting functor that overloads ``void operator ()(int x, int y)``.
-
- :return: Inpainting functor.
-
-
-videostab::FastMarchingMethod::distanceMap
-------------------------------------------
-
-.. ocv:function:: Mat videostab::FastMarchingMethod::distanceMap() const
-
- :return: Distance map that's created during working of the method.
+++ /dev/null
-Global Motion Estimation
-========================
-
-.. highlight:: cpp
-
-The video stabilization module contains a set of functions and classes for global motion estimation between point clouds or between images. In the last case features are extracted and matched internally. For the sake of convenience the motion estimation functions are wrapped into classes. Both the functions and the classes are available.
-
-videostab::MotionModel
-----------------------
-Describes motion model between two point clouds.
-
-.. ocv:enum:: videostab::MotionModel
-
- .. ocv:emember:: MM_TRANSLATION = 0
- .. ocv:emember:: MM_TRANSLATION_AND_SCALE = 1
- .. ocv:emember:: MM_ROTATION = 2
- .. ocv:emember:: MM_RIGID = 3
- .. ocv:emember:: MM_SIMILARITY = 4
- .. ocv:emember:: MM_AFFINE = 5
- .. ocv:emember:: MM_HOMOGRAPHY = 6
- .. ocv:emember:: MM_UNKNOWN = 7
-
-
-videostab::RansacParams
------------------------
-
-.. ocv:struct:: videostab::RansacParams
-
-Describes RANSAC method parameters.
-
-::
-
- struct RansacParams
- {
- int size; // subset size
- float thresh; // max error to classify as inlier
- float eps; // max outliers ratio
- float prob; // probability of success
-
- RansacParams() : size(0), thresh(0), eps(0), prob(0) {}
- RansacParams(int size, float thresh, float eps, float prob);
-
- int niters() const;
-
- static RansacParams default2dMotion(MotionModel model);
- };
-
-
-videostab::RansacParams::RansacParams
--------------------------------------
-
-.. ocv:function:: videostab::RansacParams::RansacParams()
-
- :return: RANSAC method empty parameters object.
-
-
-videostab::RansacParams::RansacParams
--------------------------------------
-
-.. ocv:function:: videostab::RansacParams::RansacParams(int size, float thresh, float eps, float prob)
-
- :param size: Subset size.
-
- :param thresh: Maximum re-projection error value to classify as inlier.
-
- :param eps: Maximum ratio of incorrect correspondences.
-
- :param prob: Required success probability.
-
- :return: RANSAC method parameters object.
-
-
-videostab::RansacParams::niters
--------------------------------
-
-.. ocv:function:: int videostab::RansacParams::niters() const
-
- :return: Number of iterations that'll be performed by RANSAC method.
-
-
-videostab::RansacParams::default2dMotion
-----------------------------------------
-
-.. ocv:function:: static RansacParams videostab::RansacParams::default2dMotion(MotionModel model)
-
- :param model: Motion model. See :ocv:enum:`videostab::MotionModel`.
-
- :return: Default RANSAC method parameters for the given motion model.
-
-
-videostab::estimateGlobalMotionLeastSquares
--------------------------------------------
-
-Estimates best global motion between two 2D point clouds in the least-squares sense.
-
-.. note:: Works in-place and changes input point arrays.
-
-.. ocv:function:: Mat videostab::estimateGlobalMotionLeastSquares(InputOutputArray points0, InputOutputArray points1, int model = MM_AFFINE, float *rmse = 0)
-
- :param points0: Source set of 2D points (``32F``).
-
- :param points1: Destination set of 2D points (``32F``).
-
- :param model: Motion model (up to ``MM_AFFINE``).
-
- :param rmse: Final root-mean-square error.
-
- :return: 3x3 2D transformation matrix (``32F``).
-
-
-videostab::estimateGlobalMotionRansac
--------------------------------------
-
-Estimates best global motion between two 2D point clouds robustly (using RANSAC method).
-
-.. ocv:function:: Mat videostab::estimateGlobalMotionRansac(InputArray points0, InputArray points1, int model = MM_AFFINE, const RansacParams ¶ms = RansacParams::default2dMotion(MM_AFFINE), float *rmse = 0, int *ninliers = 0)
-
- :param points0: Source set of 2D points (``32F``).
-
- :param points1: Destination set of 2D points (``32F``).
-
- :param model: Motion model. See :ocv:enum:`videostab::MotionModel`.
-
- :param params: RANSAC method parameters. See :ocv:struct:`videostab::RansacParams`.
-
- :param rmse: Final root-mean-square error.
-
- :param ninliers: Final number of inliers.
-
-
-videostab::getMotion
---------------------
-
-Computes motion between two frames assuming that all the intermediate motions are known.
-
-.. ocv:function:: Mat videostab::getMotion(int from, int to, const std::vector<Mat> &motions)
-
- :param from: Source frame index.
-
- :param to: Destination frame index.
-
- :param motions: Pair-wise motions. ``motions[i]`` denotes motion from the frame ``i`` to the frame ``i+1``
-
- :return: Motion from the frame ``from`` to the frame ``to``.
-
-
-videostab::MotionEstimatorBase
-------------------------------
-
-.. ocv:class:: videostab::MotionEstimatorBase
-
-Base class for all global motion estimation methods.
-
-::
-
- class MotionEstimatorBase
- {
- public:
- virtual ~MotionEstimatorBase();
-
- virtual void setMotionModel(MotionModel val);
- virtual MotionModel motionModel() const;
-
- virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0) = 0;
- };
-
-
-videostab::MotionEstimatorBase::setMotionModel
-----------------------------------------------
-
-Sets motion model.
-
-.. ocv:function:: void videostab::MotionEstimatorBase::setMotionModel(MotionModel val)
-
- :param val: Motion model. See :ocv:enum:`videostab::MotionModel`.
-
-
-
-videostab::MotionEstimatorBase::motionModel
--------------------------------------------
-
-.. ocv:function:: MotionModel videostab::MotionEstimatorBase::motionModel() const
-
- :return: Motion model. See :ocv:enum:`videostab::MotionModel`.
-
-
-videostab::MotionEstimatorBase::estimate
-----------------------------------------
-
-Estimates global motion between two 2D point clouds.
-
-.. ocv:function:: Mat videostab::MotionEstimatorBase::estimate(InputArray points0, InputArray points1, bool *ok = 0)
-
- :param points0: Source set of 2D points (``32F``).
-
- :param points1: Destination set of 2D points (``32F``).
-
- :param ok: Indicates whether motion was estimated successfully.
-
- :return: 3x3 2D transformation matrix (``32F``).
-
-
-videostab::MotionEstimatorRansacL2
-----------------------------------
-
-.. ocv:class:: videostab::MotionEstimatorRansacL2 : public videostab::MotionEstimatorBase
-
-Describes a robust RANSAC-based global 2D motion estimation method which minimizes L2 error.
-
-::
-
- class MotionEstimatorRansacL2 : public MotionEstimatorBase
- {
- public:
- MotionEstimatorRansacL2(MotionModel model = MM_AFFINE);
-
- void setRansacParams(const RansacParams &val);
- RansacParams ransacParams() const;
-
- void setMinInlierRatio(float val);
- float minInlierRatio() const;
-
- virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0);
- };
-
-
-videostab::MotionEstimatorL1
-----------------------------
-
-.. ocv:class:: videostab::MotionEstimatorL1 : public videostab::MotionEstimatorBase
-
-Describes a global 2D motion estimation method which minimizes L1 error.
-
-.. note:: To be able to use this method you must build OpenCV with CLP library support.
-
-::
-
- class MotionEstimatorL1 : public MotionEstimatorBase
- {
- public:
- MotionEstimatorL1(MotionModel model = MM_AFFINE);
-
- virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0);
- };
-
-
-videostab::ImageMotionEstimatorBase
------------------------------------
-
-.. ocv:class:: videostab::ImageMotionEstimatorBase
-
-Base class for global 2D motion estimation methods which take frames as input.
-
-::
-
- class ImageMotionEstimatorBase
- {
- public:
- virtual ~ImageMotionEstimatorBase();
-
- virtual void setMotionModel(MotionModel val);
- virtual MotionModel motionModel() const;
-
- virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0) = 0;
- };
-
-
-videostab::KeypointBasedMotionEstimator
----------------------------------------
-
-.. ocv:class:: videostab::KeypointBasedMotionEstimator : public videostab::ImageMotionEstimatorBase
-
-Describes a global 2D motion estimation method which uses keypoints detection and optical flow for matching.
-
-::
-
- class KeypointBasedMotionEstimator : public ImageMotionEstimatorBase
- {
- public:
- KeypointBasedMotionEstimator(Ptr<MotionEstimatorBase> estimator);
-
- virtual void setMotionModel(MotionModel val);
- virtual MotionModel motionModel() const;
-
- void setDetector(Ptr<FeatureDetector> val);
- Ptr<FeatureDetector> detector() const;
-
- void setOpticalFlowEstimator(Ptr<ISparseOptFlowEstimator> val);
- Ptr<ISparseOptFlowEstimator> opticalFlowEstimator() const;
-
- void setOutlierRejector(Ptr<IOutlierRejector> val);
- Ptr<IOutlierRejector> outlierRejector() const;
-
- virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0);
- };
+++ /dev/null
-Introduction
-============
-
-The video stabilization module contains a set of functions and classes that can be used to solve the problem of video stabilization. There are a few methods implemented, most of them are descibed in the papers [OF06]_ and [G11]_. However, there are some extensions and deviations from the orginal paper methods.
-
-References
-----------
-
-.. [OF06] Full-Frame Video Stabilization with Motion Inpainting. Matsushita, Y. Ofek, E. Ge, W. Tang, X. Shum, H.-Y., IEEE TRANSACTIONS ON PATTERN ANALYSIS AND MACHINE INTELLIGENCE, 2006
-
-.. [G11] Auto-directed video stabilization with robust L1 optimal camera paths, M. Grundmann, V. Kwatra, I. Essa, Computer Vision and Pattern Recognition (CVPR), 2011
-
-.. [T04] An Image Inpainting Technique Based on the Fast Marching Method, Alexandru Telea, Journal of graphics tools, 2004
+++ /dev/null
-******************************
-videostab. Video Stabilization
-******************************
-
-.. toctree::
- :maxdepth: 2
-
- introduction
- global_motion
- fast_marching
+++ /dev/null
-***********************
-viz. 3D Visualizer
-***********************
-
-.. toctree::
- :maxdepth: 2
-
- viz3d.rst
- widget.rst
+++ /dev/null
-Viz
-===
-
-.. highlight:: cpp
-
-This section describes 3D visualization window as well as classes and methods
-that are used to interact with it.
-
-3D visualization window (see :ocv:class:`Viz3d`) is used to display widgets (see :ocv:class:`Widget`), and it provides
-several methods to interact with scene and widgets.
-
-viz::makeTransformToGlobal
---------------------------
-Takes coordinate frame data and builds transform to global coordinate frame.
-
-.. ocv:function:: Affine3d viz::makeTransformToGlobal(const Vec3f& axis_x, const Vec3f& axis_y, const Vec3f& axis_z, const Vec3f& origin = Vec3f::all(0))
-
- :param axis_x: X axis vector in global coordinate frame.
- :param axis_y: Y axis vector in global coordinate frame.
- :param axis_z: Z axis vector in global coordinate frame.
- :param origin: Origin of the coordinate frame in global coordinate frame.
-
-This function returns affine transform that describes transformation between global coordinate frame and a given coordinate frame.
-
-viz::makeCameraPose
--------------------
-Constructs camera pose from position, focal_point and up_vector (see gluLookAt() for more infromation).
-
-.. ocv:function:: Affine3d makeCameraPose(const Vec3f& position, const Vec3f& focal_point, const Vec3f& y_dir)
-
- :param position: Position of the camera in global coordinate frame.
- :param focal_point: Focal point of the camera in global coordinate frame.
- :param y_dir: Up vector of the camera in global coordinate frame.
-
-This function returns pose of the camera in global coordinate frame.
-
-viz::getWindowByName
---------------------
-Retrieves a window by its name.
-
-.. ocv:function:: Viz3d getWindowByName(const String &window_name)
-
- :param window_name: Name of the window that is to be retrieved.
-
-This function returns a :ocv:class:`Viz3d` object with the given name.
-
-.. note:: If the window with that name already exists, that window is returned. Otherwise, new window is created with the given name, and it is returned.
-
-.. note:: Window names are automatically prefixed by "Viz - " if it is not done by the user.
-
- .. code-block:: cpp
-
- /// window and window_2 are the same windows.
- viz::Viz3d window = viz::getWindowByName("myWindow");
- viz::Viz3d window_2 = viz::getWindowByName("Viz - myWindow");
-
-viz::isNan
-----------
-Checks **float/double** value for nan.
-
- .. ocv:function:: bool isNan(float x)
-
- .. ocv:function:: bool isNan(double x)
-
- :param x: return true if nan.
-
-Checks **vector** for nan.
-
- .. ocv:function:: bool isNan(const Vec<_Tp, cn>& v)
-
- :param v: return true if **any** of the elements of the vector is *nan*.
-
-Checks **point** for nan
-
- .. ocv:function:: bool isNan(const Point3_<_Tp>& p)
-
- :param p: return true if **any** of the elements of the point is *nan*.
-
-viz::Viz3d
-----------
-.. ocv:class:: Viz3d
-
-The Viz3d class represents a 3D visualizer window. This class is implicitly shared. ::
-
- class CV_EXPORTS Viz3d
- {
- public:
- typedef cv::Ptr<Viz3d> Ptr;
- typedef void (*KeyboardCallback)(const KeyboardEvent&, void*);
- typedef void (*MouseCallback)(const MouseEvent&, void*);
-
- Viz3d(const String& window_name = String());
- Viz3d(const Viz3d&);
- Viz3d& operator=(const Viz3d&);
- ~Viz3d();
-
- void showWidget(const String &id, const Widget &widget, const Affine3d &pose = Affine3d::Identity());
- void removeWidget(const String &id);
- Widget getWidget(const String &id) const;
- void removeAllWidgets();
-
- void setWidgetPose(const String &id, const Affine3d &pose);
- void updateWidgetPose(const String &id, const Affine3d &pose);
- Affine3d getWidgetPose(const String &id) const;
-
- void showImage(InputArray image, const Size& window_size = Size(-1, -1));
-
- void setCamera(const Camera &camera);
- Camera getCamera() const;
- Affine3d getViewerPose();
- void setViewerPose(const Affine3d &pose);
-
- void resetCameraViewpoint (const String &id);
- void resetCamera();
-
- void convertToWindowCoordinates(const Point3d &pt, Point3d &window_coord);
- void converTo3DRay(const Point3d &window_coord, Point3d &origin, Vec3d &direction);
-
- Size getWindowSize() const;
- void setWindowSize(const Size &window_size);
- String getWindowName() const;
- void saveScreenshot (const String &file);
- void setWindowPosition (int x, int y);
- void setFullScreen (bool mode);
- void setBackgroundColor(const Color& color = Color::black());
-
- void spin();
- void spinOnce(int time = 1, bool force_redraw = false);
- bool wasStopped() const;
-
- void registerKeyboardCallback(KeyboardCallback callback, void* cookie = 0);
- void registerMouseCallback(MouseCallback callback, void* cookie = 0);
-
- void setRenderingProperty(const String &id, int property, double value);
- double getRenderingProperty(const String &id, int property);
-
-
- void setRepresentation(int representation);
- private:
- /* hidden */
- };
-
-viz::Viz3d::Viz3d
------------------
-The constructors.
-
-.. ocv:function:: Viz3d::Viz3d(const String& window_name = String())
-
- :param window_name: Name of the window.
-
-viz::Viz3d::showWidget
-----------------------
-Shows a widget in the window.
-
-.. ocv:function:: void Viz3d::showWidget(const String &id, const Widget &widget, const Affine3d &pose = Affine3d::Identity())
-
- :param id: A unique id for the widget.
- :param widget: The widget to be displayed in the window.
- :param pose: Pose of the widget.
-
-viz::Viz3d::removeWidget
-------------------------
-Removes a widget from the window.
-
-.. ocv:function:: void removeWidget(const String &id)
-
- :param id: The id of the widget that will be removed.
-
-viz::Viz3d::getWidget
----------------------
-Retrieves a widget from the window. A widget is implicitly shared;
-that is, if the returned widget is modified, the changes will be
-immediately visible in the window.
-
-.. ocv:function:: Widget getWidget(const String &id) const
-
- :param id: The id of the widget that will be returned.
-
-viz::Viz3d::removeAllWidgets
-----------------------------
-Removes all widgets from the window.
-
-.. ocv:function:: void removeAllWidgets()
-
-viz::Viz3d::showImage
----------------------
-Removed all widgets and displays image scaled to whole window area.
-
-.. ocv:function:: void showImage(InputArray image, const Size& window_size = Size(-1, -1))
-
- :param image: Image to be displayed.
- :param size: Size of Viz3d window. Default value means no change.
-
-viz::Viz3d::setWidgetPose
--------------------------
-Sets pose of a widget in the window.
-
-.. ocv:function:: void setWidgetPose(const String &id, const Affine3d &pose)
-
- :param id: The id of the widget whose pose will be set.
- :param pose: The new pose of the widget.
-
-viz::Viz3d::updateWidgetPose
-----------------------------
-Updates pose of a widget in the window by pre-multiplying its current pose.
-
-.. ocv:function:: void updateWidgetPose(const String &id, const Affine3d &pose)
-
- :param id: The id of the widget whose pose will be updated.
- :param pose: The pose that the current pose of the widget will be pre-multiplied by.
-
-viz::Viz3d::getWidgetPose
--------------------------
-Returns the current pose of a widget in the window.
-
-.. ocv:function:: Affine3d getWidgetPose(const String &id) const
-
- :param id: The id of the widget whose pose will be returned.
-
-viz::Viz3d::setCamera
----------------------
-Sets the intrinsic parameters of the viewer using Camera.
-
-.. ocv:function:: void setCamera(const Camera &camera)
-
- :param camera: Camera object wrapping intrinsinc parameters.
-
-viz::Viz3d::getCamera
----------------------
-Returns a camera object that contains intrinsic parameters of the current viewer.
-
-.. ocv:function:: Camera getCamera() const
-
-viz::Viz3d::getViewerPose
--------------------------
-Returns the current pose of the viewer.
-
-..ocv:function:: Affine3d getViewerPose()
-
-viz::Viz3d::setViewerPose
--------------------------
-Sets pose of the viewer.
-
-.. ocv:function:: void setViewerPose(const Affine3d &pose)
-
- :param pose: The new pose of the viewer.
-
-viz::Viz3d::resetCameraViewpoint
---------------------------------
-Resets camera viewpoint to a 3D widget in the scene.
-
-.. ocv:function:: void resetCameraViewpoint (const String &id)
-
- :param pose: Id of a 3D widget.
-
-viz::Viz3d::resetCamera
------------------------
-Resets camera.
-
-.. ocv:function:: void resetCamera()
-
-viz::Viz3d::convertToWindowCoordinates
---------------------------------------
-Transforms a point in world coordinate system to window coordinate system.
-
-.. ocv:function:: void convertToWindowCoordinates(const Point3d &pt, Point3d &window_coord)
-
- :param pt: Point in world coordinate system.
- :param window_coord: Output point in window coordinate system.
-
-viz::Viz3d::converTo3DRay
--------------------------
-Transforms a point in window coordinate system to a 3D ray in world coordinate system.
-
-.. ocv:function:: void converTo3DRay(const Point3d &window_coord, Point3d &origin, Vec3d &direction)
-
- :param window_coord: Point in window coordinate system.
- :param origin: Output origin of the ray.
- :param direction: Output direction of the ray.
-
-viz::Viz3d::getWindowSize
--------------------------
-Returns the current size of the window.
-
-.. ocv:function:: Size getWindowSize() const
-
-viz::Viz3d::setWindowSize
--------------------------
-Sets the size of the window.
-
-.. ocv:function:: void setWindowSize(const Size &window_size)
-
- :param window_size: New size of the window.
-
-viz::Viz3d::getWindowName
--------------------------
-Returns the name of the window which has been set in the constructor.
-
-.. ocv:function:: String getWindowName() const
-
-viz::Viz3d::saveScreenshot
---------------------------
-Saves screenshot of the current scene.
-
-.. ocv:function:: void saveScreenshot(const String &file)
-
- :param file: Name of the file.
-
-viz::Viz3d::setWindowPosition
------------------------------
-Sets the position of the window in the screen.
-
-.. ocv:function:: void setWindowPosition(int x, int y)
-
- :param x: x coordinate of the window
- :param y: y coordinate of the window
-
-viz::Viz3d::setFullScreen
--------------------------
-Sets or unsets full-screen rendering mode.
-
-.. ocv:function:: void setFullScreen(bool mode)
-
- :param mode: If true, window will use full-screen mode.
-
-viz::Viz3d::setBackgroundColor
-------------------------------
-Sets background color.
-
-.. ocv:function:: void setBackgroundColor(const Color& color = Color::black())
-
-viz::Viz3d::spin
-----------------
-The window renders and starts the event loop.
-
-.. ocv:function:: void spin()
-
-viz::Viz3d::spinOnce
---------------------
-Starts the event loop for a given time.
-
-.. ocv:function:: void spinOnce(int time = 1, bool force_redraw = false)
-
- :param time: Amount of time in milliseconds for the event loop to keep running.
- :param force_draw: If true, window renders.
-
-viz::Viz3d::wasStopped
-----------------------
-Returns whether the event loop has been stopped.
-
-.. ocv:function:: bool wasStopped()
-
-viz::Viz3d::registerKeyboardCallback
-------------------------------------
-Sets keyboard handler.
-
-.. ocv:function:: void registerKeyboardCallback(KeyboardCallback callback, void* cookie = 0)
-
- :param callback: Keyboard callback ``(void (*KeyboardCallbackFunction(const KeyboardEvent&, void*))``.
- :param cookie: The optional parameter passed to the callback.
-
-viz::Viz3d::registerMouseCallback
----------------------------------
-Sets mouse handler.
-
-.. ocv:function:: void registerMouseCallback(MouseCallback callback, void* cookie = 0)
-
- :param callback: Mouse callback ``(void (*MouseCallback)(const MouseEvent&, void*))``.
- :param cookie: The optional parameter passed to the callback.
-
-viz::Viz3d::setRenderingProperty
---------------------------------
-Sets rendering property of a widget.
-
-.. ocv:function:: void setRenderingProperty(const String &id, int property, double value)
-
- :param id: Id of the widget.
- :param property: Property that will be modified.
- :param value: The new value of the property.
-
- **Rendering property** can be one of the following:
-
- * **POINT_SIZE**
- * **OPACITY**
- * **LINE_WIDTH**
- * **FONT_SIZE**
- * **REPRESENTATION**: Expected values are
- * **REPRESENTATION_POINTS**
- * **REPRESENTATION_WIREFRAME**
- * **REPRESENTATION_SURFACE**
- * **IMMEDIATE_RENDERING**:
- * Turn on immediate rendering by setting the value to ``1``.
- * Turn off immediate rendering by setting the value to ``0``.
- * **SHADING**: Expected values are
- * **SHADING_FLAT**
- * **SHADING_GOURAUD**
- * **SHADING_PHONG**
-
-viz::Viz3d::getRenderingProperty
---------------------------------
-Returns rendering property of a widget.
-
-.. ocv:function:: double getRenderingProperty(const String &id, int property)
-
- :param id: Id of the widget.
- :param property: Property.
-
- **Rendering property** can be one of the following:
-
- * **POINT_SIZE**
- * **OPACITY**
- * **LINE_WIDTH**
- * **FONT_SIZE**
- * **REPRESENTATION**: Expected values are
- * **REPRESENTATION_POINTS**
- * **REPRESENTATION_WIREFRAME**
- * **REPRESENTATION_SURFACE**
- * **IMMEDIATE_RENDERING**:
- * Turn on immediate rendering by setting the value to ``1``.
- * Turn off immediate rendering by setting the value to ``0``.
- * **SHADING**: Expected values are
- * **SHADING_FLAT**
- * **SHADING_GOURAUD**
- * **SHADING_PHONG**
-
-viz::Viz3d::setRepresentation
------------------------------
-Sets geometry representation of the widgets to surface, wireframe or points.
-
-.. ocv:function:: void setRepresentation(int representation)
-
- :param representation: Geometry representation which can be one of the following:
-
- * **REPRESENTATION_POINTS**
- * **REPRESENTATION_WIREFRAME**
- * **REPRESENTATION_SURFACE**
-
-viz::Color
-----------
-.. ocv:class:: Color
-
-This class a represents BGR color. ::
-
- class CV_EXPORTS Color : public Scalar
- {
- public:
- Color();
- Color(double gray);
- Color(double blue, double green, double red);
-
- Color(const Scalar& color);
-
- static Color black();
- static Color blue();
- static Color green();
- static Color cyan();
-
- static Color red();
- static Color magenta();
- static Color yellow();
- static Color white();
-
- static Color gray();
- };
-
-viz::Mesh
------------
-.. ocv:class:: Mesh
-
-This class wraps mesh attributes, and it can load a mesh from a ``ply`` file. ::
-
- class CV_EXPORTS Mesh
- {
- public:
-
- Mat cloud, colors, normals;
-
- //! Raw integer list of the form: (n,id1,id2,...,idn, n,id1,id2,...,idn, ...)
- //! where n is the number of points in the poligon, and id is a zero-offset index into an associated cloud.
- Mat polygons;
-
- //! Loads mesh from a given ply file
- static Mesh load(const String& file);
- };
-
-viz::Mesh::load
----------------------
-Loads a mesh from a ``ply`` file.
-
-.. ocv:function:: static Mesh load(const String& file)
-
- :param file: File name (for no only PLY is supported)
-
-
-viz::KeyboardEvent
-------------------
-.. ocv:class:: KeyboardEvent
-
-This class represents a keyboard event. ::
-
- class CV_EXPORTS KeyboardEvent
- {
- public:
- enum { ALT = 1, CTRL = 2, SHIFT = 4 };
- enum Action { KEY_UP = 0, KEY_DOWN = 1 };
-
- KeyboardEvent(Action action, const String& symbol, unsigned char code, int modifiers);
-
- Action action;
- String symbol;
- unsigned char code;
- int modifiers;
- };
-
-viz::KeyboardEvent::KeyboardEvent
----------------------------------
-Constructs a KeyboardEvent.
-
-.. ocv:function:: KeyboardEvent (Action action, const String& symbol, unsigned char code, Modifiers modifiers)
-
- :param action: Signals if key is pressed or released.
- :param symbol: Name of the key.
- :param code: Code of the key.
- :param modifiers: Signals if ``alt``, ``ctrl`` or ``shift`` are pressed or their combination.
-
-
-viz::MouseEvent
----------------
-.. ocv:class:: MouseEvent
-
-This class represents a mouse event. ::
-
- class CV_EXPORTS MouseEvent
- {
- public:
- enum Type { MouseMove = 1, MouseButtonPress, MouseButtonRelease, MouseScrollDown, MouseScrollUp, MouseDblClick } ;
- enum MouseButton { NoButton = 0, LeftButton, MiddleButton, RightButton, VScroll } ;
-
- MouseEvent(const Type& type, const MouseButton& button, const Point& pointer, int modifiers);
-
- Type type;
- MouseButton button;
- Point pointer;
- int modifiers;
- };
-
-viz::MouseEvent::MouseEvent
----------------------------
-Constructs a MouseEvent.
-
-.. ocv:function:: MouseEvent (const Type& type, const MouseButton& button, const Point& p, Modifiers modifiers)
-
- :param type: Type of the event. This can be **MouseMove**, **MouseButtonPress**, **MouseButtonRelease**, **MouseScrollDown**, **MouseScrollUp**, **MouseDblClick**.
- :param button: Mouse button. This can be **NoButton**, **LeftButton**, **MiddleButton**, **RightButton**, **VScroll**.
- :param p: Position of the event.
- :param modifiers: Signals if ``alt``, ``ctrl`` or ``shift`` are pressed or their combination.
-
-viz::Camera
------------
-.. ocv:class:: Camera
-
-This class wraps intrinsic parameters of a camera. It provides several constructors
-that can extract the intrinsic parameters from ``field of view``, ``intrinsic matrix`` and
-``projection matrix``. ::
-
- class CV_EXPORTS Camera
- {
- public:
- Camera(double f_x, double f_y, double c_x, double c_y, const Size &window_size);
- Camera(const Vec2d &fov, const Size &window_size);
- Camera(const Matx33d &K, const Size &window_size);
- Camera(const Matx44d &proj, const Size &window_size);
-
- inline const Vec2d & getClip() const;
- inline void setClip(const Vec2d &clip);
-
- inline const Size & getWindowSize() const;
- void setWindowSize(const Size &window_size);
-
- inline const Vec2d & getFov() const;
- inline void setFov(const Vec2d & fov);
-
- inline const Vec2d & getPrincipalPoint() const;
- inline const Vec2d & getFocalLength() const;
-
- void computeProjectionMatrix(Matx44d &proj) const;
-
- static Camera KinectCamera(const Size &window_size);
-
- private:
- /* hidden */
- };
-
-viz::Camera::Camera
--------------------
-Constructs a Camera.
-
-.. ocv:function:: Camera(double f_x, double f_y, double c_x, double c_y, const Size &window_size)
-
- :param f_x: Horizontal focal length.
- :param f_y: Vertical focal length.
- :param c_x: x coordinate of the principal point.
- :param c_y: y coordinate of the principal point.
- :param window_size: Size of the window. This together with focal length and principal point determines the field of view.
-
-.. ocv:function:: Camera(const Vec2d &fov, const Size &window_size)
-
- :param fov: Field of view (horizontal, vertical)
- :param window_size: Size of the window.
-
- Principal point is at the center of the window by default.
-
-.. ocv:function:: Camera(const Matx33d &K, const Size &window_size)
-
- :param K: Intrinsic matrix of the camera.
- :param window_size: Size of the window. This together with intrinsic matrix determines the field of view.
-
-.. ocv:function:: Camera(const Matx44d &proj, const Size &window_size)
-
- :param proj: Projection matrix of the camera.
- :param window_size: Size of the window. This together with projection matrix determines the field of view.
-
-viz::Camera::computeProjectionMatrix
-------------------------------------
-Computes projection matrix using intrinsic parameters of the camera.
-
-.. ocv:function:: void computeProjectionMatrix(Matx44d &proj) const
-
- :param proj: Output projection matrix.
-
-viz::Camera::KinectCamera
--------------------------
-Creates a Kinect Camera.
-
-.. ocv:function:: static Camera KinectCamera(const Size &window_size)
-
- :param window_size: Size of the window. This together with intrinsic matrix of a Kinect Camera determines the field of view.
+++ /dev/null
-Widget
-======
-
-.. highlight:: cpp
-
-In this section, the widget framework is explained. Widgets represent
-2D or 3D objects, varying from simple ones such as lines to complex one such as
-point clouds and meshes.
-
-Widgets are **implicitly shared**. Therefore, one can add a widget to the scene,
-and modify the widget without re-adding the widget.
-
-.. code-block:: cpp
-
- ...
- /// Create a cloud widget
- viz::WCloud cw(cloud, viz::Color::red());
- /// Display it in a window
- myWindow.showWidget("CloudWidget1", cw);
- /// Modify it, and it will be modified in the window.
- cw.setColor(viz::Color::yellow());
- ...
-
-viz::Widget
------------
-.. ocv:class:: Widget
-
-Base class of all widgets. Widget is implicitly shared. ::
-
- class CV_EXPORTS Widget
- {
- public:
- Widget();
- Widget(const Widget& other);
- Widget& operator=(const Widget& other);
- ~Widget();
-
- //! Create a widget directly from ply file
- static Widget fromPlyFile(const String &file_name);
-
- //! Rendering properties of this particular widget
- void setRenderingProperty(int property, double value);
- double getRenderingProperty(int property) const;
-
- //! Casting between widgets
- template<typename _W> _W cast();
- private:
- /* hidden */
- };
-
-viz::Widget::fromPlyFile
-------------------------
-Creates a widget from ply file.
-
-.. ocv:function:: static Widget fromPlyFile(const String &file_name)
-
- :param file_name: Ply file name.
-
-viz::Widget::setRenderingProperty
----------------------------------
-Sets rendering property of the widget.
-
-.. ocv:function:: void setRenderingProperty(int property, double value)
-
- :param property: Property that will be modified.
- :param value: The new value of the property.
-
- **Rendering property** can be one of the following:
-
- * **POINT_SIZE**
- * **OPACITY**
- * **LINE_WIDTH**
- * **FONT_SIZE**
- * **REPRESENTATION**: Expected values are
- * **REPRESENTATION_POINTS**
- * **REPRESENTATION_WIREFRAME**
- * **REPRESENTATION_SURFACE**
- * **IMMEDIATE_RENDERING**:
- * Turn on immediate rendering by setting the value to ``1``.
- * Turn off immediate rendering by setting the value to ``0``.
- * **SHADING**: Expected values are
- * **SHADING_FLAT**
- * **SHADING_GOURAUD**
- * **SHADING_PHONG**
-
-viz::Widget::getRenderingProperty
----------------------------------
-Returns rendering property of the widget.
-
-.. ocv:function:: double getRenderingProperty(int property) const
-
- :param property: Property.
-
- **Rendering property** can be one of the following:
-
- * **POINT_SIZE**
- * **OPACITY**
- * **LINE_WIDTH**
- * **FONT_SIZE**
- * **REPRESENTATION**: Expected values are
- * **REPRESENTATION_POINTS**
- * **REPRESENTATION_WIREFRAME**
- * **REPRESENTATION_SURFACE**
- * **IMMEDIATE_RENDERING**:
- * Turn on immediate rendering by setting the value to ``1``.
- * Turn off immediate rendering by setting the value to ``0``.
- * **SHADING**: Expected values are
- * **SHADING_FLAT**
- * **SHADING_GOURAUD**
- * **SHADING_PHONG**
-
-viz::Widget::cast
------------------
-Casts a widget to another.
-
-.. ocv:function:: template<typename _W> _W cast()
-
-.. code-block:: cpp
-
- // Create a sphere widget
- viz::WSphere sw(Point3f(0.0f,0.0f,0.0f), 0.5f);
- // Cast sphere widget to cloud widget
- viz::WCloud cw = sw.cast<viz::WCloud>();
-
-.. note:: 3D Widgets can only be cast to 3D Widgets. 2D Widgets can only be cast to 2D Widgets.
-
-viz::WidgetAccessor
--------------------
-.. ocv:class:: WidgetAccessor
-
-This class is for users who want to develop their own widgets using VTK library API. ::
-
- struct CV_EXPORTS WidgetAccessor
- {
- static vtkSmartPointer<vtkProp> getProp(const Widget &widget);
- static void setProp(Widget &widget, vtkSmartPointer<vtkProp> prop);
- };
-
-viz::WidgetAccessor::getProp
-----------------------------
-Returns ``vtkProp`` of a given widget.
-
-.. ocv:function:: static vtkSmartPointer<vtkProp> getProp(const Widget &widget)
-
- :param widget: Widget whose ``vtkProp`` is to be returned.
-
-.. note:: vtkProp has to be down cast appropriately to be modified.
-
- .. code-block:: cpp
-
- vtkActor * actor = vtkActor::SafeDownCast(viz::WidgetAccessor::getProp(widget));
-
-viz::WidgetAccessor::setProp
-----------------------------
-Sets ``vtkProp`` of a given widget.
-
-.. ocv:function:: static void setProp(Widget &widget, vtkSmartPointer<vtkProp> prop)
-
- :param widget: Widget whose ``vtkProp`` is to be set.
- :param prop: A ``vtkProp``.
-
-viz::Widget3D
--------------
-.. ocv:class:: Widget3D
-
-Base class of all 3D widgets. ::
-
- class CV_EXPORTS Widget3D : public Widget
- {
- public:
- Widget3D() {}
-
- //! widget position manipulation, i.e. place where it is rendered.
- void setPose(const Affine3d &pose);
- void updatePose(const Affine3d &pose);
- Affine3d getPose() const;
-
- //! updates internal widget data, i.e. points, normals, etc.
- void applyTransform(const Affine3d &transform);
-
- void setColor(const Color &color);
-
- };
-
-viz::Widget3D::setPose
-----------------------
-Sets pose of the widget.
-
-.. ocv:function:: void setPose(const Affine3d &pose)
-
- :param pose: The new pose of the widget.
-
-viz::Widget3D::updateWidgetPose
--------------------------------
-Updates pose of the widget by pre-multiplying its current pose.
-
-.. ocv:function:: void updateWidgetPose(const Affine3d &pose)
-
- :param pose: The pose that the current pose of the widget will be pre-multiplied by.
-
-viz::Widget3D::getPose
-----------------------
-Returns the current pose of the widget.
-
-.. ocv:function:: Affine3d getWidgetPose() const
-
-
-viz::Widget3D::applyTransform
--------------------------------
-Transforms internal widget data (i.e. points, normals) using the given transform.
-
-.. ocv:function:: void applyTransform(const Affine3d &transform)
-
- :param transform: Specified transformation to apply.
-
-viz::Widget3D::setColor
------------------------
-Sets the color of the widget.
-
-.. ocv:function:: void setColor(const Color &color)
-
- :param color: color of type :ocv:class:`Color`
-
-viz::Widget2D
--------------
-.. ocv:class:: Widget2D
-
-Base class of all 2D widgets. ::
-
- class CV_EXPORTS Widget2D : public Widget
- {
- public:
- Widget2D() {}
-
- void setColor(const Color &color);
- };
-
-viz::Widget2D::setColor
------------------------
-Sets the color of the widget.
-
-.. ocv:function:: void setColor(const Color &color)
-
- :param color: color of type :ocv:class:`Color`
-
-viz::WLine
-----------
-.. ocv:class:: WLine
-
-This 3D Widget defines a finite line. ::
-
- class CV_EXPORTS WLine : public Widget3D
- {
- public:
- WLine(const Point3f &pt1, const Point3f &pt2, const Color &color = Color::white());
- };
-
-viz::WLine::WLine
------------------
-Constructs a WLine.
-
-.. ocv:function:: WLine(const Point3f &pt1, const Point3f &pt2, const Color &color = Color::white())
-
- :param pt1: Start point of the line.
- :param pt2: End point of the line.
- :param color: :ocv:class:`Color` of the line.
-
-viz::WPlane
------------
-.. ocv:class:: WPlane
-
-This 3D Widget defines a finite plane. ::
-
- class CV_EXPORTS WPlane : public Widget3D
- {
- public:
- //! created default plane with center point at origin and normal oriented along z-axis
- WPlane(const Size2d& size = Size2d(1.0, 1.0), const Color &color = Color::white());
-
- //! repositioned plane
- WPlane(const Point3d& center, const Vec3d& normal, const Vec3d& new_plane_yaxis,const Size2d& size = Size2d(1.0, 1.0), const Color &color = Color::white());
- };
-
-viz::WPlane::WPlane
--------------------
-Constructs a default plane with center point at origin and normal oriented along z-axis.
-
-.. ocv:function:: WPlane(const Size2d& size = Size2d(1.0, 1.0), const Color &color = Color::white())
-
- :param size: Size of the plane
- :param color: :ocv:class:`Color` of the plane.
-
-viz::WPlane::WPlane
--------------------
-Constructs a repositioned plane
-
-.. ocv:function:: WPlane(const Point3d& center, const Vec3d& normal, const Vec3d& new_yaxis,const Size2d& size = Size2d(1.0, 1.0), const Color &color = Color::white())
-
- :param center: Center of the plane
- :param normal: Plane normal orientation
- :param new_yaxis: Up-vector. New orientation of plane y-axis.
- :param color: :ocv:class:`Color` of the plane.
-
-viz::WSphere
-------------
-.. ocv:class:: WSphere
-
-This 3D Widget defines a sphere. ::
-
- class CV_EXPORTS WSphere : public Widget3D
- {
- public:
- WSphere(const cv::Point3f ¢er, double radius, int sphere_resolution = 10, const Color &color = Color::white())
- };
-
-viz::WSphere::WSphere
----------------------
-Constructs a WSphere.
-
-.. ocv:function:: WSphere(const cv::Point3f ¢er, double radius, int sphere_resolution = 10, const Color &color = Color::white())
-
- :param center: Center of the sphere.
- :param radius: Radius of the sphere.
- :param sphere_resolution: Resolution of the sphere.
- :param color: :ocv:class:`Color` of the sphere.
-
-viz::WArrow
-----------------
-.. ocv:class:: WArrow
-
-This 3D Widget defines an arrow. ::
-
- class CV_EXPORTS WArrow : public Widget3D
- {
- public:
- WArrow(const Point3f& pt1, const Point3f& pt2, double thickness = 0.03, const Color &color = Color::white());
- };
-
-viz::WArrow::WArrow
------------------------------
-Constructs an WArrow.
-
-.. ocv:function:: WArrow(const Point3f& pt1, const Point3f& pt2, double thickness = 0.03, const Color &color = Color::white())
-
- :param pt1: Start point of the arrow.
- :param pt2: End point of the arrow.
- :param thickness: Thickness of the arrow. Thickness of arrow head is also adjusted accordingly.
- :param color: :ocv:class:`Color` of the arrow.
-
-Arrow head is located at the end point of the arrow.
-
-viz::WCircle
------------------
-.. ocv:class:: WCircle
-
-This 3D Widget defines a circle. ::
-
- class CV_EXPORTS WCircle : public Widget3D
- {
- public:
- //! creates default planar circle centred at origin with plane normal along z-axis
- WCircle(double radius, double thickness = 0.01, const Color &color = Color::white());
-
- //! creates repositioned circle
- WCircle(double radius, const Point3d& center, const Vec3d& normal, double thickness = 0.01, const Color &color = Color::white());
- };
-
-viz::WCircle::WCircle
--------------------------------
-Constructs default planar circle centred at origin with plane normal along z-axis
-
-.. ocv:function:: WCircle(double radius, double thickness = 0.01, const Color &color = Color::white())
-
- :param radius: Radius of the circle.
- :param thickness: Thickness of the circle.
- :param color: :ocv:class:`Color` of the circle.
-
-viz::WCircle::WCircle
--------------------------------
-Constructs repositioned planar circle.
-
-.. ocv:function:: WCircle(double radius, const Point3d& center, const Vec3d& normal, double thickness = 0.01, const Color &color = Color::white())
-
- :param radius: Radius of the circle.
- :param center: Center of the circle.
- :param normal: Normal of the plane in which the circle lies.
- :param thickness: Thickness of the circle.
- :param color: :ocv:class:`Color` of the circle.
-
-
-viz::WCone
--------------------------------
-.. ocv:class:: WCone
-
-This 3D Widget defines a cone. ::
-
- class CV_EXPORTS WCone : public Widget3D
- {
- public:
- //! create default cone, oriented along x-axis with center of its base located at origin
- WCone(double length, double radius, int resolution = 6.0, const Color &color = Color::white());
-
- //! creates repositioned cone
- WCone(double radius, const Point3d& center, const Point3d& tip, int resolution = 6.0, const Color &color = Color::white());
- };
-
-viz::WCone::WCone
--------------------------------
-Constructs default cone oriented along x-axis with center of its base located at origin
-
-.. ocv:function:: WCone(double length, double radius, int resolution = 6.0, const Color &color = Color::white())
-
- :param length: Length of the cone.
- :param radius: Radius of the cone.
- :param resolution: Resolution of the cone.
- :param color: :ocv:class:`Color` of the cone.
-
-viz::WCone::WCone
--------------------------------
-Constructs repositioned planar cone.
-
-.. ocv:function:: WCone(double radius, const Point3d& center, const Point3d& tip, int resolution = 6.0, const Color &color = Color::white())
-
- :param radius: Radius of the cone.
- :param center: Center of the cone base.
- :param tip: Tip of the cone.
- :param resolution: Resolution of the cone.
- :param color: :ocv:class:`Color` of the cone.
-
-viz::WCylinder
---------------
-.. ocv:class:: WCylinder
-
-This 3D Widget defines a cylinder. ::
-
- class CV_EXPORTS WCylinder : public Widget3D
- {
- public:
- WCylinder(const Point3d& axis_point1, const Point3d& axis_point2, double radius, int numsides = 30, const Color &color = Color::white());
- };
-
-viz::WCylinder::WCylinder
------------------------------------
-Constructs a WCylinder.
-
-.. ocv:function:: WCylinder(const Point3f& pt_on_axis, const Point3f& axis_direction, double radius, int numsides = 30, const Color &color = Color::white())
-
- :param axis_point1: A point1 on the axis of the cylinder.
- :param axis_point2: A point2 on the axis of the cylinder.
- :param radius: Radius of the cylinder.
- :param numsides: Resolution of the cylinder.
- :param color: :ocv:class:`Color` of the cylinder.
-
-viz::WCube
-----------
-.. ocv:class:: WCube
-
-This 3D Widget defines a cube. ::
-
- class CV_EXPORTS WCube : public Widget3D
- {
- public:
- WCube(const Point3f& pt_min, const Point3f& pt_max, bool wire_frame = true, const Color &color = Color::white());
- };
-
-viz::WCube::WCube
----------------------------
-Constructs a WCube.
-
-.. ocv:function:: WCube(const Point3f& pt_min, const Point3f& pt_max, bool wire_frame = true, const Color &color = Color::white())
-
- :param pt_min: Specifies minimum point of the bounding box.
- :param pt_max: Specifies maximum point of the bounding box.
- :param wire_frame: If true, cube is represented as wireframe.
- :param color: :ocv:class:`Color` of the cube.
-
-.. image:: images/cube_widget.png
- :alt: Cube Widget
- :align: center
-
-viz::WCoordinateSystem
-----------------------
-.. ocv:class:: WCoordinateSystem
-
-This 3D Widget represents a coordinate system. ::
-
- class CV_EXPORTS WCoordinateSystem : public Widget3D
- {
- public:
- WCoordinateSystem(double scale = 1.0);
- };
-
-viz::WCoordinateSystem::WCoordinateSystem
----------------------------------------------------
-Constructs a WCoordinateSystem.
-
-.. ocv:function:: WCoordinateSystem(double scale = 1.0)
-
- :param scale: Determines the size of the axes.
-
-viz::WPolyLine
---------------
-.. ocv:class:: WPolyLine
-
-This 3D Widget defines a poly line. ::
-
- class CV_EXPORTS WPolyLine : public Widget3D
- {
- public:
- WPolyLine(InputArray points, const Color &color = Color::white());
- };
-
-viz::WPolyLine::WPolyLine
------------------------------------
-Constructs a WPolyLine.
-
-.. ocv:function:: WPolyLine(InputArray points, const Color &color = Color::white())
-
- :param points: Point set.
- :param color: :ocv:class:`Color` of the poly line.
-
-viz::WGrid
-----------
-.. ocv:class:: WGrid
-
-This 3D Widget defines a grid. ::
-
- class CV_EXPORTS WGrid : public Widget3D
- {
- public:
- //! Creates grid at the origin and normal oriented along z-axis
- WGrid(const Vec2i &cells = Vec2i::all(10), const Vec2d &cells_spacing = Vec2d::all(1.0), const Color &color = Color::white());
-
- //! Creates repositioned grid
- WGrid(const Point3d& center, const Vec3d& normal, const Vec3d& new_yaxis,
- const Vec2i &cells = Vec2i::all(10), const Vec2d &cells_spacing = Vec2d::all(1.0), const Color &color = Color::white());
- };
-
-viz::WGrid::WGrid
----------------------------
-Constructs a WGrid.
-
-.. ocv:function:: WGrid(const Vec2i &cells = Vec2i::all(10), const Vec2d &cells_spacing = Vec2d::all(1.0), const Color &color = Color::white())
-
- :param cells: Number of cell columns and rows, respectively.
- :param cells_spacing: Size of each cell, respectively.
- :param color: :ocv:class:`Color` of the grid.
-
-.. ocv:function: WGrid(const Point3d& center, const Vec3d& normal, const Vec3d& new_yaxis, Vec2i &cells, const Vec2d &cells_spacing, const Color &color;
-
- :param center: Center of the grid
- :param normal: Grid normal orientation
- :param new_yaxis: Up-vector. New orientation of grid y-axis.
- :param cells: Number of cell columns and rows, respectively.
- :param cells_spacing: Size of each cell, respectively.
- :param color: :ocv:class:`Color` of the grid..
-
-viz::WText3D
-------------
-.. ocv:class:: WText3D
-
-This 3D Widget represents 3D text. The text always faces the camera. ::
-
- class CV_EXPORTS WText3D : public Widget3D
- {
- public:
- WText3D(const String &text, const Point3f &position, double text_scale = 1.0, bool face_camera = true, const Color &color = Color::white());
-
- void setText(const String &text);
- String getText() const;
- };
-
-viz::WText3D::WText3D
--------------------------------
-Constructs a WText3D.
-
-.. ocv:function:: WText3D(const String &text, const Point3f &position, double text_scale = 1.0, bool face_camera = true, const Color &color = Color::white())
-
- :param text: Text content of the widget.
- :param position: Position of the text.
- :param text_scale: Size of the text.
- :param face_camera: If true, text always faces the camera.
- :param color: :ocv:class:`Color` of the text.
-
-viz::WText3D::setText
----------------------
-Sets the text content of the widget.
-
-.. ocv:function:: void setText(const String &text)
-
- :param text: Text content of the widget.
-
-viz::WText3D::getText
----------------------
-Returns the current text content of the widget.
-
-.. ocv:function:: String getText() const
-
-viz::WText
-----------
-.. ocv:class:: WText
-
-This 2D Widget represents text overlay. ::
-
- class CV_EXPORTS WText : public Widget2D
- {
- public:
- WText(const String &text, const Point2i &pos, int font_size = 10, const Color &color = Color::white());
-
- void setText(const String &text);
- String getText() const;
- };
-
-viz::WText::WText
------------------
-Constructs a WText.
-
-.. ocv:function:: WText(const String &text, const Point2i &pos, int font_size = 10, const Color &color = Color::white())
-
- :param text: Text content of the widget.
- :param pos: Position of the text.
- :param font_size: Font size.
- :param color: :ocv:class:`Color` of the text.
-
-viz::WText::setText
--------------------
-Sets the text content of the widget.
-
-.. ocv:function:: void setText(const String &text)
-
- :param text: Text content of the widget.
-
-viz::WText::getText
--------------------
-Returns the current text content of the widget.
-
-.. ocv:function:: String getText() const
-
-viz::WImageOverlay
-------------------
-.. ocv:class:: WImageOverlay
-
-This 2D Widget represents an image overlay. ::
-
- class CV_EXPORTS WImageOverlay : public Widget2D
- {
- public:
- WImageOverlay(InputArray image, const Rect &rect);
-
- void setImage(InputArray image);
- };
-
-viz::WImageOverlay::WImageOverlay
----------------------------------
-Constructs an WImageOverlay.
-
-.. ocv:function:: WImageOverlay(InputArray image, const Rect &rect)
-
- :param image: BGR or Gray-Scale image.
- :param rect: Image is scaled and positioned based on rect.
-
-viz::WImageOverlay::setImage
-----------------------------
-Sets the image content of the widget.
-
-.. ocv:function:: void setImage(InputArray image)
-
- :param image: BGR or Gray-Scale image.
-
-viz::WImage3D
--------------
-.. ocv:class:: WImage3D
-
-This 3D Widget represents an image in 3D space. ::
-
- class CV_EXPORTS WImage3D : public Widget3D
- {
- public:
- //! Creates 3D image at the origin
- WImage3D(InputArray image, const Size2d &size);
- //! Creates 3D image at a given position, pointing in the direction of the normal, and having the up_vector orientation
- WImage3D(InputArray image, const Size2d &size, const Vec3d &position, const Vec3d &normal, const Vec3d &up_vector);
-
- void setImage(InputArray image);
- };
-
-viz::WImage3D::WImage3D
------------------------
-Constructs an WImage3D.
-
-.. ocv:function:: WImage3D(InputArray image, const Size2d &size)
-
- :param image: BGR or Gray-Scale image.
- :param size: Size of the image.
-
-.. ocv:function:: WImage3D(InputArray image, const Size2d &size, const Vec3d &position, const Vec3d &normal, const Vec3d &up_vector)
-
- :param position: Position of the image.
- :param normal: Normal of the plane that represents the image.
- :param up_vector: Determines orientation of the image.
- :param image: BGR or Gray-Scale image.
- :param size: Size of the image.
-
-viz::WImage3D::setImage
------------------------
-Sets the image content of the widget.
-
-.. ocv:function:: void setImage(InputArray image)
-
- :param image: BGR or Gray-Scale image.
-
-viz::WCameraPosition
---------------------
-.. ocv:class:: WCameraPosition
-
-This 3D Widget represents camera position in a scene by its axes or viewing frustum. ::
-
- class CV_EXPORTS WCameraPosition : public Widget3D
- {
- public:
- //! Creates camera coordinate frame (axes) at the origin
- WCameraPosition(double scale = 1.0);
- //! Creates frustum based on the intrinsic marix K at the origin
- WCameraPosition(const Matx33d &K, double scale = 1.0, const Color &color = Color::white());
- //! Creates frustum based on the field of view at the origin
- WCameraPosition(const Vec2d &fov, double scale = 1.0, const Color &color = Color::white());
- //! Creates frustum and display given image at the far plane
- WCameraPosition(const Matx33d &K, InputArray image, double scale = 1.0, const Color &color = Color::white());
- //! Creates frustum and display given image at the far plane
- WCameraPosition(const Vec2d &fov, InputArray image, double scale = 1.0, const Color &color = Color::white());
- };
-
-viz::WCameraPosition::WCameraPosition
--------------------------------------
-Constructs a WCameraPosition.
-
-- **Display camera coordinate frame.**
-
- .. ocv:function:: WCameraPosition(double scale = 1.0)
-
- Creates camera coordinate frame at the origin.
-
- .. image:: images/cpw1.png
- :alt: Camera coordinate frame
- :align: center
-
-- **Display the viewing frustum.**
-
- .. ocv:function:: WCameraPosition(const Matx33d &K, double scale = 1.0, const Color &color = Color::white())
-
- :param K: Intrinsic matrix of the camera.
- :param scale: Scale of the frustum.
- :param color: :ocv:class:`Color` of the frustum.
-
- Creates viewing frustum of the camera based on its intrinsic matrix K.
-
- .. ocv:function:: WCameraPosition(const Vec2d &fov, double scale = 1.0, const Color &color = Color::white())
-
- :param fov: Field of view of the camera (horizontal, vertical).
- :param scale: Scale of the frustum.
- :param color: :ocv:class:`Color` of the frustum.
-
- Creates viewing frustum of the camera based on its field of view fov.
-
- .. image:: images/cpw2.png
- :alt: Camera viewing frustum
- :align: center
-
-- **Display image on the far plane of the viewing frustum.**
-
- .. ocv:function:: WCameraPosition(const Matx33d &K, InputArray image, double scale = 1.0, const Color &color = Color::white())
-
- :param K: Intrinsic matrix of the camera.
- :param img: BGR or Gray-Scale image that is going to be displayed on the far plane of the frustum.
- :param scale: Scale of the frustum and image.
- :param color: :ocv:class:`Color` of the frustum.
-
- Creates viewing frustum of the camera based on its intrinsic matrix K, and displays image on the far end plane.
-
- .. ocv:function:: WCameraPosition(const Vec2d &fov, InputArray image, double scale = 1.0, const Color &color = Color::white())
-
- :param fov: Field of view of the camera (horizontal, vertical).
- :param img: BGR or Gray-Scale image that is going to be displayed on the far plane of the frustum.
- :param scale: Scale of the frustum and image.
- :param color: :ocv:class:`Color` of the frustum.
-
- Creates viewing frustum of the camera based on its intrinsic matrix K, and displays image on the far end plane.
-
- .. image:: images/cpw3.png
- :alt: Camera viewing frustum with image
- :align: center
-
-viz::WTrajectory
-----------------
-.. ocv:class:: WTrajectory
-
-This 3D Widget represents a trajectory. ::
-
- class CV_EXPORTS WTrajectory : public Widget3D
- {
- public:
- enum {FRAMES = 1, PATH = 2, BOTH = FRAMES + PATH};
-
- //! Displays trajectory of the given path either by coordinate frames or polyline
- WTrajectory(InputArray path, int display_mode = WTrajectory::PATH, double scale = 1.0, const Color &color = Color::white(),;
- };
-
-viz::WTrajectory::WTrajectory
------------------------------
-Constructs a WTrajectory.
-
-.. ocv:function:: WTrajectory(InputArray path, int display_mode = WTrajectory::PATH, double scale = 1.0, const Color &color = Color::white())
-
- :param path: List of poses on a trajectory. Takes std::vector<Affine<T>> with T == [float | double]
- :param display_mode: Display mode. This can be PATH, FRAMES, and BOTH.
- :param scale: Scale of the frames. Polyline is not affected.
- :param color: :ocv:class:`Color` of the polyline that represents path. Frames are not affected.
-
- Displays trajectory of the given path as follows:
-
- * PATH : Displays a poly line that represents the path.
- * FRAMES : Displays coordinate frames at each pose.
- * PATH & FRAMES : Displays both poly line and coordinate frames.
-
-viz::WTrajectoryFrustums
-------------------------
-.. ocv:class:: WTrajectoryFrustums
-
-This 3D Widget represents a trajectory. ::
-
- class CV_EXPORTS WTrajectoryFrustums : public Widget3D
- {
- public:
- //! Displays trajectory of the given path by frustums
- WTrajectoryFrustums(InputArray path, const Matx33d &K, double scale = 1.0, const Color &color = Color::white());
- //! Displays trajectory of the given path by frustums
- WTrajectoryFrustums(InputArray path, const Vec2d &fov, double scale = 1.0, const Color &color = Color::white());
- };
-
-viz::WTrajectoryFrustums::WTrajectoryFrustums
----------------------------------------------
-Constructs a WTrajectoryFrustums.
-
-.. ocv:function:: WTrajectoryFrustums(const std::vector<Affine3d> &path, const Matx33d &K, double scale = 1.0, const Color &color = Color::white())
-
- :param path: List of poses on a trajectory. Takes std::vector<Affine<T>> with T == [float | double]
- :param K: Intrinsic matrix of the camera.
- :param scale: Scale of the frustums.
- :param color: :ocv:class:`Color` of the frustums.
-
- Displays frustums at each pose of the trajectory.
-
-.. ocv:function:: WTrajectoryFrustums(const std::vector<Affine3d> &path, const Vec2d &fov, double scale = 1.0, const Color &color = Color::white())
-
- :param path: List of poses on a trajectory. Takes std::vector<Affine<T>> with T == [float | double]
- :param fov: Field of view of the camera (horizontal, vertical).
- :param scale: Scale of the frustums.
- :param color: :ocv:class:`Color` of the frustums.
-
- Displays frustums at each pose of the trajectory.
-
-viz::WTrajectorySpheres
------------------------
-.. ocv:class:: WTrajectorySpheres
-
-This 3D Widget represents a trajectory using spheres and lines, where spheres represent the positions of the camera, and lines
-represent the direction from previous position to the current. ::
-
- class CV_EXPORTS WTrajectorySpheres : public Widget3D
- {
- public:
- WTrajectorySpheres(InputArray path, double line_length = 0.05, double radius = 0.007,
- const Color &from = Color::red(), const Color &to = Color::white());
- };
-
-viz::WTrajectorySpheres::WTrajectorySpheres
--------------------------------------------
-Constructs a WTrajectorySpheres.
-
-.. ocv:function:: WTrajectorySpheres(InputArray path, double line_length = 0.05, double radius = 0.007, const Color &from = Color::red(), const Color &to = Color::white())
-
- :param path: List of poses on a trajectory. Takes std::vector<Affine<T>> with T == [float | double]
- :param line_length: Max length of the lines which point to previous position
- :param sphere_radius: Radius of the spheres.
- :param from: :ocv:class:`Color` for first sphere.
- :param to: :ocv:class:`Color` for last sphere. Intermediate spheres will have interpolated color.
-
-viz::WCloud
------------
-.. ocv:class:: WCloud
-
-This 3D Widget defines a point cloud. ::
-
- class CV_EXPORTS WCloud : public Widget3D
- {
- public:
- //! Each point in cloud is mapped to a color in colors
- WCloud(InputArray cloud, InputArray colors);
- //! All points in cloud have the same color
- WCloud(InputArray cloud, const Color &color = Color::white());
- //! Each point in cloud is mapped to a color in colors, normals are used for shading
- WCloud(InputArray cloud, InputArray colors, InputArray normals);
- //! All points in cloud have the same color, normals are used for shading
- WCloud(InputArray cloud, const Color &color, InputArray normals);
- };
-
-viz::WCloud::WCloud
--------------------
-Constructs a WCloud.
-
-.. ocv:function:: WCloud(InputArray cloud, InputArray colors)
-
- :param cloud: Set of points which can be of type: ``CV_32FC3``, ``CV_32FC4``, ``CV_64FC3``, ``CV_64FC4``.
- :param colors: Set of colors. It has to be of the same size with cloud.
-
- Points in the cloud belong to mask when they are set to (NaN, NaN, NaN).
-
-.. ocv:function:: WCloud(InputArray cloud, const Color &color = Color::white())
-
- :param cloud: Set of points which can be of type: ``CV_32FC3``, ``CV_32FC4``, ``CV_64FC3``, ``CV_64FC4``.
- :param color: A single :ocv:class:`Color` for the whole cloud.
-
- Points in the cloud belong to mask when they are set to (NaN, NaN, NaN).
-
-.. ocv:function:: WCloud(InputArray cloud, InputArray colors, InputArray normals)
-
- :param cloud: Set of points which can be of type: ``CV_32FC3``, ``CV_32FC4``, ``CV_64FC3``, ``CV_64FC4``.
- :param colors: Set of colors. It has to be of the same size with cloud.
- :param normals: Normals for each point in cloud. Size and type should match with the cloud parameter.
-
- Points in the cloud belong to mask when they are set to (NaN, NaN, NaN).
-
-.. ocv:function:: WCloud(InputArray cloud, const Color &color, InputArray normals)
-
- :param cloud: Set of points which can be of type: ``CV_32FC3``, ``CV_32FC4``, ``CV_64FC3``, ``CV_64FC4``.
- :param color: A single :ocv:class:`Color` for the whole cloud.
- :param normals: Normals for each point in cloud. Size and type should match with the cloud parameter.
-
- Points in the cloud belong to mask when they are set to (NaN, NaN, NaN).
-
-.. note:: In case there are four channels in the cloud, fourth channel is ignored.
-
-viz::WCloudCollection
----------------------
-.. ocv:class:: WCloudCollection
-
-This 3D Widget defines a collection of clouds. ::
-
- class CV_EXPORTS WCloudCollection : public Widget3D
- {
- public:
- WCloudCollection();
-
- //! Each point in cloud is mapped to a color in colors
- void addCloud(InputArray cloud, InputArray colors, const Affine3d &pose = Affine3d::Identity());
- //! All points in cloud have the same color
- void addCloud(InputArray cloud, const Color &color = Color::white(), Affine3d &pose = Affine3d::Identity());
- //! Repacks internal structure to single cloud
- void finalize();
- };
-
-viz::WCloudCollection::WCloudCollection
----------------------------------------
-Constructs a WCloudCollection.
-
-.. ocv:function:: WCloudCollection()
-
-viz::WCloudCollection::addCloud
--------------------------------
-Adds a cloud to the collection.
-
-.. ocv:function:: void addCloud(InputArray cloud, InputArray colors, const Affine3d &pose = Affine3d::Identity())
-
- :param cloud: Point set which can be of type: ``CV_32FC3``, ``CV_32FC4``, ``CV_64FC3``, ``CV_64FC4``.
- :param colors: Set of colors. It has to be of the same size with cloud.
- :param pose: Pose of the cloud.
-
- Points in the cloud belong to mask when they are set to (NaN, NaN, NaN).
-
-.. ocv:function:: void addCloud(InputArray cloud, const Color &color = Color::white(), const Affine3d &pose = Affine3d::Identity())
-
- :param cloud: Point set which can be of type: ``CV_32FC3``, ``CV_32FC4``, ``CV_64FC3``, ``CV_64FC4``.
- :param colors: A single :ocv:class:`Color` for the whole cloud.
- :param pose: Pose of the cloud.
-
- Points in the cloud belong to mask when they are set to (NaN, NaN, NaN).
-
-.. note:: In case there are four channels in the cloud, fourth channel is ignored.
-
-viz::WCloudCollection::finalize
--------------------------------
-Finalizes cloud data by repacking to single cloud. Useful for large cloud collections to reduce memory usage
-
-.. ocv:function:: void finalize()
-
-viz::WCloudNormals
-------------------
-.. ocv:class:: WCloudNormals
-
-This 3D Widget represents normals of a point cloud. ::
-
- class CV_EXPORTS WCloudNormals : public Widget3D
- {
- public:
- WCloudNormals(InputArray cloud, InputArray normals, int level = 100, double scale = 0.02f, const Color &color = Color::white());
- };
-
-viz::WCloudNormals::WCloudNormals
----------------------------------
-Constructs a WCloudNormals.
-
-.. ocv:function:: WCloudNormals(InputArray cloud, InputArray normals, int level = 100, double scale = 0.02f, const Color &color = Color::white())
-
- :param cloud: Point set which can be of type: ``CV_32FC3``, ``CV_32FC4``, ``CV_64FC3``, ``CV_64FC4``.
- :param normals: A set of normals that has to be of same type with cloud.
- :param level: Display only every ``level`` th normal.
- :param scale: Scale of the arrows that represent normals.
- :param color: :ocv:class:`Color` of the arrows that represent normals.
-
-.. note:: In case there are four channels in the cloud, fourth channel is ignored.
-
-viz::WMesh
-----------
-.. ocv:class:: WMesh
-
-This 3D Widget defines a mesh. ::
-
- class CV_EXPORTS WMesh : public Widget3D
- {
- public:
- WMesh(const Mesh &mesh);
- WMesh(InputArray cloud, InputArray polygons, InputArray colors = noArray(), InputArray normals = noArray());
- };
-
-viz::WMesh::WMesh
------------------
-Constructs a WMesh.
-
-.. ocv:function:: WMesh(const Mesh &mesh)
-
- :param mesh: :ocv:class:`Mesh` object that will be displayed.
-
-.. ocv:function:: WMesh(InputArray cloud, InputArray polygons, InputArray colors = noArray(), InputArray normals = noArray())
-
- :param cloud: Points of the mesh object.
- :param polygons: Points of the mesh object.
- :param colors: Point colors.
- :param normals: Point normals.
-
-viz::WWidgetMerger
----------------------
-.. ocv:class:: WWidgetMerger
-
-This class allows to merge several widgets to single one. It has quite limited functionality and can't merge widgets with different attributes. For instance,
-if widgetA has color array and widgetB has only global color defined, then result of merge won't have color at all. The class is suitable for merging large amount of similar widgets. ::
-
- class CV_EXPORTS WWidgetMerger : public Widget3D
- {
- public:
- WWidgetMerger();
-
- //! Add widget to merge with optional position change
- void addWidget(const Widget3D& widget, const Affine3d &pose = Affine3d::Identity());
-
- //! Repacks internal structure to single widget
- void finalize();
- };
-
-viz::WWidgetMerger::WWidgetMerger
----------------------------------------
-Constructs a WWidgetMerger.
-
-.. ocv:function:: WWidgetMerger()
-
-viz::WWidgetMerger::addCloud
--------------------------------
-Adds a cloud to the collection.
-
-.. ocv:function:: void addWidget(const Widget3D& widget, const Affine3d &pose = Affine3d::Identity())
-
- :param widget: Widget to merge.
- :param pose: Pose of the widget.
-
-viz::WWidgetMerger::finalize
--------------------------------
-Finalizes merger data and constructs final merged widget
-
-.. ocv:function:: void finalize()
projects / platform / upstream / opencv.git / commitdiff
