NAME

Vector::Object3D::Matrix - Matrix definitions and basic operations

SYNOPSIS

  use Vector::Object3D::Matrix;

  # Create an instance of a class:
  my $matrix = Vector::Object3D::Matrix->new(rows => [[-2, 2], [2, 1], [-1, -1]]);
  my $matrix = Vector::Object3D::Matrix->new(cols => [[-2, 2, -1], [2, 1, -1]]);

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

  # Get number of columns/rows from a matrix object:
  my $num_cols = $matrix->num_cols;
  my $num_rows = $matrix->num_rows;

  # Fetch matrix data as an array of column/row values:
  my $cols = $matrix->get_cols;
  my $rows = $matrix->get_rows;

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

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

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

  # Produce a matrix that is a result of scalar multiplication:
  my $matrix2 = 2 * $matrix1;

  # Produce a matrix that is a result of matrix multiplication:
  my $matrix3 = $matrix1 * $matrix2;

  # Add two matrices:
  my $matrix4 = $matrix1 + $matrix2;

  # Subtract one matrix from another:
  my $matrix5 = $matrix1 - $matrix2;

  # Compare two matrix objects:
  my $are_the_same = $matrix1 == $matrix2;

  # Append another column to a matrix object:
  $matrix->add(col => [2, -1, 3]);

  # Add another row to a matrix object:
  $matrix->add(row => [0, 1, -2]);

DESCRIPTION

Although Vector::Object3D::Matrix was originally meant as an auxiliary package supporting all the necessary calculations performed in the 3D space that are handled by Vector::Object3D module only, it may still be used as a standalone module providing support for basic matrix operations (please note however that there are plenty more advanced modules available on CPAN already that serve exactly same purpose).

Matrix definitions and basic operations like multiplication, addition and subtraction are implemented. It is also feasible to print out text-based contents of a matrix object to the standard output. Auxiliary static methods allow setting up 2D/3D transformation matrices.

METHODS

new

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

  my $rows = [[-2, 2], [2, 1], [-1, -1]];
  my $matrix = Vector::Object3D::Matrix->new(rows => $rows);

  my $cols = [[-2, 2, -1], [2, 1, -1]];
  my $matrix = Vector::Object3D::Matrix->new(cols => $cols);

There are two individual means of Vector::Object3D::Matrix object construction, provided list of either rows or columns of numeric values. Although data is internally always stored as rows, cols constructor parameter takes precedence over rows in case both values are provided at the same time.

copy

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

  my $copy = $matrix->copy;

num_cols

Get number of columns from a matrix object:

  my $num_cols = $matrix->num_cols;

num_rows

Get number of rows from a matrix object:

  my $num_rows = $matrix->num_rows;

get_cols

Fetch matrix data as an array of column values:

  my $cols = $matrix->get_cols;

get_rows

Fetch matrix data as an array of row values:

  my $rows = $matrix->get_rows;

add

Append another column to a matrix instance:

  $matrix->add(col => [2, -1, 3]);

Add another row to an existing matrix object:

  $matrix->add(row => [0, 1, -2]);

Both add scenarios (adding a new column and adding a new row) will skip adding values that would exceed the other size of a matrix and fill in the missing ones with zeroes.

set

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

  my $precision = 2;
  $matrix->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 = $matrix->get(parameter => 'precision');

print

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

  $matrix->print(fh => $fh, precision => $precision);

fh defaults to the standard output. precision is intended for internal use by string format specifier that outputs individual matrix values as decimal floating points, and defaults to 2.

get_rotation_matrix

Construct rotation matrix on a 2D plane:

  my $rotateMatrix2D = Vector::Object3D::Matrix->get_rotation_matrix(
    rotate_xy => (30 * $pi / 180),
  );

Construct rotation matrix in a 3D space:

  my $rotateMatrix3D = Vector::Object3D::Matrix->get_rotation_matrix(
    rotate_xy => (30 * $pi / 180),
    rotate_yz => -30 * ($pi / 180),
    rotate_xz => 45 * ($pi / 180),
  );

get_scaling_matrix

Construct scaling matrix on a 2D plane:

  my $scaleMatrix2D = Vector::Object3D::Matrix->get_scaling_matrix(
    scale_x => 2,
    scale_y => 2,
  );

Construct scaling matrix in a 3D space:

  my $scaleMatrix3D = Vector::Object3D::Matrix->get_scaling_matrix(
    scale_x => 2,
    scale_y => 2,
    scale_z => 3,
  );

get_translation_matrix

Construct translation matrix on a 2D plane:

  my $translateMatrix2D = Vector::Object3D::Matrix->get_translation_matrix(
    shift_x => -2,
    shift_y => 1,
  );

Construct translation matrix in a 3D space:

  my $translateMatrix3D = Vector::Object3D::Matrix->get_translation_matrix(
    shift_x => -2,
    shift_y => 1,
    shift_z => 3,
  );

OPERATORS

multiply (*)

Produce a matrix that is a result of scalar multiplication:

  my $matrix2 = 2 * $matrix1;

Produce a matrix that is a result of matrix multiplication:

  my $matrix3 = $matrix1 * $matrix2;

add (+)

Add two matrices:

  my $matrix3 = $matrix1 + $matrix2;

A matrix may be added to another one if they both share exactly same dimensions.

subtract (-)

Subtract one matrix from another:

  my $matrix3 = $matrix1 - $matrix2;

A matrix may be subtracted from another one if they both share exactly same dimensions.

compare (==)

Compare two matrix objects:

  my $are_the_same = $matrix1 == $matrix2;

Overloaded comparison operator evaluates to true whenever two matrix objects are identical (same number of rows, columns and identical values in the corresponding cells).

negative compare (!=)

Compare two matrix objects:

  my $are_not_the_same = $matrix1 != $matrix2;

Overloaded negative comparison operator evaluates to true whenever two matrix objects differ (unequal number of rows, columns or diverse values in the corresponding cells).

BUGS

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

EXPORT

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

SEE ALSO

Inline::Octave, Math::Cephes::Matrix, Math::Matrix, PDL::MatrixOps, Vector::Object3D, Vector::Object3D::Matrix::Transform, Vector::Object3D::Parameters.

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