• 4.7.1 Sub-matrices
  • Using sub-matrices in stars
  • The sub-matrix "particles"
• 4.7.2 Image particles
• 4.7.3 "First-class" types

4.7.1 Sub-matrices

There are four sub-matrix classes, one for each concrete matrix class: ComplexSubMatrix, FixSubMatrix, FloatSubMatrix, and IntSubMatrix, each of which inherits from the corresponding PtMatrix class. A sub-matrix contains a reference to a "parent" matrix of the same type, and modifies its internal data pointers and matrix size parameters to reference a rectangular region of the parent's data. The constructors for the submatrix classes have arguments that specify the region of the parent matrix referenced by the sub-matrix.

As for matrices, the description of sub-matrices uses the convention that XXX means Complex, Fix, Float, or Int, and xxx means Complex, Fix, double, or int.

The submatrix constructors are:

Return a pointer to the start of the row of the sub-matrix's data storage.

Using sub-matrices in stars

Sub-matrices are not currently useful in general-purpose dataflow stars. Rather, they were developed to provide an efficient means of referencing portions of a single larger matrix in the multi-dimensional synchronous dataflow (MDSDF) domain. We give here a summary. For more details, see [Che94] and the MDSDF sources in $PTOLEMY/src/domains/mdsdf/kernel and $PTOLEMY/src/domains/mdsdf/stars.

Unlike other domains, the MDSDF kernel does not transfer particles through FIFO buffers. Instead, each geodesic keeps a single copy of a "parent" matrix, that represents the "current" two-dimensional datablock. Each time a star fires, it obtains a sub-matrix that references this parent matrix with the getOutput() function of the MDSDF input port class. For example, a star might contain:

FloatSubMatrix* data = (FloatSubMatrix*)(input.getInput()); Note that this is not really getting a matrix, but a sub-matrix that references a region of the current data matrix. The size of the sub-matrix has been set by the star in its initialization code by calling the setMDSDFParams() function of the port.

To write data to the output matrix, the star gets a sub-matrix which references a region of the current output matrix and writes to it with a matrix operator. For example,

FloatSubMatrix* result = (FloatSubMatrix*)(output.getOutput());
result = -data; Because the sub-matrices are only references to the current matrix on each arc they must be deleted after use:

delete &input;
delete &result; Here is a simplified example of a complete MDSDF star:

defstar {
name { Add }
domain { MDSDF }
desc {
Matrix addition of two input matrices A and B to
produce matrix C. All matrices must have the same
dimensions.
}
version { %W% %G% }
author { Mike J. Chen }
location { MDSDF library }
input {
name { Ainput }
type { FLOAT_MATRIX }
}
input {
name { Binput }
type { FLOAT_MATRIX }
}
output {
name { output }
type { FLOAT_MATRIX }
}
defstate {
name { numRows }
type { int }
default { 2 }
desc { The number of rows in the input/output matrices. }
}
defstate {
name { numCols }
type { int }
default { 2 }
desc { The number of columns in the input/output
matrices. }
}
ccinclude { "SubMatrix.h" }
setup {
Ainput.setMDSDFParams(int(numRows), int(numCols));
Binput.setMDSDFParams(int(numRows), int(numCols));
output.setMDSDFParams(int(numRows), int(numCols));
}
go {
// get a SubMatrix from the buffer
FloatSubMatrix& input1
= *(FloatSubMatrix*) (Ainput.getInput());
FloatSubMatrix& input2
= *(FloatSubMatrix*)(Binput.getInput());
FloatSubMatrix& result
= *(FloatSubMatrix*)(output.getOutput());

// compute product, putting result into output

result = input1 + input2;

delete &input1;
delete &input2;
delete &result;
}
}

The sub-matrix "particles"

