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 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.
SEE ALSO
Vector::Object3D::Examples, Vector::Object3D::Point, Vector::Object3D::Polygon.
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!