.. _changelog_v1_6_0:

v1.6.0
======

v1.6.0 adds a Time-of-Flight (:mod:`tof`) module, ``image.find_displacement()``
(FFT phase-correlation optical flow), an image **pooling** API,
:func:`sensor.set_windowing`, and ``image.find_template()`` search options.
``find_template()`` now enforces its ROI — read the breaking changes below.

.. contents:: On this page
   :local:
   :depth: 1

Highlights
----------

- :mod:`tof` module — Time-of-Flight distance-sensor support.
- ``image.find_displacement()`` — FFT phase-correlation (optical flow).
- **Pooling** — ``midpoint_pool()`` / ``mean_pool()`` and pooled variants.
- :func:`sensor.set_windowing` — sensor windowing / binning, with new
  low-res framesizes.
- ``find_template()`` — added ``step`` / ``search`` (``SEARCH_EX`` /
  ``SEARCH_DS``) / ``roi`` options.
- **Breaking:** ``image.find_template()`` now enforces a valid ROI — see the
  breaking changes.

New features
------------

- :mod:`tof` — added a Time-of-Flight module with :func:`tof.init` /
  :func:`tof.deinit` / ``tof.read_frame()`` / ``tof.draw_frame()`` /
  ``tof.write_reg()`` (I2C ToF sensor support).
- ``image.find_displacement()`` — added FFT phase-correlation
  displacement (with subpixel and quality-of-result), with an optical-flow
  example.
- **Pooling** — added ``Image.midpoint_pool()`` / ``midpoint_pooled()`` /
  ``mean_pool()`` / ``mean_pooled()``.
- ``sensor.set_windowing((x, y, w, h))`` — sensor windowing/binning, with
  new ``sensor.B40x30`` / ``B64x32`` / ``B64x64`` framesizes for optical flow.
- ``image.find_template()`` — added ``step``, ``search``
  (``image.SEARCH_EX`` default / ``image.SEARCH_DS`` fast diamond search),
  and ``roi`` keyword arguments.
- ``Image.copy_to_fb()`` — copy an image into the framebuffer (with an
  optional ``(x, y)`` offset) and a ``copy2fb.py`` example.

Other changes and improvements
------------------------------

- ``find_template()`` diamond search refines its step more precisely (more
  accurate, slower); binning auto-enables for framesizes above VGA on the
  OpenMV 2; auto zoom/scale is disabled at VGA on the OV7725.

Bug fixes
---------

- Fixed the integral-image and integral-image-square computations (affecting
  Haar / feature / template-matching accuracy), the 1D/2D FFT and
  phase-correlation, and in-place pooling resizing the framebuffer.

Hardware and board support
--------------------------

- **Time-of-Flight (ToF)** distance sensor over I2C.
- New low-resolution framesizes (``B40x30`` / ``B64x32`` / ``B64x64``) for
  optical flow.

Breaking API changes
--------------------

User-visible API breaks between v1.5.0 and v1.6.0. Scope: Python C-modules in
``modules/`` and Python libraries in ``scripts/libraries/``.

The breaking change is a *behavior* change (same API, different result) —
re-check affected scripts. Each commit hash links to its diff on GitHub.

.. _v1_6_0_findtemplate:

``image.find_template()`` enforces its ROI *(behavior)*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``image.find_template()`` now validates its region of interest and raises
("Region of interest is bigger than image!") when the ROI is absent/oversized
or smaller than the template. Pass a valid ``roi=(x, y, w, h)`` that is at
least the template size and fits within the image.

*Commits:* `a25e0c162 <https://github.com/openmv/openmv/commit/a25e0c162>`__

.. _v1_6_0_migration:

Migration checklist
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Pass a valid ``roi`` (≥ template size, within the image) to
``image.find_template()`` (:ref:`the find_template change
<v1_6_0_findtemplate>`). All other scripts run unchanged.