# NAME

Vector::Object3D - Three-dimensional object type definitions and operations

## SYNOPSIS

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

# Create an instance of a class:
my \$object = Vector::Object3D->new(polygons => [\$polygon1, \$polygon2, \$polygon3]);

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

# Get number of polygons that make up an object:
my \$num_faces = \$object->num_faces;

# Get index of last polygon:
my \$last_face_index = \$object->last_face_index;

# Get first polygon:
my \$polygon1 = \$object->get_polygon(index => 0);

# Get last polygon:
my \$polygonn = \$object->get_polygon(index => \$last_face_index);

# Get all polygons:
my @polygons = \$object->get_polygons;
my @polygons = \$object->get_polygons(mode => 'all');

# Get visible polygons only:
my \$observer = Vector::Object3D::Point->new(x => 0, y => 0, z => 5);
my @polygons = \$object->get_polygons(mode => 'visible', observer => \$observer);

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

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

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

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

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

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

# Compare two objects:
my \$are_the_same = \$object1 == \$object2;``````

# DESCRIPTION

`Vector::Object3D` provides an abstraction layer for describing objects made of polygons in a three-dimensional space. It has been primarily designed to help with rapid prototyping of simple 3D vector graphic transformations, and is most likely unsuitable for realtime calculations that usually demand high computational CPU power.

This version of `Vector::Object3D` package has been entirely rewritten using Moose object system and is significantly slower than its predecessor initially developed using classic Perl's object system. Main reasoning for switching over to Moose was my desire to comply with the concepts of modern Perl programming.

# METHODS

## new

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

``  my \$object = Vector::Object3D->new(polygons => [\$polygon1, \$polygon2, \$polygon3]);``

`Vector::Object3D` require provision of at least one polygon in order to successfully construct an object instance, there is no exception from this rule.

## copy

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

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

## num_faces

Get number of polygons that make up an object:

``  my \$num_faces = \$object->num_faces;``

## last_face_index

Get index of last polygon:

``  my \$last_face_index = \$object->last_face_index;``

## get_polygon

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

``  my \$polygonn = \$object->get_polygon(index => \$n);``

## get_polygons

Get all polygons:

``  my @polygons = \$object->get_polygons;``

The same effect is achieved by explicitly setting mode of getting polygons to `all`:

``  my @polygons = \$object->get_polygons(mode => 'all');``

Get visible polygons only by setting mode of getting polygons to `visible` and specifying optional observer:

``````  my \$observer = Vector::Object3D::Point->new(x => 0, y => 0, z => 5);
my @polygons = \$object->get_polygons(mode => 'visible', observer => \$observer);``````

## print

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

``  \$object->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 object a constant distance in a specified direction:

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

Enlarge, shrink or stretch object by a scale factor:

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

Rotate object by a given angle around three rotation axis:

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

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

``  my \$object2D = \$object->cast(type => 'parallel');``

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

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

## compare (==)

Compare two objects:

``  my \$are_the_same = \$object1 == \$object2;``

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

# BUGS

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

# EXPORT

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

# AUTHOR

Pawel Krol, <pawelkrol@cpan.org>.

# VERSION

Version 0.01 (2012-12-24)

# COPYRIGHT AND LICENSE

Copyright (C) 2012 by Pawel Krol.

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

PLEASE NOTE THAT IT COMES WITHOUT A WARRANTY OF ANY KIND!