mirror of
https://github.com/ZoneMinder/zoneminder.git
synced 2026-08-04 17:22:31 -04:00
863fac4d72
Add dedicated documentation page for the zma binary covering synopsis, all command-line options, operating modes (update-existing vs create-events), save-analysis functionality, and usage examples. Add zma entry to the components page and user guide toctree. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
120 lines
3.5 KiB
ReStructuredText
120 lines
3.5 KiB
ReStructuredText
zma - Event Re-Analysis
|
|
=======================
|
|
|
|
Description
|
|
-----------
|
|
|
|
``zma`` re-analyses a previously recorded event using the current zone settings
|
|
for the monitor. It decodes each frame from the event's stored video or JPEG
|
|
files and runs the full motion detection pipeline.
|
|
|
|
This is useful for tuning zone settings and re-running analysis on existing
|
|
footage without needing live cameras. After adjusting zones in the web
|
|
interface, you can use ``zma`` to see how those changes would affect detection
|
|
on past events.
|
|
|
|
By default, ``zma`` updates the existing event's motion statistics
|
|
(AlarmFrames, TotScore, AvgScore, MaxScore) in the database. With the
|
|
``--create-events`` option, it instead creates new events from the detected
|
|
motion regions.
|
|
|
|
Synopsis
|
|
--------
|
|
|
|
.. code-block:: bash
|
|
|
|
zma -e <event_id> [options]
|
|
|
|
Options
|
|
-------
|
|
|
|
``-e, --event <event_id>``
|
|
Event ID to re-analyse. Required.
|
|
|
|
``-m, --monitor <monitor_id>``
|
|
Override the monitor ID used for zone configuration. By default, ``zma``
|
|
uses the monitor that owns the event. Use this option to apply a different
|
|
monitor's zone settings to the event's footage.
|
|
|
|
``-c, --create-events``
|
|
Create new events from detected motion instead of updating the original
|
|
event's scores. The new events are inserted into the database and linked
|
|
to the source video files via hard links (falling back to copies if on a
|
|
different filesystem).
|
|
|
|
``-a, --save-analysis``
|
|
Write analysis JPEG images showing zone alarm overlays for each frame
|
|
that triggered motion. The images are written to the event's directory
|
|
using the standard analysis file naming convention.
|
|
|
|
``-v, --verbose``
|
|
Increase debug verbosity. Can be specified multiple times for higher
|
|
verbosity levels.
|
|
|
|
``-h, --help``
|
|
Display usage information.
|
|
|
|
``-V, --version``
|
|
Print the installed version of ZoneMinder.
|
|
|
|
Modes of Operation
|
|
------------------
|
|
|
|
Update Existing (default)
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
When run without ``--create-events``, ``zma`` processes every frame and then
|
|
updates the original event row in the database with the recalculated scores:
|
|
|
|
- **AlarmFrames** -- number of frames that triggered motion
|
|
- **TotScore** -- sum of all alarm frame scores
|
|
- **AvgScore** -- average score across alarm frames
|
|
- **MaxScore** -- highest single-frame score
|
|
|
|
This lets you see how zone tuning changes the event's score metrics without
|
|
creating any new data.
|
|
|
|
Create Events
|
|
^^^^^^^^^^^^^
|
|
|
|
With ``--create-events``, ``zma`` uses the monitor's alarm state machine
|
|
(including ``AlarmFrameCount`` and ``PostEventCount`` settings) to detect
|
|
alarm regions in the footage and creates new event records in the database for
|
|
each one. The source video files are hard-linked into the new event directories
|
|
so no additional disk space is used (on the same filesystem).
|
|
|
|
Save Analysis
|
|
^^^^^^^^^^^^^
|
|
|
|
The ``--save-analysis`` flag can be combined with either mode. When a frame
|
|
triggers motion, ``zma`` writes analysis JPEG images with zone alarm overlays
|
|
into the event directory. These images show which zones were triggered and can
|
|
be viewed in the web interface to visually verify zone configuration.
|
|
|
|
Examples
|
|
--------
|
|
|
|
Re-analyse event 12345 and update its scores in the database:
|
|
|
|
.. code-block:: bash
|
|
|
|
zma -e 12345
|
|
|
|
Re-analyse event 12345 using monitor 2's zone settings:
|
|
|
|
.. code-block:: bash
|
|
|
|
zma -e 12345 -m 2
|
|
|
|
Create new events from detected motion in event 12345:
|
|
|
|
.. code-block:: bash
|
|
|
|
zma -e 12345 --create-events
|
|
|
|
Re-analyse with analysis images and verbose output:
|
|
|
|
.. code-block:: bash
|
|
|
|
zma -e 12345 --save-analysis -v
|