Object Library

General Purpose July 23, 1997

Introduction

This project is driven by the need to provide a wide range of structure base quantitative analysis applications to meet the demand from several research projects in our lab. All these applications are centered on a well defined geometric model which represents the study structure. The entire task can be divided into two stages. The first stage focuses on creating the model. Depending on the quality of the data and the complexity of the model, modeling can be done either automaticaaly or manually in Priism. Often models obtained by autmated methods contain errors which need to be edited out manually. In the second stage, models are used as the templates for various types of data measurements such as volume, integrated intensity, etc. Toward this end, Priism provides functions like Straight, VolumeBuilder, FindPoint, etc. Since structure models have become an important element in our data analysis process, it is necessary that IVE platform defines a system wise methods for both storing and retrieving model information in the programs. This not only greatly reduces programming task at the application level also ensures compatibility on model format among IVE applications.

We start the project by introducing the concept of object to IWL. Here, object means a subregion of a data space defined by the header information in a data file or IWL/Window. "Object" can be specified by one of the following three formats:(1)simple geometric primitives such as cube, circle, sphere,etc.(2) 2D contour which is made out of data points along the object border. (3) the complete list of data points in the object. For the first two formats, object coordinates can be in either real space or grid space(data space). The 3rd format only supports coordinates in grid space. Along with the geometric inforamtion, each object also has its own set of display attributes which dictates its presentation as overlay graphics in a window. Object is solid by default unless its shell thickness is specified. Objects in one of the above formats are called Simple Objects and they can be grouped together to create composite Objects for more complicated model structures.

The first step in using the IWL/Object funtion is to create a object list which link to a exiting data stream. Once program establishs a proper data stream by calling IMOpen and IMRdHdr or IMCrHdr, it can have a object list link to the data stream with IWOpenObj or IWInitObj funtions. IWInitObj is used for making a new object list, it will copy data space information from the data stream header which it attachs to. IWOpenObj takes istream and a disk object filename as input arguments. It will read the entire object information into memory and have it linked to the data stream specified in the first argument. If Monitor detect there is a object list attach to a data stream, in the display it will automatically display object related graphics. This eliminate the burden on the application level to maintain a complete list object related graphic ID.

If IWL/SHM is available, object information will be kept in SHM so that multiple data streams can link to the same object list .

The following is a compete list of IWL Object functions and the detailed description of their functionalities.

Topics

Makeing_newObjects

Routines for making new object For all objects, space specifies if the object is described in real space or data space coords. 2D objects that are specified in data space will be put in section lists. All 3D objects and real space objects will be put into a single list.

IWAreaObj | IWBoxObj | IWCircleObj | IWPolyObj | IWPtsObj | IWSphereObj | IWSurfaceHarmonicObj

IWPolyObj

Name

IWPolyObj -- create polygon object.

Synopsis

long IWPolyObj(long headerID, IW_POINT *poly, int npt, int iwave, int itime, int space, int color);

Arguments

headerID	object list header id
poly	array of point structs to describe the polygon
npt	specify the length of list array.
iwave	specify the wave number.
itime	specify the time number.
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
color	specify the object display color.

Description

Routine for adding a new polygon object to a window. All the points in the polygon structure need to be on the same data section. The section number is taken from the Z coordinate of the first data point in the list. In the first release, coordinates can only be entered in data space. If no error, it returns object ID back to calling routine. Otherwise, IW_ERROR is returned.

IWBoxObj

Name

IWBoxObj -- create box object.

Synopsis

long IWBoxObj(long headerID, IW_POINT box[2], int iwave, int itime, int space, int color);

Arguments

headerID	object list header id
box	array of point structs to describe the box
iwave	specify the wave number.
itime	specify the time number.
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
color	specify the object display color.

Description

Routine for defining a rectangular shape object on an image by specifying the two data locations of either of its diagonal vectors.

/* not implemented */

IWCubeObj

Name

IWCubeObj -- create cube object.

Synopsis

long IWCubeObj(long headerID, IW_POINT *list, int npt, int iwave, int itime, int space, int color);

Arguments

headerID	object list header id
list	array of point structs to describe the cube
npt	specify the length of list array.
iwave	specify the wave number.
itime	specify the time number.
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
color	specify the object display color.

Description

Routine for defining a cube shape object in a volume by specifying the two data locations of any of its diagonal vectors.

