# 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.

# 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!