[Artwork] / [QisMLib]

QisMHExtract Extension

A QisMLib extension to create a hierarchical GDSII/OASIS output from a view of a source database along with various options for clipping and filtering

QisMHExtract C++ API (qismhextract.h)

QisMHExtractFlags

Various enumerated constants relevant to QisMHExtract

struct QisMHExtractFlags { ... };

ClipMode

Represents the clipping mode

• All entities completely inside the clipping window(s) are extracted

• Clipping modes apply only to partially crossing entities

• For TEXTs, only insertion points are tested

• All entities fully-inside the clipping windows are extracted as-is

xxxxxxxxxx
enum ClipMode {
  CLIP_OFF=0 /* No clipping. Partially crossing boundaries, paths, refs are 
  extracted as-is */
 ,CLIP_PART_POLYS=1 /* Partially crossing boundaries are clipped, partially
  crossing paths are converted to boundaries and clipped, partially crossing
  refs are exploded */
 ,DROP_PART_POLYS=2 /* Partially crossing boundaries/paths are dropped,
  partially crossing refs are exploded */
 ,DROP_PART_DATA=3 /* All partially crossing entities are dropped */
};

FileFormat

Output file format types

xxxxxxxxxx
enum FileFormat {
  FMT_GDSII=0 /* Output GDSII file */
 ,FMT_OASIS=1 /* Output OASIS file */
 ,FMT_COASIS=2 /* Output compressed OASIS file (At the moment, same as 
  FMT_OASIS) */
};

QisMHExtractUpdate

Interface to a callback handler to get updates during extraction

xxxxxxxxxx
class QisMHExtractUpdate { ... };

Version Control (QisMHExtractUpdate)

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* QisMHExtractUpdate_cast(const int version) = 0;
/* PLEASE ADD THIS IMPLEMENTATION IN YOUR HANDLER { 
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<QisMHExtractUpdate*>(this);
  }
  return 0;
} */
virtual const void* QisMHExtractUpdate_cast(const int version) const = 0;
/* PLEASE ADD THIS IMPLEMENTATION IN YOUR HANDLER { 
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<const QisMHExtractUpdate*>(this);
  }
  return 0;
} */
virtual int QisMHExtractUpdate_latest_version() const = 0;
/* PLEASE ADD THIS IMPLEMENTATION IN YOUR HANDLER { 
  return 1;
} */

On_extract_refresh

Opportunity for the client to refresh (update progress, handle events etc.)

• cellname : Name of the cell being processed

• nGeometries, nTexts, nReferences : No. geometries (boundary, path); texts references (single, array) processed (not necessarily extracted)

• Return 0 to continue the extraction, non-zero code to terminate

xxxxxxxxxx
virtual int On_extract_refresh(
  const char* cellname, const long long nGeometries, const long long nTexts,
  const long long nReferences
  ) { return 0; }

QisMHExtractTarget

Interface to a client (or a file writer) that will receive the data being extracted

xxxxxxxxxx
class QisMHExtractTarget { ... };

Version Control (QisMHExtractTarget)

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* QisMHExtractTarget_cast(const int version) = 0;
/* PLEASE ADD THIS IMPLEMENTATION IN YOUR HANDLER { 
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<QisMHExtractTarget*>(this);
  }
  return 0;
} */
virtual const void* QisMHExtractTarget_cast(const int version) const = 0;
/* PLEASE ADD THIS IMPLEMENTATION IN YOUR HANDLER { 
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<const QisMHExtractTarget*>(this);
  }
  return 0;
} */
virtual int QisMHExtractTarget_latest_version() const = 0;
/* PLEASE ADD THIS IMPLEMENTATION IN YOUR HANDLER { 
  return 1;
} */

On_extract_begin

Signals the start of the extraction where filedb is a handle to the source db

xxxxxxxxxx
virtual int On_extract_begin(NsQisMLib::QisMFile* filedb) { return 0; }

On_extract_begin_cell

Indicates the beginning of a cell definition during extraction

• Return 0 to continue the extraction, non-zero code to terminate

xxxxxxxxxx
virtual int On_extract_begin_cell(const char* cellName) { return 0; }

On_extract_boundary

Indicates that a boundary is being added (extracted) to the current cell definition

• xy : Array of x,y co-ordinate pairs forming the boundary (in DBU)

• nv : Number of vertices (= num_integers(xy)/2) (> 3)

• l : Layer number

• d : Datatype number

• Return 0 to continue the extraction, non-zero code to terminate

• 1 DBU = (file-units-in-meters) * (grid-in-file-units) e.g for a um file with resolution of 0.001 um (1 nm), 1 DBU = 1e-6 * 0.001 = 1e-9 m

xxxxxxxxxx
virtual int On_extract_boundary(
  const int* xy, const int nv, const unsigned short l, const unsigned short d
  ) { return 0; }

On_extract_path

Indicates that a path is being added (extracted) to the current cell definition

• xy : Array of x,y co-ordinate pairs forming the path (in DBU)

• nv : Number of vertices (= num_integers(xy)/2)

• l : Layer number

• d : Datatype number

• width : Path width (in DBU)

• type : 'F' flush, 'H' half-extended or 'R' round

• Return 0 to continue the extraction, non-zero code to terminate

• 1 DBU = (file-units-in-meters) * (grid-in-file-units) e.g for a um file with resolution of 0.001 um (1 nm), 1 DBU = 1e-6 * 0.001 = 1e-9 m

