NAME

Rinchi::CIGIPP::HAT_HOTRequest - Perl extension for the Common Image Generator Interface - HAT/HOTRequest data packet. data packet. =head1 SYNOPSIS

use Rinchi::CIGIPP::HAT_HOTRequest;
my $hgt_rqst = Rinchi::CIGIPP::HAT_HOTRequest->new();

$packet_type = $hgt_rqst->packet_type();
$packet_size = $hgt_rqst->packet_size();
$request_ident = $hgt_rqst->request_ident(13384);
$coordinate_system = $hgt_rqst->coordinate_system(Rinchi::CIGIPP->GeodeticCS);
$request_type = $hgt_rqst->request_type(Rinchi::CIGIPP->HeightOfTerrain);
$update_period = $hgt_rqst->update_period(156);
$entity_ident = $hgt_rqst->entity_ident(48093);
$latitude = $hgt_rqst->latitude(69.592);
$x_offset = $hgt_rqst->x_offset(17.607);
$longitude = $hgt_rqst->longitude(68.523);
$y_offset = $hgt_rqst->y_offset(20.113);
$altitude = $hgt_rqst->altitude(43.044);
$z_offset = $hgt_rqst->z_offset(23.044);

DESCRIPTION

The HAT/HOT Request packet is used by the Host to request the Height Above Terrain (HAT) of a specified point and/or the Height Of Terrain (HOT) below a specified test point. The test point may be defined with respect to either the Geodetic coordinate system or an entity's body coordinate system.

Each request is identified by the HAT/HOT ID attribute. When the IG responds to the request, it will set the HAT/HOT ID attribute of the response packet to match that in the request.

The Update Period attribute specifies the number of frames between periodic responses. This allows the Host to send just one HAT/HOT Request packet but receive continuous responses if the test point will not move with respect to the specified coordinate system. If Update Period is set to zero, the request will be treated as a one- shot request and the IG will return a single response. The Host should manipulate the value of HAT/HOT ID so that an ID is not reused before the IG has sufficient time to process and respond to the request. If Update Period is set to some value n greater than zero, the IG will return a request every nth frame until the Entity is destroyed or until the Update Period attribute set to zero.

If the Request Type attribute is set to HAT (0) or HOT (1), the IG will respond with a HAT/HOT Response packet (Section 4.2.2) containing the requested datum. If the attribute is set to Extended HAT/HOT (2), the IG will respond with a HAT/HOT Extended Response packet (Section 4.2.3) containing both data, along with the surface material code and normal vector.

The IG can only return valid HAT and/or HOT data if the test point is located within the bounds of the current database. If the HAT or HOT cannot be calculated, the Valid attribute of the response packet will be set to Invalid (0). Besides the range of the HAT/HOT ID attribute, there is no restriction on the number of HAT and/or HOT requests that can be sent in a single frame; however, the response time of the IG might be degraded as the number of requests increases.

EXPORT

None by default.

#==============================================================================

new $hgt_rqst = Rinchi::CIGIPP::HAT_HOTRequest->new()

Constructor for Rinchi::HAT_HOTRequest.

sub packet_type()

$value = $hgt_rqst->packet_type();

Data Packet Identifier.

This attribute identifies this data packet as the HAT/HOT Request packet. The value of this attribute must be 24.

sub packet_size()

$value = $hgt_rqst->packet_size();

Data Packet Size.

This attribute indicates the number of bytes in this data packet. The value of this attribute must be 32.

sub request_ident([$newValue])

$value = $hgt_rqst->request_ident($newValue);

HAT/HOT ID.

This attribute identifies the HAT/HOT request. When the IG returns a HAT/HOT Response or HAT/HOT Extended Response packet in response to this request, the HAT/HOT ID attribute of that packet will contain this value to correlate the response with this request.

sub coordinate_system([$newValue])

$value = $hgt_rqst->coordinate_system($newValue);

Coordinate System.

This attribute specifies the coordinate system within which the test point is defined. If this attribute is set to Geodetic (0), the test point is defined as a Latitude, Longitude, and Altitude. If this attribute is set to Entity (1), the test point is defined as X, Y, and Z offsets from the reference point of the entity specified by Entity ID.

GeodeticCS   0
EntityCS     1

sub request_type([$newValue])

$value = $hgt_rqst->request_type($newValue);

Request Type.

This attribute determines what type of response packet the IG should return for this request.

If this attribute is set to HAT (0), the IG will respond with a HAT/HOT Response packet containing the Height Above Terrain. If this attribute is set to HOT (1), the IG will respond with a HAT/HOT Response packet containing the Height Of Terrain. If this attribute is set to Extended (2), the IG will respond with a HAT/HOT Extended Response packet, which contains both the Height Above Terrain and the Height Of Terrain.

HeightAboveTerrain   0
HeightOfTerrain      1
Extended             2

sub update_period([$newValue])

$value = $hgt_rqst->update_period($newValue);

Update Period.

This attribute specifies the interval between successive responses to this request. A value of zero (0) indicates that the IG should return a single response. A value of n > 0 indicates that the IG should return a response every nth frame.

sub entity_ident([$newValue])

$value = $hgt_rqst->entity_ident($newValue);

Entity ID.

This attribute specifies the entity relative to which the test point is defined. This attribute is ignored if Coordinate System is set to Geodetic (0).

sub latitude([$newValue])

$value = $hgt_rqst->latitude($newValue);

Latitude.

This attribute specifies the latitude from which the HAT/HOT request is being made.

sub x_offset([$newValue])

$value = $hgt_rqst->x_offset($newValue);

X Offset.

This attribute specifies the latitude from which the HAT/HOT request is being made. This value is given relative to the entity's reference point.

sub longitude([$newValue])

$value = $hgt_rqst->longitude($newValue);

Longitude.

This attribute specifies the longitude from which the HAT/HOT request is being made.

sub y_offset([$newValue])

$value = $hgt_rqst->y_offset($newValue);

Y Offset.

This attribute specifies the longitude from which the HAT/HOT request is being made. This value is given relative to the entity's reference point.

sub altitude([$newValue])

$value = $hgt_rqst->altitude($newValue);

Altitude.

This attribute specifies the altitude from which the HAT/HOT request is being made. This attribute is ignored if Request Type is set to HOT (1).

sub z_offset([$newValue])

$value = $hgt_rqst->z_offset($newValue);

Z Offset.

This attribute specifies the altitude from which the HAT/HOT request is being made. This value is given relative to the entity's reference point.

sub pack()

$value = $hgt_rqst->pack();

Returns the packed data packet.

sub unpack()

$value = $hgt_rqst->unpack();

Unpacks the packed data packet.

sub byte_swap()

$obj_name->byte_swap();

Byte swaps the packed data packet.

SEE ALSO

Refer the the Common Image Generator Interface ICD which may be had at this URL: http://cigi.sourceforge.net/specification.php

AUTHOR

Brian M. Ames, <bmames@apk.net>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Brian M. Ames

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6 or, at your option, any later version of Perl 5 you may have available.