Sequence_

This class provides fast (multi-dimensional) Ruby arrays where all elements are of the same type. It is also possible to define custom types and fast operations on them. Nested sequences are used to represent multi-dimensional arrays.

The class Sequence_ is designed to be mostly compatible with Masahiro Tanaka’s NArray. However it allows the definition of custom element types and fast operations on them. Sequence_ is also inspired by Ronald Garcia’s boost::multi_array and by Todd Veldhuizen’s Blitz++. Using Sequence_ you can do number crunching in Ruby!

Sequence_ is implemented as a parametric class. You need to use the constructor methods provided by the classes Sequence and MultiArray to instantiate objects.

Inherits

CompositeType

Sequence_	This class provides fast (multi-dimensional) Ruby arrays where all elements are of the same type.
Functions
Sequence_.stride=	Used internally to override default array stride for non-contiguous data.
Sequence_.stride	Used internally to get array stride.
Sequence_.default	Used internally.
inspect	Create textual representation of this array showing part of the content.
to_s	Get raw data of array.
save_raw	Write meta-information and raw data to file.
to_a	Convert to standard Ruby array.
to_ary	Convert to standard Ruby array.
save	Save image using RMagick.
savef	Save image using OpenEXR.
save_ubyte	Save as 8-bit greyscale image.
save_usint	Save as 16-bit greyscale image.
save_ubytergb	Save as colour image.
save_sfloat	Save as single-precision floating-point greyscale image.
save_sfloatrgb	Save as floating-point colour image.
to_object	Shortcut for to_type( OBJECT ).
to_bool	Shortcut for to_type( BOOL ).
to_ubyte	Shortcut for to_type( UBYTE ).
to_byte	Shortcut for to_type( BYTE ).
to_usint	Shortcut for to_type( USINT ).
to_sint	Shortcut for to_type( SINT ).
to_uint	Shortcut for to_type( UINT ).
to_int	Shortcut for to_type( INT ).
to_ulong	Shortcut for to_type( ULONG ).
to_long	Shortcut for to_type( LONG ).
to_dfloat	Shortcut for to_type( DFLOAT ).
to_sfloat	Shortcut for to_type( SFLOAT ).
to_dcomplex	Shortcut for to_type( DCOMPLEX ).
to_scomplex	Shortcut for to_type( SCOMPLEX ).
to_ubytergb	Shortcut for to_type( UBYTERGB ).
to_bytergb	Shortcut for to_type( BYTERGB ).
to_usintrgb	Shortcut for to_type( USINTRGB ).
to_sintrgb	Shortcut for to_type( SINTRGB ).
to_uintrgb	Shortcut for to_type( UINTRGB ).
to_intrgb	Shortcut for to_type( INTRGB ).
to_ulongrgb	Shortcut for to_type( ULONGRGB ).
to_longrgb	Shortcut for to_type( LONGRGB ).
to_dfloatrgb	Shortcut for to_type( DFLOATRGB ).
to_sfloatrgb	Shortcut for to_type( SFLOATRGB ).
to_yv12	Convert two-dimensional array to YV12 colourspace.
to_i420	Convert two-dimensional array to I420 colourspace.
dup	Create duplicate of array.
coerce	Perform coercion with another object.
mask	Create an array containing only the selected elements.
unmask	Distribute elements using a mask.
components	N-dimensional connected component labeling.
warp	Create warped array using an array of warp vectors (indices).
warp_mask	Create warped array using masked array of warp vectors (indices).
warp_clipped	Create warped array using an array of warp vectors (indices).
downsample	Downsampling of arrays.
upsample	Upsampling of arrays.
shift	Cycle array along each dimension by the given number of elements.
transpose	Reorder the indices of the array.
roll	Transpose array buy shifting indices to the left n-times.
roll	Transpose array buy shifting indices to the right n-times.
zip	Converts the elements of self and each argument to arrays and concatenates them.
repmat	Create repetition of array.
between?	Check whether each element is within the given boundaries.
normalise	Normalise values of elements.
clip	Clip values of array using a range which specifies a lower and an upper threshold.
min	Get minimum element of all elements.
max	Get maximum element of all elements.
range	Get range of elements.
sum	Compute sum of elements.
prod	Compute product of elements.
display	Display all values.
sobel	Compute Sobel-gradient.
prewitt	Compute Prewitt-gradient.
gauss_blur	Apply Gaussian blur to the array.
gauss_gradient	Compute Gauss gradient.
morphology	Apply generic morphology filter to image.
erode	Morphological operator reducing the masked area of a binary image.
dilate	Morphological operator increasing the masked area of a binary image.
fft	Wrapper to use the (inverse) Discrete Fourier Transform as implemented in the FFTW-library.
ifft	Wrapper to use the inverse of the Discrete Fourier Transform as implemented in the FFTW-library.
rfft	Wrapper to use the (inverse) Discrete Fourier Transform for real data as implemented in the FFTW-library.
irfft	Wrapper to use the inverse of the Discrete Fourier Transform for symmetric data as implemented in the FFTW-library.
to_magick	Convert to Magick::Image.
to_narray	Convert to NArray.
to_cvmat	Convert to OpenCV matrix.
show	Opens a window and displays the image.
Related
Functions
Sequence	Create an array class.
MultiArray	Create a multi-dimensional array class.