IWSphereObj

Name

IWSphereObj -- create sphere object.

Synopsis

long IWSphereObj(long headerID, IW_POINT center, int iwave, int itime, float radius, int space, int color);

Arguments

headerID	object list header id
center	center to describe the sphere
iwave	specify the wave number.
itime	specify the time number.
radius	specify the radius of circle.
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
color	specify the object display color.

Description

- add a sphere object to list. * we decided that it will not be reasonable to try to make a sphere in data space

IWAreaObj

Name

IWAreaObj -- create area object.

Synopsis

long IWAreaObj(long headerID, IW_POINT *list, int npt, int iwave, int itime, int space, int color);

Arguments

headerID	object list header id
list	array of point structs to describe the area
npt	specify the length of list array.
iwave	specify the wave number.
itime	specify the time number.
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
color	specify the object display color.

Description

Routine to create an object by specifying the data coordinates of all the points in the object. Again, the Z coordinate is taken from the first data point and it assume all the points located on the same section.

IWPtsObj

Name

IWPtsObj -- create multi-points object.

Synopsis

long IWPtsObj(long headerID, IW_POINT *list, int npt, int iwave, int itime, int space, int color);

Arguments

headerID	object list header id
list	array of point structs to describe the points list.
npt	specify the length of list array.
iwave	specify the wave number.
itime	specify the time number.
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
color	specify the object display color.

Description

- add a 3 Dimensional list of points as an object to the object list. These points do NOT have to be in the same section. Only same wave and time.

/* not implemented */

IWVectorObj

Name

IWVectorObj

Synopsis

/*** not implemented yet */
IWVectorObj(long headerID, IW_POINT *list, int npt, int iwave, int itime, float width, int space,int color);

Arguments

headerID	object list header id
list	array of point structs to describe the vector
npt	specify the length of list array.
iwave	specify the wave number.
itime	specify the time number.
width	specify the radius.
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
color	specify the object display color.

Description

Routines for creating a tubular object . list contains a set of data location along the path of the object and ÒwidthÓ defines the radius.

IWCircleObj

Name

IWCircleObj

Synopsis

IWCircleObj(long headerID, IW_POINT center, int iwave, int itime, float radius, int space, int color);

Arguments

headerID	object list header id
center	center point to describe the circle
iwave	specify the wave number.
itime	specify the time number.
radius	specify the radius of circle.
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
color	specify the object display color.

Description

Routine to create a Circle object by specifying the data coordinates of its center and radius.

/* not implemented */

IWAreaToPoly

Name

IWAreaToPoly

Synopsis

IWAreaToPoly(long headerID, int iarea);

Arguments

headerID	object list header id
iarea	object ID of area object.

Description

Routine to create a Polygon type of object which represents same data region as the input Area object. The input Area object structure remains intact. /*****************/

Object_Manipulation

IWCopyObj | IWDelObj | IWGroupObj
IWAddMemObj | IWDelMemObj
IWAlObjDis | IWAlObjDisAttr | IWAlObjName | IWAlObjPt

/* not implemented */

IWCopyObj

Name

IWCopyObj -- make a duplicate of an existing object.

Synopsis

long IWCopyObj(long headerID, long objID);

Arguments

headerID	object list header id
objID	object ID

Description

make a duplicate of an existing object.

IWGroupObj

Name

IWGroupObj -- create composite object.

Synopsis

long IWGroupObj(long headerID, long *obj_list, int nobj);

Arguments

headerID	object list header id
obj_list	array of object ID structs to describe the composite object.
nobj	specify the number of objects.

Description

- create a composite object by grouping objects together. - composite objects can be made up of simple or composite objects so that you can group as many levels as you want.

IWDelObj

Name

IWDelObj -- delete an existing object.

Synopsis

long IWDelObj(long headerID, long objID, long delete_child);

Arguments

headerID	object list header id
objID	object ID
delete_child	specify the child need to be delete or not.

Description

- delete an existing object from the list. - delete_child is a flag that if set to one, will delete all the member simple objects(if they are not shared by other composite objects);

IWDelMemObj

Name

IWDelMemObj -- delete a member from a composite object .

Synopsis

long IWDelMemObj(long headerID, long com_objID, long mem_objID);

Arguments

headerID	object list header id
com_objID	object ID of composite object
mem_objID	object ID of member object.

Description