The ptlang type of submatrices is FLOAT_MATRIX, INT_MATRIX, and so on. (This is not documented in the User's Manual and is likely to change in a future release.) Each of these ptlang types is implemented by a sub-class of Particle: IntMatrixParticle, FloatMatrixParticle, FixMatrixParticle and ComplexMatrixParticle. These particle classes exist only for setting up the portholes and performing type-checking-they are never created or passed around during a simulation. Instead, sub-matrices are created and destroyed by the MDSDF kernel and stars as described above.

4.7.2 Image particles

A set of experimental image data types, designed to make it convenient to manipulate images and video sequences in Ptolemy, were defined by Paul Haskell. They are based on Ptolemy's built-in Message type, described above. A library of stars that uses these image data types can be found in the image library of the DE domain.

This set of classes is being replaced by the PtMatrix classes, and the SDF image classes now all use PtMatrix. We give here a brief introduction to the image data types used in the DE domain, although new work should consider using PtMatrix classes instead. Class definitions can be found in $PTOLEMY/src/domains/de/kernel.

The base class of all the image classes is called BaseImage. It has some generic methods and members for manipulating images. Most of the methods are redefined in the derived classes. The fragment method partitions an image into many smaller images, which together represent the same picture as the original. The assemble method combines many small images which make up a single picture into a single image that contains the picture. The fragment method works recursively, so an image that has been produced by a previous fragment call can be further fragmented. Assembly always produces a full-sized image from fragments, however small.

Use of the size, fullSize, and startPos members varies within each subclass. Typically the size variable holds the number of pixels that an object is storing. If an object is not produced by fragment(), then (size == fullSize). If the object is produced by a fragment() call, size may be less than or equal to fullSize. An objects's fullSize may be bigger or smaller than width*height. It would be bigger, for example, in DCTImage, where the amount of allocated storage must be rounded up to be a multiple of the blocksize. It would be smaller, for example, for an object that contains run-length coded video.

The frameId variable is used during assembly. Fragments with the same frameId's are assembled into the same image. So, it is important that different frames from the same source have different frameIds.

The comparison functions {==, !=, <, >, etc.} compare two objects' frameId's. They can be used to resequence images or to sort image fragments.

The copy constructor and clone methods have an optional integer argument. If a nonzero argument is provided, then all state values of the copied object are copied to the created object, but none of the image data is copied. If no argument or a zero argument is provided, then the image data is copied as well. Classes derived from BaseImage should maintain this policy.

The GrayImage class, derived from BaseImage, is used to represent gray-scale images. The DCTImage class is used to represent images or image fragments that have been encoded using the discrete-cosine transform. The MVImage class is a bit more specialized; it stores a frame's worth of motion vectors.

4.7.3 "First-class" types

All of the types built-in to the Ptolemy kernel are "first-class" in the sense that they are understood by pigi and ptlang. We recommend that users create their own types using the mechanism described in "Defining New Data Types" on page 4-14. This approach has the disadvantage that all user-defined types are seen by pigi and ptlang as being of type "message." If this is not acceptable, then it is possible to create your own first-class types by sub-classing Particle and adding the new types to VEM. The following instructions briefly describes this process. We stress, however, that this method is not officially supported and that types created this way will probably have to be reworked in a future release of Ptolemy. You will need to use some other color-say fileColor-as a sample to follow when modifying the various source files.

• Sub-class Particle and Message. Use the classes in $PTOLEMY/src/kernel/FileMessage.h/cc and $PTOLEMY/src/kernel/FileParticle.{h,cc} as examples. You will need to create a static instance of your Particle and static Plasma and PlasmaGate instances to hold your particles, as demonstrated by FileParticle.
• Modify $PTOLEMY/src/pigilib/mkTerm.c. There are three switch statements where you will need to insert a new case.
• In the directory $PTOLEMY/lib/colors/ptolemy, edit bw.pat and colors.pat to add the new color. The color is in RBG format, with 1000 being full-scale.
• Run the Octtools installColors program. It will ask you a series of mysterious and strangely beautiful questions. To start with, use the defaults, except for "Output display type", where you answer GENERIC-COLOR. Run the same program again with the following output display types: GENERIC-BW, Postscript-Color, and Postscript-BW.
• To support monochrome screens (when pigi is started with the -bw option), repeat the above, but specify $PTOLEMY/lib/colors/ptolemy/bw.pat as the pattern file, $PTOLEMY/lib/bw_patterns as the directory in which to install, GENERIC-COLOR as the display device, and answer YES to the question about color output device.
• After rebuilding pigilib and restarting, create an icon for a star that has your new type as an input or output. The terminal should be of the new color.

---

---

Copyright © 1990-1997, University of California. All rights reserved.