[Artwork] / [QisMLib]

QisMClipExtract Extension

A QisMLib extension to extract tiny clips from a database as polygons or images

QisMClipExtract C++ API (qismclipextract.h)

QisMClipExtractFlags

Various enumerated constants used by the QisMClipExtract API

struct QisMClipExtractFlags { ... };

ImageFormat

Format for image extraction

xxxxxxxxxx
enum ImageFormat
{
  RBUF=1, /* Do not write to disk */
  TIFF=2, /* Write to disk as a monochrome TIFF file with packbits compression (.tif) */
  BMP=3, /* Write to disk as an uncompressed monochrome top-down BMP file (.bmp) */
  RAW=4 /* Write to disk as-is with a small header for information (.raw) */
  /* RAW Format --------------------------------------------------------------
  'L''G''R''A''W''0''0'<width-in-pixels><height-in-pixels><image-bytes-size>
  <image-bytes>
  ----------------------------------------------------------------------------
  <width-in-pixels> : 4 bytes 
  <height-in-pixels> : 4 bytes
  <image-bytes-size> : 8 bytes
  <image-bytes> : <image-bytes-size> bytes
  --------------------------------------------------------------------------*/
  ,VBMP=5 /* Write to disk as an uncompressed monochrome bottom-up BMP file (.bmp) */
};

PolygonFormat

Format for polygon extraction

xxxxxxxxxx
enum PolygonFormat
{
  PBUF=1, /* Do not write to disk */
  GDSII=2, /* Write to disk as GDSII format (.gds) */
  OASIS=3 /* Write to disk as OASIS format (.oas) */
};

QisMClipExtractImageInfo

An object API to store and access raster image information

xxxxxxxxxx
class QisMClipExtractImageInfo { ... };

Object_name

Get implementation name and version

xxxxxxxxxx
virtual const char* Object_name() const = 0;

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied). The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMClipExtractImageInfo_cast(const int version) = 0;
virtual const void* QisMClipExtractImageInfo_cast(const int version) const = 0;
virtual int QisMClipExtractImageInfo_latest_version() const = 0;

Set_data_extents

Data_extents_llx

Data_extents_lly

Data_extents_urx

Data_extents_ury

Set/Get image data extents -- lower-left and upper-right points (in file units)

xxxxxxxxxx
virtual void Set_data_extents(
  const double llx, const double lly, const double urx, const double ury
  ) = 0;
virtual double Data_extents_llx() const = 0;
virtual double Data_extents_lly() const = 0;
virtual double Data_extents_urx() const = 0;
virtual double Data_extents_ury() const = 0;

Set_image_extents

Image_extents_llx

Image_extents_lly

Image_extents_urx

Image_extents_ury

Set/Get image data extents -- lower-left and upper-right points (in pixels)

xxxxxxxxxx
virtual void Set_image_extents(
  const int llx, const int lly, const int urx, const int ury
  ) = 0;
virtual int Image_extents_llx() const = 0;
virtual int Image_extents_lly() const = 0;
virtual int Image_extents_urx() const = 0;
virtual int Image_extents_ury() const = 0;

Set_image_size

Get_image_size

Set/Get image size (in bytes)

xxxxxxxxxx
virtual void Set_image_size(const long long size) = 0;
virtual long long Get_image_size() const = 0;

Set_counts

Counts_p

Counts_pv

Set/Get number of polygons and polygon vertices used to generate the raster image

• nP : No. polygons

• nPv : No. polygon vertices (total)

xxxxxxxxxx
virtual void Set_counts(const long long nP, const long long nPv) = 0;
virtual long long Counts_p() const = 0;
virtual long long Counts_pv() const = 0;

Set_pixelsize

Pixelsize_x

Pixelsize_y

Set/Get image resolution in form of size of 1 pixel (in file units) along X and Y axes.

• x : Size of a pixel along X

• y : Size of a pixel along Y

xxxxxxxxxx
virtual void Set_pixelsize(const double x, const double y) = 0;
virtual double Pixelsize_x() const = 0;
virtual double Pixelsize_y() const = 0;

DPI_x

DPI_y

Get image resolution in form of dots-per-inch along X and Y axes (from pixelsize)

• unitsInM : Size of the file units in meter (e.g 1 micron = 1e-6 meter)

xxxxxxxxxx
virtual double DPI_x(const double unitsInM) const = 0;
virtual double DPI_y(const double unitsInM) const = 0;

QisMClipExtractPolySet

xxxxxxxxxx
class QisMClipExtractPolySet { ... };

An object API to access a set of polygons

Object_name

Get implementation name and version

xxxxxxxxxx
virtual const char* Object_name() const = 0;

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied). The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMClipExtractPolySet_cast(const int version) = 0;
virtual const void* QisMClipExtractPolySet_cast(const int version) const = 0;
virtual int QisMClipExtractPolySet_latest_version() const = 0;

Num_poly

