The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

# NAME

Vector::Object3D::Polygon - Three-dimensional polygon object definitions and operations

## SYNOPSIS

``````  use Vector::Object3D::Polygon;

# Create polygon vertices:
my \$vertex1 = Vector::Object3D::Point->new(x => -1, y => 2, z => 3);
my \$vertex2 = Vector::Object3D::Point->new(x => 3, y => -1, z => -2);
my \$vertex3 = Vector::Object3D::Point->new(x => 2, y => 1, z => 1);

# Create an instance of a class:
my \$polygon = Vector::Object3D::Polygon->new(vertices => [\$vertex1, \$vertex2, \$vertex3]);

# Create a new object as a copy of an existing object:
my \$copy = \$polygon->copy;

# Get number of polygon vertices:
my \$num_vertices = \$polygon->num_vertices;

# Get index of last polygon vertex:
my \$last_vertex_index = \$polygon->last_vertex_index;

# Get first vertex point:
my \$vertex1 = \$polygon->get_vertex(index => 0);

# Get last vertex point:
my \$vertexn = \$polygon->get_vertex(index => \$last_vertex_index);

# Get all vertex points:
my @vertices = \$polygon->get_vertices;

# Get polygon data as a set of line objects connecting vertices in construction order:
my @lines = \$polygon->get_lines;

# Print out formatted polygon data:
\$polygon->print(fh => \$fh, precision => \$precision);

# Move polygon a constant distance in a specified direction:
my \$polygon_translated = \$polygon->translate(
shift_x => -2,
shift_y => 1,
shift_z => 3,
);

# Enlarge, shrink or stretch polygon by a scale factor:
my \$polygon_scaled = \$polygon->scale(
scale_x => 2,
scale_y => 2,
scale_z => 3,
);

# Rotate polygon by a given angle around three rotation axis:
my \$polygon_rotated = \$polygon->rotate(
rotate_xy => 30 * (\$pi / 180),
rotate_yz => -30 * (\$pi / 180),
rotate_xz => 45 * (\$pi / 180),
);

# Project polygon onto a two-dimensional plane using an orthographic projection:
my \$polygon2D = \$polygon->cast(type => 'parallel');

# Project polygon onto a two-dimensional plane using a perspective projection:
my \$distance = 5;
my \$polygon2D = \$polygon->cast(type => 'perspective', distance => \$distance);

# Check whether polygon's plane is visible to the observer:
my \$observer = Vector::Object3D::Point->new(x => 0, y => 0, z => \$distance);
my \$is_plane_visible = \$polygon->is_plane_visible(observer => \$observer);

# Get point coordinates located exactly in the middle of a polygon's plane:
my \$middle_point = \$polygon->get_middle_point;

# Get vector normal to a polygon's plane:
my \$normal_vector = \$polygon->get_normal_vector;
my \$normal_vector = \$polygon->get_orthogonal_vector;

# Compare two polygon objects:
my \$are_the_same = \$polygon1 == \$polygon2;``````

# DESCRIPTION

`Vector::Object3D::Polygon` provides an abstraction layer for describing polygon object in a three-dimensional space by composing it from any number of `Vector::Object3D::Point` objects (referred onwards as vertices).

# METHODS

## new

Create an instance of a `Vector::Object3D::Polygon` class:

``````  my \$vertex1 = Vector::Object3D::Point->new(x => -1, y => 2, z => 3);
my \$vertex2 = Vector::Object3D::Point->new(x => 3, y => -1, z => -2);
my \$vertex3 = Vector::Object3D::Point->new(x => 2, y => 1, z => 1);

my \$polygon = Vector::Object3D::Polygon->new(vertices => [\$vertex1, \$vertex2, \$vertex3]);``````

`Vector::Object3D::Polygon` requires provision of at least three endpoints in order to successfully construct an object instance, there is no exception from this rule. Furthermore, it is assumed that all vertex points are located on the same plane. This rule is neither enforced nor validated, however this assumption impacts all related calculations, i.a. normal vector computation.

## copy

Create a new `Vector::Object3D::Polygon` object as a copy of an existing object:

``  my \$copy = \$polygon->copy;``

## num_vertices

Get number of polygon vertices:

``  my \$num_vertices = \$polygon->num_vertices;``

## last_vertex_index

Get index of last polygon vertex:

``  my \$last_vertex_index = \$polygon->last_vertex_index;``

## get_vertex

Get `\$n`-th vertex point, where `\$n` is expected to be any number between first and last vertex index:

``  my \$vertexn = \$polygon->get_vertex(index => \$n);``

## get_vertices

Get all vertex points:

``  my @vertices = \$polygon->get_vertices;``

## get_lines

Get polygon data as a set of line objects connecting vertices in construction order:

``  my @lines = \$polygon->get_lines;``

## print

Print out text-formatted polygon data (which might be, for instance, useful for debugging purposes):

``  \$polygon->print(fh => \$fh, precision => \$precision);``

`fh` defaults to the standard output. `precision` is intended for internal use by string format specifier that outputs individual point coordinates as decimal floating points, and defaults to 2 (unless adjusted individually for each vertex).

Move polygon a constant distance in a specified direction:

``````  my \$polygon_translated = \$polygon->translate(
shift_x => -2,
shift_y => 1,
shift_z => 3,
);``````

Enlarge, shrink or stretch polygon by a scale factor:

``````  my \$polygon_scaled = \$polygon->scale(
scale_x => 2,
scale_y => 2,
scale_z => 3,
);``````

Rotate polygon by a given angle around three rotation axis:

``````  my \$polygon_rotated = \$polygon->rotate(
rotate_xy => 30 * (\$pi / 180),
rotate_yz => -30 * (\$pi / 180),
rotate_xz => 45 * (\$pi / 180),
);``````

Project polygon onto a two-dimensional plane using an orthographic projection:

``  my \$polygon2D = \$polygon->cast(type => 'parallel');``

Project polygon onto a two-dimensional plane using a perspective projection:

``````  my \$distance = 5;
my \$polygon2D = \$polygon->cast(type => 'perspective', distance => \$distance);``````

Check whether polygon's plane is visible to the observer located at the given point:

``````  my \$observer = Vector::Object3D::Point->new(x => 0, y => 0, z => 5);
my \$is_plane_visible = \$polygon->is_plane_visible(observer => \$observer);``````

## get_middle_point

Get point coordinates located exactly in the middle of a polygon's plane (remember assumption that all vertex points are located on the same plane):

``  my \$middle_point = \$polygon->get_middle_point;``

## get_normal_vector

Get vector normal to a polygon's plane (remember assumption that all vertex points are located on the same plane):

``  my \$normal_vector = \$polygon->get_normal_vector;``

Result of calling this method is a Math::VectorReal object instance. You may access individual x, y, z elements of the vector as a list of values using `array` method:

``  my (\$x, \$y, \$z) = \$normal_vector->array;``

## get_orthogonal_vector

Get vector normal to a polygon's plane:

``  my \$normal_vector = \$polygon->get_orthogonal_vector;``

This is an alias for `get_normal_vector`.

## compare (==)

Compare two polygon objects:

``  my \$are_the_same = \$polygon1 == \$polygon2;``

Overloaded comparison operator evaluates to true whenever two polygon objects are identical (all their endpoints are located at exactly same positions, note that vertex order matters as well).

# BUGS

There are no known bugs at the moment. Please report any bugs or feature requests.

# EXPORT

`Vector::Object3D::Polygon` exports nothing neither by default nor explicitly.

# AUTHOR

Pawel Krol, <pawelkrol@cpan.org>.

# VERSION

Version 0.01 (2012-12-24)