ONVIF::...PTZPort(3)

✨ ONVIF::...PTZPort(3) ✨

part 1 of 2, bestie — more parts follow, so don't think this is the whole story. 💅

okay so welcome to this user-contributed Perl documentation for ONVIF::...PTZPort(3) — it's the SOAP interface for the PTZ Web Service, and we're gonna get you all the way through the method tea without spilling a single detail. 💖

---

🌸 NAME 🌸

ONVIF::PTZ::Interfaces::PTZ::PTZPort — the SOAP Interface for the PTZ Web Service. That's the whole name vibe. 🎀

---

🦋 SYNOPSIS 🦋

okay here's the whole little spell you cast to get the interface and call every method in the order the page lists them. copy-paste energy, but make it your own:

        use ONVIF::PTZ::Interfaces::PTZ::PTZPort;
        my $interface = ONVIF::PTZ::Interfaces::PTZ::PTZPort->new();

        my $response;
        $response = $interface->GetServiceCapabilities();
        $response = $interface->GetConfigurations();
        $response = $interface->GetPresets();
        $response = $interface->SetPreset();
        $response = $interface->RemovePreset();
        $response = $interface->GotoPreset();
        $response = $interface->GetStatus();
        $response = $interface->GetConfiguration();
        $response = $interface->GetNodes();
        $response = $interface->GetNode();
        $response = $interface->SetConfiguration();
        $response = $interface->GetConfigurationOptions();
        $response = $interface->GotoHomePosition();
        $response = $interface->SetHomePosition();
        $response = $interface->ContinuousMove();
        $response = $interface->RelativeMove();
        $response = $interface->SendAuxiliaryCommand();
        $response = $interface->AbsoluteMove();
        $response = $interface->Stop();
        $response = $interface->GetPresetTours();
        $response = $interface->GetPresetTour();
        $response = $interface->GetPresetTourOptions();
        $response = $interface->CreatePresetTour();
        $response = $interface->ModifyPresetTour();
        $response = $interface->OperatePresetTour();
        $response = $interface->RemovePresetTour();
        $response = $interface->GetCompatibleConfigurations();

---

💜 DESCRIPTION 💜

SOAP Interface for the PTZ web service located at http://www.examples.com/PTZ/. That's the URL, no cap. ✨

---

👑 SERVICE PTZ 👑

💅 Port PTZPort 💅

this is the service and port we're living in for this page, bestie. 🫶

---

🌈 METHODS 🌈

🧚 General methods 🧚

✨ new ✨

Constructor. All arguments are forwarded to SOAP::WSDL::Client. slay. 💅

---

🫶 SOAP Service methods 🫶

Method synopsis is displayed with hash refs as parameters — yes, hash refs, bestie. 😌

The commented class names in the method's parameters denote that objects of the corresponding class can be passed instead of the marked hash ref. 🎀

You may pass any combination of objects, hash and list refs to these methods, as long as you meet the structure. 🦋

List items (i.e. multiple occurrences) are not displayed in the synopsis. You may generally pass a list ref of hash refs (or objects) instead of a hash ref - this may result in invalid XML if used improperly, though. Note that SOAP::WSDL always expects list references at maximum depth position. ⭐

XML attributes are not displayed in this synopsis and cannot be set using hash refs. See the respective class' documentation for additional information. 💖

---

💖 GetServiceCapabilities 💖

Returns the capabilities of the PTZ service. The result is returned in a typed answer. ✨

Returns a ONVIF::PTZ::Elements::GetServiceCapabilitiesResponse object.

        $response = $interface->GetServiceCapabilities( {
         },,
        );

---

💖 GetConfigurations 💖

okay so the allowed pan and tilt range for Pan/Tilt Limits is defined by a two-dimensional space range that is mapped to a specific Absolute Pan/Tilt Position Space. At least one Pan/Tilt Position Space is required by the PTZNode to support Pan/Tilt limits. The limits apply to all supported absolute, relative and continuous Pan/Tilt movements. The limits shall be checked within the coordinate system for which the limits have been specified. That means that even if movements are specified in a different coordinate system, the requested movements shall be transformed to the coordinate system of the limits where the limits can be checked. When a relative or continuous movements is specified, which would leave the specified limits, the PTZ unit has to move along the specified limits. The Zoom Limits have to be interpreted accordingly. 🌀

Returns a ONVIF::PTZ::Elements::GetConfigurationsResponse object.

        $response = $interface->GetConfigurations(,,
        );