Get number of polygons in the set

xxxxxxxxxx
virtual size_t Num_poly() const = 0;

Num_vertices

Get number of polygon vertices in the set

xxxxxxxxxx
virtual size_t Num_vertices() const = 0;

NV_array

Get the number of vertices per polygon as a contiguous array of integers

• The size of NV_array() is Num_poly() integers

• The number of x,y pairs for a given polygon i (0 <= i < Num_poly()) is determined by (NV_array())[i]

• The number of integer values for a given polygon = 2 * number of x,y pairs

• The last co-ordinate it identical to the first since the polygons is closed (A rectangle has 5 x,y pairs or 10 values)

• If Num_poly() == 0, return is NULL

xxxxxxxxxx
virtual const int* NV_array() const = 0;

XY_array

Get the list of xy co-ordinates for all the polygons as a contiguous array of x,y pairs

• The number of x,y pairs for a given polygon i (0 <= i < Num_poly()) is determined by (NV_array())[i]

• The number of integer values for a given polygon = 2 * number of x,y pairs

• The last co-ordinate it identical to the first since the polygons is closed (A rectangle has 5 x,y pairs or 10 values)

• If Num_poly() == 0, return is NULL

xxxxxxxxxx
virtual const int* XY_array() const = 0;

XY_array_index

Get the index of a particular polygon in array returned by XY_array()

• pNumber : polygon number (0 <= pNo < Num_poly())

• Success : index >= 0

• Failure : < 0. Invalid polygon number (pNumber < 0 or pNumber >= Num_poly())

• The index returned here is the position of the first x co-ordinate for a particular polygon in XY_array()

• (NV_array())[pNumber] is the number of x,y pairs in that particular polygon

• The next polygon is located at index + (NV_array())[pNumber] in XY_array()

xxxxxxxxxx
virtual int XY_array_index(const int pNumber) const = 0;

QisMClipExtractNotify

API for the ClipExtract notifications handler (callback client)

xxxxxxxxxx
class QisMClipExtractNotify { ... };

Version Control

Cast a pointer to your handler to any type in the QisMClipExtractNotify hierarchy using the version number

• The version of a class is embedded in the name in form of a suffix V

• The version of the topmost base class is 1

• E.g if QisMClipExtractNotify is the topmost base class (version 1), QisMClipExtractNotifyV2 QisMClipExtractNotifyV3 etc. would be the future extensions of QisMClipExtractNotify

• Return NULL if the version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMClipExtractNotify_cast(const int version) = 0;
/* PLEASE ADD THE FOLLOWING IMPLEMENTATION IN YOUR HANDLER { 
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<QisMClipExtractNotify*>(this);
    //Add more casts based on the implementation of your handler
  }
  return 0;
} */
virtual const void* QisMClipExtractNotify_cast(const int version) const = 0;
/* PLEASE ADD THE FOLLOWING IMPLEMENTATION IN YOUR HANDLER { 
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<const QisMClipExtractNotify*>(this);
    //Add more casts based on the implementation of your handler
  }
  return 0;
} */
virtual int QisMClipExtractNotify_latest_version() const  = 0;
/* PLEASE ADD THE FOLLOWING IMPLEMENTATION IN YOUR HANDLER { 
     return 1; //Return the newest version implemented by your handler
   } */

On_clipextract_info

Get notifications with information about the operation in progress

• pre : Prefix to the message for the purposes of formatting

• msg : Message containing information

• post : Suffix to the message for the purposes of formatting

• To subscribe to this notification, override this method in the handler class and pass a pointer to an object of this class to Extract_image or Extract_polygons

• Any return value from this notification is ignored

xxxxxxxxxx
virtual int On_clipextract_info(
  const char* pre, const char* msg, const char* post
  ) { return 0; }

On_clipextract_warning

Get warning messages during an operation

• pre : Prefix to the message for the purposes of formatting

• msg : Warning message

• post : Suffix to the message for the purposes of formatting

• To subscribe to this notification, override this method in the handler class and pass a pointer to an object of this class to Extract_image or Extract_polygons

• Any return value from this notification is ignored

xxxxxxxxxx
virtual int On_clipextract_warning(
  const char* pre, const char* msg, const char* post 
  ) { return 0; }

On_clipextract_image

Get notification when a raster image is ready

• imgName : Name associated with the window from which this image was generated

• bufferPtr : Address of the raster buffer where the image is held

• imageInfo : Address of an object containing information about this image including the buffer size (in bytes)

• threadId : A unique number (>=0) to identify the thread that generated this raster image

• infoMsg : A message string containing a summary for this image/notification

• Return 0 to continue execution

• Return non-zero integer to interrupt the execution of Extract_image resulting in an error

• To subscribe to this notification, override this method in the handler class and pass a pointer to an object of this class to Extract_image or Extract_polygons

• If the output format is TIFF/BMP or RAW, any changes made to the raster image during this call will be reflected in the output on disk

