NAME

Rinchi::CIGIPP::SymbolCircleDefinition - Perl extension for the Common Image Generator Interface - Symbol Circle Definition data packet. data packet. =head1 SYNOPSIS

use Rinchi::CIGIPP::SymbolCircleDefinition;
my $sym_circ = Rinchi::CIGIPP::SymbolCircleDefinition->new();

$packet_type = $sym_circ->packet_type();
$packet_size = $sym_circ->packet_size(144);
$symbol_ident = $sym_circ->symbol_ident(64120);
$drawing_style = $sym_circ->drawing_style(Rinchi::CIGIPP->DrawingStyleLine);
$stipple_pattern = $sym_circ->stipple_pattern(0x1F1F);
$line_width = $sym_circ->line_width(1.125);
$stipple_pattern_length = $sym_circ->stipple_pattern_length(21.99115);

my $circle0 = Rinchi::CIGIPP::SymbolCircle->new();
$sym_circ->circle(0, $circle0);
$circle0->center_u(0.0);
$circle0->center_v(0.0);
$circle0->radius(7.0);
$circle0->inner_radius(4.0);
$circle0->start_angle(45);
$circle0->end_angle(135);

my $circle1 = Rinchi::CIGIPP::SymbolCircle->new();
$sym_circ->circle(1, $circle1);
$circle1->center_u(0.0);
$circle1->center_v(0.0);
$circle1->radius(10.0);
$circle1->inner_radius(7.0);
$circle1->start_angle(135);
$circle1->end_angle(45);

DESCRIPTION

The Symbol Circle Definition packet is used to create a single circle or arc. This packet can also be used to create a composite symbol composed of up to 9 circles and/or arcs. Note that this section uses the term "circle" to refer to both circles and arcs unless otherwise indicated.

Each circle symbol is identified by a Symbol ID value that is unique from all other symbols (including text and line symbols). Every symbol must be created independently with its own unique Symbol ID, even if two or more symbols are visually identical.

Once a Symbol Circle Definition packet describing a circle symbol is sent to the IG, that symbol's type may not be changed. If a Symbol Text Definition, Symbol Line Definition, or Symbol Clone packet is received specifying the same Symbol ID but a different type, then the existing circle symbol will be destroyed along with any children and a new symbol will be created using the new definition packet.

The center of each circle is located at a point (u, v) on the symbol's 2D coordinate system (see CIGI ICD Section 3.4.5.2) as defined by the Center U and Center V attributes. The radius of the circle is specified in scaled symbol surface units by the Radius attribute. Note that if the symbol surface's 2D coordinate system is defined such that horizontal units are not the same length as vertical units, then a circle will appear as an ellipse and an arc will appear as an elliptical arc.

The Start Angle and End Angle attributes define the endpoints of the curve. These angles are measured counter-clockwise from the symbol's +U axis. If these two values are equal, then the symbol defines a full circle. If these two values are not equal, then the symbol defines an arc. For circles, it is recommended that values of 0.0 be used for consistency and to avoid floating-point errors.

A circle can either be drawn as a curved line along the circumference or be filled, depending upon the value of the Drawing Style attribute. If Drawing Style is set to Line (0), then a curve is drawn from the start angle to the end angle with the specified Radius. The Inner Radius attribute is ignored.

A curved line's pen attributes are defined by the Line Width, Stipple Pattern, and Stipple Pattern Length attributes.

Line Width specifies the thickness of the line in scaled symbol surface units. Note that if the surface's horizontal and vertical units are not equal in size, then curved lines will not appear to be uniform in thickness.

The Stipple Pattern attribute defines a bit mask to be applied to the line: if a bit is set (1) then the section of the curve corresponding to that bit will be drawn; if the bit is cleared (0) then the corresponding section will not be drawn. If the value of this attribute is 0xFFFF, then the line is solid.

The length of each section is equal to 1/16 of the length specified by the Stipple Pattern Length attribute. This attribute defines the length of the stipple pattern in terms of scaled symbol surface units. If the curved line is longer than the stipple pattern length, then the pattern is repeated.

Note that the end-cap style of a curved line is implementation-dependent and may optionally be controlled with a Component Control packet.

If Drawing Style is set to Fill (1), then the circle is drawn as a filled region defined by the Start Angle, End Angle, Radius, and Inner Radius attributes. Note that if the Inner Radius attribute is 0.0, then the circle is completely filled.

The Line Width, Stipple Pattern, and Stipple Pattern Length attributes are ignored for filled circle symbols.

When the IG creates a new symbol, that symbol is always hidden by default. The symbol is not made visible until the Host sends a Symbol Control packet or Short Symbol Control packet with the Symbol State attribute set to Visible (1).

EXPORT

None by default.

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

new $sym_circ = Rinchi::CIGIPP::SymbolCircleDefinition->new()

Constructor for Rinchi::SymbolCircleDefinition.

sub packet_type()

$value = $sym_circ->packet_type();

Data Packet Identifier.

