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.

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!

cpanm Vector::Object3D

perl -MCPAN -e shell
install Vector::Object3D