xxxxxxxxxx
virtual int On_clipextract_image(
  const char* imgName, unsigned char* bufferPtr, 
  const QisMClipExtractImageInfo* imageInfo, const int threadId,
  const char* infoMsg
  ) { return 0; }

On_clipextract_polygons

Get notification when a set of polygons have been extracted into a polygon buffer for a specific layer

• imgName : Name associated with the window from which this image was generated

• layer : layer number for all polygons in this set

• dttp : datatype number for all polygons in this set

• inSet : Set of input polygons for this window+layer+dttp

• outSet : Set of output polygons for this window+layer+dttp (may or may not be same as inSet)

• threadId : A unique number (>=0) to identify the thread that generated this raster image

• infoMsg : A message string containing a summary for this image/notification

• 0 to continue execution

• non-zero integer to interrupt the execution of Extract_polygons resulting in an error

• To subscribe to this notification, override this method in the handler class and pass a pointer to an object of this class to Extract_image or Extract_polygons

xxxxxxxxxx
virtual int On_clipextract_polygons(
  const char* imgName, const unsigned short layer, const unsigned short dttp, 
  const QisMClipExtractPolySet* inSet, const QisMClipExtractPolySet* outSet, 
  const int threadId, const char* infoMsg
  ) { return 0; }

QisMClipExtractImageArgs

An object API to specify rasterization parameters

xxxxxxxxxx
class QisMClipExtractImageArgs { ... };

Object_name

Get implementation name and version

xxxxxxxxxx
virtual const char* Object_name() const = 0;

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied). The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMClipExtractImageArgs_cast(const int version) = 0;
virtual const void* QisMClipExtractImageArgs_cast(const int version) const = 0;
virtual int QisMClipExtractImageArgs_latest_version() const = 0;

Reset

Reset to default values

xxxxxxxxxx
virtual void Reset() = 0;

Set_pixelsize

Pixelsize_x

Pixelsize_y

Set/Get image resolution along X and Y axes in form of pixel-size (in file units). Default: 1.0 file units along X and Y

xxxxxxxxxx
virtual void Set_pixelsize(const double x, const double y) = 0;
virtual double Pixelsize_x() const = 0;
virtual double Pixelsize_y() const = 0;

Set_dither

Get_dither

Set/Get a value to apply dithering to the portions of the image that contain data using a 8x8 Bayer matrix (ordered dithering)

• zeroToOneValue : A value >= 0.0 and <= 1.0. If 0.0, every 8x8 pixel block in the data areas is completely clear. If 1.0, every such block is completely filled

• Default: 1.0

xxxxxxxxxx
virtual void Set_dither(const double zeroToOneValue) = 0;
virtual double Get_dither() const = 0;

Set_invert

Get_invert

Set/Get image polarity

• If set is true, the image polarity is reversed. Areas containing data are clear while the empty areas are filled. Otherwise, areas containing data are filled while the empty areas are clear

• Default: false

xxxxxxxxxx
virtual void Set_invert(const bool set = true) = 0;
virtual bool Get_invert() const = 0;

Set_right_to_left_raster

Get_right_to_left_raster

Set/Get raster direction along X axis

• If set is true, the image is rasterized from right to left. Thus a point on the min-X boundary of the image data appears on the right side of the raster image, a point on the max-X boundary appears on the left. Byte 0 of the image represents the max-X, max-Y portion of the data

• If false, the image is rasterized from left to right so that a point on the min-X boundary of the image data appears on the left, max-X on the right. Byte 0 of the image represents min-X, max-Y portion of the data

• Default: false

xxxxxxxxxx
virtual void Set_right_to_left_raster(const bool set = true) = 0;
virtual bool Get_right_to_left_raster() const = 0;

Set_image_format

Get_image_format

Set/Get output image format on disk

• Refer to QisMClipExtractFlags::ImageFormat for allowed options

• Default: QisMClipExtractFlags::RBUF (Rasterize image but do not write to disk)

xxxxxxxxxx
virtual void Set_image_format(const QisMClipExtractFlags::ImageFormat format) = 0;
virtual QisMClipExtractFlags::ImageFormat Get_image_format() const = 0;

QisMClipExtractImageArgsV2

Extension (version = 2) for QisMClipExtractImageArgs

xxxxxxxxxx
class QisMClipExtractImageArgsV2: public QisMClipExtractImageArgs { ... };

Set_bottom_to_top_raster

Get_bottom_to_top_raster

Set/Get raster direction along Y axis

• If set is true, the image is rasterized from bottom to top. Thus a point on the min-Y boundary of the image data appears on the top row of the raster image, a point on the max-Y boundary appears on the bottom row. Byte 0 of the image represents the min-Y portion of the data

• If false, the image is rasterized from top to bottom so that a point on the min-Y boundary of the image data appears on the bottom row, max-Y on the top. Byte 0 of the image represents max-Y portion of the data