Functions

Sequence_.stride=

def Sequence_.stride=( value )

Used internally to override default array stride for non-contiguous data.

Sequence_.stride

def Sequence_.stride

Used internally to get array stride.

Sequence_.default

def Sequence_.default

Used internally. Returns default instance value.

inspect

def inspect

Create textual representation of this array showing part of the content.

to_s

def to_s

Get raw data of array.

save_raw

def save_raw( file )

Write meta-information and raw data to file.

to_a

def to_a

Convert to standard Ruby array.

to_ary

def to_ary

Convert to standard Ruby array.

save

def save( file )

Save image using RMagick. Note that saving is not supported for every element-type. The array is assumed to be two-dimensional. It is recommended to use one of the save_* methods instead.

Parameters

file	A filename or an open file.

savef

def savef( file )

Save image using OpenEXR. The array is assumed to be two-dimensional. It is recommended to use one of the save_* methods instead.

Parameters

file	A filename or an open file.

save_ubyte

def save_ubyte( file )

Save as 8-bit greyscale image. The array is assumed to be two-dimensional.

Parameters

file	A filename or an open file.

save_usint

def save_usint( file )

Save as 16-bit greyscale image. The array is assumed to be two-dimensional.

Parameters

file	A filename or an open file.

save_ubytergb

def save_ubytergb( file )

Save as colour image. The array is assumed to be two-dimensional.

Parameters

file	A filename or an open file.

save_sfloat

def save_sfloat( file )

Save as single-precision floating-point greyscale image. The array is assumed to be two-dimensional.

Parameters

file	A filename or an open file.

save_sfloatrgb

def save_sfloatrgb( file )

Save as floating-point colour image. The array is assumed to be two-dimensional.

Parameters

file	A filename or an open file.

to_object

def to_object

Shortcut for to_type( OBJECT ).

to_bool

def to_bool

Shortcut for to_type( BOOL ).

to_ubyte

def to_ubyte

Shortcut for to_type( UBYTE ).

to_byte

def to_byte

Shortcut for to_type( BYTE ).

to_usint

def to_usint

Shortcut for to_type( USINT ).

to_sint

def to_sint

Shortcut for to_type( SINT ).

to_uint

def to_uint

Shortcut for to_type( UINT ).

to_int

def to_int

Shortcut for to_type( INT ).

to_ulong

def to_ulong

Shortcut for to_type( ULONG ).

to_long

def to_long

Shortcut for to_type( LONG ).

to_dfloat

def to_dfloat

Shortcut for to_type( DFLOAT ).

to_sfloat

def to_sfloat

Shortcut for to_type( SFLOAT ).

to_dcomplex

def to_dcomplex

Shortcut for to_type( DCOMPLEX ).

to_scomplex

def to_scomplex

Shortcut for to_type( SCOMPLEX ).

to_ubytergb

def to_ubytergb

Shortcut for to_type( UBYTERGB ).

to_bytergb

def to_bytergb

Shortcut for to_type( BYTERGB ).

to_usintrgb

def to_usintrgb

Shortcut for to_type( USINTRGB ).

to_sintrgb

def to_sintrgb

Shortcut for to_type( SINTRGB ).

to_uintrgb

def to_uintrgb

Shortcut for to_type( UINTRGB ).

to_intrgb

def to_intrgb

Shortcut for to_type( INTRGB ).

to_ulongrgb

def to_ulongrgb

Shortcut for to_type( ULONGRGB ).

to_longrgb

def to_longrgb

Shortcut for to_type( LONGRGB ).

to_dfloatrgb

def to_dfloatrgb

Shortcut for to_type( DFLOATRGB ).

to_sfloatrgb

def to_sfloatrgb

