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