---

💖 GetPresets 💖

Operation to request all PTZ presets for the PTZNode in the selected profile. The operation is supported if there is support for at least on PTZ preset by the PTZNode. 🔥

Returns a ONVIF::PTZ::Elements::GetPresetsResponse object.

        $response = $interface->GetPresets( {
           ProfileToken => $some_value, # ReferenceToken
         },,
        );

---

💖 SetPreset 💖

The SetPreset command saves the current device position parameters so that the device can move to the saved preset position through the GotoPreset operation. In order to create a new preset, the SetPresetRequest contains no PresetToken. If creation is successful, the Response contains the PresetToken which uniquely identifies the Preset. An existing Preset can be overwritten by specifying the PresetToken of the corresponding Preset. In both cases (overwriting or creation) an optional PresetName can be specified. The operation fails if the PTZ device is moving during the SetPreset operation. The device MAY internally save additional states such as imaging properties in the PTZ Preset which then should be recalled in the GotoPreset operation. 🎀

Returns a ONVIF::PTZ::Elements::SetPresetResponse object.

        $response = $interface->SetPreset( {
           ProfileToken => $some_value, # ReferenceToken
           PresetName =>  $some_value, # string
           PresetToken => $some_value, # ReferenceToken
         },,
        );

---

💖 RemovePreset 💖

Operation to remove a PTZ preset for the Node in the selected profile. The operation is supported if the PresetPosition capability exists for the Node in the selected profile. ✨

Returns a ONVIF::PTZ::Elements::RemovePresetResponse object.

        $response = $interface->RemovePreset( {
           ProfileToken => $some_value, # ReferenceToken
           PresetToken => $some_value, # ReferenceToken
         },,
        );

---

💖 GotoPreset 💖

Operation to go to a saved preset position for the PTZNode in the selected profile. The operation is supported if there is support for at least on PTZ preset by the PTZNode. 💫

Returns a ONVIF::PTZ::Elements::GotoPresetResponse object.

        $response = $interface->GotoPreset( {
           ProfileToken => $some_value, # ReferenceToken
           PresetToken => $some_value, # ReferenceToken
           Speed =>  { # ONVIF::PTZ::Types::PTZSpeed
             PanTilt => ,
             Zoom => ,
           },
         },,
        );

---

💖 GetStatus 💖

Operation to request PTZ status for the Node in the selected profile. 👑

Returns a ONVIF::PTZ::Elements::GetStatusResponse object.

        $response = $interface->GetStatus( {
           ProfileToken => $some_value, # ReferenceToken
         },,
        );

---

💖 GetConfiguration 💖

The allowed pan and tilt range for Pan/Tilt Limits is defined by a two-dimensional space range that is mapped to a specific Absolute Pan/Tilt Position Space. At least one Pan/Tilt Position Space is required by the PTZNode to support Pan/Tilt limits. The limits apply to all supported absolute, relative and continuous Pan/Tilt movements. The limits shall be checked within the coordinate system for which the limits have been specified. That means that even if movements are specified in a different coordinate system, the requested movements shall be transformed to the coordinate system of the limits where the limits can be checked. When a relative or continuous movements is specified, which would leave the specified limits, the PTZ unit has to move along the specified limits. The Zoom Limits have to be interpreted accordingly. 🌈

Returns a ONVIF::PTZ::Elements::GetConfigurationResponse object.

        $response = $interface->GetConfiguration( {
           PTZConfigurationToken => $some_value, # ReferenceToken
         },,
        );

---

💖 GetNodes 💖

A PTZ-capable device may have multiple PTZ Nodes. The PTZ Nodes may represent mechanical PTZ drivers, uploaded PTZ drivers or digital PTZ drivers. PTZ Nodes are the lowest level entities in the PTZ control API and reflect the supported PTZ capabilities. The PTZ Node is referenced either by its name or by its reference token. 🦋

Returns a ONVIF::PTZ::Elements::GetNodesResponse object.

        $response = $interface->GetNodes(,,
        );

---

💖 GetNode 💖

Get a specific PTZ Node identified by a reference token or a name. 🔍

Returns a ONVIF::PTZ::Elements::GetNodeResponse object.

        $response = $interface->GetNode( {
           NodeToken => $some_value, # ReferenceToken
         },,
        );

---

💖 SetConfiguration 💖

Set/update a existing PTZConfiguration on the device. 💅