• Default: false

xxxxxxxxxx
virtual void Set_bottom_to_top_raster(const bool set) = 0;
virtual bool Get_bottom_to_top_raster() const = 0;

QisMClipExtractSynthArgs

Represents args. for extraction with layer synthesis

xxxxxxxxxx
class QisMClipExtractSynthArgs { ... };

Object_name

Get implementation name and version

xxxxxxxxxx
virtual const char* Object_name() const = 0;

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied). The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMClipExtractSynthArgs_cast(const int version) = 0;
virtual const void* QisMClipExtractSynthArgs_cast(
  const int version
  ) const = 0;
virtual int QisMClipExtractSynthArgs_latest_version() const = 0;

Reset

Reset to default values

xxxxxxxxxx
virtual void Reset() = 0;

Set_max_vert_per_polygon

Get_max_vert_per_polygon

Set/Get max. number of vertices per polygon if union or clipping is enabled

• Default: 8190 vertices

• Polygons with more vertices than this setting will be broken up into smaller polygons

xxxxxxxxxx
virtual void Set_max_vert_per_polygon(const int maxv) = 0;
virtual int Get_max_vert_per_polygon() const = 0;

Set_clip

Get_clip

Set/Get clipping mode on/off to clip polygons at the window edges

• Default: false

• Clipping does not imply union. If clipping is on and union is off, the output may have overlapping polygons (in a layer:datatype)

xxxxxxxxxx
virtual void Set_clip(const bool set = true) = 0;
virtual bool Get_clip() const = 0;

Set_polygon_format

Get_polygon_format

Set/Get output data format on disk

• Default: QisMClipExtractFlags::PBUF (Extract polygons but do not write to disk)

xxxxxxxxxx
virtual void Set_polygon_format(
  const QisMClipExtractFlags::PolygonFormat format
  ) = 0;
virtual QisMClipExtractFlags::PolygonFormat Get_polygon_format() const = 0;

Set_butting_mode

Get_butting_mode

Get_butting_overlap

Set/Get mode for representing polygons with holes

• set: If true, split polygons with holes into butting polygons. If false, create cutlines between the outer boundary and the holes. Default: false

• overlap: If butting is set to true, specify the amount of overlap in file units between the butting edges. Default: 0.0

xxxxxxxxxx
virtual void Set_butting_mode(const bool set, const double overlap) = 0;
virtual bool Get_butting_mode() const = 0;
virtual double Get_butting_overlap() const = 0;

QisMClipExtractPolygonArgs

An object API to specify polygon extraction parameters

xxxxxxxxxx
class QisMClipExtractPolygonArgs { ... };

Object_name

Get implementation name and version

xxxxxxxxxx
virtual const char* Object_name() const = 0;

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied). The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMClipExtractPolygonArgs_cast(const int version) = 0;
virtual const void* QisMClipExtractPolygonArgs_cast(
  const int version
  ) const = 0;
virtual int QisMClipExtractPolygonArgs_latest_version() const = 0;

Reset

Reset to default values

xxxxxxxxxx
virtual void Reset() = 0;

Set_unionize_per_layer

Get_unionize_per_layer

Set/Get union mode on/off for unionizing polygons belonging to the same layer:datatype

• Default: false

• Polygons with holes will be split into butting polygons

• Union does not imply clipping. If union is on and clipping is off, polygons that cross the window boundaries will be extracted fully, however there won't be any overlapping polygons (in a layer:datatype) since they will be unionized

xxxxxxxxxx
virtual void Set_unionize_per_layer(const bool set = true) = 0;
virtual bool Get_unionize_per_layer() const = 0;

Set_max_vert_per_polygon

Get_max_vert_per_polygon

Set/Get max. number of vertices per polygon if union or clipping is enabled

• Default: 8190 vertices

• Polygons with more vertices than this setting will be broken up into smaller polygons

xxxxxxxxxx
virtual void Set_max_vert_per_polygon(const int maxv) = 0;
virtual int Get_max_vert_per_polygon() const = 0;

Set_clip

Get_clip

Set/Get clipping mode on/off to clip polygons at the window edges

• Default: false

• Clipping does not imply union. If clipping is on and union is off, the output may have overlapping polygons (in a layer:datatype)

xxxxxxxxxx
virtual void Set_clip(const bool set = true) = 0;
virtual bool Get_clip() const = 0;

Set_polygon_format

Get_polygon_format

Set/Get output data format on disk

• Default: QisMClipExtractFlags::PBUF (Extract polygons but do not write to disk)

xxxxxxxxxx
virtual void Set_polygon_format(
  const QisMClipExtractFlags::PolygonFormat format
  ) = 0;
virtual QisMClipExtractFlags::PolygonFormat Get_polygon_format() const = 0;

Set_butting_mode

Get_butting_mode

Get_butting_overlap

Set/Get mode for representing polygons with holes

