NAME

Vector::Object3D::Point - Three-dimensional point object definitions and operations

SYNOPSIS

  use Vector::Object3D::Point;

  use Readonly;
  Readonly my $pi => 3.14159;

  # Create an instance of a class:
  my $point = Vector::Object3D::Point->new(x => 3, y => -2, z => 1);
  my $point = Vector::Object3D::Point->new(coord => [-2, 2, 1]);

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

  # Get current X coordinate value:
  my $x = $point->get_x;
  # Get current Y coordinate value:
  my $y = $point->get_y;
  # Get current Z coordinate value:
  my $z = $point->get_z;

  # Get current coordinate values on two-dimensional plane:
  my ($x, $y) = $point->get_xy;
  # Get current coordinate values in three-dimensional space:
  my ($x, $y, $z) = $point->get_xyz;

  # Get current coordinates as a matrix object:
  my $pointMatrix = $point->get_matrix;

  # Set new X coordinate value:
  $point->set_x($x);
  # Set new Y coordinate value:
  $point->set_y($y);
  # Set new Z coordinate value:
  $point->set_z($z);

  # Set new precision value (which is used while printing out data and comparing
  # the point object with others):
  my $precision = 2;
  $point->set(parameter => 'precision', value => $precision);

  # Get currently used precision value (undef indicates maximum possible precision
  # which is designated to the Perl core):
  my $precision = $point->get(parameter => 'precision');

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

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

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

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

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

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

  # Compare two point objects:
  my $are_the_same = $point1 == $point2;

DESCRIPTION

Vector::Object3D::Point describes point object in a three-dimensional space, providing basic operations to manipulate, transform and cast its coordinates.

METHODS

new

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

  my $point = Vector::Object3D::Point->new(x => 3, y => -2, z => 1);
  my $point = Vector::Object3D::Point->new(coord => [-2, 2, 1]);

There are two individual means of Vector::Object3D::Point object construction, provided a hash of individual components or a list of coordinates. When present, coord constructor parameter takes precedence over individual coordinates in case both values are provided at the same time.

copy

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

  my $copy = $point->copy;

get_x

Get current X coordinate value:

  my $x = $point->get_x;

get_y

Get current Y coordinate value:

  my $y = $point->get_y;

get_z

Get current Z coordinate value:

  my $z = $point->get_z;

get_xy

Get current coordinate values on two-dimensional plane:

  my ($x, $y) = $point->get_xy;

Note these values are not casted, they are the actual coordinate values that were used to initialize an object. See description of the cast method for details about point projection onto a two-dimensional plane.

get_xyz

Get current coordinate values in three-dimensional space:

  my ($x, $y, $z) = $point->get_xyz;

get_matrix

Get current coordinates as a matrix object:

  my $pointMatrix = $point->get_matrix;

set_x

Set new X coordinate value:

  $point->set_x($x);

set_y

Set new Y coordinate value:

  $point->set_y($y);

set_z

Set new Z coordinate value:

  $point->set_z($z);

set

Set new precision value (which is used while comparing point objects with each other):

  my $precision = 2;
  $point->set(parameter => 'precision', value => $precision);

get

Get currently used precision value (undef indicates maximum possible precision which is designated to the Perl core):

  my $precision = $point->get(parameter => 'precision');

print

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

  $point->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.

rotate

Rotate point by a given angle around three rotation axis:

  my $point_rotated = $point->rotate(
    rotate_xy => 30 * ($pi / 180),
    rotate_yz => -30 * ($pi / 180),
    rotate_xz => 45 * ($pi / 180),
  );

scale

Enlarge, shrink or stretch point by a scale factor:

  my $point_scaled = $point->scale(
    scale_x => 2,
    scale_y => 2,
    scale_z => 3,
  );

Non-uniform scaling (anisotropic scaling), obtained when at least one of the scaling factors is different from the others, is allowed.

translate

Move point a constant distance in a specified direction:

  my $point_translated = $point->translate(
    shift_x => -2,
    shift_y => 1,
    shift_z => 3,
  );

cast

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

  my $point2D = $point->cast(type => 'parallel');

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

  my $point2D = $point->cast(type => 'perspective', distance => 5);

compare (==)

Compare two point objects:

  my $are_the_same = $point1 == $point2;

Overloaded comparison operator evaluates to true whenever two point objects are identical (all their coordinates are exactly the same).

negative compare (!=)

Compare two point objects:

  my $are_not_the_same = $point1 != $point2;

Overloaded negative comparison operator evaluates to true whenever two point objects differ (any of their coordinates do not match).

BUGS

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

EXPORT

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

SEE ALSO

Vector::Object3D, Vector::Object3D::Line, Vector::Object3D::Parameters, Vector::Object3D::Point::Cast, Vector::Object3D::Point::Transform, 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