At this point, the IW object library in IVE 4 is intended to make it possible to port the small number of applications from IVE 3.3 (Clouds, Pick Points, and Volume Builder that made use of the object library. It is not clear if the object library is a viable platform for building new applications. I've quoted the introduction from IVE 3.3 object library's documentation below to give the originators' intent (circa July 1997) for the library.
This project is driven by the need to provide a wide range of structure-based 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 automatically or manually in Priism. Often models obtained by automated 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 systemwide methods for both storing and retrieving model information in the programs. This not only greatly reduces programming task at the application level also ensures model format compatibility 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: simple geometric primitives such as cube, circle, sphere, etc; 2D contour which is made out of data points along the object border; 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 information, 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 functions is to create a object list which link to a exiting data stream. Once program establishes a proper data stream by calling IMOpen and IMRdHdr or IMCrHdr, it can link an object list to the data stream with IWOpenObj or IWInitObj functions. IWInitObj is used for making a new object list, it will copy data space information from the data stream header which it attaches 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 a Monitor detects that there is a object list attached to a data stream, it will automatically display object related graphics. This eliminates the burden on the application level to maintain a complete list object related graphic IDs.
If IWL/SHM is available, object information will be kept in SHM so that multiple data streams can link to the same object list.
| Table of Contents | Introduction | Compiling and Linking | Release Notes | List of Functions by Category | List of Functions by Name |
Programs written in C/C++ which use the IW object library functions should include IWGrCC.h to provide prototypes and define types and macros used with the object library functions. When linking those programs, link against libIWObj.so (libIWObj.dylib on Mac OS X) or libIWObj.a.
The libraries are in the n32 object format; therefore, you will need to compile and link your application so that it is in the n32 format as well Supplying the -n32 option to the compiler and linker is one way to do this; see the pe_environ (5) man page for others.
The header file is located in the IRIX/INCLUDE directory and the library in the IRIX/LIB directory of the Priism distribution. If you use the archive version of the library, libIWObj.a, you should link with the MIPS Proc C++ compiler (the library contains C++ code and linking with the C++ compiler ensures that the C++ constructs are properly initialized).
When linking against libIWObj.a, you also need to link against libIWL and libive which are available in shared or archive versions in the same directory as libIWGrObj.a. The other options you may need to specify are
-lX11 -lm -lGL -lpthread
To use the x86 Linux library, you will need an x86 Linux system that supports compiling ELF executables and has at least glibc2.1 (if you use the archive libraries, you will have to have a version of glibc that will support archive libraries generated for glibc2.1). To use the library and header, the X libraries and headers must be installed.
The header file is located in the Linux/x86/INCLUDE directory and the library in the Linux/x86/LIB directory of the Priism distribution.
If you link against libIWObj.so, it is necessary to instruct the linker to search Linux/x86/LIB for libraries that libIWObj.so uses. If you invoke the linker directly, this can be done by adding
-rpath-link install_dir/Linux/x86/LIB
to the linker options (replace install_dir with the path to the Priism distribution). If the compiler is used to invoke the linker, then you will need to determine how to instruct the compiler to pass the above option to the linker; for most compilers it can be done with
-Wl,-rpath-link,install_dir/Linux/x86/LIB
libIWObj.so or its indirect dependencies also depend on the X and OpenGL libraries so if the X and OpenGL library directories are not in the directory search path it is also necessary to supply a -rpath-link option for the X and OpenGL library directories.
If you link against the archive library (libIWObj.a), you should link with the egcs-2.91 g++ compiler (the library contains C++ code and linking with the C++ compiler ensures that the C++ constructs are properly initialized). You also need to link against libIWL and libive which are available in shared or archive versions in the same directory as libIWGrObj.a. The other options you may need to specify are
-lX11 -ldl -lm -lGL
(this assumes that the X and OpenGL libraries are in the library directory search path; if not it will be necessary to add them).
To use the IW object library on Mac OS X, it is necessary to have the X libraries and an OpenGL library compatible with those libraries installed.
The header file is located in the Darwin/INCLUDE directory of the Priism distribution.
The library is located in the Darwin/LIB directory of the Priism distribution. If you link against libIWObj.dylib, it is necessary to link against libIWL and libive which are in the same directory as libIWObj.dylib, i.e. add
-lIWL -live
to the link options. If you use libIWObj.a, you should link with gcc 3.1 version of the C++ compiler to pull in the proper C++ libraries. In addition, you will have to link against the Priism libraries, libIWL and libive, the X11 library, and an OpenGL library compatible with X11. For a typical configuration (X11 in /usr/X11R6), you would add
-Linstall_dir/Darwin/LIB -lIWL -live -L/usr/X11R6/lib -lX11 -lGL
to your link options where install_dir is the full path to the directory where Priism is installed.
| Table of Contents | Introduction | Compiling and Linking | Release Notes | List of Functions by Category | List of Functions by Name |
The object library first became available in IVE 4.2.2. The known problems with the object library are:
The following incompatibilities are known to have been introduced while porting the object library from IVE 3.3 to IVE 4.
| Table of Contents | Introduction | Compiling and Linking | Release Notes | List of Functions by Category | List of Functions by Name |
| Table of Contents | Introduction | Compiling and Linking | Release Notes | List of Functions by Category | List of Functions by Name |
| Table of Contents | Introduction | Compiling and Linking | Release Notes | List of Functions by Category | List of Functions by Name |
Adds a member to a composite object.
include "IWGrCC.h"
int IWAddMemObj(IWGrHeaderID headerID IWGrObjID com_objID,
IWGrObjID mem_objID);
Adds the object referred to by mem_objID to the composite object referred to by com_objID. Unexpected results can occur if mem_objID refers to the same object as com_objID or refers to a composite object that contains (directly or indirectly) the object referred to by com_objID. Both objects must be in the object list referred to by headerID. Returns IW_ERROR if the object list referred to by headerID is not valid, the objects referred to by mem_objID or com_objID are not valid, or it was not possible to allocate resources to resolve the references or update the list of members in the composite object; otherwise, returns IW_SUCCESS.
Alters whether or not an object is displayed.
#include "IWGrCC.h"
int IWAlObjDis(IWGrHeaderID headerID, IWGrObjID objID,
int iflag);
If iflag is zero, the object referred to by objID, which is part of the object list referred to by headerID, will not be displayed in any image windows attached to the object list; otherwise, the object will be displayed. If the object is composite, applies the visibility setting to all the object's members. A new object is initially visible (will be drawn in an image window attached to the object list when the image window is redrawn). IWAlObjDis returns IW_ERROR if the object list referred to by headerID is not valid or the object referred to by objID is not valid; otherwise, returns IW_SUCCESS.
Alters the display attributes of an object.
#include "IWGrCC.h"
int IWAlObjDisAttr(IWGrHeaderID headerID, IWGrObjID objID,
int color, int pattern, int thickness, int method);
Modifies the display attributes of the object referred to by objID which is a member of the object list referred to by headerID. If the object is composite, applies the display attributes to all of the object's members. color specifies the index for the color used to display the object. pattern specifies the new type of fill pattern to use. Currently, the value of pattern has no effect on the appearance of objects. thickness is the width of the lines, in screen pixels, used when drawing the object. method specifies the style of drawing to use for the object; method may be one of the following constants defined in IWGrCC.h:
IWAlObjDisAttr returns IW_ERROR if the object list referred to by headerID is not valid or the object referred to by objID is not valid; otherwise, returns IW_SUCCESS. For objects that are not composite, the initial color index is the value specified when the object was created, the initial pattern value is one, the initial line thickness is one pixel, and the initial drawing method is IWOBJ_OUTLINE.
Modifies the name associated with an object.
#include "IWGrCC.h"
int IWAlObjName(IWGrHeaderID headerID, IWGrObjID objID,
const char* name);
Changes the name associated with the object referred to by objID to be the null-terminated string of characters pointed to by name. The object must be a member of the object list referred to by headerID. If name is a null pointer, the new name of the object will be the empty string. If name points to a string of characters with more than MAX_OBJ_FILE_NAME_SIZE minus one characters before the first null character, only the first MAX_OBJ_FILE_NAME_SIZE minus one characters are used for the object's name. Returns IW_ERROR if the object list referred to by headerID is not valid or the object referred to by objID is not valid; otherwise, returns IW_SUCCESS.
Changes the position of one of the points of an object.
#include "IWGrCC.h"
int IWAlObjPt(IWGrHeaderID headerID, IWGrObjID objID,
int pt_num, IW_POINT pt);
pt_num is the zero-based index of the point which will be modified. pt holds the new values for the coordinates of the point. objID refers to the object to modified; that object must be a member of the object list referred to by headerID. IWAlObjPt returns IW_ERROR if the object list referred to by headerID is not valid or the object referred to by objID is not valid; otherwise, returns IW_SUCCESS.
A call to IWAlObjPt will have no effect it pt_num is less than zero or is greater or equal to the number of control points in the object. Objects created by IWCircleObj and IWSphereObj have one control point, the center. Objects created by IWBoxObj have two control points, the two ends of the diagonal specified when the object was created. For objects created by IWAreaObj, IWPolyObj, and IWPtsObj, the control points are the points specified when the object was created. For composite objects, the control points are the control points of all the member objects with the first member object's control points first in the list, the second member object's control points second in the list, and so on.
A call to IWAlObjPt does not force the modified object to be redrawn if the object is displayed in an image window.
Defines a new object in a single z plane by explicitly providing all the points in the object.
IWGrObjID IWAreaObj(IWGrHeaderID headerID, const IW_POINT list[], int npt, int iwave, int itime, int space, int color);
Creates an object consisting of the npt points specified in list and adds that object to the object list referred to by headerID. The points should all have the same z coordinate values. The points all lie in the same wavelength, whose zero-based index is given by iwave, and time point, whose zero-based index is given by itime. If space is IWOBJ_DATA_SP, the coordinates are assumed to be in pixel units (i.e. grid space); if space is IWOBJ_REAL_SP, the coordinates are assumed to be in "real space". color specifies the color index to be used when displaying the points. Returns zero if the object list referred to by headerID is not valid, the object list has not had a coordinate system established, or it was not possible to allocate resources for the new object; otherwise, returns a reference to the new object.
Attaches an object list to an image window.
#include "IWGrCC.h"
int IWAttachObjToWin(IWGrHeaderID headerID, int istr);
Attaches the object list referred to by headerID to the image window connected to the IM library stream number istr. Subsequent redraws of the image window will include graphics representing the objects in the list. The object list remains connected to the image window until an application detaches the object list from the image window with IWDetachObjFromWin or the image window is overwritten or deleted. IWAttachObjToWin returns IW_SUCCESS if successful. It returns IW_ERROR if one of the input arguments is invalid or there insufficient resources to complete the operation.
Creates an object representing a rectangle parallel to the xy plane.
#include "IWGrCC.h"
IWGrObjID IWBoxObj(IWGrHeaderID headerID, const IW_POINT box[2],
int iwave, int itime, int space, int color);
Defines a rectangle by the two endpoints of one of its diagonals, box[0] and box[1]. Uses the z coordinate of box[0] as the z coordinate for the rectangle and ignores the z coordinate of box[1]. The rectangle lies in the wavelength whose zero-based index is given by iwave and the time point whose zero-based index is given by itime. If space is IWOBJ_DATA_SP, the coordinates are assumed to be in pixel units (i.e. grid space); if space is IWOBJ_REAL_SP, the coordinates are assumed to be in "real space". color specifies the color index to be used when displaying the rectangle. Returns zero if the object list referred to by headerID is not valid, the object list has not had a coordinate system established, or it was not possible to allocate resources for the new object; otherwise, returns a reference to the new object.
Creates an object representing a circle parallel to the xy plane.
include "IWGrCC.h"
IWGrObjID IWCircleObj(IWGrHeaderID headerID, IW_POINT center,
int iwave, int itime, float radius, int space,
int color);
Defines a circle by its center point, center, and a radius, radius. The circle lies in the wavelength whose zero-based index is given by iwave and the time point whose zero-based index is given by itime. If space is IWOBJ_DATA_SP, the coordinates are assumed to be in pixel units (i.e. grid space); if space is IWOBJ_REAL_SP, the coordinates are assumed to be in "real space". color specifies the color index to be used when displaying the rectangle. Returns zero if the object list referred to by headerID is not valid, the object list has not had a coordinate system established, or it was not possible to allocate resources for the new object; otherwise, returns a reference to the new object.
Closes the connection to an object list and deletes the object list if no other connections are open to the list.
#include "IWGrCC.h"
int IWCloseObjList(IWGrHeaderID headerID);
If headerID refers to an object list the program had previously connected to with IWInitObjList, IWCloseObjList closes the connection to the object list and returns IW_SUCCESS; otherwise, IWCloseObjList returns IW_ERROR. If IWCloseObjList determines that the object list is not attached to any image windows and there are no other outstanding connections (i.e. calls to IWInitObjList which do not have a matching call to IWCloseObjList) to the list, IWCloseObjList deletes the object list and its contents.
Removes a member from a composite object.
#include "IWGrCC.h"
int IWDelMemObj(IWGrHeaderID headerID, IWGrObjID com_objID,
IWGrObjID mem_objID);
Removes the member object referred to by mem_objID from the composite object referred to by com_objID. Both objects must be in the object list referred to by headerID. Returns IW_ERROR if the object list referred to by headerID is not valid, the objects referred to by mem_objID or com_objID are not valid, the object referred to by mem_objID was not part of the composite object referred to by com_objID, or it was not possible to allocate resources to resolve the references; otherwise, returns IW_SUCCESS.
Deletes an object.
include "IWGrCC.h"
int IWDelObj(IWGrHeaderID headerID, IWGrObjID objID, int delete_child);
Deletes the object referred to by objID from the object list referred to by headerID. If the object is a composite object and delete_child is not zero, deletes any components of the composite object as well. Returns IW_ERROR if headerID does not refer to a valid object list or if objID does not refer to a valid object; otherwise, returns IW_SUCCESS. Deleting a member of a composite object before deleting the composite object itself creates a dangling reference in this implementation and can cause unexpected results when operating on the composite object.
Detaches an object list from an image window.
#include "IWGrCC.h"
int IWDetachObjFromWin(IWGrHeaderID headerID, int istr);
Detaches the object list referred to by headerID from the image window connected to the IM library stream number istr. IWDetachObjFromWin returns IW_SUCCESS if successful. It returns IW_ERROR if one of the arguments is invalid or the object list referred to by headerID is not attached to the image window connected to istr.
Creates a composite object, an object that groups together zero or more other objects from the same object list.
#include "IWGrCC.h"
IWGrObjID IWGroupObj(IWGrHeaderID headerID, const IWGrObjId obj_list[], int nobj);
Creates a composite object in the object list referred to by headerID. Initially the composite object will group together the objects referred to by the first nobj elements of obj_list. Returns zero if the object list referred to by headerID is not valid, the object list has not had a coordinate system established, or it was not possible to assemble the references to the component objects; otherwise, returns a reference to the new composite object.
If nobj is not positive, the coordinate system type (either "data space" or "real space") of the new composite is "data space"; otherwise, the composite object inherits the coordinate system type of the first element in obj_list. After creating a composite object, you can add new members with IWAddMemObj and can delete members with IWDelMemObj. Additions or deletions do not change the coordinate system type set when you created the composite object.
Establishes a coordinate system and bounds for an object list.
#include "IWGrCC.h"
int IWInitObjHdr(IWGrHeaderID headerID, const int nxyzwt[],
const float delt[], const float tilt[],
const float orig[], const int xyzst[]);
IWInitObjHdr establishes a coordinate system and bounds for the object list referred to by headerID; it has the side effect of deleting any objects associated with the object list. Establishing a coordinate system and bounds for an object list is a prerequisite for adding objects to the list and determines the conversion between the two coordinate system conventions, "data space" and "real space". IWInitObjHdr returns IW_SUCCESS if the the operation was successful or IW_ERROR if the operation was not successful.
nxyzwt holds the number of sample points along each dimension. The first element is for the x axis, the second is for the y axis, the third is for for the z axis, the fourth is for the wavelength axis, and the fifth is for the time axis. delt holds the distance between sample points for the x, y, and z axes (in that order). tilt holds the three rotation angles, in degrees, describing the orientation of the volume. orig holds the x, y, and z coordinates (in that order) for the origin; the units on the coordinates are assumed to be the same as the units for the distances between sample points. xyzst holds the x, y, and z indices (in that order) corresponding to the origin.
The conversion from "data space" (where coordinates are in the units of pixels) to "real space" (where the coordinates use the same units as used for delt) will be:
[ x' ] [ x * delt[0] + orig[1] ] [ y' ] = Z * Y * X * [ y * delt[1] + orig[1] ] [ z' ] [ z * delt[2] + orig[2] ]
where Z, Y, and X are
[ cos(tilt[2]) sin(tilt[2]) 0 ]
Z = [ -sin(tilt[2]) cos(tilt[2]) 0 ]
[ 0 0 1 ]
[ cos(tilt[1]) 0 -sin(tilt[1]) ]
Y = [ 0 1 0 ]
[ sin(tilt[1]) 0 cos(tilt[1]) ]
[ 1 0 0 ]
X = [ 0 cos(tilt[0]) sin(tilt[0]) ]
[ 0 -sin(tilt[0]) cos(tilt[0]) ]
Looks up an object list by name. If the a list with that name already exists, returns a reference to that list; otherwise, returns a reference to a new object list.
#include "IWGrCC.h"
IWGrHeaderID IWInitObjList(const char* name);
If an object list with the name given by the null-terminated string name already exists in memory, creates a reference to that list and returns it. If an object list with the given name does not already exist in memory, creates a new list and returns a reference to it. If the process of creating a reference or a new list fails, the IWInitObjList will return zero. For the purposes of comparing object list names, at most MAX_OBJ_FILE_NAME_SIZE minus one characters are used. Use IWCloseObjList to disconnect from a list that you connected to with IWInitObjList.
Returns whether or not a given point falls within the boundaries of an object.
#include "IWGrCC.h"
int IWIsObjSelected(IWGrHeaderID headerID, IWGrObjID objID,
int dtype, IW_POINT pt, int wave, int time);
IWIsObjSelected returns IW_ERROR if unable to allocate resources for resolving the object reference, objID. IWIsObjSelected returns zero if the object list reference by headerID is invalid or the point, pt does not fall within the bounds of the object referred to by objID, or that object is not in the wavelength with index wave and the time point with index time. Otherwise, IWIsObjSelected returns one. space controls how the coordinates of pt are interpreted. If space is IWOBJ_DATA_SP, the point is assumed to be in "data space. If space is IWOBJ_REAL_SP, the point is assumed to be in "real space". For compatibility with the behavior of the IVE 3.3 version, IWIsObjSelected will never return one when objID refers to an object created with a call to IWAreaObj, IWCircleObj, IWPtsObj, or IWSphereObj.
Loads into memory a list of objects previously saved to a file.
#include "IWGrCC.h"
int IWLoadObjList(IWGrHeaderID headerID, const char* filename,
int mode);
Loads an object list from the file named filename into the object list referred to by headerID. If mode is IWOBJ_TRUNCATE, the coordinate system and any objects associated with the object list referred to by headerID are replaced by the objects and coordinate system stored in the file. If mode is IWOBJ_APPEND, any objects in the object list referred to by headerID are preserved in order at the front of the object list. The coordinated system for the object list referred to by headerID is preserved as well unless it had not yet been set. IWLoadObjList returns IW_SUCCESS if the object list referred to by headerID is valid, mode is IWOBJ_TRUNCATE or IWOBJ_APPEND, and an object list was successfully extracted from the file named filename; otherwise, IWLoadObjList returns IW_ERROR.
Creates an object representing a polygon parallel to the xy plane.
#include "IWGrCC.h"
IWGrObjID IWPolyObj(IWGrHeaderID headerID, const IW_POINT poly[],
int npt, int iwave, int itime, int type,
int color);
Creates a polygon object with npt vertices whose coordinates are stored in the array poly. The vertices are assumed to lie on the same z plane whose z coordinate is the z coordinate for the first vertex. The circle lies in the wavelength whose zero-based index is given by iwave and the time point whose zero-based index is given by itime. If space is IWOBJ_DATA_SP, the coordinates are assumed to be in pixel units (i.e. grid space); if space is IWOBJ_REAL_SP, the coordinates are assumed to be in "real space". color specifies the color index to be used when displaying the rectangle. Returns zero if the object list referred to by headerID is not valid, the object list has not had a coordinate system established, or it was not possible to allocate resources for the new object; otherwise, returns a reference to the new object.
Defines an object by explicitly providing all the the points in the object.
#include "IWGrCC.h"
IWGrObjID IWPtsObj(IWGrHeaderID headerID, const IW_POINT list[],
int npt, int iwave, int itime, int space,
int color);
Creates an object consisting of the npt points specified in list and adds that object to the object list referred to by headerID. The points all lie in the same wavelength, whose zero-based index is given by iwave, and time point, whose zero-based index is given by itime. If space is IWOBJ_DATA_SP, the coordinates are assumed to be in pixel units (i.e. grid space); if space is IWOBJ_REAL_SP, the coordinates are assumed to be in "real space". color specifies the color index to be used when displaying the points. Returns zero if the object list referred to by headerID is not valid, the object list has not had a coordinate system established, or it was not possible to allocate resources for the new object; otherwise, returns a reference to the new object.
Constructs a list of references to the member objects of an object.
#include "IWGrCC.h"
int IWRtMemObjs(IWGrHeaderID headerID, IWGrObjID objID,
IWGrObjID** obj_list, int* nobj);
If headerID is not a reference to a valid object list or objID is not a reference to a valid object, IWRtMemObjs returns IW_ERROR and sets *obj_list and *nobj to zero. If headerID is a reference to a valid object list and objID is a reference to an object in that list and that object is either a non-composite object or a composite object with zero members, IWRtMemObjs returns IW_SUCCESS and sets *obj_list and *nobj to zero. If headerID is a reference to a valid object list and objID is a reference to a composite object in that list with at least one member, IWRtMemObjs sets *nobj to the number of member objects. Then, if IWRtMemObjs could allocate an array of references to the member objects, it will set *obj_list to point to the array of references and will return IW_SUCCESS; otherwise it will set *obj_list to zero and will return IW_ERROR. When you are finished with the array of references to the member objects, you should call free() with the pointer to the first array element (i.e. free(*obj_list)) to release the memory associated with the array.
Returns the number of object lists currently in memory.
#include "IWGrCC.h"
int IWRtNumObjLists(void);
If the program is not attached to the Priism shared memory file, then IWRtNumObjLists will return the number of object lists the program currently has open. If the program is attached to the Priism shared memory file, then IWRtNumObjLists will return the total number of object lists available in shared memory.
Computes the weighted mean position of a set of points within an object where the weight of each point is the intensity at that point. For an object created by IWAreaObj or IWPtsObj, the point used are the points that define the object. For an object which is non-composite and was not created by IWAreaObj or IWPtsObj, the points used are those points which have integral coordinates in the object's preferred coordinate convention (for 2D objects, only the x and y coordinates have to be integral) and which lie within or on the boundary of the object. For a composite object, the points used are the union of all the points contained by the composite object's members.
#include "IWGrCC.h"
int IWRtObjCM(IWGrHeaderID headerID, IWGrObjID objID,
int istr, int dtype, IW_POINT* pt);
If headerID does not refer to a valid object list, objID does not refer to a valid object, or there was insufficient resources to resolve the references, IWRtObjCM returns IW_ERROR and does not modify the coordinates of *pt. Otherwise, IWRtObjGC returns IW_SUCCESS and sets the coordinates of *pt equal to the coordinates of the weighted mean of the set of points drawn from the object referred to by objID. The weights are the intensities drawn from the IM library stream, istr. If a point does not fall within the bounds of that data set, its weight is zero. When dtype is IWOBJ_DATA_SP, the coordinates of *pt are reported in "data space". If dtype is IWOBJ_REAL_SP, the coordinates are reported in "real space".
Computes the unweighted mean of a set of points within an object. For an object created by IWAreaObj or IWPtsObj, the point used are the points that define the object. For an object which is non-composite and was not created by IWAreaObj or IWPtsObj, the points used are those points which have integral coordinates in the object's preferred coordinate convention (for 2D objects, only the x and y coordinates have to be integral) and which lie within or on the boundary of the object. For a composite object, the points used are the union of all the points contained by the composite object's members.
#include "IWGrCC.h"
int IWRtObjGC(IWGrHeaderID headerID, IWGrObjID objID,
int dtype, IW_POINT* pt);
If headerID does not refer to a valid object list, objID does not refer to a valid object, or there was insufficient resources to resolve the references, IWRtObjGC returns IW_ERROR and does not modify the coordinates of *pt. Otherwise, IWRtObjGC returns IW_SUCCESS and sets the coordinates of *pt equal to the coordinates of the unweighted mean of the set of points drawn from the object referred to by objID. When dtype is IWOBJ_DATA_SP, the coordinates of *pt are reported in "data space". If dtype is IWOBJ_REAL_SP, the coordinates are reported in "real space".
Retrieves the coordinate system and bounds associated with an object list.
#include "IWGrCC.h"
int IWRtObjHdr(IWGrHeaderID headerID, int nxyzwt[],
float delt[], float tilt[], float orig[],
int xyzst[]);
IWRtObjHdr returns IW_ERROR and does not modify the contents of nxyzwt, delt, tilt, orig, and xyzst if the object list referred to by headerID is invalid or a coordinate system and bounds have not been established for that object list with a previous call to IWInitObjHdr. Otherwise, IWRtObjHdr returns IW_SUCCESS and fills nxyzwt, delt, tilt, orig, and xyzst with the bounds and coordinate system information for the object list referred to by headerID. The meanings of the elements of nxyzwt, delt, tilt, orig, and xyzst are the same as described in the documentation for IWInitObjHdr.
Computes the sum of intensities at a set of points within an object. For an object created by IWAreaObj or IWPtsObj, the point used are the points that define the object. For an object which is non-composite and was not created by IWAreaObj or IWPtsObj, the points used are those points which have integral coordinates in the object's preferred coordinate convention (for 2D objects, only the x and y coordinates have to be integral) and which lie within or on the boundary of the object. For a composite object, the points used are the union of all the points contained by the composite object's members.
#include "IWGrCC.h"
float IWRtObjInt(IWGrHeaderID headerID, IWGrObjID objID,
int istr);
If headerID does not refer to a valid object list, objID does not refer to a valid object, or there was insufficient resources to resolve the references, IWRtObjInt returns IW_ERROR. Otherwise, returns the sum of the intensities from the IM library stream, istr, at the points within the object that fall within the bounds of that data set. if no points vall within the bounds of that data set or memory for the data set images could not be allocated, returns zero.
Constructs a list of the names of all the object lists currently in memory.
#include "IWGrCC.h"
char** IWRtObjListNames(void);
Returns an array of pointers to the names (null-terminated) of the object lists currently in memory. When the application is finished with the array of names, it should call free() with the pointer returned to release the memory.
Returns the number of composite objects to which an object belongs.
#include "IWGrCC.h"
int IWRtObjLnCount(IWGrHeaderID headerID, IWGrObjID objID);
If headerID is not a reference to a valid object list or objID is not a reference to a valid object or is a reference to a composite object, IWRtObjLnCount returns IW_ERROR; otherwise, IWRtObjLnCount returns the number of composite objects of which the object referred to by objID is a member.
Retrieves the name associated with an object.
#include "IWGrCC.h"
int IWRtObjName(IWGrHeaderID headerID, IWGrObjID objID,
char* name);
Returns IW_ERROR if the object list referred to by headerID is not valid or the object referred to by objID is not valid; otherwise, returns IW_SUCCESS and fills the memory pointed to by name with the null-terminated name associated with the object referred to by objID. For reliable operation, name must point to memory with room for at least MAX_OBJ_FILE_NAME_SIZE characters (including the terminating null).
Retrieves the coordinates of the control points for an object.
#include "IWGrCC.h"
int IWRtObjPts(IWGrHeaderID headerID, IWGrObjID objID,
int space, IW_POINT** pts, int* pt_num, int* iwave,
int* itime);
IWRtObjPts returns IW_ERROR if the object list referred to by headerID is not valid, the object referred to by objID is not valid, or there were insufficient resources for resolving references. In that case, IWRtObjPts sets *pts, *pt_num, *iwave, and *itime to zero. If the object list referred to by headerID is valid and the object referred to by objID is valid, IWRtObjPts stores the wavelength index of the object in *iwave, the time point index of the object in *itime, and the number of control points in the object in *pt_num. If the number of control points is zero, IWRtObjPts sets *pts to zero and returns IW_SUCCESS. If the number of control points is not zero but there were insufficient resources to allocate space for the control point coordinates, IWRtObjPts sets *pts to zero and returns IW_ERROR. If the number of control points is not zero and IWRtObjPts could allocate space for the coordinates, IWRtObjPts sets *pts to point to the array of coordinates. When you are finished with the coordinates, you should call free() with the value of *pts to release the memory used for the array. If space is IWOBJ_REAL_SP, IWRtObjPts reports the coordinates in "real space"; otherwise, IWRtObjPts reports the coordinates in "data space".
Returns a reference to the first non-composite object that has a control point within a given distance of a specified point.
#include "IWGrCC.h"
IWGrObjID IWRtObjPtSelected(IWGrHeaderID headerID, int space,
IW_POINT pt, int wave, int time, int max_dist,
int* pt_num);
Returns a reference to the first non-composite object in the object list referred to by headerID that has a control point within a distance, max_dist, of the point, pt, and is in the wavelength with index wave and the time point with index time. space controls how the coordinates of pt are interpreted and the units of max_dist. If space is IWOBJ_DATA_SP, the point is assumed to be in "data space" and the distance in pixels. If space is IWOBJ_REAL_SP, the point is assumed to be in "real space" and the distance in the units of the pixel spacing. If headerID does not refer to a valid object list, a coordinate system has not been established for the object list, there was no object matching the given criteria, or resources could not be allocated for the reference, IWRtObjPtSelected will return zero and set *pt_num to zero. Otherwise, IWRtObjPtSelected will set *pt_num to the zero-based index of the first control point in the object that is within a distance, max_dist, of the point, pt.
Computes the bounding box for an object.
#include "IWGrCC.h"
int IWRtObjRange(IWGrHeaderID headerID, IWGrObjID objID,
int space, float range[10]);
If headerID does not refer to a valid object list, objID does not refer to a valid object, or there was insufficient resources to resolve the references, IWRtObjRange returns IW_ERROR and does not modify the values of range. Otherwise, IWRtObjRange returns IW_SUCCESS and returns the bounding box in range:
If space is IWOBJ_DATA_SP, the x, y, and z values for the bounding box are reported in "data space". If space is IWOBJ_REAL_SP, the x, y, and z values for the bounding box are reported in "real space".
Constructs a list of references to objects which match criteria based on object type and bounding box.
#include "IWGrCC.h"
int IWRtObjs(IWGrHeaderID headerID, int type_mask,
int space, const float range[10], IWGrObjID** obj_list,
int* nobj);
Given the object list referred to by headerID, IWRtObjs constructs a list of references to objects from that list. It sets *obj_list to point to the array of object references in the constructed list and *nobj to the number of objects in the constructed list. All objects in the constructed list have an object type which matches an object type included in type_mask. type_mask should be a bitwise-or of one or more of the following values:
Also, any object in the constructed list falls within the bounds specified by range. If range[0] is IWOBJ_RANGE_ALL, no object is excluded from the constructed list on the basis of the object's x, y, or z bounds; an object will be excluded from the constructed list if its wavelength index or time point index does not fall in the bounds set previously set for the object list with a call to IWInitObjHdr. Otherwise, an object is only included if its bounding box fits within the bounding box specified by the elements of range. For an object to be included in the constructed list, it must satisfy the conditions listed below. If the coordinate convention used for the object matches that given by space (IWOBJ_DATA_SP for "data space" or IWOBJ_REAL_SP for "real space"), the elements of bound are equal to the elements of range. If the coordinate convention used for the object does not match that given by space, bound[0], bound[2], and bound[4] are equal to the x, y, and z coordinates, respectively, of the result of converting the point, (range[0], range[2], range[4]), to the object's coordinate convention; bound[1], bound[3], and bound[5] are equal to the x, y, and z coordinates respectively, of the result of converting the point (range[1], range[3], range[5]) to the object's coordinate convention; bound[6], bound[7], bound[8], and bound[9] are equal to range[6], range[7], range[8], and range[9], respectively.
If the object list referred to by headerID is not valid, the object list does not have an established coordinate system and bounds, or there were insufficient resources to construct the list, IWRtObjs returns IW_ERROR and sets *obj_list and *nobj to zero. Otherwise, IWRtObjs returns IW_SUCCESS and sets *obj_list to point to the array of objects and *nobj to the number of elements in the array. In that case, you should call free() with the value of *obj_list when you no longer need the array.
Returns a reference to the first non-composite object whose boundaries contain a given point.
#include "IWGrCC.h"
IWGrObjID IWRtObjSelected(IWGrHeaderID headerID, int space,
IW_POINT pt, int wave, int time);
Returns a reference to the first non-composite object in the object list referred to by headerID whose boundaries enclose the point, pt, and is in the the wavelength with index wave and the time point with index time. space controls how the coordinates of pt are interpreted. If space is IWOBJ_DATA_SP, the point is assumed to be in "data space. If space is IWOBJ_REAL_SP, the point is assumed to be in "real space". If headerID does not refer to a valid object list, a coordinate system has not been established for the object list, there was no object enclosing the point, or resources could not be allocated for the reference, IWRtObjSelected will return zero. For compatibility with the behavior of the IVE 3.3 version, IWRtObjPtSelected will never return a reference to an object created with a call to IWAreaObj, IWCircleObj, IWPtsObj, or IWSphereObj.
Returns an object's type (box, circle, etc.).
#include "IWGrCC.h"
int IWRtObjType(IWGrHeaderID headerID, IWGrObjID objID);
Returns IW_ERROR if the object list referred to by headerID is not valid or the object referred to by objID is not valid; otherwise, returns an integer describing the type of object referred to by objID. The integer will have one of the values listed below.
Computes the number of points with an object. For an object created by IWAreaObj or IWPtsObj, the point used are the points that define the object. For an object which is non-composite and was not created by IWAreaObj or IWPtsObj, the points used are those points which have integral coordinates in the object's preferred coordinate convention (for 2D objects, only the x and y coordinates have to be integral) and which lie within or on the boundary of the object. For a composite object, the points used are the union of all the points contained by the composite object's members.
#include "IWGrCC.h"
float IWRtObjVol(IWGrHeaderID headerID, IWGrObjID objID);
If headerID does not refer to a valid object list, objID does not refer to a valid object, or there was insufficient resources to resolve the references, IWRtObjVol returns IW_ERROR. Otherwise, IWRtObjVol returns the number of points within the object referred to by objID.
Saves an object list to a file.
#include "IWGrCC.h"
int IWSaveObjList(IWGrHeaderID headerID, const char* filename);
Saves the object list referred to by headerID to the file with the name given by the null-terminated string filename. IWSaveObjList returns IW_SUCCESS if the object list referred to by headerID is valid, the object has an established coordinate system, and the object list was successfully written to the file; otherwise, IWSaveObjList returns IW_ERROR.
Creates an object representing a sphere.
#include "IWGrCC.h"
IWGrObjID IWSphereObj(IWGrHeaderID headerID, IW_POINT center,
int iwave, int itime, float radius, int space,
int color);
Defines a sphere by its center point, center, and a radius, radius. The sphere lies in the wavelength whose zero-based index is given by iwave and the time point whose zero-based index is given by itime. If space is IWOBJ_DATA_SP, the coordinates are assumed to be in pixel units (i.e. grid space); if space is IWOBJ_REAL_SP, the coordinates are assumed to be in "real space". Using pixel units for the coordinates is problematic if the pixel spacing is not isotropic (i.e. then a sphere in pixel coordinates is not a sphere in real coordinates). color specifies the color index to be used when displaying the rectangle. Returns zero if the object list referred to by headerID is not valid, the object list has not had a coordinate system established, or it was not possible to allocate resources for the new object; otherwise, returns a reference to the new object.