• set: If true, split polygons with holes into butting polygons. If false, create cutlines between the outer boundary and the holes. Default: false

• overlap: If butting is set to true, specify the amount of overlap in file units between the butting edges. Default: 0.0

xxxxxxxxxx
virtual void Set_butting_mode(const bool set, const double overlap) = 0;
virtual bool Get_butting_mode() const = 0;
virtual double Get_butting_overlap() const = 0;

QisMClipExtractWindowSet

An object API for a set of rectangular windows

xxxxxxxxxx
class CLIPEXTRACT_LNX_DECLSPEC QisMClipExtractWindowSet { ... };

Object_name

Get implementation name and version

xxxxxxxxxx
virtual const char* Object_name() const = 0;

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied). The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMClipExtractWindowSet_cast(const int version) = 0;
virtual const void* QisMClipExtractWindowSet_cast(const int version) const = 0;
virtual int QisMClipExtractWindowSet_latest_version() const = 0;

Reset

Clear the set of windows

xxxxxxxxxx
virtual void Reset() = 0;

Get_last_error_code

Get a numeric code for the last erorr condition in some of the methods

xxxxxxxxxx
virtual int Get_last_error_code() const = 0;

Add_window

Add a window to the set

• name: Specify a name for the window. If data from this window is written to disk, this name will form the base of the output file. This may contain the directory path in addition to the name if the file is to be placed in a specific location

• llx, lly : lower-left (min) X and Y co-ordinates in file units

• urx, ury : upper-right (max) X and Y co-ordinates in file units

• Success : true

• Failure : false. Call Get_last_error_code() to get the error code

xxxxxxxxxx
virtual bool Add_window(
  const char* name, const double llx, const double lly, const double urx, 
  const double ury
  ) = 0;

Count

Get the number of windows in the set

xxxxxxxxxx
virtual size_t Count() const = 0;

Get a window from the set

• index: Zero based index of the window. (0 <= index < Count())

• llx, lly : lower-left (min) X and Y co-ordinates in file units

• urx, ury : upper-right (max) X and Y co-ordinates in file units

• Success : Non-null string containing window name

• Failure : NULL. Call Get_last_error_code() to get the error code

xxxxxxxxxx
virtual const char* Get_window(
  const int index, double& llx, double& lly, double& urx, double& ury
  ) const = 0;

QisMClipExtract

ClipExtract (QisMExtension) API for multi-threaded extraction of small clips of raster images or polygons

• To get access to this interface, call QisMLib::Get_extension_api with QISMEXTENSION_CLIPEXTRACT as the api name and typecast (dynamic_cast) to QisMClipExtract*

xxxxxxxxxx
class CLIPEXTRACT_LNX_DECLSPEC QisMClipExtract: public NsQisMLib::QisMExtensionAPI { ... };

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied). The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMClipExtract_cast(const int version) = 0;
virtual const void* QisMClipExtract_cast(const int version) const = 0;
virtual int QisMClipExtract_latest_version() const = 0;

Last_error_msg

Last_error_code

Get a numeric code and a message string containing more information about the last error condition

xxxxxxxxxx
virtual const char* Last_error_msg() const = 0;
virtual int Last_error_code() const = 0;

New_window_set

Delete_window_set

Create/Destroy an object to hold a set of windows

• handle : Handle to the window set to be destroyed

• Success : Non-null handle to a window set object

• Failure : an exception of type std::bad_alloc will be thrown

• Every object allocated using New_window_set() must be destroyed using Delete_window_set() to avoid memory leaks

xxxxxxxxxx
virtual QisMClipExtractWindowSet* New_window_set() const = 0;
virtual void Delete_window_set(QisMClipExtractWindowSet* handle) const = 0;

New_image_args

Delete_image_args

Create/Destroy an object to hold rasterization settings

• handle : Handle to the settings object to be destroyed

• Success : Non-null handle to a raster settings object

• Failure : an exception of type std::bad_alloc will be thrown

• Every object allocated using New_image_args() must be destroyed using Delete_image_args() to avoid memory leaks

xxxxxxxxxx
virtual QisMClipExtractImageArgs* New_image_args() const = 0;
virtual void Delete_image_args(QisMClipExtractImageArgs* handle) const = 0;

Extract_image

Extract raster images for a set of windows

• filedb : Handle to the file database obtained from a call to QisMLib::Load_file

• layers : A comma-separated list of layer(s) or layer:datatype(s) to rasterize. Use "ALL" to rasterize all the layers loaded

• viewCell : Name as the cell to be used as the view cell

• windows : A set of one or more windows to rasterize. A raster image will be generated for each of these windows

• settings : Address of a raster settings object to control various rasterization parameters

• clientCb : Address of a notification handler to receive information updates (QisMClipExtractNotify::On_clipextract_info), warnings (QisMClipExtractNotify::On_clipextract_warning) or raster image information (QisMClipExtractNotify::On_clipextract_image)