Shortcut for to_type( SFLOATRGB ).

to_yv12

def to_yv12

Convert two-dimensional array to YV12 colourspace.

to_i420

def to_i420

Convert two-dimensional array to I420 colourspace.

dup

def dup

Create duplicate of array.

coerce

def coerce( other )

Perform coercion with another object.

mask

def mask( m )

Create an array containing only the selected elements. The elements themselves can be arrays as well.

Parameters

m	An array with elements of type BOOL representing a mask.

Returns

Array with selected elements.

unmask

def unmask( m,
default = typecode.default,
options = { :safe => true } )

Distribute elements using a mask. This is the inverse operation of mask.

Parameters

m	An array with elements of type BOOL representing a mask.
default	Default value for the region outside the mask.
safe	Perform range checks to avoid segmentation fault.

Returns

Array with the same shape as the mask.

components

def components( default = typecode.default,
target = UINT )

N-dimensional connected component labeling. Two pixel get the same label if they have the same value and are next to each other (full connectivity). Every pixel with the default value is labeled with 0.

warp

def warp( field,
options = { :safe => true } )

Create warped array using an array of warp vectors (indices). Here is an example

Parameters

field	Array containing warp vectors.
safe	Do range checks to avoid segmentation fault

Returns

Warped sequence with the same shape as the warp vector field.

warp_mask

def warp_mask( field,
m,
default = typecode.default,
options = { :safe => true } )

Create warped array using masked array of warp vectors (indices). Here is an example

Parameters

field	Array object containing warp vectors.
m	Mask for selecting warp vectors.
default	Default value for undefined pixel.
safe	Do range checks to avoid segmentation fault

Returns

Warped array with the same shape as the warp vector field.

warp_clipped

def warp_clipped( field,
default = typecode.default )

Create warped array using an array of warp vectors (indices). A clipping mask is computed from the warp indices. Undefined pixel are assigned the default value.

Parameters

field	Array containing warp indices.
default	Default value for undefined pixel.

Returns

Warped array.

downsample

def downsample( intervals,
offsets )

Downsampling of arrays.

Parameters

intervals	array specifying sampling interval for each dimension
offsets	array specifying sampling offsets for each dimension

upsample

def upsample( intervals,
offsets,
shape = nil )

Upsampling of arrays. The shape of the return value can be specified.

Parameters

intervals	array specifying sampling interval for each dimension
offsets	array specifying sampling offsets for each dimension
shape	array specifying the shape of the return value.

shift

def shift( * offset )

Cycle array along each dimension by the given number of elements.

transpose

def transpose( * order )

Reorder the indices of the array.

Parameters

order

new order of indices

roll

def roll( n = 1 )

Transpose array buy shifting indices to the left n-times.

Parameters

n	number of times to roll (optional)

roll

def unroll( n = 1 )

Transpose array buy shifting indices to the right n-times.

Parameters

n	number of times to unroll (optional)

zip

def zip( * arrs )

Converts the elements of self and each argument to arrays and concatenates them. Similar to Array#zip, which is part of the Ruby core.

repmat

def repmat( * repshape )

Create repetition of array. Create an array of arrays and fill with the values of this array.

Parameters

repshape

additional dimensions

between?

def between?( a,
b )

Check whether each element is within the given boundaries.

Parameters

a	lower value which can be a scalar or a array
b	upper value which can be a scalar or a array

normalise

def normalise( range = 0.0..255.0 )

Normalise values of elements. Normalise the values. This is only defined for arrays with scalar values or RGB triplets.

clip

def clip( range = 0..255 )

Clip values of array using a range which specifies a lower and an upper threshold. This function only works with scalar values.

min

def min

Get minimum element of all elements.

Returns

Smallest element in this array.

max

def max

Get maximum element of all elements.

Returns

Largest element in this array.

range

def range

Get range of elements. Same as

min..max

Returns

Range of elements

sum

def sum

Compute sum of elements.

prod

def prod

Compute product of elements.

display

def display( port = $> )

Display all values.

sobel

def sobel( direction )

Compute Sobel-gradient.

A two-dimensional Sobel x-gradient for example means a correlation of the array with the following separable filter:

+----+----+----+
| -1 |  0 |  1 |
+----+----+----+
| -2 |  0 |  2 |
+----+----+----+
| -1 |  0 |  1 |
+----+----+----+

Parameters

direction

Orientation of gradient-operator

prewitt

def prewitt( direction )

Compute Prewitt-gradient.

