DATAMANIP (kdatamanip) functions


LIBRARY ROUTINE

lkextract - extract rectangular region from data object

LIBRARY CALL

int lkextract(
   kobject src_obj,
   int    w_off,
   int    h_off,
   int    d_off,
   int    t_off,
   int    e_off,
   int    w_size,
   int    h_size,
   int    d_size,
   int    t_size,
   int    e_size,
   int    subpos,
   kobject dst_obj)

INPUT

OUTPUT

RETURN VALUE

TRUE (1) on success, FALSE (0) on failure

DESCRIPTION

Library Routine for kextract.

Lkextract is based on implicit indexing. This means that if location or time data exist, the extract operation is not done in terms an interpretation of the location/time data values, but in terms of the implicit indexing of these data (which is specified by the width, height, depth, time, elements indices of the polymorphic data model).

Lkextract extracts from the source data object (src_obj) a region specified by the w_size, h_size, d_size, t_size, and e_size parameters and places the extracted data into the corresponding segment(s) in the destination object (dst_obj). The region will be extracted starting at the point defined by (w_off, h_off, d_off, t_off, e_off). This point will be the origin (0,0,0,0,0) of the destination object. The size attributes of the destination object's segment(s) are set according to the <dimension>_size input parameters.

If the source data object has mask, location, time, and/or value data segments, the specified region is extracted from each existing segment in the source and placed in the corresponding segment of the destination object. If the segment does not already exist in the destination object, it will be created.

If the offset (defined by w_off, h_off, d_off, t_off, e_off) and/or the extracted region size, fall outside the indexing bounds, or size, of the data segments, the object segments will be padded with the values pad value attribute of the source object, which can be set prior to calling lkextract.

If the destination object contains segments not present in the source object, they will automatically be resized according to the size input parameters (to maintain the integrety of the data with respect to the polymorphic data model). The offset will be the origin (0,0,0,0,0), not the. offset values passed in. If padding of these segments is necessary, the padding values will be determined from the pad attribute of the destination object, which can be set prior to calling lkextract.

If the subpos parameter is TRUE, lkextract sets the KPDS_SUBOBJECT_POSITION attribute of the destination object to the subregion origin coordinates (w_off, h_off, d_off, t_off, e_off). If subpos is FALSE, the KPDS_SUBOBJECT_POSITION is set to (0,0,0,0,0).

Error Checks: The size parameters passed in must be greater than zero, lkextract will fail if they are not. Lkextract will also fail if the source and destination objects passed in are not valid. Any offset value is legal.

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

Only operates on value, mask, location, and time segments.

MODIFICATION

none

FILES

$DATAMANIP/objects/library/kdatamanip/src/lkextract.c

SEE ALSO

kdatamanip(3)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.