• nThreadsE : Number of windows to rasterize in parallel (Number of exploder threads). If 0, this is automatically set based on the number of cores

• nThreadsF : Number of threads to use for formatting output (TIFF/BMP). If 0, this is automatically set based on the number of cores and nThreadsE

• Success : true

• Failure : false. Call Last_error_msg() and/or Last_error_code() to get more information about the error

• This method creates a QisMExploder per window to get boundaries that cross that particular window for each one of the layers specified

• It then generates a raster buffer of appropriate size to hold the raster image

• A boundary is rasterized into this buffer as soon as it is receieved from the exploder

• Once all the boundaries (for all layers) are rasterized for the given window, a notification (QisMClipExtractNotify::On_clipextract_image) containing the raster image (buffer) and image information is emitted.

• If the output format is TIFF/BMP/RAW, it writes the image contained in the raster buffer to disk

• The path of the file is : <window_name> + .

• The amount of parallel processing depends on the combination of nThreadsE and nThreadsF

xxxxxxxxxx
virtual bool Extract_image(
  NsQisMLib::QisMFile* filedb, const char* layers, const char* viewCell, 
  const QisMClipExtractWindowSet* windows, 
  const QisMClipExtractImageArgs* settings, QisMClipExtractNotify* clientCb, 
  const int nThreadsE = 0, const int nThreadsF = 0
  ) = 0;

New_polygon_args

Delete_polygon_args

Create/Destroy an object to hold polygon extraction settings

• handle : Handle to the settings object to be destroyed

• Success : Non-null handle to a polygon settings object

• Failure : an exception of type std::bad_alloc will be thrown

• Every object allocated using New_polygon_args() must be destroyed using Delete_polygon_args() to avoid memory leaks

xxxxxxxxxx
virtual QisMClipExtractPolygonArgs* New_polygon_args() const = 0;
virtual void Delete_polygon_args(QisMClipExtractPolygonArgs* handle) const = 0;

Extract_polygons

Extract polygons for one or more layers for a set of windows

• filedb : Handle to the file database obtained from a call to QisMLib::Load_file

• layers : A comma-separated list of layer(s) or layer:datatype(s) to extract polygons from. Use "ALL" to use all the layers loaded

• viewCell : Name as the cell to be used as the view cell

• windows : A set of one or more windows to extract data from

• settings : Address of a polygon settings object to control various extraction parameters

• clientCb : Address of a notification handler to receive information updates (QisMClipExtractNotify::On_clipextract_info), warnings (QisMClipExtractNotify::On_clipextract_warning) or output polygon set for each layer (QisMClipExtractNotify::On_clipextract_polygons)

• nThreadsE : Number of windows to extract in parallel (Number of exploder threads). If 0, this is automatically set based on the number of cores

• nThreadsF : Number of threads to use for unionizing/clipping. If 0, this is automatically set based on the number of cores and nThreadsE

• Success : true

• Failure : false. Call Last_error_msg() and/or Last_error_code() to get more information about the error

• This method creates a QisMExploder per window to get boundaries that cross that particular window for each one of the layers specified

• It then operates upon each set (one per layer:datatype) of boundaries based on the polygon extraction settings and generates a new set of polygons to be outputted and emits a notification (QisMClipExtractNotify::On_clipextract_polygons) containing the input and output polygon sets and the layer:datatype.

• If the output format is GDSII/OASIS, it writes the output set of polygons (for all specified layers) to a file on disk, one per window of extraction

• The path of the file is : <window_name> + <suffix> . <format>

• The amount of parallel processing depends on the combination of nThreadsE and nThreadsF

xxxxxxxxxx
virtual bool Extract_polygons(
  NsQisMLib::QisMFile* filedb, const char* layers, const char* viewCell,
  const QisMClipExtractWindowSet* windows, 
  const QisMClipExtractPolygonArgs* settings, QisMClipExtractNotify* clientCb, 
  const int nThreadsE = 0, const int nThreadsP = 0
  ) = 0; 

QisMClipExtractLsynth

Enhances the QisMClipExtract class to support extraction of clips containing polygons synthesized by performing boolean operations between one or more layers

xxxxxxxxxx
class CLIPEXTRACT_LNX_DECLSPEC QisMClipExtractLsynth: public QisMClipExtract { ... };

New_synth_args

Delete_synth_args

Create/Destroy an object to hold synthesized extraction settings

• handle : Handle to the settings object to be destroyed

• Success : Non-null handle to a lsynth settings object

• Failure : an exception of type std::bad_alloc will be thrown

• Every object allocated using New_synth_args() must be destroyed using Delete_synth_args() to avoid memory leaks

xxxxxxxxxx
virtual QisMClipExtractSynthArgs* New_synth_args() const = 0;
virtual void Delete_synth_args(QisMClipExtractSynthArgs* handle) const = 0;

Extract_synthesized_polygons

Extract synthesized polygons from boolean operations between one or more layers for a set of windows

