Skip to content

Extend preset tours to recorded tours. #735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HansBusch wants to merge 7 commits into
base: development
Choose a base branch
from
+144 −19
Open

Extend preset tours to recorded tours. #735

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e56fe77
Add support for recorded preset-tours.
HansBusch Mar 10, 2026
5327fe5
Incorporate feedback from WG meeting.
HansBusch Mar 10, 2026
e804653
Improve documentation.
HansBusch Mar 11, 2026
a1aac80
- Incorporate Genetec comments.
HansBusch Mar 11, 2026
2b0af46
Create separate method RecordTour to avoid creation of unclear tour t…
HansBusch Mar 14, 2026
5c25aef
Editorial: fix accidental blank.
HansBusch Mar 31, 2026
ad041a1
Revert record operation. Fix typos.
HansBusch Mar 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 90 additions & 17 deletions doc/PTZ.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -412,6 +412,10 @@ Add GeoMove</revremark>
<listitem>
<para>MaximumNumberOfPresetTours – Indicates number of preset tours that can be created. Required preset tour operations shall be available for this PTZ node if one or more preset tours are supported.</para>
</listitem>
<listitem>
<para>MaxRecordedTours - Indicates the maximum number of recorded tours that can be
created.</para>
</listitem>
</itemizedlist>
</section>
<section>
Expand Down Expand Up @@ -1726,13 +1730,23 @@ Add GeoMove</revremark>
</section>
</section>
<section>
<title>Preset Tour Operations</title>
<para>Preset tour is a feature for PTZ-capable devices, enabling the PTZ unit to move on specified presets sequentially at some interval.</para>
<para>This section describes operations that manage the preset tours. These operations shall be implemented when a PTZ node in the PTZ service indicates support of preset tours with MaximumNumberOfPresetTours&gt;0 capability value, All operations require a profile token referencing a Media Profile including a PTZConfiguration. All operations for preset tours shall always be persistent.</para>
<para>PresetTours can have forward and backward directions, and in case direction is omitted, it is assumed to be forward. However, it is possible to specify random execution by setting the RandomPresetOrder attribute. In case RandomPresetOrder is set to true and Direction is also present, Direction will be ignored and presets of the Tour will be recalled randomly.</para>
<title>Tour Operations</title>
<para>Tours are a feature for PTZ-capable devices, enabling the PTZ unit to move sequentially
on a set of presets or a recorded tour. This section describes operations to manage and
operate tours. </para>
<para>All operations require a profile token referencing a Media Profile including a
PTZConfiguration. Tour configurations shall be persistent.</para>
<para>Preset tours can have forward and backward directions, and in case direction is omitted,
it is assumed to be forward. However, it is possible to specify random execution by setting
the RandomPresetOrder attribute. In case RandomPresetOrder is set to true and Direction is
also present, Direction will be ignored and presets of the Tour will be recalled
randomly.</para>
<para>A device signaling support for operation mode Record shall support recording of
tours.</para>
<section>
<title>GetPresetTours</title>
<para>A device supporting Preset Tour feature shall return all available preset tours through GetPresetTours.</para>
<para>A device with PTZ node signaling support for SupportedPresetTour or MaxRecordedTours
shall support this command to return all tours of a PTZ node.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
Expand Down Expand Up @@ -1767,7 +1781,8 @@ Add GeoMove</revremark>
</section>
<section>
<title>GetPresetTour</title>
<para>A device supporting preset tours shall return the requested preset tour through GetPresetTour.</para>
<para>A device with PTZ node signaling support for SupportedPresetTour or MaxRecordedTours
shall support this command to return the configuration of the requested tour.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
Expand Down Expand Up @@ -1806,7 +1821,9 @@ Add GeoMove</revremark>
</section>
<section>
<title>GetPresetTourOptions</title>
Copy link
Copy Markdown

@cemond-genetec cemond-genetec Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add GetRecordedTourOptions for AutoStart and recurring time ?

