Icont Module

Header to include: icont.h

General Contour Manipulation

Simple Contour Get/Set Functions

Contour Information Functions

Contour-modifying Functions

Advanced Functions (Scan Contours, Overlap, Nesting)

General Contour Manipulation

Icont *imodContourNew(void)

Creates one new contour and initializes it to default values.  Returns NULL if error.

Icont *imodContoursNew(int size)

Creates an array of size contours and initializes them to default values. Returns NULL if error.

void imodContourDefault(Icont *cont)

Initializes cont to default values for an empty contour.

int imodContourCopy(Icont *from, Icont *to)

Copies the contour structure in from to to without copying any data. Returns -1 if error.

Icont *imodContourDup(Icont *cont)

Creates a new contour containing the same point, size, and label data as cont.  Returns NULL if error.

int imodContourDelete(Icont *cont)

Deletes cont, freeing all data and the contour structure.  Returns -1 if error (i.e., cont is NULL).

int imodContourClear(Icont *cont)

Frees all data in contour cont and sets its pointers to NULL.  Returns -1 if error

int imodContourClearPoints(Icont *cont)

Frees just the point data in contour cont and sets the pointer for point data to NULL and the point count to 0.  Returns -1 if error.

int imodContoursDelete(Icont *cont, int size)

Deletes an array of size contours in cont, freeing all data and the array itself.  Returns -1 if error (i.e., cont is NULL).

int imodContoursDeleteToEnd(Iobj *obj, int keep)

Deletes contours from object obj, retaining keep.  The contour data are freed and the contour array is reallocated to the new size.  Returns -1 if error.

int imodel_contour_newsurf(Iobj *obj, Icont *cont)

Assigns a new surface number to contour cont and adjusts the maximum surface number for obj, the object that it is in.  Returns -1 if error.

int imodel_unused_surface(Iobj *obj)

Finds the first unused surface number in object obj, and returns this number or 0 for an error.

void imodel_contour_check_wild(Icont *cont)

Sets the wild flag in contour cont (ICONT_FLAG in cont->flags) if Z is not the same for all points when rounded to the nearest integer.  cont can be NULL.

Simple Contour Get/Set Functions

Ilabel *imodContourGetLabel(Icont *inContour)

Returns pointer to the label structure of inContour or NULL if no contour or label

void imodContourSetLabel(Icont *inContour, Ilabel *inLabel)

Sets the label pointer of inContour to inLabel after freeing an existing label if any

int imodContourGetMaxPoint(Icont *inContour)

Returns the number of points in inContour

Ipoint *imodContourGetPoints(Icont *inContour)

Returns pointer to the point array of inContour, or NULL if none

void imodContourSetPointData(Icont *inContour, Ipoint *inPoint, int inMax)

Sets the point array of inContour to inPoint and sets the number of points to inMax

Ipoint *imodContourGetPoint(Icont *inContour, int inIndex)

Returns pointer to point inIndex of inContour or NULL for error

int imodContourGetTimeIndex(Icont *inContour)

Returns the time value of inContour, or 0 if no contour

void imodContourSetTimeIndex(Icont *inContour, int inTime)

Sets the time value of inContour to inTime

int imodContourGetSurface(Icont *inContour)

Returns the surface number of inContour, or 0 if no contour

void imodContourSetSurface(Icont *inContour, int inSurface)

Sets the surface number of inContour to inSurface

void imodContourSetFlag(Icont *inContour, unsigned int inFlag, int inState)

Sets bit flags defined by inFlag in the flag element of inContour to the off if inState is 0 or on if inState is nonzero.

int imodContourGetFlag(Icont *inContour, unsigned int inFlag)

Returns the value of the bit flags defined by inFlag in the flag element of inContour

char *imodContourGetName(Icont *inContour)

Returns pointer to name string of inContour, or to empty string if none

int imodContourPointIsGap(Icont *inContour, int index)

Returns 1 if the point at index in inContour is defined as a gap in the contour store or if it is at the end of an open-type contour.

Contour Information Functions

float imodContourArea(Icont *cont)

Returns area of contour cont in square pixels.  The contour need not be COplanar.  The area is computed as half the magnitude of the sum of cross-products of adjacent line segments.

int imodel_contour_area(Icont *icont)

Returns area of contour cont in the X/Y plane in square pixels, or 0 for an error.  Area is measured by converting to a scan contour and summing the length of the scan lines.  Used (only) by imodContourCircularity.

float imodContourLength(Icont *cont, int closed)

returns length of contour cont in pixels, including the distance from ending to starting point if closed is non-zero.  Returns -1 for error.