Returns a ONVIF::PTZ::Elements::SetConfigurationResponse object.

        $response = $interface->SetConfiguration( {
           PTZConfiguration =>  { # ONVIF::PTZ::Types::PTZConfiguration
             NodeToken => $some_value, # ReferenceToken
             DefaultAbsolutePantTiltPositionSpace =>  $some_value, # anyURI
             DefaultAbsoluteZoomPositionSpace =>  $some_value, # anyURI
             DefaultRelativePanTiltTranslationSpace =>  $some_value, # anyURI
             DefaultRelativeZoomTranslationSpace =>  $some_value, # anyURI
             DefaultContinuousPanTiltVelocitySpace =>  $some_value, # anyURI
             DefaultContinuousZoomVelocitySpace =>  $some_value, # anyURI
             DefaultPTZSpeed =>  { # ONVIF::PTZ::Types::PTZSpeed
               PanTilt => ,
               Zoom => ,
             },
             DefaultPTZTimeout =>  $some_value, # duration
             PanTiltLimits =>  { # ONVIF::PTZ::Types::PanTiltLimits
               Range =>  { # ONVIF::PTZ::Types::Space2DDescription
                 URI =>  $some_value, # anyURI
                 XRange =>  { # ONVIF::PTZ::Types::FloatRange
                   Min =>  $some_value, # float
                   Max =>  $some_value, # float
                 },
                 YRange =>  { # ONVIF::PTZ::Types::FloatRange
                   Min =>  $some_value, # float
                   Max =>  $some_value, # float
                 },
               },
             },
             ZoomLimits =>  { # ONVIF::PTZ::Types::ZoomLimits
               Range =>  { # ONVIF::PTZ::Types::Space1DDescription
                 URI =>  $some_value, # anyURI
                 XRange =>  { # ONVIF::PTZ::Types::FloatRange
                   Min =>  $some_value, # float
                   Max =>  $some_value, # float
                 },
               },
             },
             Extension =>  { # ONVIF::PTZ::Types::PTZConfigurationExtension
               PTControlDirection =>  { # ONVIF::PTZ::Types::PTControlDirection
                 EFlip =>  { # ONVIF::PTZ::Types::EFlip
                   Mode => $some_value, # EFlipMode
                 },
                 Reverse =>  { # ONVIF::PTZ::Types::Reverse
                   Mode => $some_value, # ReverseMode
                 },
                 Extension =>  { # ONVIF::PTZ::Types::PTControlDirectionExtension
                 },
               },
               Extension =>  { # ONVIF::PTZ::Types::PTZConfigurationExtension2
               },
             },
           },
           ForcePersistence =>  $some_value, # boolean
         },,
        );

---

💖 GetConfigurationOptions 💖

part 2 picks this one up right here, bestie — the rest is literally rolling in next. 🎧

okay so finishing up GetConfigurationOptions is literally just coordinate-system lore 🌀✨: it lists supported coordinate systems including their range limitations. so the options MAY differ depending on whether the PTZ Configuration is assigned to a Profile containing a Video Source Configuration. in that case, the options may additionally contain coordinate systems referring to the image coordinate system described by the Video Source Configuration. and if the PTZ Node supports continuous movements, it shall return a Timeout Range within which Timeouts are accepted by the PTZ Node. no cap.

Returns a ONVIF::PTZ::Elements::GetConfigurationOptionsResponse object. 🫶

       $response = $interface->GetConfigurationOptions( {
          ConfigurationToken => $some_value, # ReferenceToken
        },,
       );

GotoHomePosition 🏠

Operation to move the PTZ device to it's "home" position. The operation is supported if the HomeSupported element in the PTZNode is true.

Returns a ONVIF::PTZ::Elements::GotoHomePositionResponse object.

       $response = $interface->GotoHomePosition( {
          ProfileToken => $some_value, # ReferenceToken
          Speed =>  { # ONVIF::PTZ::Types::PTZSpeed
            PanTilt => ,
            Zoom => ,
          },
        },,
       );

SetHomePosition 🎀

Operation to save current position as the home position. The SetHomePosition command returns with a failure if the "home" position is fixed and cannot be overwritten. If the SetHomePosition is successful, it is possible to recall the Home Position with the GotoHomePosition command.

Returns a ONVIF::PTZ::Elements::SetHomePositionResponse object.

       $response = $interface->SetHomePosition( {
          ProfileToken => $some_value, # ReferenceToken
        },,
       );

ContinuousMove 🌈