IWAddMemObj

Name

IWAddMemObj -- add a new member to an existing composite object.

Synopsis

long IWAddMemObj(long headerID, long com_objID, long mem_objID);

Arguments

headerID	object list header id
com_objID	object ID of composite object
mem_objID	object ID of member object.

Description

- add a new member to an existing composite object.

IWAlObjDisAttr

Name

IWAlObjDisAttr -- alter the display attributes of the object.

Synopsis

long IWAlObjDisAttr(long headerID, long objID, int color, int pattern, int thickness, int method);

Arguments

headerID	object list header id
color	specify the color of object.
pattern	specify the fill pattern of object.
thickness	specify the thickness of object.
method	specify the fill method of object.

Description

- alter the display attributes of the object. color: color used in displaying input object. pattern: pattern used in line drawing for showing the input object thickness: Thickness in screen pixel used in line drawing method: IW_OUTLINE or IW_SOLID.

IWAlObjDis

Name

IWAlObjDis -- alter whether the object will be displayed or not.

Synopsis

long IWAlObjDis(long headerID, long objID, long iflag);

Arguments

headerID	object list header id
objID	object ID
iflag	turn the display on/off.

Description

- alter whether the object will be displayed or not.

IWAlObjName

Name

IWAlObjName -- add or change the name assoc. with a composite object.

Synopsis

long IWAlObjName(long headerID, long objID, char *name);

Arguments

headerID	object list header id
objID	object ID
name	the name of object

Description

- add or change the name assoc. with a composite object.

IWAlObjPt

Name

IWAlObjPt -- change the position of one of the points of an object.

Synopsis

long IWAlObjPt(long headerID, long objID, int pt_num, IW_POINT pt);

Arguments

headerID	object list header id
objID	object ID
pt_num	the point index in the point list.
pt	the new point data.

Description

- change the position of one of the points of an object.

Retrieving_Object_Info

Routines for inquiring object related infomation:

IWRtMemObjs | IWRtObjs | IWRtObjSelected
IWRtObjPtSelected | IWRtObjPts
IWRtObjType | IWRtObjName | IWRtObjLnCount

IWRtMemObjs

Name

IWRtMemObjs -- return all the members of a composite object.

Synopsis

long IWRtMemObjs(long headerID, long objID, long **obj_list, int *nobj);

Arguments

headerID	object list header id
objID	object ID
obj_list	list of object ID structs to describe the members of composite object
nobj	specify the length of list array.

Description

- return all the members of a composite object. - appl. must free the obj_list when done with it.

IWRtObjs

Name

IWRtObjs -- return a list of all the objects that are of type "type_mask".

Synopsis

long IWRtObjs(long headerID, int type_mask, int space, float *range, long **obj_list, int *nobj);

Arguments

headerID	object list header id
type_mask	specify the type of object to be retrived. for expamle: IWOBJ_COMPOSITE, IWOBJ_SIMPLE, or IWOBJ_POLY.
range	specify the range of object are interested.
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
obj_list	list of object ID structs to describe the members of composite object
nobj	specify the length of list array.

Description

- return a list of all the objects that are of type "type_mask". - can narrow this down to fewer objects of this type by specifying an xyzwt range in which to look. Must tell the library if you are specifying a real space or data space range. - appl. must free the object list when done with it.

IWRtObjSelected

Name

IWRtObjSelected -- returns the simple object which has the given point insideof it.

Synopsis

long IWRtObjSelected(long headerID, int space, IW_POINT pt, int wave, int time);

Arguments

headerID	object list header id
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
pt	the point coordinate to be used for search which object it belong to.
wave	specify the wave number.
time	specify the time number.

Description

- returns the simple object which has the given point inside of it. - appl. needs to specify if the point is in real or data space.

IWRtObjPtSelected

Name

IWRtObjPtSelected -- returns the object which has a point that is within max_dist of the given point.

Synopsis

long IWRtObjPtSelected(long headerID, int space, IW_POINT pt, int wave, int time, int max_dist, int *pt_num);

Arguments

headerID	object list header id
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
pt	the point used to match one of the point in the points list.
wave	specify the wave number.
time	specify the time number.
max_dist	specify the max distance offset for matching the point within the points list.
pt_num	specify the length of list array.

Description

- returns the object which has a point that is within max_dist of the given point. - app. needs to specify if the point is in real or data space.