double imodel_contour_length(Icont *cont)

Returns length of contour cont, excluding a connection between last and first points, or -1 if error.

double imodContourMoment(Icont *cont, int a, int b)

Returns a moment of the contour cont relative to the origin, where the order of the moment is a in X and b in Y.  It computes the sum x**a * y**b over all pixels within the contour.  cont can be scan contour; if it is not, a temporary scan contour is generated.  Returns 0 for error. Unused as of 12/7/17.

int imodContourCenterOfMass(Icont *cont, Ipoint *rpt)

Computes the center of mass of contour cont and returns the result in rpt.  The contour is assumed to lie in the X/Y plane.  Returns 0 for success, -1 for an error, or 0 if the cont is NULL or has no points, in which case rpt is 0,0,0. cont can be a scan contour; if not, a temporary scan contour is made.  Calls imodel_contour_centroid.

int imodel_contour_centroid(Icont *icont, Ipoint *rcp, double *rtw)

Computes components of the centroid of contour icont.  If ICONT_TEMPUSE is not set in the flags element of icont, it treats the contour as coming from a closed contour object and assumes it is confined to the X/Y plane, and returns the sum of pixel locations inside the contour in rcp and the pixel sum, or area, in rtw.  The input contour can be a scan contour; if not, a temporary scan contour is made. If ICONT_TEMPUSE is set, it treats it as coming from an open contour object and returns the sum of pixel locations along the contour in rcp and the contour length in rtw.  In either case the centroid is rcp->x/rtw, rcp->y/rtw, rcp->z/rtw.  Returns -1 for error.

double imodContourCenterMoment(Icont *cont, Ipoint *org, int a, int b)

Returns the moment of contour cont of order a in X and order b in Y, relative to the point org.  Computes (x - org->x)**b * (y - org->y)**a over all pixels inside the contour.  cont can already be a scan contour; if not, a temporary scan contour is generated.  Returns 0 for error.

int imodContourEquivEllipse(Icont *cont, Ipoint *center, float *longAxis, float *shortAxis, float *angle)

Computes an ellipse whose moments are the same as the area inside contour cont, which is assumed to be planar, and returns the center position in center, the a and b parameters for long and short axes in longAxis and shortAxis, and the orientation of the long axis, in degrees between 0 and 180, in angle.  Returns 1 for error, including having a contour with less than 3 points.  Although cont can already be a scan contour, accuracy will be higher if it is not, because a scan contour is created after scaling the contour up by a factor of 4.

double imodContourCircularity(Icont *cont)

Returns the circularity of a closed contour, based on perimeter squared to area.  A perfect circle = 1.0, a square = 1.27.  Returns 1000. for error or zero area contour.

double imodContourLongAxis(Icont *cont, float precision, float *aspect, float *longaxis)

Measures the angle at which the contour is most elongated, to the precision set by precision, in degrees.  It simply rotates the contour, looking for the bounding box with the greatest ratio of height to width. Returns the angle to the long axis in radians, or 0 for an error. Returns the ratio of long to short axis in aspect, and the length of the long axis in longaxis.

int imodContourFitPlane(Icont *cont, Ipoint *scale, Ipoint *norm, float *dval, double *alpha, double *beta)

Fits a plane to the contour cont, where points are scaled by scale. For a plane equation Ax + By + Cz + D = 0, the normal (A,B,C) is returned in norm, and D is returned in dval.  The rotations (in radians) around the Y axis then the X axis that will make the plane be flat are returned in beta and alpha.  Returns 1 if there are too few points in the contour or if the points are too close to colinear.

int imodContourGetBBox(Icont *cont, Ipoint *ll, Ipoint *ur)

Calculates the full 3D bounding box of contour cont and returns the lower left, bottom coordinates in ll and the upper right, top coordinates in ur.  Returns -1 if error.

int imodContourZValue(Icont *cont)

Computes the mean Z value of a contour and rounds to nearest integer, or returns -1 if no contour or no points

float imodContourFloatZValue(Icont *cont)

Computes the mean Z value of a contour or returns -1.e20 if no contour or no points

int imodContZDirection(Icont *cont)

Determines whether contour cont is clockwise or counter-clockwise and returns IMOD_CONTOUR_CLOCKWISE or IMOD_CONTOUR_COUNTER_CLOCKWISE, or 0 for an error an a contour with no area.

int imodel_contour_on(Icont *cont, int x, int y)

Returns non-zero if (x, y) is in point list of contour cont, or 0 if it is not.  (unused 4/22/05)

int imodContourNearest(Icont *cont, Ipoint *pnt)