Operation for continuous Pan/Tilt and Zoom movements. The operation is supported if the PTZNode supports at least one continuous Pan/Tilt or Zoom space. If the space argument is omitted, the default space set by the PTZConfiguration will be used.

Returns a ONVIF::PTZ::Elements::ContinuousMoveResponse object.

       $response = $interface->ContinuousMove( {
          ProfileToken => $some_value, # ReferenceToken
          Velocity =>  { # ONVIF::PTZ::Types::PTZSpeed
            PanTilt => ,
            Zoom => ,
          },
          Timeout =>  $some_value, # duration
        },,
       );

RelativeMove 🦋

The speed argument is optional. If an x/y speed value is given it is up to the device to either use the x value as absolute resoluting speed vector or to map x and y to the component speed. If the speed argument is omitted, the default speed set by the PTZConfiguration will be used.

Returns a ONVIF::PTZ::Elements::RelativeMoveResponse object.

       $response = $interface->RelativeMove( {
          ProfileToken => $some_value, # ReferenceToken
          Translation =>  { # ONVIF::PTZ::Types::PTZVector
            PanTilt => ,
            Zoom => ,
          },
          Speed =>  { # ONVIF::PTZ::Types::PTZSpeed
            PanTilt => ,
            Zoom => ,
          },
        },,
       );

SendAuxiliaryCommand ✨

Operation to send auxiliary commands to the PTZ device mapped by the PTZNode in the selected profile. The operation is supported if the AuxiliarySupported element of the PTZNode is true.

Returns a ONVIF::PTZ::Elements::SendAuxiliaryCommandResponse object.

       $response = $interface->SendAuxiliaryCommand( {
          ProfileToken => $some_value, # ReferenceToken
          AuxiliaryData => $some_value, # AuxiliaryData
        },,
       );

AbsoluteMove 🔥

The speed argument is optional. If an x/y speed value is given it is up to the device to either use the x value as absolute resoluting speed vector or to map x and y to the component speed. If the speed argument is omitted, the default speed set by the PTZConfiguration will be used.

Returns a ONVIF::PTZ::Elements::AbsoluteMoveResponse object.

       $response = $interface->AbsoluteMove( {
          ProfileToken => $some_value, # ReferenceToken
          Position =>  { # ONVIF::PTZ::Types::PTZVector
            PanTilt => ,
            Zoom => ,
          },
          Speed =>  { # ONVIF::PTZ::Types::PTZSpeed
            PanTilt => ,
            Zoom => ,
          },
        },,
       );

Stop 🛑

Operation to stop ongoing pan, tilt and zoom movements of absolute relative and continuous type. If no stop argument for pan, tilt or zoom is set, the device will stop all ongoing pan, tilt and zoom movements.

Returns a ONVIF::PTZ::Elements::StopResponse object.

       $response = $interface->Stop( {
          ProfileToken => $some_value, # ReferenceToken
          PanTilt =>  $some_value, # boolean
          Zoom =>  $some_value, # boolean
        },,
       );

GetPresetTours 🎠

Operation to request PTZ preset tours in the selected media profiles.

Returns a ONVIF::PTZ::Elements::GetPresetToursResponse object.

       $response = $interface->GetPresetTours( {
          ProfileToken => $some_value, # ReferenceToken
        },,
       );

GetPresetTour 🎡

Operation to request a specific PTZ preset tour in the selected media profile.

Returns a ONVIF::PTZ::Elements::GetPresetTourResponse object.

       $response = $interface->GetPresetTour( {
          ProfileToken => $some_value, # ReferenceToken
          PresetTourToken => $some_value, # ReferenceToken
        },,
       );

GetPresetTourOptions 🧚

Operation to request available options to configure PTZ preset tour.

Returns a ONVIF::PTZ::Elements::GetPresetTourOptionsResponse object.

       $response = $interface->GetPresetTourOptions( {
          ProfileToken => $some_value, # ReferenceToken
          PresetTourToken => $some_value, # ReferenceToken
        },,
       );

CreatePresetTour 🌸

Operation to create a preset tour for the selected media profile.

Returns a ONVIF::PTZ::Elements::CreatePresetTourResponse object.

       $response = $interface->CreatePresetTour( {
          ProfileToken => $some_value, # ReferenceToken
        },,
       );

ModifyPresetTour 🌳

Operation to modify a preset tour for the selected media profile.

Returns a ONVIF::PTZ::Elements::ModifyPresetTourResponse object.