<para>A device supporting preset tours shall provide options for how preset tours can be configured through GetPresetTourOptions.</para>
<para>A device with PTZ node signaling SupportedPresetTour shall support this command and
provide options for how preset tours can be configured through
GetPresetTourOptions.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
Expand Down Expand Up @@ -1843,7 +1860,9 @@ Add GeoMove</revremark>
</section>
<section>
<title>CreatePresetTour</title>
<para>A device supporting Preset Tour feature shall allow creating a new Preset Tour through the CreatePresetTour.</para>
<para>Create an empty preset tour to be filled via ModifyPresetTour. A device signaling
support via its PTZ node field MaximumNumberOfPresetTours shall support this
command.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
Expand Down Expand Up @@ -1878,9 +1897,54 @@ Add GeoMove</revremark>
</varlistentry>
</variablelist>
</section>
<section>
<title>RecordTour</title>
<para>Create a recorded tour or overwrite an existing tour. Finish the recording with tour
operation stop. A tour can be deleted with RemovePresetTour.</para>
<para>A device signaling support for recorded tours via the capability MaxRecordedTours
shall support this command.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="param">ProfileToken [tt:ReferenceToken]</para>
<para role="text">Reference to an existing media profile.</para>
<para role="param">TourToken - optional [tt:ReferenceToken]</para>
<para role="text">If provided an existing tour will be overwritten instead of creating a new one.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="param">TourToken [tt:ReferenceToken]</para>
<para role="text">Reference to the newly created tour.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>faults</term>
<listitem>
<para role="param">env:Sender - ter:InvalidArgVal - ter:NoProfile</para>
<para role="text">The requested profile token ProfileToken does not exist.</para>
<para role="param">env:Sender - ter:InvalidArgVal - ter:NoPTZProfile</para>
<para role="text">The requested profile token does not reference a PTZ configuration.</para>
<para role="param">env:Sender - ter:InvalidArgVal - ter:TooManyRecordedTours</para>
<para role="text">The limit of MaxRecordedTours has been reached and no further
recorded tours can be created for the requested PTZ node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access class</term>
<listitem>
<para role="access">ACTUATE</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>ModifyPresetTour</title>
<para>A device supporting preset tours shall allow modifying a preset tour through ModifyPresetTour.</para>
<para>A device signaling support for preset tours via the PTZ node parameter
MaximumNumberOfPresetTours shall support modifying a preset tour through
ModifyPresetTour.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
Expand Down Expand Up @@ -1924,20 +1988,23 @@ Add GeoMove</revremark>
</section>
<section>
<title>OperatePresetTour</title>
<para>A device supporting preset tours shall allow starting, stopping, or pausing a preset tour through OperatePresetTour.</para>
<para>A device supporting preset tours shall allow starting, stopping, or pausing a preset
tour as signaled by the PTZ node configuration.</para>
<para>Preset tour can be operated with the PresetTourOperation parameter of OperatePresetTour command. </para>
<itemizedlist>
<listitem>
<para>Start: indicates starting the preset tour or re-starting the paused preset tour. </para>
<para>Start: indicates starting the tour or re-starting the paused preset tour. </para>
</listitem>
<listitem>
<para>Stop: indicates stopping the preset tour.</para>
<para>Stop: indicates stopping a tour or a recording.</para>
</listitem>
<listitem>
<para>Pause:iIndicates pausing the preset tour.</para>
<para>Pause: indicates pausing the preset tour.</para>
</listitem>
</itemizedlist>
<para>When receiving another OperatePresetTour command of Start operation for a preset tour which has already been started, the preset tour shall be restarted with the newly requested parameter.</para>
<para>A PTZ node that signals support for recorded tours via its MaxRecordedTours field
shall support the Record operation.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
Expand All @@ -1946,8 +2013,8 @@ Add GeoMove</revremark>
<para role="text">Reference to an existing media profile.</para>
<para role="param">PresetTourToken [tt:PTZPresetTourToken]</para>
<para role="text">Reference to an existing preset tour.</para>
<para role="param">Operation [tt:PTZPresetTourOperation]</para>
<para role="text">Operation information.</para>
<para role="param">Operation [xs:string]</para>
<para role="text">Operation as define by tt:PTZTourOperation.</para>
</listitem>
</varlistentry>
<varlistentry>
Expand Down Expand Up @@ -1981,7 +2048,8 @@ Add GeoMove</revremark>
</section>
<section>
<title>RemovePresetTour</title>
<para>A device supporting preset tours shall support removing preset tours through RemoevPresetTour.</para>
<para>A device supporting tours shall support removing preset and recorded tours through
RemovePresetTour.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
Expand Down Expand Up @@ -2083,7 +2151,8 @@ Add GeoMove</revremark>
</itemizedlist>
</listitem>
<listitem>
<para>PresetTourDirection: A device refers this flag to choose which direction the preset tour goes. It is omissible parameter and Forward shall be chosen in case it is omitted. [Optional] </para>
<para>PresetTourDirection: Optional list of supported operation direction. Defaults
to forward only.</para>
<itemizedlist>
<listitem>
<para>Forward: Preset tour goes in forward order.</para>
Expand All @@ -2095,6 +2164,10 @@ Add GeoMove</revremark>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>IsRecorded: The preset tour has been recorded instead of being defined by a set of
presets.</para>
</listitem>
<listitem>
<para>Token: Unique identifier of the preset tour</para>
</listitem>
Expand Down
16 changes: 14 additions & 2 deletions wsdl/ver10/schema/onvif.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4162,6 +4162,13 @@ decoding .A decoder shall decode every data it receives (according to its capabi
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="MaxRecordedTours" type="xs:int">
<xs:annotation>
<xs:documentation>
Indicates the maximum number of different tours that can be recorded.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:anyAttribute processContents="lax"/>
</xs:extension>
</xs:complexContent>
Expand Down Expand Up @@ -4196,7 +4203,7 @@ decoding .A decoder shall decode every data it receives (according to its capabi
</xs:element>
<xs:element name="PTZPresetTourOperation" type="tt:PTZPresetTourOperation" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>Indicates which preset tour operations are available for this PTZ Node.</xs:documentation>
<xs:documentation>List of operations provided for preset tours.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="Extension" type="tt:PTZPresetTourSupportedExtension" minOccurs="0"/>
Expand Down Expand Up @@ -4763,6 +4770,11 @@ decoding .A decoder shall decode every data it receives (according to its capabi
<xs:documentation>Unique identifier of this preset tour.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="IsRecorded" type="xs:boolean">
<xs:annotation>
<xs:documentation>Signal that this tour has been recorded and may have an empty list of tour spots.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>
<!--===============================-->
Expand Down Expand Up @@ -4973,7 +4985,7 @@ decoding .A decoder shall decode every data it receives (according to its capabi
</xs:element>
<xs:element name="Direction" type="tt:PTZPresetTourDirection" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>Supported options for Direction of Preset Tour.</xs:documentation>
<xs:documentation>Supported direction of Preset Tour. Defaults to forward.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="Extension" type="tt:PTZPresetTourStartingConditionOptionsExtension" minOccurs="0"/>
Expand Down
40 changes: 40 additions & 0 deletions wsdl/ver20/ptz/wsdl/ptz.wsdl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -634,6 +634,26 @@ IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FO
</xs:complexType>
</xs:element>
<!--===============================-->
<xs:element name="RecordTour">
<xs:complexType>
<xs:sequence>
<xs:element name="ProfileToken" type="tt:ReferenceToken"/>
<xs:element name="TourToken" type="tt:ReferenceToken" minOccurs="0">
<xs:annotation>
<xs:documentation>Optional tour to be overwritten. By default create a new tour.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="RecordTourResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="TourToken" type="tt:ReferenceToken"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<!--===============================-->
<xs:element name="ModifyPresetTour">
<xs:complexType>
<xs:sequence>
Expand Down Expand Up @@ -896,6 +916,12 @@ IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FO
<wsdl:message name="CreatePresetTourResponse">
<wsdl:part name="parameters" element="tptz:CreatePresetTourResponse"/>
</wsdl:message>
<wsdl:message name="RecordTourRequest">
<wsdl:part name="parameters" element="tptz:RecordTour"/>
</wsdl:message>
<wsdl:message name="RecordTourResponse">
<wsdl:part name="parameters" element="tptz:RecordTourResponse"/>
</wsdl:message>
<wsdl:message name="ModifyPresetTourRequest">
<wsdl:part name="parameters" element="tptz:ModifyPresetTour"/>
</wsdl:message>
Expand Down Expand Up @@ -1146,6 +1172,11 @@ If no stop argument for pan, tilt or zoom is set, the device will stop all ongoi
<wsdl:input message="tptz:CreatePresetTourRequest"/>
<wsdl:output message="tptz:CreatePresetTourResponse"/>
</wsdl:operation>
<wsdl:operation name="RecordTour">
<wsdl:documentation>Start recording of a new recorded tour or start overwriting an existing tour.</wsdl:documentation>
<wsdl:input message="tptz:RecordTourRequest"/>
<wsdl:output message="tptz:RecordTourResponse"/>
</wsdl:operation>
<wsdl:operation name="ModifyPresetTour">
<wsdl:documentation>Operation to modify a preset tour for the selected media profile.</wsdl:documentation>
<wsdl:input message="tptz:ModifyPresetTourRequest"/>
Expand Down Expand Up @@ -1399,6 +1430,15 @@ If no stop argument for pan, tilt or zoom is set, the device will stop all ongoi
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="RecordTour">
<soap:operation soapAction="http://www.onvif.org/ver20/ptz/wsdl/RecordTour"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="ModifyPresetTour">
<soap:operation soapAction="http://www.onvif.org/ver20/ptz/wsdl/ModifyPresetTour"/>
<wsdl:input>
Expand Down