Returns the index of the point in contour cont that is nearest in 3D to point pnt, or -1 for an error.

int imodel_contour_nearest(Icont *cont, int x, int y)

Returns the index of the point in contour cont that is nearest in X and Y to (x, y), or -1 for an error.

int imodContourInsideCont(Icont *inner, Icont *outer)

Returns 1 if contour inner is completely inside or touching contour outer, otherwise returns 0.

Contour-modifying Functions

Icont *imodContourJoin(Icont *c1, Icont *c2, int st1, int st2, int fill, int counterdir)

Joins two contours c1 and c2 by adding a connecting lines between them and arranging points from the two contours into a single path.
If st1 and st2 are >=0 the contours will be joined at points st1 and st2; if either one is negative they will be joined at their nearest points.
If fill is  1 or -1, a point will be placed in the middle of the connector at 0.75 pixels up or down in Z, respectively.  The fill point will be given the general storage properties of the preceding point in the contour.
If counterdir is nonzero the two contours will be made to go in opposite directions before being joined.  
If fill is 0, then it will separate the two connecting lines to leave an open channel between the contours, moving them each back up to 1 pixel from being in the same position.  Otherwise, the two connecting lines overlap.  This is needed for meshing, which is why the fill value prevents the separation.  If fill is greater than 10, the width of the channel will be fill - 10 pixels. If fill is any non-zero value besides 1 or -1 up to 10, it will not separate the connecting lines, which is useful for polygon fill drawing.

Icont *imodContourSplice(Icont *c1, Icont *c2, int p1, int p2)

Returns a contour with points 0 to p1 from contour c1 and points from p2 to the end from contour c2.

Icont *imodContourScanAdd(Icont *c1, Icont *c2)

Adds together two scan contours c1 and c2, returning all of their segments in order and combining segments where they overlap.  Returns NULL for error.

Icont *imodContourBreak(Icont *cont, int p1, int p2)

Returns a contour containing points from p1 to p2, inclusive, from contour cont, and removes those points from cont.  If p2 is < 0 all points from p1 to the end are transferred to the new contour.  Returns NULL if error.

int imodel_contour_sortx(Icont *cont, int bgnpt, int endpt)

Sorts points in contour cont from index bgnpt through index endpt by their X coordinates; preserves sizes but not label indexes. Returns -1 for error.  Used (only) by imodel_contour_scan.

int imodel_contour_sorty(Icont *cont, int bgnpt, int endpt)

Sorts points in contour cont from index bgnpt through index endpt by their Y coordinates; preserves sizes but not label indexes. Returns -1 for error.  (Unused 4/22/05)

int imodel_contour_sortz(Icont *cont, int bgnpt, int endpt)

Sorts points in contour cont from index bgnpt through index endpt by their Z coordinates; preserves sizes but not label indexes. Returns -1 for error.  Used in 3dmod.

int imodContourSort3D(Icont *cont, Ipoint *scale)

Sorts points in contour cont by proximity, using the scale factors in scale to evaluate distances in 3D.  Starting from the first point, it makes the closest point be the next point, then moves on to the next point and makes the closest among the remaining points be the next point. It then runs a second pass in the opposite direction.  It preserves sizes but not label indexes.  Returns -1 for error.  Used by 3dmod.

int imodel_contour_sort(Icont *cont)

Sorts points in contour cont by proximity in the X/Y plane, by calling imodContourSort3D with a scale of 1,1,0.  Returns -1 for error.  Maintained for consistency with previous behavior of this sort function.

int imodel_contour_invert(Icont *cont)

Inverts the order of points in contour cont; preserves points sizes and labels.  Returns -1 for error.

void imodContourReduce(Icont *cont, float tol)

Reduces the points in contour cont by selecting a minimal subset of the points.  Each of the original points will be within a tolerance tol of the segments defined by the remaining points.

int imodContourShave(Icont *cont, double dist)

Removes points from contour cont whose distance from both the previous and the next point is less than dist.  Returns -1 for error. See imodContourReduce, which will preserve structure better.

int imodContourUnique(Icont *cont)

Removes adjacent duplicate points from contour cont. Returns non-zero for error.

int imodContourStrip(Icont *cont)

Removes points that are not needed in contour cont; specifically, if three sequential points are colinear it removes the middle one.  Returns 0.

void imodel_contour_whole(Icont *cont)

Rounds off X/Y point coordinates of contour cont to the nearest integer.

void imodContourFlatten(Icont *cont)

Sets the Z values of all points in the contour to the mean Z value rounded to the nearest integer

void imodContourScale(Icont *cont, Ipoint *spoint)