this code block is a whole ancestral tree, bestie — copy it exactly 🫶

       $response = $interface->ModifyPresetTour( {
          ProfileToken => $some_value, # ReferenceToken
          PresetTour =>  { # ONVIF::PTZ::Types::PresetTour
            Name => $some_value, # Name
            Status =>  { # ONVIF::PTZ::Types::PTZPresetTourStatus
              State => $some_value, # PTZPresetTourState
              CurrentTourSpot =>  { # ONVIF::PTZ::Types::PTZPresetTourSpot
                PresetDetail =>           { # ONVIF::PTZ::Types::PTZPresetTourPresetDetail
                  # One of the following elements.
                  # No occurrence checks yet, so be sure to pass just one...
                  PresetToken => $some_value, # ReferenceToken
                  Home =>  $some_value, # boolean
                  PTZPosition =>  { # ONVIF::PTZ::Types::PTZVector
                    PanTilt => ,
                    Zoom => ,
                  },
                  TypeExtension =>  { # ONVIF::PTZ::Types::PTZPresetTourTypeExtension
                  },
                },
                Speed =>  { # ONVIF::PTZ::Types::PTZSpeed
                  PanTilt => ,
                  Zoom => ,
                },
                StayTime =>  $some_value, # duration
                Extension =>  { # ONVIF::PTZ::Types::PTZPresetTourSpotExtension
                },
              },
              Extension =>  { # ONVIF::PTZ::Types::PTZPresetTourStatusExtension
              },
            },
            AutoStart =>  $some_value, # boolean
            StartingCondition =>  { # ONVIF::PTZ::Types::PTZPresetTourStartingCondition
              RecurringTime =>  $some_value, # int
              RecurringDuration =>  $some_value, # duration
              Direction => $some_value, # PTZPresetTourDirection
              Extension =>  { # ONVIF::PTZ::Types::PTZPresetTourStartingConditionExtension
              },
            },
            TourSpot =>  { # ONVIF::PTZ::Types::PTZPresetTourSpot
              PresetDetail =>         { # ONVIF::PTZ::Types::PTZPresetTourPresetDetail
                # One of the following elements.
                # No occurrence checks yet, so be sure to pass just one...
                PresetToken => $some_value, # ReferenceToken
                Home =>  $some_value, # boolean
                PTZPosition =>  { # ONVIF::PTZ::Types::PTZVector
                  PanTilt => ,
                  Zoom => ,
                },
                TypeExtension =>  { # ONVIF::PTZ::Types::PTZPresetTourTypeExtension
                },
              },
              Speed =>  { # ONVIF::PTZ::Types::PTZSpeed
                PanTilt => ,
                Zoom => ,
              },
              StayTime =>  $some_value, # duration
              Extension =>  { # ONVIF::PTZ::Types::PTZPresetTourSpotExtension
              },
            },
            Extension =>  { # ONVIF::PTZ::Types::PTZPresetTourExtension
            },
          },
        },,
       );

OperatePresetTour 🎛️

Operation to perform specific operation on the preset tour in selected media profile.

Returns a ONVIF::PTZ::Elements::OperatePresetTourResponse object.

       $response = $interface->OperatePresetTour( {
          ProfileToken => $some_value, # ReferenceToken
          PresetTourToken => $some_value, # ReferenceToken
          Operation => $some_value, # PTZPresetTourOperation
        },,
       );

RemovePresetTour 🗑️

Operation to delete a specific preset tour from the media profile.

Returns a ONVIF::PTZ::Elements::RemovePresetTourResponse object.

       $response = $interface->RemovePresetTour( {
          ProfileToken => $some_value, # ReferenceToken
          PresetTourToken => $some_value, # ReferenceToken
        },,
       );

GetCompatibleConfigurations 👑

A device providing more than one PTZConfiguration or more than one VideoSourceConfiguration or which has any other resource interdependency between PTZConfiguration entities and other resources listable in a media profile should implement this operation. PTZConfiguration entities returned by this operation shall not fail on adding them to the referenced media profile.

Returns a ONVIF::PTZ::Elements::GetCompatibleConfigurationsResponse object.

       $response = $interface->GetCompatibleConfigurations( {
          ProfileToken => $some_value, # ReferenceToken
        },,
       );

🫶 AUTHOR 🫶

Generated by SOAP::WSDL on Mon Jun 30 13:37:28 2014.

---

byeee bestie 💖 this little icon is ONVIF::...PTZPort(3), powered by perl v5.42.3, dated 1980-01-01 🎀✨