• filedb : Handle to the file database obtained from a call to QisMLib::Load_file

• layersynthSpec : Layer synthesis specification. Refer to LAYER SYNTHESIS SPEC for details

• viewCell : Name as the cell to be used as the view cell

• windows : A set of one or more windows to extract data from

• settings : Address of a polygon settings object to control various extraction parameters

• clientCb : Address of a notification handler to receive information updates (QisMClipExtractNotify::On_clipextract_info), warnings (QisMClipExtractNotify::On_clipextract_warning) or output polygon set for each layer (QisMClipExtractNotify::On_clipextract_polygons)

• nThreadsE : Number of windows to extract in parallel (Number of exploder threads). If 0, this is automatically set based on the number of cores

• nThreadsF : Number of threads to use for unionizing/clipping. If 0, this is automatically set based on the number of cores and nThreadsE

• Success : true

• Failure : false. Call Last_error_msg() and/or Last_error_code() to get more information about the error

• This method creates a QisMExploder per window to get boundaries that cross that particular window for each one of the layers specified

• It then performs boolean operations on these polygon sets per the synthesis specification generates new sets of polygons to be outputted and emits a notification (QisMClipExtractNotify::On_clipextract_polygons) containing the output polygon sets and the layer:datatype.

• If the output format is GDSII/OASIS, it writes the output set of polygons (for all specified layers) to a file on disk, one per window of extraction

• The path of the file is : <window_name> + <suffix> . <format>

• The amount of parallel processing depends on the combination of nThreadsE and nThreadsF

xxxxxxxxxx
virtual bool Extract_synthesized_polygons(
  NsQisMLib::QisMFile* filedb, const char* layersynthSpec, const char* viewCell,
  const QisMClipExtractWindowSet* windows, 
  const QisMClipExtractSynthArgs* settings, QisMClipExtractNotify* clientCb, 
  const int nThreadsE = 0, const int nThreadsP = 0
  ) = 0;

QisMClipExtractV2

xxxxxxxxxx
typedef QisMClipExtractLsynth QisMClipExtractV2;

QisMClipExtract commands

• Requires the QisMClipExtract extension be installed and loaded (qismclipextract64.dll/so)

• Select commands may require a valid license

• See qismclipextract.h for the C++ API

clip.extract_images

xxxxxxxxxx
clip.extract_images
  $filedb={filedb_id}
  $windows={window_set_id}
  resolution={PXS | DPI | DBU},{x}[,{y}]
  [layers={layer_list}]
  [cell={cellname}]
  [thrnum={n_window_threads}]
  [invert]
  [dither={0.0_to_1.0}]
  [right_to_left]
  [bottom_to_top]
  [format={TIF | BMP | RAW | VBMP}]

• Extract clips (windows) of monochrome bitmaps to TIFF/BMP/RAW files on disk

• Requires N licenses of (31209) where N = {n_window_threads} i.e no. clips to extract in parallel

• {filedb_id} represents name of the variable of type QisMFile* associated with the source database

• {window_set_id} represents name of a variable of type QisMBoxSet* associated with a set of windows created using script.new_window_set. It MUST contain at least one window

• {layer_list} if specified is a comma-separated list of layer(s) or layer:datatype(s) representing the layers to be extracted. Default: ALL layers are extracted

• {cellname} if specified represents the view cell. Default: default top cell is used

• {n_window_threads} represents the no. clips to be extracted in parallel

• invert if used reverses the image polarity to white (data) on black (background)

• dither if used applies dithering using a 8x8 bayer matrix

• right_to_left if used reverses the bits each row along X. i.e first pixel of a row will represent max-x instead of min-x.

• bottom_to_top is used reverses the order of rows of pixels so that the first row represents the min-y position in data space instead of max-y

• format determines the output file format. TIF is compressed (packbits). BMP and RAW are uncompressed. VBMP implied bottom-to-top BMP where the BiHeight parameter of the BITMAPINFOHEADER is flipped

• resolution can be specified as size of a pixel in file units PXS, or dots/pixels per inch DPI, or no. file grids per pixel DBU. A pixel can be rectangular ( {x} != {y}) or square. If {y} is omitted, the {x} value is used to form a square pixel

• All the clips are created in the current working directory

clip.extract_polygons

xxxxxxxxxx
clip.extract_polygons
  $filedb={filedb_id}
  $windows={window_set_id}
  [layers={layer_list}]
  [cell={cellname}]
  [thrnum={n_window_threads},{n_threads_per_window}]
  [per_layer_union]
  [clip]
  [maxvert={max_vertices_per_polygon}]
  [format={GDS | OAS}]
  [butting={overlap}]

• Extract clips (windows) of polygons to GDSII or OASIS files on disk (flat polygonal data)

• Requires N licenses of (31209) where N = {n_window_threads} i.e no. clips to extract in parallel

• {filedb_id} represents name of the variable of type QisMFile* associated with the source database