xxxxxxxxxx
virtual int On_extract_path(
  const int* xy, const int nv, const unsigned short l, 
  const unsigned short d, const int width, const char type
  ) { return 0; }

On_extract_text

Indicates that a text is being added (extracted) to the current cell definition

• textstr : Text string

• x,y : Insertion point (in DBU)

• l : Layer number

• d : Datatype number

• Return 0 to continue the extraction, non-zero code to terminate

• 1 DBU = (file-units-in-meters) * (grid-in-file-units) e.g for a um file with resolution of 0.001 um (1 nm), 1 DBU = 1e-6 * 0.001 = 1e-9 m

xxxxxxxxxx
virtual int On_extract_text(
  const char* textstr, const int x, const int y, const unsigned short l,
  const unsigned short d
  ) { return 0; }

On_extract_sref

Indicates that a single cell reference is being added (extracted) to the current cell definition

• refName : Name of the cell being referenced

• x,y : Insertion point (in DBU)

• angle : Rotation in degrees

• scale : Scale along X and Y (> 0.0)

• flipY : If true, reflection about the X-axis

• Return 0 : Continue extraction. This reference will not be exploded. Any other value : Terminate execution

• 1 DBU = (file-units-in-meters) * (grid-in-file-units) e.g for a um file with resolution of 0.001 um (1 nm), 1 DBU = 1e-6 * 0.001 = 1e-9 m

xxxxxxxxxx
virtual int On_extract_sref(
  const char* refName, const int x, const int y, const double angle,
  const double scale, const bool flipY
  ) { return 0; }

On_extract_aref

Indicates that an arrayed cell reference is being added (extracted) to the current cell definition