This attribute identifies this data packet as the Symbol Circle Definition packet. The value of this attribute must be 31.

sub packet_size([$newValue])

$value = $sym_circ->packet_size($newValue);

Data Packet Size.

This attribute indicates the number of bytes in this data packet. The value of this attribute must be an even multiple of 8 ranging from 16 to 232.

sub symbol_ident([$newValue])

$value = $sym_circ->symbol_ident($newValue);

Symbol ID.

This attribute specifies the identifier of the symbol that is being defined.

This identifier must be unique among all existing symbols. If a symbol with the specified identifier already exists, then that symbol and any children will be destroyed and a new symbol created.

sub drawing_style([$newValue])

$value = $sym_circ->drawing_style($newValue);

Drawing Style.

This attribute specifies whether the circles and arcs defined in this packet are defined as curved lines or filled volumes.

DrawingStyleLine   0
DrawingStyleFill   1

sub stipple_pattern([$newValue])

$value = $sym_circ->stipple_pattern($newValue);

Stipple Pattern.

This attribute specifies the dash pattern used when drawing the curved line of a circle or arc.

Each curved line is divided into sections that are 1/32 of the length specified by the Stipple Pattern Length attribute. The stipple pattern is a bit mask that is used when drawing the sections. If a bit is set (1) then section corresponding to that bit will be drawn; if the bit is cleared (0) then the corresponding section will not be drawn.

If the value of this attribute is 0xFFFF, then the line will be solid.

If the line is longer than the stipple pattern length, the pattern is repeated.

This value is ignored if the Drawing Style attribute is set to Fill (1).

sub line_width([$newValue])

$value = $sym_circ->line_width($newValue);

Line Width.

This attribute specifies the thickness of the line used to draw the circles and arcs. This thickness is measured in symbol surface units and will be scaled if the symbol is scaled (see CIGI ICD Section 3.4.5.2).

Note that if the symbol surface's horizontal and vertical units are not the same size, then horizontal, diagonal, and vertical lines will not appear to be the same thickness.

This attribute is ignored if the Drawing Style attribute is set to Fill (1).

sub stipple_pattern_length([$newValue])

$value = $sym_circ->stipple_pattern_length($newValue);

Stipple Pattern Length.

This attribute specifies the length of one complete repetition of the stipple pattern. This length is measured in symbol surface units and will be scaled if the symbol is scaled (see CIGI ICD Section 3.4.5.2).

If a line is longer than the stipple pattern length, then the pattern is repeated along that line.

This attribute is ignored if the Drawing Style attribute is set to Fill (1).

sub circle($index,[$newCircle])

$circle = $sym_circ->circle($index,$newCircle);

Circle Array.

sub pack()

$value = $sym_circ->pack();

Returns the packed data packet.

sub unpack()

$value = $sym_circ->unpack();

Unpacks the packed data packet.

sub byte_swap()

$obj_name->byte_swap();

Byte swaps the packed data packet.

new $circle = Rinchi::CIGIPP::SymbolCircle->new()

Constructor for Rinchi::SymbolCircle.

sub center_u([$newValue])

$value = $circle->center_u($newValue);

Center U.

This attribute specifies the u position of the circle's center with respect to the symbol's local coordinate system. This position is measured in scaled symbol surface units (see CIGI ICD Section 3.4.5.2).

sub center_v([$newValue])

$value = $circle->center_v($newValue);

Center V.

This attribute specifies the v position of the circle's center with respect to the symbol's local coordinate system. This position is measured in scaled symbol surface units (see CIGI ICD Section 3.4.5.2).

sub radius([$newValue])

$value = $circle->radius($newValue);

Radius.

For a filled circle or arc, this attribute specifies the distance from the center of the circle to its outer circumference.

For a line circle or arc, this attribute specifies the distance from the center of the circle to the center ofthe curve.

This value is measured in scaled symbol surface units(see CIGI ICD Section 3.4.5.2).

sub inner_radius([$newValue])

$value = $circle->inner_radius($newValue);

Inner Radius.

For a filled circle or arc, this attribute specifies the distance from the center of the circle to its inner boundary in scaled symbol surface units (see CIGI ICD Section 3.4.5.2). The fill extends from the Inner Radius to the Radius.

For line circles and arcs, this attribute is ignored.

sub start_angle([$newValue])

$value = $circle->start_angle($newValue);

Start Angle.

This attribute specifies the starting angle of the arc and is measured counter-clockwise from the +U axis.

If Start Angle is greater than End Angle, then the arc will cross the +U axis.

sub end_angle([$newValue])

$value = $circle->end_angle($newValue);

End Angle.

This attribute specifies the ending angle of the arc and is measured counter-clockwise from the +U axis.

If Start Angle is greater than End Angle, then the arc will cross the +U axis.

sub pack()

$value = $circle->pack();

Returns the packed data packet.

sub unpack()

$value = $circle->unpack();

Unpacks the packed data packet.

sub byte_swap()

$circle->byte_swap();

Byte swaps the packed circle data.

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.