Scales all point values in contour cont by spoint.  (Unused 4/22/05)

void imodContourRotateZ(Icont *cont, double rot)

Rotates contour cont in the X/Y plane about the origin by angle rot in radians.

void imodContourMakeDirection(Icont *cont, int direction)

Sets the direction of the contour cont to the value of direction, either IMOD_CONTOUR_CLOCKWISE or IMOD_CONTOUR_COUNTER_CLOCKWISE.

Advanced Functions (Scan Contours, Overlap, Nesting)

Icont *imodel_contour_scan(Icont *incont)

Creates a scan contour from contour incont and returns pointer to it, or NULL for an error.  A scan contour consists of pairs of points at the starts and ends of horizontal lines.  The pairs are in order by increasing Y, and by increasing X at each Y level.  Z coordinates are ignored, except that the Z coordinate of the first point on incont is transferred to the first point of the scan contour.

int imodel_contour_overlap(Icont *c1, Icont *c2)

Returns 1 if contour c1 overlaps contour c2 when projected onto the X/Y plane.  Returns 0 if not, or if an error occurs.

int imodel_scans_overlap(Icont *cs1, Ipoint pmin1, Ipoint pmax1, Icont *cs2, Ipoint pmin2, Ipoint pmax2)

Returns 1 if scan contour c1 overlaps scan contour c2. Returns 0 if not, or for an error.

int imodel_overlap_fractions(Icont **cs1p, Ipoint pmin1, Ipoint pmax1, Icont **cs2p, Ipoint pmin2, Ipoint pmax2, float *frac1, float *frac2)

Returns 1 if there is overlap between the contours whose addresses are pointed to by cs1p and cs2p, and returns fractions of each contour's area that overlaps in frac1 and frac2.  The bounding boxes of the contours must be provided in in pmin1, pmax1, pmin2, and pmax2. If the contours are already scan contours, they are unchanged.  If they are not scan contours and their bounding boxes do not overlap, the contours are converted to scan contours and the address of the scan contour is placed into cs1p and/or cs2p.  This allows scan conversions to be done only when needed.  Returns 0 for no overlap or error.

void imodContourSwap(Icont *c1, Icont *c2)

Swaps the values in two contour structures c1 and c2 (Unused 4/22/05)

int imodContourMakeZTables(Iobj *obj, int incz, unsigned int clearFlag, int **contzp, int **zlistp, int **numatzp, int ***contatzp, int *zminp, int *zmaxp, int *zlsizep, int *nummaxp)

Makes tables for object obj of contour z values, number and contours at each z value.  Returns -1 if error.
incz = Z increment
clearFlag = a flag to clear in cont->flags
contzp = pointer to array for Z values, which is allocated for the number of contours
zlist = pointer to returned array for list of z values
numatzp = pointer to returned array for number of contours at each Z
contatzp = pointer to returned array of int pointers to list of contours at each Z
zminp, zmaxp = pointers for return values of minimum and maximum Z
zlsizep = pointer for return value of size of list of Z values
nummaxp = pointer for return value of maximum contours on any section
The arrays for zlist, numatzp, and contatzp are allocated to have zmax + 2 - zmin elements and would be indexed by z - zmin for z between zmin and zmax, exclusive.

void imodContourFreeZTables(int *numatz, int **contatz, int *contz, int *zlist, int zmin, int zmax)

Frees the tables of contour Z values, number and contours at Z created by imodContourMakeZTables

int imodContourCheckNesting(int co, int eco, Icont **scancont, Ipoint *pmin, Ipoint *pmax, Nesting **nests, int *nestind, int *numnests, int *numwarn)

Checks for one contour inside another and maintains nesting structures
co, eco = contour numbers that are indexes into arrays here, not the original contour numbers in the object  
scancont = pointer to array of scan contours, which must already exist  
pmin, pmax = arrays of minimum and maximum points (bounding boxes)
nests = pointer to array of nesting structures, which will be built up over repeated calls and should not start out pointing to anything, but need not start out NULL
nestind = array for index from contours to nests, which must be allocated for the maximum contour number that this is called with plus 1 and initialized to -1
numnests = pointer to number of nests found, which must be initialized to 0
numwarn = pointer to flag for warning on contour overlap: -1 for no warnings, 0 for warnings, becomes 1 after first warning

void imodContourFreeNests(Nesting *nests, int numnests)

Frees the array of numnests nests in nests and their internal arrays

void imodContourNestLevels(Nesting *nests, int *nestind, int numnests)

Analyzes inside and outside contours to determine level. nests is an array of numnests nesting structures, nestind is an array with indexes from contours to nests.