• `refName : Name of the cell being referenced

• x,y : Insertion point (in DBU)

• angle : Rotation in degrees

• scale : Scale along X and Y (> 0.0)

• flipY : If true, reflection about the X-axis

• nCols, colDx, colDy : No. columns, offset between elements of the same row and consecutive columns

• nRows, rowDx, rowDy : No. rows, offset between elements of the same column and consecutive rows

• Return 0 : Continue extraction. This reference will not be exploded. Any other value : Terminate execution

• 1 DBU = (file-units-in-meters) * (grid-in-file-units) e.g for a um file with resolution of 0.001 um (1 nm), 1 DBU = 1e-6 * 0.001 = 1e-9 m

xxxxxxxxxx
virtual int On_extract_aref(
  const char* refName, const int x, const int y, const double angle,
  const double scale, const bool flipY, const int nCols, const int nRows,
  const int colDx, const int colDy, const int rowDx, const int rowDy
  ) { return 0; }

On_extract_end_cell

Indicates the end of a cell definition during extraction

xxxxxxxxxx
virtual void On_extract_end_cell() { }

On_extract_end

Indicates the end of extraction

xxxxxxxxxx
virtual void On_extract_end() { }

QisMHExtractClipper_p

Opaque handle to an internal object that is responsible for clipping vector data

xxxxxxxxxx
typedef void* QisMHExtractClipper_p;

QisMHextractRegions

An object to specify a set of clipping regions (boxes, polygons or circles)

xxxxxxxxxx
class QisMHextractRegions { ... };

Version Control (QisMHextractRegions)

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 const char* QisMHextractRegions_name(const int version) const = 0;
virtual void* QisMHextractRegions_cast(const int version) = 0;
virtual const void* QisMHextractRegions_cast(const int version) const = 0;
virtual int QisMHextractRegions_latest_version() const = 0;

Reset

Clear all the clipping regions

xxxxxxxxxx
virtual void Reset() = 0;

Consolidate

Clear unused memory allocated to store clipping regions

xxxxxxxxxx
virtual void Consolidate() = 0;

Add_box

Add a box (orthogonal rectangle) to the set of clipping regions

• llx,lly,urx,ury are the min-max (lower left, upper right) extents in file units

xxxxxxxxxx
virtual bool Add_box(
  const double llx, const double lly, const double urx, const double ury
  ) = 0;

Add_polygon

Add a closed polygon to the set of clipping regions

• nv is the number of vertices and xy is an array of x,y co-oridinate pairs (nv*2 ints) in file units

xxxxxxxxxx
virtual bool Add_polygon(const int nv, const double* xy) = 0;

Add_circle

Add a circle to the set of clipping regions (to be converted to a polygon)

• cx,cy is the center point in file units

• arcres is the angle subtended by a single edge to the center of the circle (e.g arcres of 9.0 indicates that the polygon will have 360.0/9.0 = 40 edges)

• arcsag is the sagitta of the circular arc that is approximated by each edge of the polygon. If 0.0, this parameter is ignored.

• The parameter that results in a finer circle becomes the dominant parameter

xxxxxxxxxx
virtual bool Add_circle(
  const double cx, const double cy, const double radius, const double arcres,
  const double arcsag
  ) = 0;

Complement

Compute the complement of the clipping regions w.r.t the extents of the view cell

xxxxxxxxxx
virtual void Complement(const bool onOff) = 0;

QisMHExtractOpts

An object to specify various extraction options

xxxxxxxxxx
class QisMHExtractOpts { ... };

Version Control (QisMHExtractOpts)

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 const char* QisMHExtractOpts_name(const int version) const = 0;
virtual void* QisMHExtractOpts_cast(const int version) = 0;
virtual const void* QisMHExtractOpts_cast(const int version) const = 0;
virtual int QisMHExtractOpts_latest_version() const = 0;

Reset

Reset to default values

xxxxxxxxxx
virtual void Reset() = 0;

Copy_from

Clone settings from another object

xxxxxxxxxx
virtual void Copy_from(const QisMHExtractOpts* opts) = 0;

Set_flatten

Get_flatten

Flatten the output

• Output will not have any hierarchy

• Default: NO (false)

xxxxxxxxxx
virtual void Set_flatten(const bool yes) = 0;
virtual bool Get_flatten() const = 0;

Set_clip_mode

Get_clip_mode

Clipping mode

• Default: QisMHExtractFlags::CLIP_PART_POLYS

xxxxxxxxxx
virtual void Set_clip_mode(const QisMHExtractFlags::ClipMode mode) = 0;
virtual QisMHExtractFlags::ClipMode Get_clip_mode() const = 0;

Set_text

Get_text

Extract TEXT data

• Default: NO (false)

xxxxxxxxxx
virtual void Set_text(const bool yes) = 0;
virtual bool Get_text() const = 0;

Set_path_to_boundary

Get_path_to_boundary

Convert all paths to boundaries

• Default: NO (false)

xxxxxxxxxx
virtual void Set_path_to_boundary(const bool yes) = 0;
virtual bool Get_path_to_boundary() const = 0;

Set_sliver

Get_sliver_value

Get_sliver_area

Filter tiny boundaries

• 'ratio' is the ratio of the perimeter to the area ( applied only during clipping)

• 'area' is used always and is in file-units

• Polygons smaller than the specified values will be dropped

• Default: 0.0 for both (extract all polygons)

xxxxxxxxxx
virtual void Set_sliver(const double ratio, const double area) = 0;
virtual double Get_sliver_value() const = 0;
virtual double Get_sliver_area() const = 0;

Set_extracted_name

Get_extracted_name

Name of the extracted cell

• Default: Same as the view cell

xxxxxxxxxx
virtual void Set_extracted_name(const char* outputCellName) = 0;
virtual const char* Get_extracted_name() const = 0;

Set_only_refs

Get_only_refs

Only extract refs that match atleast one of the specified regular expressions (dos-like) and immediate child of the view cell

• Default: Extract all refs

• cellnameRegularExpressions is a comma-separated list of expressions or cellnames

xxxxxxxxxx
virtual void Set_only_refs(const char* cellnameRegularExpressions) = 0;
virtual const char* Get_only_refs() const = 0;

Set_drop_refs

Get_drop_refs

Get_drop_refs_all

Drop references to the specified cells (via regular expressions)

• cellnameRegularExpressions is a comma-separated list of dos-like regular expressions

• Default: No filtering by cell name (empty/null string)

• If allrefs is false (default), only the references that are immediate children of the view cell are dropped

xxxxxxxxxx
virtual void Set_drop_refs(
  const char* cellnameRegularExpressions, const bool allrefs
  ) = 0;
virtual const char* Get_drop_refs() const = 0;
virtual bool Get_drop_refs_all() const = 0;

Set_post_transform

Get_post_translate_x

Get_post_translate_y

Get_post_scale

Get_post_angle

Get_post_flipY

Get_post_transform

Transform the final output

• dx,dy is the translation in file-units

• angle is in degrees

• flipY is reflection about the X-axis

• Default: No transformation

xxxxxxxxxx
virtual void Set_post_transform(
  const double dx, const double dy, const double scale, const double angle, 
  const bool flipY
  ) = 0;
virtual double Get_post_translate_x() const = 0;
virtual double Get_post_translate_y() const = 0;
virtual double Get_post_scale() const = 0;
virtual double Get_post_angle() const = 0;
virtual bool Get_post_flipY() const = 0;
virtual bool Get_post_transform(const double grid) const = 0;

Set_cellname_mod

Get_cellname_prefix

Get_cellname_suffix

Add a prefix and/or suffix to every cellname in the output

• Also applies to the top cell unless Get_extracted_name has been specified in which case Get_extracted_name is used

xxxxxxxxxx
virtual void Set_cellname_mod(const char* prefix, const char* suffix) = 0;
virtual const char* Get_cellname_prefix() const = 0;
virtual const char* Get_cellname_suffix() const = 0;

QisMHExtractOptsV2

Extension to QisMHExtractOpts for offsetting the output layers

xxxxxxxxxx
class QisMHExtractOptsV2: public QisMHExtractOpts { ... };

Set_layer_offset

Get_layer_offset

Get_dttp_offset

Set/Get offsets for ALL layers in the output

• layer, dttp: offsets to be added to the extracted layer and datatypes

xxxxxxxxxx
virtual void Set_layer_offset(
  const unsigned short layer, const unsigned short dttp 
  ) = 0;
virtual unsigned short Get_layer_offset() const = 0;
virtual unsigned short Get_dttp_offset() const = 0;

QisMHExtractor

Interface to a single instance of the extractor

xxxxxxxxxx
class QisMHExtractor { ... };

Version Control (QisMHExtractor)

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 const char* QisMHExtractor_name(const int version) const = 0;
virtual void* QisMHExtractor_cast(const int version) = 0;
virtual const void* QisMHExtractor_cast(const int version) const = 0;
virtual int QisMHExtractor_latest_version() const = 0;

Get_last_error_msg (QisMHExtractor)

Get_last_error_code (QisMHExtractor)

Get error message/code for the last error condition

xxxxxxxxxx
virtual const char* Get_last_error_msg() const = 0;
virtual int Get_last_error_code() const = 0;

Create_clipper

Create an instance of the clipper object from a set of regions

• regions : A set of box, polygon, circular regions to be used for clipping

• viewcell : Name of the cell being extracted (for computing complement)

• error : If true - Use Get_last_error_msg() or Get_last_error_code() for details

• non-null : Handle to a new clipper object

• null : Error. Use Get_last_error_msg() or Get_last_error_code() for details

• MUST be destroyed eventually using Destroy_clipper()

xxxxxxxxxx
virtual QisMHExtractClipper_p Create_clipper(
  const QisMHextractRegions* regions, const char* viewcell, bool& error
  ) = 0;

Create_box_clipper

Create an instance of the clipper object from a single box

• viewcell : If used, name of the cell being extracted for computing complement otherwise NULL (no complement)

• minx, miny,maxx,maxy` : Extents of a box in file-units