IWRtMemObjs

Name

IWRtMemObjs -- return all the members of a composite object.

Synopsis

long IWRtMemObjs(long headerID, long objID, long **obj_list, int *nobj);

Arguments

headerID	object list header id
objID	object ID
obj_list	array of object ID structs to describe the composite object.
nobj	specify the number of objects.

Description

- return all the members of a composite object. - appl. must free the obj_list when done with it.

IWRtObjPts

Name

IWRtObjPts

Synopsis

long IWRtObjPts(long headerID, long objID, int space, IW_POINT **pts, int *pt_num, int *iwave, int *itime);

Arguments

headerID	object list header id
objID	object ID
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
pts	array of point structs to describe the object.
pt_num	specify the length of list array.
iwave	specify the wave number.
itime	specify the time number.

Description

- returns all the points in an object. This call is only for simple objects. So you need to find all the simple objects of a composite object then get the points of those objects. - appl. needs to free the point list when done with it.

IWRtObjType

Name

IWRtObjType

Synopsis

long IWRtObjType(long headerID, long objID);

Arguments

headerID	object list header id
objID	object ID

Description

- returns the object type as integer meaning one of following: IWOBJ_POLY,IWOBJ_VECTOR,IWOBJ_AREA, IWOBJ_CIRCLE, IWOBJ_SPHERE, IWOBJ_AREA, IWOBJ_BOX, IWOBJ_CUBE, IWOBJ_HARMONIC, IWOBJ_PTS, IWOBJ_COMPOSITE. If "iobj" is not a valid object ID, function return IW_ERROR.

IWRtObjName

Name

IWRtObjName

Synopsis

long IWRtObjName(long headerID, long objID, char *name);

Arguments

headerID	object list header id
objID	object ID
name	the name of this object list

Description

- return the name associated with this object. - for now only composite objects can be given a name.

IWRtObjLnCount

Name

IWRtObjLnCount

Synopsis

long IWRtObjLnCount(long headerID, long objID);

Arguments

headerID	object list header id
objID	object ID

Description

- returns number of composite objects this object is a member of.

Object_list_IO

Routines for Read/Write objects

IWRtNumObjLists | IWRtObjListNames | IWInitObjList
IWLoadObjList | IWSaveObjList
IWInitObjHdr | IWRtObjHdr | IWAttachObjToWin | IWDetachObjFromWin | IWCloseObjList

IWRtNumObjLists

Name

IWRtNumObjLists

Synopsis

long IWRtNumObjLists();

Arguments

headerID

object list header id

Description

- returns the number of Object Lists currently in memory.

IWRtObjListNames

Name

IWRtObjListNames -- create sphere object.

Synopsis

char **IWRtObjListNames();

Arguments

headerID

object list header id

Description

- returns a list of the names for each Object List. - appl. needs to free the character array when done.

IWInitObjList

Name

IWInitObjList

Synopsis

long IWInitObjList(char *name);

Arguments

headerID	object list header id
name	the name of this object list

Description

- initializes a new object list using a reference name. - returns the header id which is used (like istream) to reference this object list in every object call. - if object list of input name exists, current header id returned.

IWLoadObjList

Name

IWLoadObjList

Synopsis

long IWLoadObjList(long headerID, char *file_name, int mode);

Arguments

headerID	object list header id
file_name	the file name of the object list.
mode	specify the mode either IWOBJ_TRUNCATE or IWOBJ_APPEND.

Description

- reads object list into memory from a file

IWSaveObjList

Name

IWSaveObjList

Synopsis

long IWSaveObjList(long headerID, char *filename);

Arguments

headerID	object list header id
file_name	the file name of the object list.

Description

- saves object list to a file.

IWInitObjHdr

Name

IWInitObjHdr

Synopsis

long IWInitObjHdr(long headerID, long nxyzwt[], float delt[], float tilt[], float orig[]);

Arguments

headerID	object list header id
nxyzwt	the size of this object list in xyzwt 5D.
delt	the delt value of this object list.
tilt	the tilt value of this object list.
orig	the orig value of this object list.

Description

- appl. must give image file dimension info before any objects can be added to a list.

IWRtObjHdr

Name

IWRtObjHdr

Synopsis

long IWRtObjHdr(long headerID, long nxyzwt[], float delt[], float tilt[], float orig[]);

Arguments