A two-dimensional Prewitt x-gradient for example means a correlation of the array with the following separable filter:

+----+----+----+
| -1 |  0 |  1 |
+----+----+----+
| -1 |  0 |  1 |
+----+----+----+
| -1 |  0 |  1 |
+----+----+----+

Parameters

direction

Orientation of gradient-operator

gauss_blur

def gauss_blur( sigma,
maxError = 1.0 / 256.0 )

Apply Gaussian blur to the array.

gauss_gradient

def gauss_gradient( sigma,
direction,
max_error = 1.0 / 256.0 )

Compute Gauss gradient.

Compute gradient of the array. A gradient filter is applied in the specified direction. The filter blurs in all other directions.

Parameter

sigma	extend of filter
direction	Number of dimension in which the gradient resides
max_error	maximum relative error caused by limiting the filter size

morphology

def morphology( w = 3,
h = w )

Apply generic morphology filter to image. The input image should be a binary image (values of 0 and 1 only). The result of this operation can be used to implement any morphological operation. Note that if the filter is too large the correlation has to be performed using Ruby’s big integers which is very slow.

+-----+-----+-----+
|   1 |   2 |   4 |
+-----+-----+-----+
|   8 |  16 |  32 |
+-----+-----+-----+
|  64 | 128 | 256 |
+-----+-----+-----+

Parameters

w	width of filter (default is 3)
h	height of filter (default is w)

(see log.jpg)

erode

def erode( size = 3 )

Morphological operator reducing the masked area of a binary image.

dilate

def dilate( size = 3 )

Morphological operator increasing the masked area of a binary image.

fft

def fft( forward = true )

Wrapper to use the (inverse) Discrete Fourier Transform as implemented in the FFTW-library.

Parameters

forward

Boolean indicating whether to compute forward or backward transform.

ifft

def ifft

Wrapper to use the inverse of the Discrete Fourier Transform as implemented in the FFTW-library. The result returned by the FFTW-library is divided by the size of the array.

rfft

def rfft( forward = true )

Wrapper to use the (inverse) Discrete Fourier Transform for real data as implemented in the FFTW-library. The first dimension of the array must be even.

Parameters

forward

Boolean indicating whether to compute forward or backward transform.

irfft

def irfft

Wrapper to use the inverse of the Discrete Fourier Transform for symmetric data as implemented in the FFTW-library. The result returned by the FFTW-library is divided by the size of the resulting array.

to_magick

def to_magick

Convert to Magick::Image. This conversion allows you to apply methods implemented in the RMagick-extension.

The array is assumed to be two-dimensional.

to_narray

def to_narray

Convert to NArray. This conversion allows you to apply methods implemented in the NArray-extension.

to_cvmat

def to_cvmat

Convert to OpenCV matrix. The array must have two or three dimensions. The array may contain complex values or RGB triplets if it has two dimensions.

show

def show( width = nil,
height = nil )

Opens a window and displays the image. Only works for 2D arrays.

Parameters

width	optional parameter specifying the width of the window interior
height	optional parameter specifying the width of the window interior

Functions

Sequence

def Sequence( element_type,
num_elements,
stride = element_type.size )

Create an array class.

Parameters

element_type	Type of array elements. Can be an array type as well.
num_elements	Number of array elements.
stride	Override array stride for non-contiguous storage (optional).

MultiArray

def MultiArray( element_type,
* shape )

Create a multi-dimensional array class.

Parameters

element_type	Type of array elements. Can be an array type as well.
shape	Dimensions of multi-dimensional array.

Sequence_

Inherits

See also

Functions

Sequence_.stride=

Sequence_.stride

Sequence_.default

inspect

to_s

save_raw

See also

to_a

to_ary

save

Parameters

See also

savef

Parameters

See also

save_ubyte

Parameters

save_usint

Parameters

save_ubytergb

Parameters

save_sfloat

Parameters

save_sfloatrgb

Parameters

to_object

See also

to_bool

See also

to_ubyte

See also

to_byte

See also

to_usint

See also

to_sint

See also

to_uint

See also

to_int

See also

to_ulong

See also

to_long

See also

to_dfloat

See also

to_sfloat

See also

to_dcomplex

See also

to_scomplex

See also

to_ubytergb

See also

to_bytergb

See also

to_usintrgb

See also

to_sintrgb

See also

to_uintrgb

See also

to_intrgb

See also

to_ulongrgb

See also

to_longrgb

See also

to_dfloatrgb

See also

to_sfloatrgb

See also

to_yv12

See also

to_i420