[Artwork] / [QisMLib] / [Programmer's Corner]

QisMmTool Extension

A QisMLib extension that combines various QisMLib functions - multi-threaded window queue, explode, synthesize layers, boolean operations, affine transformations, corrections, patternization, cad-writer and rasterization into a simple, easy to use API for GDSII and OASIS data

QisMmTool Glossary

User Units

• Also called UU

• Same as file units

• Usually one of mm, um, inch, or mil

• Stored as real numbers

• user-unit = database-unit * file-grid

• E.g for a micron file with nanometer resolution, a user-unit value of 1.0 implies 1.0um or 1000 database units

Database Units

• Also called DBU

• Represents the file grid or resolution of the data

• Stored as integers

• database-unit = user-unit / file-grid

• E.g for a micron file with nanometer resolution, a database-unit value of 1000 implies 1.0um or 1.0 user-units

Tile

• A tile a.k.a window is a 2D box defined by it's lower-left (min-x, min-y) and upper-right (max-x, max-y) extents in user-units

• It represents a sub-set of the 2D space of a design

• See Create_proc

Tile Threads

• Tile threads process a set of tiles concurrently and independent of one another

• Tiles are made available to each thread on a first-come-first-serve basis by a multi-threaded FIFO queue

• See Create_proc and PROC_THRNUM_D

Mtool Processor

• Mtool processor is an object that --

  • Is associated with a QisMFile database

  • For a set of tiles supplied by the client application --

    • Launches multiple tile threads for concurrent processing

    • Extracts polygons from the database that cross each tile

    • Performs various polygon-level operations such as layer synthesis, boolean, correction, transform etc.

    • Outputs the final polygons back to the user via CAD/Image files on disk, callbacks or a new QisMFile database

• Multiple Mtool processors can co-exist and operate in parallel. They can be associated with the same or different databases

• Represented by QisMmToolProc

• See Create_proc

Threads per Tile

• Certain operations (such as boolean) may use more than one thread for faster processing

• Since these operations are performed per tile, their threads are created, used and destroyed on a per-tile basis

• Together with tile-threads, these form a T x P multi-threading architecture where T is the no. threads that process tiles concurrently and P is the no. threads per tile for select operations

• Default scheme used by QisMmTool is C x 1 where C is the no. logical cpu(s) in the system

• See EXP_THRNUM_D, BOOL_THRNUM_D, LSYN_THRNUM_D

Clip Mode

• Also called one-file-per-tile

• In clip mode, each tile generates it's own file/output

• Only applies to CAD and Image outputs

• Default mode is composite

• See CAD_CLIPS, IMG_CLIPS

Composite Mode

• In composite mode, final polygons from all tiles are sent to a single output - files, callbacks or database

• This is the default mode

QisMmTool C++ API (qismmtool.h)

QisMmToolProcOpts

• Represents optional parameters for Create_proc

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

struct QisMmToolProcOpts { ... };

PROC_THRNUM_D

• Specify no. of threads to be used to process tiles in parallel

• <option_string> += " " + "thrnum=" where := no. tile-threads (> 0)

• Default: = no. cpu(s) in the system

• Requires ONE license of QISMCODE_MTOOL (11119) per tile thread

• If no. tiles < thrnum, thrnum = no. tiles

• If no. licenses < thrnum, thrnum = no. licenses

xxxxxxxxxx
static const char* PROC_THRNUM_D() { return "thrnum="; }

PROC_EXPAND_TILES_G

• Expand the specified tiles by a value to create some overlap

• <option_string> += " " + "expandtiles=" where := expansion on each size in user units (>= 0.0)

• Default: = 0.0

xxxxxxxxxx
static const char* PROC_EXPAND_TILES_G() { return "expandtiles="; }

QisMmToolExplOpts

• Represents optional parameters for First_explode

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

xxxxxxxxxx
struct QisMmToolExplOpts { ... };

EXP_CELL_S

• Set the view cell

• <option_string> += " " + "cell=" where := valid cell name

• Default: = QisMFile::Get_default_top_cell()

xxxxxxxxxx
static const char* EXP_CELL_S() { return "cell="; }

EXP_LAYERS_ON_S

• Set the view layers (ON layers only)

• <option_string> += " " + "layersON=" where := valid layer string (See QisMView::Set_layers_on() in qismview.h)

• Default: = "ALL"

xxxxxxxxxx
static const char* EXP_LAYERS_ON_S() { return "layersON="; }

EXP_LAYERS_OFF_S

• Set the view layers (ALL layers - OFF layers)

• <option_string> += " " + "layersOFF=" where := valid layer string (See QisMView::Set_layers_on() in qismview.h)

• Default: = ""

xxxxxxxxxx
static const char* EXP_LAYERS_OFF_S() { return "layersOFF="; }

EXP_NESTING_D

• Set the nesting level

• <option_string> += " " + "nesting=" where := nesting level (>=1)

• Default: = QisMNesting::ALL (see QisMView::Set_nesting_level() in qismview.h)

xxxxxxxxxx
static const char* EXP_NESTING_D() { return "nesting="; }

EXP_CLIP

• Clip polygons to the tile extents

• <option_string> += " " + "clip" (used as a flag)

• Default: "" (not specified, polygons are not clipped)

• Requires ONE license of QISMCODE_QISMBOOL (11047) (see qismbool.h) per tile thread (as specified in Create_proc())

xxxxxxxxxx
static const char* EXP_CLIP() { return "clip"; }

EXP_THRNUM_D

• Specify the no. threads to be user per tile for clipping

• <option_string> += " " + "thrnum=" where := no. threads per tile for clipping operation (>= 1)

• Default: = 1

• This thread count is not the same as QisMmToolProcOpts::PROC_THRNUM_D(). The other control how many threads to process tiles and this contols how many threads during the processing of each tile

• This thread control does not require any additional licenses

xxxxxxxxxx
static const char* EXP_THRNUM_D() { return "thrnum="; }

QisMmToolCadOpts

• Represents optional parameters for Flush_to_CAD

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

xxxxxxxxxx
struct QisMmToolCadOpts { ... };

CAD_OASIS

• Specify the format for CAD output as OASIS

• <option_string> += " " + "format-OAS" (used as a flag)

• Default: output is GDSII

xxxxxxxxxx
static const char* CAD_OASIS() { return "format-OAS"; }

CAD_CLIPS

• Generate a separate output file for each tile

• <option_string> += " " + "one_file_per_tile" (used as a flag)

• Default: "" (not specified, all tiles are merged into a single output)

xxxxxxxxxx
static const char* CAD_CLIPS() { return "one_file_per_tile"; }

QisMmToolPatnOpts

• Represents optional parameters for Patternize_before_flush

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

xxxxxxxxxx
struct QisMmToolPatnOpts { ... };

PAT_CIRC

• Detect circles from the polygon stream and store/process them as circles for the purpose of pattern recognition

• <option_string> += " " + "circles" (used as a flag)

• Default: "" (not specified, polygons are treated as polygons)

xxxxxxxxxx
static const char* PAT_CIRC() { return "circles"; }

PAT_CIRC_SAG_DBU_G

• Specify the max. chord error when detecting circles

• <option_string> += " " + "maxsagdbu=" where := chord error in DBUnits

• Default: = 0.0 (works only when "circles" is used)

xxxxxxxxxx
static const char* PAT_CIRC_SAG_DBU_G() { return "maxsagdbu="; }

PAT_JITTER_G

• Specify the margin of error when comparing the co-incidence of two points/edges/polygons

• <option_string> += " " + "jitter=" where := jitter in user units

• Default: = 0.0 (exact match, may be very expensive for certain kinds of data such as curve-like polygons)

• It is recommended to always specify some jitter value that is relevant to the application

xxxxxxxxxx
static const char* PAT_JITTER_G() { return "jitter="; }

PAT_MIN_REP_D

• For CAD outputs, specify the min. repetition counts to create a new cell definition for any pattern

• <option_string> += " " + "minrepeats=" where := min. repetition (>0)

• Default: 1 (every pattern has a unique cell regardless of the repetition count)

xxxxxxxxxx
static const char* PAT_MIN_REP_D() { return "minrepeats="; }

QisMmToolBoolOpts

• Represents optional parameters for Then_unionize

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

xxxxxxxxxx
struct QisMmToolBoolOpts { ... };

BOOL_SLIVER_G

• Specify the size for sliver removal (removing tiny polygons)

• <options_string> += " " + "sliver=" where is a size in user-units

• Default: 0.0

xxxxxxxxxx
static const char* BOOL_SLIVER_G() { return "sliver="; }

BOOL_CUTLINES

• Enable cutline mode for polygons with holes (default)

• <option_string> += " " + "cutlines"

xxxxxxxxxx
static const char* BOOL_CUTLINES() { return "cutlines"; }

BOOL_BUTTING_G

• Enable butting mode for polygons with holes

• <option_string> += " " + "butting=" where is the overlap amount in user-units

• Default: cutlines

xxxxxxxxxx
static const char* BOOL_BUTTING_G() { return "butting="; }

BOOL_MAXVERT_D

• Break polygons with large number of vertices

• <option_string> += " " + "maxvert=" where is the max. no. vertices (>4 and <8190)

• Default: = 8190

xxxxxxxxxx
static const char* BOOL_MAXVERT_D() { return "maxvert="; }

BOOL_SIZING_GG

• Apply positive or negative sizing (compensation)

• <option_string> += " " + "sizing=," where is the sizing in X followed by sizing in Y in user-units

• Default: , = 0.0,0.0

• Both values MUST have the same sign (+ve or -ve or 0.0)

xxxxxxxxxx
static const char* BOOL_SIZING_GG() { return "sizing="; }

BOOL_CONVEX

• Output polygons are convex

• <options_string> += " " + "convex"

xxxxxxxxxx
static const char* BOOL_CONVEX() { return "convex"; }

BOOL_THRNUM_D

• Specify the number of threads per tile for boolean operations

• <options_string> += " " + "thrnum="

• Default: = 1

xxxxxxxxxx
static const char* BOOL_THRNUM_D() { return "thrnum="; }

BOOL_UNION

• Unionize the output polygons

• <options_string> += " " + "union"

• Sizing and butting forces unionization

xxxxxxxxxx
static const char* BOOL_UNION() { return "union"; }

BOOL_MERGE

• Remove partition lines (created during unionization) at the end of unionization

• <options_string> += " " + "mergestripes"

xxxxxxxxxx
static const char* BOOL_MERGE() { return "mergestripes"; }

BOOL_CLIP

• Clip to the tile extents

• <options_string> += " " + "clip"

xxxxxxxxxx
static const char* BOOL_CLIP() { return "clip"; }

BOOL_DBG_S

• Write internal boolean settings to a text file

• <options_string> += " " + "dbg=" where is the base path of the text file

xxxxxxxxxx
static const char* BOOL_DBG_S() { return "dbg="; }

QisMmToolXformOpts

• Represents optional parameters for Then_transform

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

xxxxxxxxxx
struct QisMmToolXformOpts { ... };

XFRM_TRANSLATE_GG

• Add translation to the current transformation matrix

• <options_string> += " " + "translate=," where is translation along X followed by Y in user-units

• Can be used more than once

xxxxxxxxxx
static const char* XFRM_TRANSLATE_GG() { return "translate="; }

XFRM_ROTATE_G

• Add rotation to the current transformation matrix

• <options_string> += " " + "rotate=" where is the angle in degrees

• Rotation is about the origin. To rotate about a point, translate to origin, rotate and translate back

• Can be used more than once

xxxxxxxxxx
static const char* XFRM_ROTATE_G() { return "rotate="; }

XFRM_SCALE_GG

• Add scaling to the current transformation matrix

• <options_string> += " " + "scale=," where is scaling along X followed by Y (both >0.0)

• Can be used more than once

xxxxxxxxxx
static const char* XFRM_SCALE_GG() { return "scale="; }

XFRM_SHEAR_GG

• Add shearing to the current transformation matrix

• <options_string> += " " + "shear=," where is shearing (factor) along X followed by Y

• Can be used more than once

xxxxxxxxxx
static const char* XFRM_SHEAR_GG() { return "shear="; }

XFRM_MIRROR_S

• Add reflection to the current transformation matrix

• <options_string> += " " + "mirror=" where is "X" or "Y" or "XY" representing the axes along which the mirror is to occur X = flip X, Y = flip Y, XY = flip X & Y

• Can be used more than once

xxxxxxxxxx
static const char* XFRM_MIRROR_S() { return "mirror="; }

QisMmToolImgOpts

• Represents optional parameters for various operations

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

xxxxxxxxxx
struct QisMmToolImgOpts { ... };

IMG_CLIPS

• Create one image per tile

• <options_string> += " " + "one_file_per_tile"

• Default: Data from all the tiles is rasterized to a single image

xxxxxxxxxx
static const char* IMG_CLIPS() { return "one_file_per_tile"; }

IMG_TIF8

• Write the image to disk as a packbits big-TIFF image (default)

• extension will be .tif8

xxxxxxxxxx
static const char* IMG_TIF8() { return "format-TIF8"; }

IMG_TIFF

• Write the image to disk as a packbits TIFF image

• <options_string> += " " + "format-TIFF"

• extension will be .tif

xxxxxxxxxx
static const char* IMG_TIFF() { return "format-TIFF"; }

IMG_BMP

• Write the image to disk as a uncompressed BMP image

• <options_string> += " " + "format-BMP"

• extension will be .bmp

xxxxxxxxxx
static const char* IMG_BMP() { return "format-BMP"; }

IMG_VBMP

• Write the image to disk as a uncompressed bottom-to-top BMP image

• <options_string> += " " + "format-VBMP"

• extension will be .bmp

xxxxxxxxxx
static const char* IMG_VBMP() { return "format-VBMP"; }

IMG_RAW

• Write the image to disk as Artwork's RAW image

• <options_string> += " " + "format-RAW"

• extension will be .raw (see qismraster.h for format details)

xxxxxxxxxx
static const char* IMG_RAW() { return "format-RAW"; }

IMG_INVERT

• Invert the image polarity (white/0 for foreground, black/1 for background)

• <options_string> += " " + "invert"

xxxxxxxxxx
static const char* IMG_INVERT() { return "invert"; }

IMG_RTL

• Reverse direction of rasterization along X (min-x appears on the right)

• <options_string> += " " + "right_to_left"

xxxxxxxxxx
static const char* IMG_RTL() { return "right_to_left"; }

IMG_BTT

• Reverse direction of rasterization along Y (min-y appears on the top)

• <options_string> += " " + "bottom_to_top"

xxxxxxxxxx
static const char* IMG_BTT() { return "bottom_to_top"; }

IMG_THRNUM_D

• Specify the number of threads to be used per tile for raster operations

• <options_string> += " " + "thrnum=" where is the no. threads per tile

• Default: = 1

xxxxxxxxxx
static const char* IMG_THRNUM_D() { return "thrnum="; }

IMG_NOCLIP

• In clip mode, do not clip the image to the tile extents

• <options_string> += " " + "noclip"

• Default: the image is clipped to the tile extents. If this option is used, the image extents reflect the extents of the final polygon set generated from a tile

xxxxxxxxxx
static const char* IMG_NOCLIP() { return "noclip"; }

IMG_ROI_GGGG

• In single image mode, clip the image to the specified extents

• <options_string> += " " + "roi=,,," where are ,,, respectively in user-units

• Default: The image extents are the extents of the entire data set that was being rasterized

• Specifying ROI can speed up the operation. Therefore, if known beforehand, ROI should be specified

xxxxxxxxxx
static const char* IMG_ROI_GGGG() { return "roi="; }

QisMmToolDbOpts

• Represents optional parameters for Flush_to_DB

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

xxxxxxxxxx
struct QisMmToolDbOpts { ... };

DB_WORKDIR_S

• Specify a working directory where the temp. folder will be created

• <options_string> += " " + "workdir=" where is the path of a writeable directory

• A temp. folder called qismmtool.{number} will be created in the working directory. By default, this directory will be deleted when the DB is destroyed using Unload_DB

• Default: the user's CWD

xxxxxxxxxx
static const char* DB_WORKDIR_S() { return "workdir="; }

DB_DBG

• Keep the temp. folder even after the DB is destroyed for inspection/debugging

• <options_string> += " " + "dbg"

xxxxxxxxxx
static const char* DB_DBG() { return "dbg"; }

QisMmToolLsynOpts

• Represents optional parameters for First_lsynth

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

xxxxxxxxxx
struct QisMmToolLsynOpts { ... };

LSYN_CELL_S

• Specify the view cell for layer synthesis

• <options_string> += " " + "cell=" where is name of a valid cell

• Default: see qismfile.h / QisMFile::Get_default_top_cell()

xxxxxxxxxx
static const char* LSYN_CELL_S() { return "cell="; }

LSYN_BUTTING_G

• Enable butting mode for polygons with holes

• <option_string> += " " + "butting=" where is the overlap amount in user-units

• Default: polygons with holes have cutlines

xxxxxxxxxx
static const char* LSYN_BUTTING_G() { return "butting="; }

LSYN_MERGE

• Remove partition lines (created during unionization) at the end of unionization

• <options_string> += " " + "mergestripes"

xxxxxxxxxx
static const char* LSYN_MERGE() { return "mergestripes"; }

LSYN_THRNUM_D

• Specify the number of threads per tile for boolean operations

• <options_string> += " " + "thrnum="

• Default: = 1

xxxxxxxxxx
static const char* LSYN_THRNUM_D() { return "thrnum="; }

QisMmToolLicOpts

• Represents optional parameters for various operations that require a license

• Optional parameters are passed as a single space-separated string of options

• Options with spaces in them should be double-quoted

• Parameters are specified as = or

• The parameter name gives a clue (in printf format style) about the type of value(s) to be added. E.g --

  • _D implies int (%d)

  • _S implies string (%s)

  • _G implies double (%g)

  • _GG implies two doubles separated by a comma (%g,%g)

  • anything else is treated as a flag

xxxxxxxxxx
struct QisMmToolLicOpts { ... };

LIC_ACSV

• Specify the vendor string

• <options_string> += " " + "acsv="

xxxxxxxxxx
static const char* LIC_ACSV() { return "acsv="; }

LIC_ACSP

• Specify the OEM key file

• <options_string> += " " + "acsp=" where is the path of the OEM key file

xxxxxxxxxx
static const char* LIC_ACSP() { return "acsp="; }

QisMmToolNotify

• Represents a handler to receive polygons during Flush_to_CB

xxxxxxxxxx
class QisMmToolNotify { ... };

Version control (QisMmToolNotify)

• 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<number>. E.g <baseclass>V<version>

• 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* QisMmToolNotify_name(const int version) const = 0;
virtual void* QisMmToolNotify_cast(const int version) = 0;
virtual const void* QisMmToolNotify_cast(const int version) const = 0;
virtual int QisMmToolNotify_latest_version() const = 0;

On_dbu_polygon_set_mt

• Callback to receive a set of polygons during Flush_to_CB

• lx..uy are the extents of the tile associated with this data

• n is the no. polygons in the set. (0 <= p < n) represents the pth polygon

• nv is a list of n vertices, one per polygon. nv[p] is the no. vertices for the pth polygon

• xy is a list of n arrays of xy co-ordinates (int*), one per polygon. Each array of xy co-ordinates contains nv[p]*2 integers

• layera is a list of n layer numbers. dttps is a list of n datatypes. Layer for polygon p is layers[p]:dttps[p]

• grid is the data grid in user-units

• Return 0 to continue operation. Return non-zero code to terminate the operation

• Originates from multiple threads simultaneously. It's the client's responsibility to provide mutual exclusion protection for shared data used during the callback

xxxxxxxxxx
virtual int On_dbu_polygon_set_mt(
  const double lx, const double ly, const double ux, const double uy,
  const int* const* xy, const int* nv, const int n, 
  const unsigned short* layers, const unsigned short* dttps, const double grid
  ) { return 0; }

QisMmToolFile

• Represents a database object created by Flush_to_DB and encapsulates a QisMFile database

xxxxxxxxxx
class QisMmToolFile { ... };

Version control (QisMmToolFile)

• 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<number>. E.g <baseclass>V<version>

• 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* QisMmToolFile_name(const int version) const = 0;
virtual void* QisMmToolFile_cast(const int version) = 0;
virtual const void* QisMmToolFile_cast(const int version) const = 0;
virtual int QisMmToolFile_latest_version() const = 0;

File_db

• Get a handle to the underlying QisMFile database

• DO NOT unload this database using QisMLib::Unload_file. The underlying database will be automatically unloaded by QisMmTool::Unload_db

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

Get_error_msg (QisMmToolFile)

Get_error_tag (QisMmToolFile)

• Get error information for a failed operation

• A tag is a string identifier associated with this error condition

• A msg is a human-readable string containing details about the error

• code is the integer code representing the condition in question

xxxxxxxxxx
virtual const char* Get_error_msg(const int code) const = 0;
virtual const char* Get_error_tag(const int code) const = 0;
virtual const char* Get_error_context(const int code) const = 0;

Save_to_gdsii

• Save the underlying database as a GDSII file at the specified gds_output_path

• Returns 0 on success. Otherwise call Get_error_* for details

xxxxxxxxxx
virtual int Save_to_gdsii(const char* gds_output_path) const = 0;

QisMmToolProc

• Represents an instance of the QisMmTool data processor

xxxxxxxxxx
class QisMmToolProc { ... };

Version control (QisMmToolProc)

• 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<number>. E.g <baseclass>V<version>

• 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* QisMmToolProc_name(const int version) const = 0;
virtual void* QisMmToolProc_cast(const int version) = 0;
virtual const void* QisMmToolProc_cast(const int version) const = 0;
virtual int QisMmToolProc_latest_version() const = 0;

Get_error_msg (QisMmToolProc)

Get_error_tag (QisMmToolProc)

Get_error_context (QisMmToolProc)

• Get error information for an operation that failed using the code returned by the said operation

xxxxxxxxxx
virtual const char* Get_error_msg(const int code) const = 0;
virtual const char* Get_error_tag(const int code) const = 0;
virtual const char* Get_error_context(const int code) const = 0;

First_explode

• Setup mtool processor to first explode polygons from each of the tiles

• opts is a string of options to customize this operation

• This operation does not require a license unless clipping (EXP_CLIP) is specified in which case, N licenses of QISMCODE_QISMBOOL (11047) are required. The licenses are released when the mtool object is destroyed

• This setup will override any previous First_explode or First_lsynth setup

• Returns 0 on success. Otherwise call Get_error_... for error information

xxxxxxxxxx
virtual int First_explode(const char* opts = 0) = 0;

First_lsynth

• Setup mtool processor to first synthesize polygons using a layer expression lsynth_spec

• See qismlayersynth.h for syntax of the layer spec.

• opts is a string of options and license options to customize this operation

• This operation requires N licenses of QISMCODE_QISMLAYERSYNTH (11069) where N is the no. tile threads

• The license is released when the mtool object is destroyed

• This setup will override any previous First_explode or First_lsynth setup

• Returns 0 on success. Otherwise call Get_error_... for error information

xxxxxxxxxx
virtual int First_lsynth(const char* lsynth_spec, const char* opts = 0) = 0;

Then_correct

• Setup the mtool processor to apply corrections (bi-linear transformations) to polygons received from the previous step

• corr_pts is a list of measured distortion points in the format {x},{y},{dx},{dy} (in user units) per point

• n_pts is the no. measured points. No. doubles in corr_pts = n_pts x 4

• opts is a string of options and license options to customize this operation

• This operation requires N licenses of QISMCODE_CORRX (11093) where N is the no. tile threads

• The license is released when the mtool object is destroyed

• This setup will override any previous Then_correct setup

• Returns 0 on success. Otherwise call Get_error_... for error information

xxxxxxxxxx
virtual int Then_correct(
  const double* corr_pts, const int n_pts, const char* opts = 0
  ) = 0;

Then_unionize

• Setup the mtool processor to unionize the polygons received from the previous step

• opts is a string of options and license options to customize this operation

• This operation requires N licenses of QISMCODE_QISMBOOL (11047) where N is the no. tile threads

• The license is released when the mtool object is destroyed

• This setup will override any previous Then_unionize setup

• Returns 0 on success. Otherwise call Get_error_... for error information

xxxxxxxxxx
virtual int Then_unionize(const char* opts = 0) = 0;

Then_transform

• Setup the mtool processor to apply affine transformations to polygons received from the previous step

• opts is a string of options to customize this operation

• This operation does not require any additional licenses

• This setup will override any previous Then_transform setup

• Returns 0 on success. Otherwise call Get_error_... for error information

xxxxxxxxxx
virtual int Then_transform(const char* opts = 0) = 0;

Patternize_before_flush

• Setup the mtool processor to group polygons into repeating patterns before being flushed to the output

• This operation MUST only be called before Flush_... because it will re-constitute the polygon storage and therefore any subsequent Then_... operations will not work

• opts is a string of options to customize this operation

• This operation does not require any additional licenses

• This setup will override any previous Patternize_before_flush setup

• Returns 0 on success. Otherwise call Get_error_... for error information

xxxxxxxxxx
virtual int Patternize_before_flush(const char* opts = 0) = 0;

Flush_to_CAD

• Write the final polygons to CAD (GDSII/OASIS) file(s) on disk

• This is when the actual execution of the entire setup chain occurs -- for each tile, polygons are collected, processed and written

• base_path is the directory + filename for the output

• The extension .gds or .oas will be automatically added

• In one-file-per-tile mode, a suffix .{tile_number} will be added before the extension. {tile_number} starts with 0 and represents the position of the tile in the list of tiles provided during Create_proc

• opts is a string of options to customize this operation

• This operation does not require any additional licenses

• This operation destroys the polygons generated by the previous steps

• Returns 0 on success. Otherwise call Get_error_... for error information

xxxxxxxxxx
virtual int Flush_to_CAD(const char* base_path, const char* opts = 0) = 0;

Flush_to_IMG

• Write the final polygons to monochrome 1bpp image file(s) on disk

• This is when the actual execution of the entire setup chain occurs -- for each tile, polygons are collected, processed and written

• base_path is the directory + filename for the output

• pxs_x and pxs_y is the desired resolution expressed as size of a pixel in user-units

• The extension .tif8, .tif, .bmp or .raw will be automatically added based on the specfied format

• In one-file-per-tile mode, a suffix .{tile_number} will be added before the extension. {tile_number} starts with 0 and represents the position of the tile in the list of tiles provided during Create_proc

• opts is a string of options to customize this operation

• This operation does not require any additional licenses

• This operation destroys the polygons generated by the previous steps

• Returns 0 on success. Otherwise call Get_error_... for error information

xxxxxxxxxx
virtual int Flush_to_IMG(
  const char* base_path, const double pxs_x, const double pxs_y, 
  const char* opts = 0
  ) = 0;

Flush_to_CB

• Send the final polygons to the application (caller) via callbacks (one callback per tile)

• This is when the actual execution of the entire setup chain occurs -- for each tile, polygons are collected, processed and sent

• cb is the callback handler

• The callbacks may original from multiple threads simultaneously. It is the responsibility of the receiver to ensure mutual-exclusion protection to any shared data accessed in these callbacks

• opts is a string of options to customize this operation

• This operation does not require any additional licenses

• This operation destroys the polygons generated by the previous steps

• Returns 0 on success. Otherwise call Get_error_... for error information

xxxxxxxxxx
virtual int Flush_to_CB(QisMmToolNotify* cb, const char* opts = 0) = 0;

Flush_to_DB

Unload_DB (QisMmToolProc)

• Create a new and independent QisMFile DB from the final polygons that can be used as a source for post-processing with other QisMLib APIs

• This is when the actual execution of the entire setup chain occurs -- for each tile, polygons are collected, processed, written and loaded

• process_cb can be used to get progress updates for the database creation just like QisMLib::Load_file(..)

• opts is a string of options to customize this operation

• This operation does not require any additional licenses

• This operation destroys the polygons generated by the previous steps

• Returns 0 on success and handle will point to a newly created database object. Otherwise call Get_error_... for error information

• The DB handle MUST be eventually destroyed using Unload_DB to avoid resource leaks

xxxxxxxxxx
virtual int Flush_to_DB(
  QisMmToolFile*& handle, NsQisMLib::QisMNotify* progess_cb = 0, 
  const char* opts = 0
  ) = 0;
virtual void Unload_DB(QisMmToolFile* handle) = 0;

QisMmTool

• Represents the gateway to the QisMmTool extension

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

Get_api

• Get the handle to the QisMmTool API

• Returns NULL if --

  • The extension is not installed or installed but not configured

  • The extension loaded in the run-time is not compatible with this API therefore forcing a name change

xxxxxxxxxx
static QisMmTool* Get_api(NsQisMLib::QisMExtensionMgr* extn_mgr)
{
  if(extn_mgr) {
    QisMExtensionAPI* extn = extn_mgr->Get_qism_extension_api(QISMEXTENSION_MTOOL);
    return extn ? (QisMmTool*)(extn->Extension_class_ptr()) : 0;
  }
  return 0;
}

Version control (QisMmTool)

• 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<number>. E.g <baseclass>V<version>

• 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* QisMmTool_name(const int version) const = 0;
virtual void* QisMmTool_cast(const int version) = 0;
virtual const void* QisMmTool_cast(const int version) const = 0;
virtual int QisMmTool_latest_version() const = 0;

Get_error_msg (QisMmTool)

Get_error_tag (QisMmTool)

Get_error_context (QisMmTool)

• Get error information for an operation that failed using the code returned by the said operation

xxxxxxxxxx
virtual const char* Get_error_msg(const int code) const = 0;
virtual const char* Get_error_tag(const int code) const = 0;
virtual const char* Get_error_context(const int code) const = 0;

Create_proc

Destroy_proc

• Create an instance of the mtool processor

• filedb is a handle to a valid DB created from GDSII/OASIS (paint/positive-only data)

• tiles is a set of one or more tiles (windows) that will --

  • be used to divide the operation amongst multiple tile threads

  • OR be used to generate clips of GDSII/OASIS/TIF8/TIFF/BMP/RAW files

• ecode can be used to retreive the error information should this operation fail

• opts is a string of options and license options to customize this operation

• On success, returns a non-NULL handle to a newly created object. Otherwise use Get_error_... to get error information

• Every instance of such an object MUST be eventually destroyed using Destroy_proc to avoid resource leaks

• **REQUIRES N licenses of QISMCODE_MTOOL (11119) where N = no. tile threads

• The licenses a released when the object is destroyed

xxxxxxxxxx
virtual QisMmToolProc* Create_proc(
  NsQisMLib::QisMFile* filedb, const NsQisMLib::QisMBoxSet* tiles, 
  int* ecode, const char* opts = 0
  ) = 0;
virtual void Destroy_proc(QisMmToolProc* proc) = 0;

Unload_DB

• Unload the DB (handle) created using Flush_to_DB

• Same as QisMmToolProc::Unload_DB

xxxxxxxxxx
virtual void Unload_DB(QisMmToolFile* handle) = 0;

QisMmTool Commands

• See qismmtool.h for the corresponding C++ api

• Some commands require a license

mtool.create_proc

xxxxxxxxxx
mtool.create_proc
  &proc={id} 
  $filedb={id} 
  $tiles={id} 
  [thrnum={nt}] 
  [overlap={uu}]

• Create an instance of the mtool object (mtool processor)

• &proc={id} is a name to be associated with the newly created processor

• $filedb={id} is a name associated with a valid DB created from GDSII/OASIS (paint/positive-only data)

• $tiles={id} is a name associated with a set of one or more tiles (windows) that will --

  • be used to divide the operation amongst multiple tile-threads/mtool-processors

  • OR be used to generate clips of GDSII/OASIS/TIF8/TIFF/BMP/RAW files

• thrnum={nt} if specified, is the number of threads to be used to process the tiles simultaneously. Default: no. cpus in the system

• overlap={uu} if specified, expands the tiles to create some overlap in user-units. Default:0.0

• Every instance of such an object MUST be eventually destroyed using mtool.destroy_proc to avoid resource leaks

• REQUIRES {nt} licenses of QISMCODE_MTOOL (11119)

• The licenses a released when the object is destroyed

• See QisMmTool::Create_proc

mtool.destroy_proc

xxxxxxxxxx
mtool.destroy_proc 
  $proc={id}

• Destroy mtool processor created using mtool.create_proc

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• See QisMmTool::Destroy_proc

mtoolproc.first_explode

xxxxxxxxxx
mtoolproc.first_explode 
  $proc={id} 
  [cell={name}] 
  [layers={ON | OFF},{str}]
  [nesting={level}] 
  [clip] 
  [thrnum={np}]

• Setup mtool processor to first explode polygons from each of the tiles

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• cell={name} if specified, sets the view cell. Default: default top cell

• layers=ON,... if specified, sets the view layers (not cumulative). Default: layers=ON,ALL

• layers=OFF,... if specified, sets the view layers to all but the specified layers (not cumulative)

• nesting={level} if specified set the nesting level at which polygons will be collected. Default: all nesting levels

• clip if specified will clip polygons to tile extents

• thrnum={np} if specified uses {nt} threads for clipping

• This operation does not require a license unless clip is specified in which case, N licenses of QISMCODE_QISMBOOL (11047) are required where N = no. mtool processors. The licenses are released when the mtool object is destroyed

• This setup will override any previous First_explode or First_lsynth setup

• See QisMmToolProc::First_explode

mtoolproc.first_lsynth

xxxxxxxxxx
mtoolproc.first_lsynth
  $proc={id} 
  spec={spec} 
  [butting={overlap}] 
  [thrnum={nt}] 
  [cell={name}] 
  [mergestripes]

• Setup mtool processor to first synthesize polygons using a layer expression spec={spec}

• See qismlayersynth.h for syntax of the layer spec.

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• butting={overlap} if used, converts output polygons with holes into butting polygons with overlap specified in user-units. Default: such polygons have cutlines instead

• thrnum={nt} if used, specifies the no. threads per tile for this operation. Default: 1

• cell={name} if used, sets the view cell. Default: default top cell of the db

• mergestripes if used, removes partition lines caused by the boolean operations

• This operation requires N licenses of QISMCODE_QISMLAYERSYNTH (11069) where N is the no. tile-threads/mtool-processors

• The license is released when the mtool object is destroyed

• This setup will override any previous first_explode or first_lsynth setup

• See QisMmToolProc::First_lsynth

mtoolproc.then_correct

xxxxxxxxxx
mtoolproc.then_correct
  $proc={id} 
  corrx={x,y,dx,dy}+

• Setup the mtool processor to apply corrections (bi-linear transformations) to polygons received from the previous step

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• corrx={...} is a list of measured distortion points in the format {x},{y},{dx},{dy} (in user units) per point

• This operation requires N licenses of QISMCODE_CORRX (11093) where N is the no. tile-threads/mtool-processors

• The license is released when the mtool object is destroyed

• This setup will override any previous Then_correct setup

• See QisMmToolProc::Then_correct

mtoolproc.then_transform

xxxxxxxxxx
  mtoolproc.then_transform
  $proc={id} 
  [translate={x_uu},{y_uu}] 
  [scale={x}[,{y}]]
  [rotate={deg}] 
  [shear={x}[,{y}]] 
  [mirror=X | Y | XY]

• Setup the mtool processor to apply affine transformations to polygons received from the previous step

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• translate=... if specified adds translation (user-units) to the transformation matrix

• scale=... if specified adds scaling (along X and Y) to the transformation matrix

• rotate=... if specified adds rotation (in degrees about 0,0) to the transformation matrix

• shear=... if specified adds shear (as factors along X and Y) to the transformation matrix

• mirror=... if specified adds reflection (negate/flip X, Y or XY) to the transformation matrix

• These transformation parameters can be used more than once in the same command for a cumulative effect

• This operation does not require any additional licenses

• This setup will override any previous Then_transform setup

• See QisMmToolProc::Then_transform

mtoolproc.then_unionize

xxxxxxxxxx
mtoolproc.then_unionize
  $proc={id} 
  [sliver={uu}] 
  [butting={overlap_uu}]
  [maxvert={4<=n<=8190}] 
  [sizing={x_uu},{y_uu}] 
  [convex] 
  [union] 
  [thrnum={n}] 
  [mergestripes] 
  [postclip] 
  [dbg={base_path}]"

• Setup the mtool processor to unionize the polygons received from the previous step

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• sliver={uu} if specified is the size in user-units for removing tiny artifacts (polygons) created by the unionization

• butting={overlap_uu} if specified converts polygons with holes into butting polygons with overlap (user-units) instead of cutlines

• sizing={x_uu},{y_uu} if specified adds positive or negative sizing (compensation)

• convex if specified generates polygons that are fully convex

• union if specified forces unionization of the output

• thrnum={n} specifies the number of threads per tile for unionization (default: 1)

• mergestripes if specified removes partitioning lines created during unionization

• postclip if specified clips the polygons to the corresponding tile extents

• dbg={base_path} if specified generates a text file with the specified base-path (dir + filename) for debugging/troubleshooting

• This operation requires N licenses of QISMCODE_QISMBOOL (11047) where N is the no. tile-threads/mtool-processors

• The license is released when the mtool object is destroyed

• This setup will override any previous Then_unionize setup

• See QisMmToolProc::Then_unionize

mtoolproc.patternize_before_flush

xxxxxxxxxx
mtoolproc.patternize_before_flush
  $proc={id} 
  [circles={max_sag_dbu}] 
  [jitter={uu}] 
  [minrep={rep_count}]

• Setup the mtool processor to group polygons into repeating patterns before being flushed to the output

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• circles={max_sag_dbu} if specified enables detection of polygons that are circles with the specified max. chord error in DBUnits

• jitter={uu} if specified uses the user-unit value as the margin of error

• minrep={rep_count} if specified generates pattern cells in the CAD output only if they repeat at least the specified number of times (default: 1)

• This operation MUST only be called before mtoolproc.flush_... commands because it will re-constitute the polygon storage and therefore any subsequent mtoolproc.then_... operations will not work

• This operation does not require any additional licenses

• This setup will override any previous mtoolproc.patternize_before_flush setup

• See QisMmToolProc::Patternize_before_flush

mtoolproc.flush_to_cad

xxxxxxxxxx
mtoolproc.flush_to_cad 
  $proc={id} 
  out={base_path} 
  [oasis] 
  [clips]

• Write the final polygons to CAD (GDSII/OASIS) file(s) on disk

• This is when the actual execution of the entire setup chain occurs -- for each tile, polygons are collected, processed and written

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• out={base_path} specifies the directory + filename for the output

• oasis if specified generates an OASIS file (default: GDSII)

• The extension .gds or .oas will be automatically added

• clips if specified generates one file per tile instead of a single composite from all the tiles

• In one-file-per-tile mode, a suffix .{tile_number} will be added before the extension. {tile_number} starts with 0 and represents the position of the tile in the list of tiles provided during Create_proc

• This operation does not require any additional licenses

• This operation destroys the polygons generated by the previous steps

• See QisMmToolProc::Flush_to_CAD

mtoolproc.flush_to_img

xxxxxxxxxx
  $proc={id} 
  out={base_path} 
  pixelsize={x}[,{y}] 
  [clips] 
  [format={TIF8 | TIFF | BMP | VBMP | RAW}] 
  [invert] 
  [r2l] 
  [b2t] 
  [thrnum={n}] 
  [noclip] 
  [roi={minx},{miny},{maxx},{maxy}]

• Write the final polygons to monochrome 1bpp image file(s) on disk

• This is when the actual execution of the entire setup chain occurs -- for each tile, polygons are collected, processed and written

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• out={base_path} specifies the directory + filename for the output

• pixelsize={x}[,{y}] is the desired resolution expressed as size of a pixel in user-units

• clips if specified, generates one file per tile instead of a composite image from all tiles

• In clips mode, a suffix .{tile_number} will be added before the extension. {tile_number} starts with 0 and represents the position of the tile in the list of tiles provided during Create_proc

• format=... if specified determines the output file format (default: TIF8)

• The extension .tif8, .tif, .bmp or .raw will be automatically added based on the specfied format

• invert if specified, changes the image polarity to black (1) background and white (0) data

• r2l if specified changes the raster direction along X (minx -> maxx) to right-to-left (default: left-to-right)

• b2t if specified changes the raster direction along Y (maxy -> miny) to bottom-to-top (default: top-to-bottom)

• thrnum={n} if specified used the specified number of threads per tile for formatting (default: 1)

• In clips mode, noclip if specified sets the per-tile image extents to the data extents instead of the tile extents

• In composite mode, roi=... will set the image extents to the specified ROI (user-units)

• This operation does not require any additional licenses

• This operation destroys the polygons generated by the previous steps

• See QisMmToolProc::Flush_to_IMG

mtoolproc.flush_to_db

xxxxxxxxxx
mtoolproc.flush_to_db
  $proc={id} 
  &filedb={id} 
  [dbg] 
  [workdir={path}]

• Create a new and independent QisMFile DB from the final polygons that can be used as a source for post-processing with other script commands

• This is when the actual execution of the entire setup chain occurs -- for each tile, polygons are collected, processed, written and loaded

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• &filedb={id} is name to be associated with the newly created DB that can be used in other commands that require a file-db

• workdir={path} if used, sets the directory where the temporary folder mtool.{number} will be created to hold temp. working files. Default: The temp. folder will be created in the user's CWD

• dbg if used keeps the temportary folder mtool.{number} even after the database has been destroyed

• This operation does not require any additional licenses

• This operation destroys the polygons generated by the previous steps

• The DB handle MUST be eventually destroyed using mtool.unload_db to avoid resource leaks

• See QisMmToolProc::Flush_to_DB

mtool.unload_db

xxxxxxxxxx
mtool.unload_db
  $filedb={id}

• Destroy the database represented by {id} created using mtoolproc.flush_to_db

• See QisMmTool::Unload_DB

mtoolproc.flush_to_cb

xxxxxxxxxx
mtoolproc.flush_to_cb
  $proc={id} 
  [counts] 
  [gds={name},{units_m},{grid_m}]

• Redirects to the C++ API method QisMmToolProc::Flush_to_CB and optionally prints per-tile polygon counts and writes them to GDSII on disk

• $proc={id} is name associated with the mtool processor created using mtool.create_proc

• counts if used prints the per-tile polygon counts

• gds={name},{units_m},{grid_m} writes the output polygons to disk as a GDSII with the specified units (in meter) and grid (in meter)

• This is when the actual execution of the entire setup chain occurs -- for each tile, polygons are collected, processed and sent

• This operation does not require any additional licenses

• This operation destroys the polygons generated by the previous steps

• See QisMmToolProc::Flush_to_CB

QisMmTool Licensing (API)

• N is the no. tile threads

• * clipping polygons to tile extents requires N x QISMBOOL licenses

QisMmTool Licensing (Script)

QisMmTool Version History

qismmtool dll/so v1.0 2024/02/13

• First cut