headerID	object list header id
nxyzwt	the size of this object list in xyzwt 5D.
delt	the delt value of this object list.
tilt	the tilt value of this object list.
orig	the orig value of this object list.

Description

- returns the header information of object list given header id as input.

IWAttachObjToWin

Name

IWAttachObjToWin

Synopsis

long IWAttachObjToWin(long headerID, long istr);

Arguments

headerID	object list header id
istr	the istream number of the image window.

Description

- attach a list to a window, so that graphics will show up. - istr: use the istream of the window, not the window number

IWDetachObjFromWin

Name

IWDetachObjFromWin

Synopsis

long IWDetachObjFromWin(long headerID, long istr);

Arguments

headerID	object list header id
istr	the istream number of the image window.

Description

- must detach a list from a window before closeing the list.

IWCloseObjList

Name

IWCloseObjList

Synopsis

long IWCloseObjList(long headerID);

Arguments

headerID

object list header id

Description

- close object list when done with it to free from memory.

Object_Utility_Funcs

Object Utility Routines:

IWRtObjRange | IWRtObjVol | IWRtObjInt | IWRtObjCM | IWRtObjGC | IWAlObjShell | IWObjIntercept | IWObjUnion

IWRtObjRange

Name

IWRtObjRange

Synopsis

long IWRtObjRange(long headerID, long objID, int space, float range[10]);

Arguments

headerID	object list header id
objID	object ID
space	specify the type of coordinates used in list. It is either IW_DATA_SP or IW_REAL_SP.
range	specify the range of object are interested.

Description

- returns the range of an object. Appl. needs to specify if they want the range in real space or data space. - range has 10 elements. starting and ending x y z w t positions

IWRtObjVol

Name

IWRtObjVol

Synopsis

long IWRtObjVol(long headerID, long objID);

Arguments

headerID	object list header id
objID	object ID

Description

Function to return the number of data points mapped in the input object. iobj can be either a simple object of a composite object. In the case of polygon object, the number return represent both data points located on the polygon and points it encloses.

IWRtObjInt

Name

IWRtObjInt

Synopsis

float IWRtObjInt(long headerID, long objID, long istr);

Arguments

headerID	object list header id
objID	object ID
istr	the istream number of the image window.

Description

Function to return the integrated intensity of the set of points calculated in IWRtObjVol. - use an istream to tell which data file get position intensities

IWRtObjCM

Name

IWRtObjCM

Synopsis

long IWRtObjCM(long headerID, long objID, long istr, IW_POINT *pt);

Arguments

headerID	object list header id
objID	object ID
istr	the istream number of the image window.
pt	the return value of center of mass of input object.

Description

Function to return the center of mass of an input object. The scope of points considered is the same as they are in IWRtObjVol. - need istream to see data to calculate center of mass

IWRtObjGC

Name

IWRtObjGC

Synopsis

long IWRtObjGC(long headerID, long objID, IW_POINT *pt);

Arguments

headerID	object list header id
objID	object ID
pt	the return value of Geometric Center of input object.

Description

Function to return the Geometric Center of an input object. The scope of points considered is the same as they are in IWRtObjVol.

/* not implemented - these parameters will need to be changed when implemented */

IWAlObjShell

Name

IWAlObjShell

Synopsis

IWAlObjShell(long headerID, int objID, float thickness) ;

Arguments

headerID	object list header id
objID	object ID
thickness	specify the thickness of object shell.

Description

Function to set the shell thickness of an input object. This allows application to create a hollow object. Thickness can be specified in either grid space or real space, depending on the coordinate type used in defining the input object.

/* not implemented */

IWObjIntercept

Name

IWObjIntercept

Synopsis

IWObjIntercept(long headerID, int methods, int nobj, int *list);

Arguments

headerID	object list header id
method	the method to be applied.
nobj	specify the length of list array.
list	array of point structs to describe the object.

Description

Create a AREA object by finding the common area of a simple object list. If no common area is detected or any member in the list is not a simple object, IW_ERROR will be returned.

/* not implemented */

IWObjUnion

Name

IWObjUnion

Synopsis

IWObjUnion(long headerID, int method, int nobj, int *list);

Arguments

headerID	object list header id
method	the method to be applied.
nobj	specify the length of list array.
list	array of point structs to describe the object.

Description

Create a AREA object by the union of a simple object list.