• {window_set_id} represents name of a variable of type QisMBoxSet* associated with a set of windows created using script.new_window_set. It MUST contain at least one window

• {layer_list} if specified is a comma-separated list of layer(s) or layer:datatype(s) representing the layers to be extracted. Default: ALL layers are extracted

• {cellname} if specified represents the view cell. Default: default top cell is used

• {n_window_thread} represents the no. clips to be extracted in parallel. {n_threads_per_window} represents the no. threads to be used per clip for processing (boolean operations)

• per_layer_union if specified unionizes all polygons by layer. Default: extract polygons as-is

• clip if specified clips the data along the window extents. Default: no clipping

• {max_vertices_per_polygon} if specified may result in large polygons being broken up into smaller ones. Default: max. 8190 vertices/polygon

• format represents the output file format. If not specified, clips are extracted but not written to disk

• butting if specified results in unionized polygons with holes represented as pairs of butting polygons where {overlap} is the amount of overlap along X. This only works if per_layer_union is used

• All the clips are created in the current working directory

clip.extract_lsynth

xxxxxxxxxx
clip.extract_lsynth
  $filedb={filedb_id}
  $windows={window_set_id}
  lsynth={lsynth_spec}
  [cell={cellname}]
  [thrnum={n_window_threads},{n_threads_per_window}]
  [clip]
  [maxvert={max_vertices_per_polygon}]
  [format={GDS | OAS}]
  [butting={overlap}]

• Extract clips (windows) of polygons created from layer synthesis to GDSII or OASIS files on disk (flat polygonal data)

• Requires N licenses of (31209) where N = {n_window_threads} i.e no. clips to extract in parallel

• {filedb_id} represents name of the variable of type QisMFile* associated with the source database

• {window_set_id} represents name of a variable of type QisMBoxSet* associated with a set of windows created using script.new_window_set. It MUST contain at least one window

• {lsynth_spec} is the expression for layer synthesis. The detailed syntax can be found here

• {cellname} if specified represents the view cell. Default: default top cell is used

• {n_window_thread} represents the no. clips to be extracted in parallel. {n_threads_per_window} represents the no. threads to be used per clip for processing (boolean operations)

• clip if specified clips the data along the window extents. Default: no clipping

• {max_vertices_per_polygon} if specified may result in large polygons being broken up into smaller ones. Default: max. 8190 vertices/polygon

• format represents the output file format. If not specified, clips are extracted but not written to disk

• butting if specified results in unionized polygons with holes represented as pairs of butting polygons where {overlap} is the amount of overlap along X. This only works if per_layer_union is used

• All the clips are created in the current working directory

QisMClipExtract Licensing (API)

Product name: QisMClipExtract License code: 31209

• The following operations require license(s) held while the operation is in progress

QisMClipExtract Licensing (SCRIPT)

Product name: QisMClipExtract License code: 31209

• The following operations require license(s) held while the operation is in progress

QisMClipExtract Version History

qismclipextract dll 1.13 11-2023

• Uses the most recent rasterizer

• Misc. bug fixes

qismclipextract dll 1.12.1 09-2021

• Improved rasterization where single pixel aberrations have been fixed

• Raster buffer is only re-allocated if the new image size greater than old or less than 2/3rd of the old

qismclipextract dll 1.11 09-2020

• Ability to terminate clip extract during layer synthesis

qismclipextract dll 1.10 06-2020

• misc. bug fixes & memory leaks

qismclipextract dll 1.9 02-2020

• New image format QisMClipExtractFlags::VBMP for a bottom-top BMP image where only the header (biHeight) value is changed

• New parameter option format=VBMP for the command clip.extract_images

qismclipextract dll 1.8 12-2019

• bug fix: top row of a raster image was blank

qismclipextract dll 1.7 12-2019

• Improvement - Rasterization of vertical manhattan polygons (stripes) was significantly slower than comparable horizontal stripes

qismclipextract dll 1.6 09-2019

• Support for bottom-to-top rasterization (reverseY)

• Support for scripting (with QisMScript)

• Misc. bug fixes

qismclipextract dll 1.5, 1.5.1 10-2018

• Major bug fix in the rasterizer that caused a steep rise in the memory footprint for polygons/paths that are extremely long along Y relative to the window/pixelsize in question

qismclipextract dll 1.4 06-2018

• Compatible with QisMLib v3.20 (API break)

• This extension will not load with earlier versions of QisMLib

qismclipextract dll 1.3 11-2017

• Compatible with QisMLib v3.9 (API break)

qismclipextract dll 1.2 03-2017

• New api QisMClipExtractV2 to extract clips of synthesized data using QisMLayerSynth

qismclipextract dll 1.1 12-2016

• Bug Fix: File was not being loaded to memory

• Bug Fix: Initialization of boolean inside a thread was causing a crash

qismclipextract dll 1.0 12-2016

• First cut