The module "mpadmatrix" of the Mastrave modelling library

Copyright and license notice of the function mpadmatrix

Copyright © 2009,2010,2013,2014 Daniele de Rigo

The file mpadmatrix.m is part of Mastrave.

Mastrave is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Mastrave is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Mastrave. If not, see http://www.gnu.org/licenses/.

Function declaration

[ padded_values, padded_mask, mask ] = mpadmatrix( values             ,
                                                   padding       = [] ,
                                                   padding_value = [] )

Description

Utility to pad a matrix of values within an external frame filled with a default element.

The defaul frame is a border around values filled with zeros. If values is an R x C matrix, then the resulting padded matrix padded_values is an R+2 x C+2 matrix, with a border of zeros and the original R x C values centered inside the matrix. The thickness of the frame is set by the optional argument padding while the filling element may be set by the optional argument padding_value .

The positioning of the original matrix values inside padded_values is defined by the true values of the corresponding padded_mask . If padding is negative, the padded_values are instead the central part of values , after the removal of its borders with a thickness of erosion set by the absolute value of padding .

The remaining elements of values are defined by the true values of mask .

Input arguments

 values            ::matrix::
                   Matrix of values to pad.

 padding           ::scalar_integer::
                   Thickness of the frame to add around  values .
                   If negative, a border of thickness:
                      - padding 
                   is instead removed from  values .
                   If empty, the default value is 1.
                   If omitted, the default value is  [] (empty).

 padding_value     ::scalar::
                   Value to use when filling the frame around  values .
                   If empty, the default value is 0.
                   If omitted, the default value is  [] (empty).

Example of usage

   % Default usage
   vals = reshape( 1:30, 5, 6 )
   mpadmatrix( vals )

   % Passing a custom padding thickness
   mpadmatrix( vals, 2 )

   % Passing a custom padding value
   mpadmatrix( vals, 2, NaN )

   % Passing a negative padding thickness
   mpadmatrix( vals, -1 )

See also:
   mblk_fun, mdeal



Keywords:
   data-transformation, matrix, blocks



Version: 0.3.1

Support

The Mastrave modelling library is committed to provide reusable and general - but also robust and scalable - modules for research modellers dealing with computational science.  You can help the Mastrave project by providing feedbacks on unexpected behaviours of this module.  Despite all efforts, all of us - either developers or users - (should) know that errors are unavoidable.  However, the free software paradigm successfully highlights that scientific knowledge freedom also implies an impressive opportunity for collectively evolve the tools and ideas upon which our daily work is based.  Reporting a problem that you found using Mastrave may help the developer team to find a possible bug.  Please, be aware that Mastrave is entirely based on voluntary efforts: in order for your help to be as effective as possible, please read carefully the section on reporting problems.  Thank you for your collaboration.