.. _changelog_v2_5_0:

v2.5.0
======

v2.5.0 is a feature-rich imaging release: it adds ``find_rects()``,
``find_circles()``, ``get_regression()`` (line/regression fitting),
``find_number()`` (LeNet digits), the ``ImageWriter`` / ``ImageReader``
stream classes, :func:`sensor.flush` / ``width()`` / ``height()``, and
:class:`pyb.RTC` support. Image loading is now framebuffer-backed — read the
breaking changes below.

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

Highlights
----------

- ``image.find_rects()`` — rectangle / quad detector with corner output.
- ``image.find_circles()`` — Hough circle detection.
- ``image.get_regression()`` — least-squares and robust (Theil-Sen) line
  fitting.
- ``image.find_number()`` — LeNet digit recognition.
- ``ImageWriter`` / ``ImageReader`` — record and play back image streams.
- :class:`pyb.RTC` support, plus :func:`sensor.flush` / :func:`sensor.width` /
  :func:`sensor.height`.
- **Breaking:** image loading is now framebuffer-backed and raises if the
  image is too large — see the breaking changes.

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

- **Feature detection** — added ``image.find_rects()`` (AprilTag quad
  detector; rect objects with ``x`` / ``y`` / ``w`` / ``h`` / ``corners`` /
  ``magnitude``), ``image.find_circles()`` (Hough), ``image.get_regression()``
  (least-squares + Theil-Sen robust line fitting), and ``image.find_number()``
  (LeNet digit recognition), each with example scripts.
- **Result corners** — added a ``corners`` attribute to the QR-code /
  AprilTag / data-matrix / barcode result objects.
- **Image streams** — added the ``image.ImageWriter`` / ``image.ImageReader``
  classes (16-byte-aligned chunk format) with ``image_writer.py`` /
  ``image_reader.py`` examples.
- **Sensor** — added :func:`sensor.flush` (push the framebuffer to the IDE
  without a snapshot) and :func:`sensor.width` / :func:`sensor.height`.
- :class:`pyb.RTC` — enabled RTC support with an ``rtc.py`` example.
- Added a cat-face Haar cascade and a Servo-Shield (PCA9685) example; the
  ``openmv-cascade.py`` host tool gained support for the new OpenCV XML
  cascade format.

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

- The framebuffer was refactored so ``copy_to_fb`` image methods update the
  IDE preview; ``HaarCascade()`` paths no longer require a leading ``/``
  (built-in vs. file is auto-detected); GIF/MJPEG recording now supports VGA
  (and BAYER GIFs); the built-in ``README.txt`` was updated and the
  ``openmv.inf`` driver file is no longer created on a fresh filesystem.

Bug fixes
---------

Imaging:

- Fixed ``find_circles()`` vote accumulation, ``get_regression()`` rho offset
  with an ROI and a memory leak, ``find_lines()`` segment merging,
  ``find_blobs()`` angle averaging and default (least-restrictive) color
  bounds, ORB keypoint sort stability / descriptor ordering and the
  matched-flag, and Haar cascade buffered loading (unaligned reads).

System:

- Enabled :mod:`pyb` Servo 3 (P9) (#256), fixed the RTC init, increased the
  UART character timeout (#240), and fixed the uninitialized sensor
  framebuffer "enabled" flag.

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

- :class:`pyb.RTC` support and :mod:`pyb` Servo 3 (P9); Servo-Shield (PCA9685)
  example.

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

User-visible API breaks between v2.4.1 and v2.5.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.

.. _v2_5_0_imageload:

Image loading is framebuffer-backed *(behavior)*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:class:`image.Image` / image loading now copies the loaded image into the main
framebuffer and raises an exception if the image is too large to fit. Loads
that previously succeeded into a heap buffer may now fail — ensure loaded
images fit the framebuffer (or handle the new error).

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

.. _v2_5_0_migration:

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

Ensure loaded images fit the framebuffer (or catch the new "image too large"
error) where you previously relied on heap-backed image loads
(:ref:`the image-load change <v2_5_0_imageload>`). All other scripts run
unchanged.