• non-null : Handle to a new clipper object

• null : Error. Use Get_last_error_msg() or Get_last_error_code() for details

• MUST be destroyed eventually using Destroy_clipper()

xxxxxxxxxx
virtual QisMHExtractClipper_p Create_box_clipper(
  const double minx, const double miny, const double maxx, const double maxy,
  const char* viewcell = 0
  ) = 0;

Create_poly_clipper

Create an instance of the clipper object from a single polygon

• `xy : List of x,y co-ordinate pairs of the polygonal clipping region

• nv : Number of vertices in the polygon (num_int(xy)/2)

• viewcell : If used, name of the cell being extracted for computing complement otherwise NULL (no complement)

• non-null : Handle to a new clipper object

• null : Error. Use Get_last_error_msg() or Get_last_error_code() for details

• MUST be destroyed eventually using Destroy_clipper()

xxxxxxxxxx
virtual QisMHExtractClipper_p Create_poly_clipper(
  const double* xy, const int nv, const char* viewcell = 0
  ) = 0;

Create_circ_clipper

Create an instance of the clipper object from a single circle

• viewcell : If used, name of the cell being extracted for computing complement otherwise NULL (no complement)

• cx,cy : Center point in file units

• radius : Circle radius in file units (>0.0)

• arcres : Angle (degrees) subtended by the resulting polygon edge at the center

• arcsag : Max. chord-error (default: 0.0)

• non-null : Handle to a new clipper object

• null : Error. Use Get_last_error_msg() or Get_last_error_code() for details

• MUST be destroyed eventually using Destroy_clipper()

xxxxxxxxxx
virtual QisMHExtractClipper_p Create_circ_clipper(
  const double cx, const double cy, const double radius, const double arcres,
  const double arcsag, const char* viewcell = 0
  ) = 0;

Destroy_clipper

Destroy an instance of the clipper object

xxxxxxxxxx
virtual void Destroy_clipper(QisMHExtractClipper_p handle) = 0;

Create_file_writer

Destroy_file_writer

Create/Destroy a GDSII/OASIS file writer as the target for extracted data

• filePath : Path of the file to be extracted

• format : File format

• fileUnitsInM : Eg. 1e-6 for a micron file

• gridInFileUnits : Eg. 0.001 for a micron file with nanometer resolution

• non-null : Handle to a file writer to be used as the target for extraction

• null : Error. Use Get_last_error_msg() or Get_last_error_code() for details

• As an alternative to receiving extracted data via callbacks, the client application can chose to write the data to a GDSII/OASIS file using this convinience feature

xxxxxxxxxx
virtual QisMHExtractTarget* Create_file_writer(
  const char* filePath, const QisMHExtractFlags::FileFormat format,
  const double fileUnitsInM, const double gridInFileUnits
  ) = 0;
virtual void Destroy_file_writer(QisMHExtractTarget* handle) = 0;

Extract

Perform a single extraction

• cell : Cell to be extracted (view cell). If null/empty, the deepest top cell in the file is used

• layerStr : Comma separated list of layers to be extracted. If null/empty, all layers in the file are candidates for extraction

• clipper : Clipping object setup using one of the Create_*clipper() methods. If null, the entire view cell is extracted

• opts : Clipping options

• target : Receiver of extracted data (either a handler specified by the client application or a file writer created using Create_file_writer())

• updates : Receiver of refresh callbacks while the extraction is in progress

• Success : true

• Failure : false. Use Get_last_error_msg() or Get_last_error_code() for details

• The extracted data is sent to the target in the same order as if creating a GDSII/OASIS file :

  xxxxxxxxxx
  > QisMHExtractTarget::On_extract_begin_cell (first cell definition)
  > QisMHExtractTarget::{ On_extract_boundary | On_extract_path | 
      On_extract_text | On_extract_sref | On_extract_aref }*
  > QisMHExtractTarget::On_extract_end_cell
  ...
  > QisMHExtractTarget::On_extract_begin_cell (last cell definition)
  ...
  > QisMHExtractTarget::On_extract_end_cell
  

xxxxxxxxxx
virtual bool Extract(
  const char* cell, const char* layerStr,
  QisMHExtractClipper_p clipper, const QisMHExtractOpts* opts,
  QisMHExtractTarget* target, QisMHExtractUpdate* updates = 0
  ) = 0;

QisMHExtractorV2

Extension v2 for QisMHExtractor

xxxxxxxxxx
class QisMHExtractorV2: public QisMHExtractor { ... };

Get_extract_report

Get a human readable summary of the last call to QisMHExtractor::Extract

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

QisMHExtractorV3

Extension v3 for QisMHExtractor

xxxxxxxxxx
class QisMHExtractorV3: public QisMHExtractorV2 { ... };

File_db

Get a handle to the linked file db

xxxxxxxxxx
virtual NsQisMLib::QisMFile* File_db() = 0;
virtual NsQisMLib::QisMFile* File_db() const = 0;

QisMHExtractFile

xxxxxxxxxx
class QisMHExtractFile { ... };

Represents a database created by loading a newly extracted file

Version Control (QisMHExtractFile)

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 const char* QisMHExtractFile_name() const = 0;
virtual int QisMHExtractFile_version() const = 0;
virtual void* QisMHExtractFile_cast(const int version) = 0;
virtual const void* QisMHExtractFile_cast(const int version) const = 0;

File_db

Get the underlying QisMFile database

• DO NOT destroy this database using QisMLib::Unload_file

xxxxxxxxxx
virtual NsQisMLib::QisMFile* File_db() = 0;
virtual const NsQisMLib::QisMFile* File_db() const = 0;

Get_last_error_msg (QisMHExtractFile)

Get_last_error_code (QisMHExtractFile)

Get information about an error condition

xxxxxxxxxx
virtual const char* Get_last_error_msg() const = 0;
virtual int Get_last_error_code() const = 0;

Save_as

Make a copy of the underlying file at the specified oas_output_path

• Returns 0 on success. Otherwise, call Get_error_msg or Get_error_tag for error information

xxxxxxxxxx
virtual bool Save_as(const char* output_path) const = 0;

QisMHExtract

Interface to the QisMHExtract extension API

xxxxxxxxxx
class QisMHExtract: public NsQisMLib::QisMExtensionAPI { ... };

Version Control (QisMHExtract)

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 const char* QisMHExtract_name(const int version) const = 0;
virtual void* QisMHExtract_cast(const int version) = 0;
virtual const void* QisMHExtract_cast(const int version) const = 0;
virtual int QisMHExtract_latest_version() const = 0;

Get_last_error_msg (QisMHExtract)

Get_last_error_code (QisMHExtract)

Get error message/code for the last error condition

xxxxxxxxxx
virtual const char* Get_last_error_msg() const = 0;
virtual int Get_last_error_code() const = 0;

New_object

Delete_object

Create an instance of a data object (MUST be eventually destroyed using Delete_object())

• `className : Name of the class whose object is to be created (One of these)

  • QisMHExtractOpts

  • QisMHextractRegions

  • QisMHExtractOptsV2

  • QisMHExtractDbOpts

• `handle : Handle of the object to be destroyed

• Success : non-null handle to the new object. MUST be type-casted appropriately before use

• Failure : null. Call Get_last_error_msg() or Get_last_error_code() for more information

• Upon creation, the handle must be type-casted to that exact same class before use

xxxxxxxxxx
virtual void* New_object(const char* className) = 0;
virtual void Delete_object(const char* className, void* handle) = 0;

Create_extractor

Destroy_extractor

Create an instance of the extractor

• Requires 1 license of QISMCODE_HEXTRACT.

• MUST be eventually destroyed using Destroy_extractor() to release the license and free up the resources

• filedb : Handle to a QisMFile object representing the file loaded in QisMLib

• argC, argT, argV : Reserved

• Success : non-null handle to a new instance of the extractor

• Failure : null. Call Get_last_error_msg() or Get_last_error_code() for more information

xxxxxxxxxx
virtual QisMHExtractor* Create_extractor(
  NsQisMLib::QisMFile* filedb, const int argC = 0, 
  const char* const* argT = 0, void* const* argV = 0
  ) = 0;
virtual void Destroy_extractor(QisMHExtractor* handle) = 0;

QisMHExtractDbOpts

Represents a set of options for creating a database from an extracted file

xxxxxxxxxx
class QisMHExtractDbOpts { ... };

ParamType

Parameter types for Set_param(..) and Get_param(..)

xxxxxxxxxx
enum ParamType {
  DBOP_DBG=1 /* keep temporary working files even after the db is destroyed
  * type: `int` default: 0 (OFF)
  int dbg = 0;
  this->Set_param(QisMHExtractDbOpts::DBOP_DBG, dbg);
  this->Get_param(QisMHExtractDbOpts::DBOP_DBG, &dbg);
  */
 ,DBOP_WORKING_DIR /* set the location of the temporary files used by the db
  * type: `const char*`  default: ""
  const char* work_dir = "";
  this->Set_param(QisMHExtractDbOpts::DBOP_WORKING_DIR, work_dir);
  this->Get_param(QisMHExtractDbOpts::DBOP_WORKING_DIR, &work_dir);
  */
 ,DBOP_FORMAT /* set the format (GDS/OAS) of the underlying db
  * type: `int` default: QisMHExtractFlags::FMT_OASIS
  int format = QisMHExtractFlags::FMT_OASIS;
  this->Set_param(QisMHExtractDbOpts::DBOP_FORMAT, format);
  this->Get_param(QisMHExtractDbOpts::DBOP_FORMAT, &format);
  */
 ,DBOP_LOADFILE_CTRL /* set the load-time option for db creation
  * type: `QisMFileLoadCtrl*` default: NULL
  QisMFileLoadCtrl* load_opts = 0;
  this->Set_param(QisMHExtractDbOpts::DBOP_LOADFILE_CTRL, load_opts);
  this->Get_param(QisMHExtractDbOpts::DBOP_LOADFILE_CTRL, &load_opts);
  */
};

Version Control (QisMHExtractDbOpts)

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 const char* QisMHExtractDbOpts_name(const int version) const = 0;
virtual void* QisMHExtractDbOpts_cast(const int version) = 0;
virtual const void* QisMHExtractDbOpts_cast(const int version) const = 0;
virtual int QisMHExtractDbOpts_latest_version() const = 0;

Set_param

Get_param

• Set/Get value(s) for specific paramters

• type represents the paramter in question -- one of the ParamType enums

• ... represents one of more variables to be passed whose type and count depend on the paramter in question

• See ParamType for details about each parameter

xxxxxxxxxx
virtual bool Set_param(const int type, ...) = 0;
virtual bool Get_param(const int type, ...) = 0;

Reset

Reset all paramters to default values

xxxxxxxxxx
virtual void Reset() = 0;

Copy

Copy settings from another object

xxxxxxxxxx
virtual void Copy(const QisMHExtractDbOpts* opts) = 0;

Clone

Make a clone of the current settings object

xxxxxxxxxx
virtual QisMHExtractDbOpts* Clone() const = 0;

QisMHExtractV2

Extension 2 for QisMHExtract

xxxxxxxxxx
class QisMHExtractV2: public QisMHExtract { ... };

Create_db

Create a new database from an extract of the source database

• qismlib is the handle to the QisMLib API

• filedb is the handle to the source db

• cell is the view cell to be used as the source of the extraction

• layerStr is a comma-separated list of layer:datatype of interest

• clip_regions is a set of regions to be used as clipping areas

• opts is a set of options for controlling the extraction

• dbOpts is a set of options for controlling the database creation

• progressCb is a callback handler to receive progress updates

xxxxxxxxxx
virtual QisMHExtractFile* Create_db(
  NsQisMLib::QisMLib* qismlib, NsQisMLib::QisMFile* filedb, 
  const char* cell, const char* layerStr, const QisMHextractRegions* clip_regions, 
  const QisMHExtractOpts* opts, const QisMHExtractDbOpts* dbOpts, 
  NsQisMLib::QisMNotify* progressCb
  ) = 0;

Destroy_db

Destroy an extracted database

xxxxxxxxxx
virtual void Destroy_db(QisMHExtractFile* handle) = 0;

QisMHextract Commands

• Requires the QisMHExtract extension to be installed and loaded

• Some commands may require a license (11083)

• See qismhextract.h for the corresponding C++ API

hextract.create_extractor

xxxxxxxxxx
hextract.create_extractor 
  &extractor={extractor_id} 
  $filedb={filedb_id}

• Create an instance of the extractor object

• Equivalent to QisMHExtract::Create_extractor in qismhextract.h

• Requires ONE license of (11083) per call

• {extractor_id} is name of a variable to be associated with the newly created object

• {filedb_id} is name of a variable associated with the database to be used as the source for extraction

• Every object created this way MUST be destroyed eventually to avoid memory/resource leaks

hextract.destroy_extractor

xxxxxxxxxx
hextract.destroy_extractor 
  $extractor={extractor_id}

• Destroy an instance of the extractor object

• {extractor_id} is name of variable associated with the extractor to be destroyed

• Releases ONE license of (11083) acquired during hextract.create_extractor

hextract.create_opts

xxxxxxxxxx
hextract.create_opts
  &opts={opts_id} 
  [flatten] 
  [text]
  [nopaths] 
  [sliver={sliver_value},{min_area}] 
  [top={top_cell_name}]
  [onlyrefs={cellname_or_regex}] 
  [droprefs={ALL | CHILD},{cellname_or_regex}]
  [txy={dx},{dy}] 
  [scale={scale}] 
  [angle={degrees}] [flipy]
  [prename={cellname_prefex}] 
  [postname={cellname_suffix}]
  [layeroffx={l_offx},{d_offx}] 
  [clip={OFF | DROP_POLYS | DROP_DATA}]

• Create an instance of the extraction settings object

• Equivalent to QisMHExtract::New_object("QisMHExtractOpts") in qismhextract.h

• Every settings object MUST be eventually destroyed using hextract.destroy_opts

• {opts_id} is name of variable of to be associated with the newly created object

• flatten if used, removes all hierarchy and generates a flat output (boundaries, paths, texts). Default: hierarchical output

• text if used extracts TEXT elements. (default: no TEXTs)

• nopaths if used converts paths to boundaries. Default: Paths are extracted as-is (except for the ones that are clipped)

• {sliver_value} and {min_area} represent the sliver and min. area for polygons to be extracted. Default: all polygons are extracted no matter how small.

• {top_cell_name} if used sets the name of the top cell in the output file. Default: same name as the view cell (being extracted)

• onlyrefs if used extracts references only to those cells whose names match the specified list of name(s) or regular expression(s) and are immediate children of the cell being extracted. Any child reference whose cell name does not match the specified filter will be dropped. Default: all applicable references are extracted

• droprefs if used drops references only to those cells whose names match the specified list of name(s) or regular expression(s). If ALL is specified, all matching references are dropped regardless of the nesting level. If CHILD is specified, only the matching references that are immediate children of the view cell are dropped. Default: all applicable references are extracted

• txy if used translates the output by the specified offset {dx},{dy} in file units. Default: 0.0,0.0

• scale if used scales the output. Default: 1.0

• angle if used rotates the output with the specified amount in degrees. Default: 0.0

• {cellname_prefix} adds a pre-fix to names of all the extracted cells. Default: No prefix

• {cellname_suffix} adds a suffix to names of all the extracted cells. Default: No suffix

• layeroffx offsets all extracted layers by the specified layer number {l_offx} and datatype number {d_offx}. Default: 0,0

• clip if used sets the clipping policy for elements partially crossing the clipping regions as follows:

  • OFF

    • Boundaries, Paths, Texts and References are extracted as-is

  • DROP_DATA

    • Boundaries, Paths and References are dropped

    • Texts whose insertion is outside the clipping regions are dropped

  • DROP_POLYS

    • Boundaries and Paths are dropped

    • References are ignored and their immediate children (contents) are processed instead

    • Texts whose insertion is outside the clipping regions are dropped

  • Default

    • Boundaries are clipped

    • Paths are converted to boundaries and clipped

    • References are ignored and their immediate children (contents) are processed instead

    • Texts whose insertion is outside the clipping regions are dropped

hextract.destroy_opts

xxxxxxxxxx
hextract.destroy_opts 
  $opts={opts_id}

• Destroy an instance of the extraction settings object

• Equivalent to QisMHExtract::Delete_object("QisMHExtractOpts") in qismhextract.h

• {opts_id} is name of variable associated with the object to be destroyed

hextract.create_regions

xxxxxxxxxx
hextract.create_regions 
  &regions={regions_id} 
  [complement] 

• Create a container of regions of interest

• Equivalent to QisMHExtract::New_object("QisMHextractRegions") in qismhextract.h

• {regions_id} is name of variable to be associated with the newly created container

• complement if specified creates a complement of the specified regions w.r.t the extents of the view cell. Default: off

• Every container MUST be destroyed eventually using hextract.destroy_regions to avoid memory leak

hextractregions.add

xxxxxxxxxx
hextractregions.add
  $regions={regions_id} 
  [$boxes={boxset_id}]
  [$bstore={grid_m},{units_m},{bstore_id}]
  {box={minx},{miny},{maxx},{maxy}}*
  {poly={x1},{y1}..{xn},{yn},{x1},{y1}}*
  {circle={x},{y},{radius},{arcres},{arcsag}}*

• Add one or more regions to the container

• {regions_id} is name of variable associated with the container to store regions of interest

• {boxset_id} if specified is name of variable associated with a set of boxes to be imported into this container

• $bstore if specified represents a set of polygons to be added to this container. {bstore_id} is name of a variable associated with the set of polygons to be added. {grid_m} and {units_m} are the grid and units in meters associated with the polygon set (or the file db)

• box if specified (one or more times) represents a single box to be added to this container. {minx}..{maxy} are it's extents in file units

• poly if specified (one or more times) represents a single closed polygon to be added to this container. {x1},{y1}... are the co-ordinates in file units

• circle if specified (one or more times) represents a single circular polygon to be added to this container. {x},{y} (the center) and {radius} are in file units.

hextract.destroy_regions

xxxxxxxxxx
hextract.extract_regions 
  $regions={regions_id}

• Destroy a container of regions of interest

• Equivalent to QisMHExtract::Delete_object("QisMHextractRegions") in qismhextract.h

• {regions_id} is name of variable to be associated with the container to be destroyed

hextractor.extract_to_writer

xxxxxxxxxx
hextractor.extract_to_writer
  $extractor={extractor_id}
  $writer={cadwriter_id}
  [cell={cellname}] 
  [layers={layer_string}] 
  [$regions={regions_id}] 
  [$opts={opts_id}]
  [cnvunits]

• Send extracted vectors of a view of the source database to an open cad file writer

• Uses QisMHExtractor::Extract from qismhextract.h

• {extractor_id} is name of a variable associated with the hierarchy extractor

• {cadwriter_id} is name of a variable associated with a writer open for composing a GDSII/OASIS file

• {cellname} if specified sets the view cell (to be extracted). Default: deepest top cell

• {layer_string} is a comma-separated list of layers to be extracted

• {regions_id} if specified is name of a variable associated with the container of regions of interest. Default: Extents of the view cell

• {opts_id} if specified is name of a variable associated with the extraction settings

• cnvunits if specified scales the extracted data appropriately to match the grid, units of the output file so that the dimension of the extracted data (in meters) remains unchanged. This option is only used if the grid of the source data does not match the grid of the output

hextractor.extract_to_file

xxxxxxxxxx
hextractor.extract_to_file
  $extractor={extractor_id}
  out={output_base_path} 
  units={grid_m},{units_m} 
  [format={GDS | OAS}]
  [cell={cellname}] 
  [layers={layer_string}] 
  [$regions={regions_id}] 
  [$opts={opts_id}]

• Extract view of the source database to a GDSII/OASIS file on disk

• Uses QisMHExtractor::Extract along with QisMHExtractor::Create_file_writer from qismhextract.h

• {extractor_id} is name of a variable associated with the hierarchy extractor

• {output_base_path} is the base path (directory + filename) where the output file will be created. Extension will be added automatically depending on the format

• {grid_m} and {units_m} are the output grid and units respectively in meters

• format if specified sets the output file format (default: GDS)

• {cellname} if specified sets the view cell (to be extracted). Default: deepest top cell

• {layer_string} is a comma-separated list of layers to be extracted

• {regions_id} if specified is name of a variable associated with the container of regions of interest. Default: Extents of the view cell

• {opts_id} if specified is name of a variable associated with the extraction settings

hextract.create_db

xxxxxxxxxx
hextract.create_db
  &hextdb={hextdb_id}
  $filedb={filedb_id}
  [cell={cellname}]
  [layers={layer_string}]
  [$regions={regions_id}]
  [$opts={opts_id}]
  [dbg]
  [workdir={path}]
  [format=GDS|OAS]
  [layermap={layermap_str}]
  [notext]

• Create a new database from an extraction of a current database

• {hextdb_id} is name of variable associated with the database object to be created

• {filedb_id} is name of variable associated with the database object to serve as the source for extraction

• {cellname} if specified is the view cell to extract from (default: top cell with the deepest hierarchy or the largest extents)

• {layer_string} if specified is a comma-separated list of {layer}[:{datatype}] representing the layers to be extracted (default: all layers)

• {regions_id} if specified is name of variable associated with a set of clipping regions (default: no clipping)

• {opts_id} if specified is name of variable associated with the extraction settings (default: extraction with default parameters)

• dbg if specified preserves the temporary working files even after the database is destroyed for the purpose of debugging/diagnostics (default: temporary working files are removed upon database deletion)

• workdir if specified sets the location for creating temporary working files (default: current working directory)

• format if specified controls the underlying format of the database (default: OAS)

• layermap if specified applies a layer map to the new database being created. See lib.load_file for details. (default: all extracted layers are loaded as-is)

• notext if specified ignores TEXT elements from the extracted data

• Requires ONE license of (11083) for this operation. The license is release once the extraction is complete

• Every database created this way MUST be destroyed using hextract.destroy_db to avoid resource leaks

hextractfile.save_as

xxxxxxxxxx
hextractfile.save_as 
  $hextdb={hextdb_id} 
  path={output_file_path}

• Make a copy of the underlying extracted file

• {hextdb_id} is name of variable associated with the database object to be created

• {output_file_path} is the path where the copy is to be made

hextract.destroy_db

xxxxxxxxxx
hextract.destroy_db 
  $hextdb={hextdb_id}

• Destroy an instance of an extracted database

• Equivalent to QisMHExtractV2::Destroy_db from qismhextract.h

• {hextdb_id} is name of variable associated with the database object to be destroyed

hextract.select_dbu

xxxxxxxxxx
hextract.select_dbu
  {dbu={grid_m},{units_m}}+
  &grid_m={grid_id}
  &units_m={units_id}

• Select the finest dbu (grid, units) from a list of dbu(s)

• This can be used to merge multiple files with different grid/units

• grid_m is the source grid in meters. units_m is the source units in meters. e.g a um file with nm resolution has a dbu of 1e-9,1e-6

• {grid_id} is name of a string variable to store the grid value of the selection. {units_m} is name of a string variable to store the units of the selection

QisMHExtract Licensing (API)

Product name: QisMHExtract License code: 11083

• The following operations require ONE license of QisMHExtract acquired during BEGIN and held until END

• The following operations require ONE license of QisMHExtract that is held only while the operation is in progress

QisMHExtract Licensing (SCRIPT)

Product name: QisMHExtract License code: 11083

• The following operations require ONE license of QisMHExtract acquired during BEGIN and held until END

• The following operations require ONE license of QisMHExtract that is held only while the operation is in progress

QisMHExtract Version History

qismhextract dll/so v1.7.2 10-2024

• Fix to suppress console popup during Create_db/Destroy_db

qismhextract dll/so v1.7.1 10-2024

• hextract script commands use the new QisMcadWriterAPI

qismhextract dll/so v1.7 04-2023

• Bug-fix : OASIS files with Arrays

• BREAKING CHANGE in the API. v1.7 is not compatible with older clients. All clients MUST be re-compiled with the new header file.

qismhextract dll/so v1.6.1 05-2020

• New script command hextract.select_dbu and new options to enable extraction to an output with a different grid, units

qismhextract dll/so v1.6 02-2020

• New API QisMHExtractV2 to create a database from an extraction of the source database

• New scripting commands hextract.create_db, hextract.destroy_db and hextractfile.save_as

• Support for clipping and extracting zero width paths

qismhextract dll/so v1.5 01-2020

• Support for scripting with QisMScript

qismhextract dll/so v1.4 06-2019

• QisMHExtractOpts extended to V2 to set layer offset for output

qismhextract dll/so v1.3 03-2019

• QisMHExtractor extended to V2 to get human readable extraction report

qismhextract dll/so v1.2 06-2018

• Compatible with QisMLib 3.20 (API break)

• This extension will not load with earlier versions of QisMLib

• API to receive progress updates during extraction (QisMHExtractUpdate)

qismhextract dll/so v1.1 04-2018

• Bug-fix: Loading the qismhextract64.so caused a crash because of invalid use of dynamic_cast

qismhextract dll/so v1.0 03-2018

• First cut