[Artwork] / [QisMLib]

QisMBoolFiles Extension

A QisMLib extension to perform boolean operations between two GDSII/OASIS/DBLOAD databases

QisMBoolFiles C++ API (qismboolfiles.h)

QisMBoolFilesFlags

Various flags used by QisMBoolFiles

struct QisMBoolFilesFlags { ... };

Operation

Op. codes for boolean operations

xxxxxxxxxx
enum Operation {  
   DO_OR = 1 /* Agrregate polygons of file1 and file2 without unionizing */
  ,DO_UNION = 2 /* Unionize polygons of file1 and file2 */
  ,DO_INTERSECTION = 3 /* Compute intersection of polygons between file1 and 
                          file2 */
  ,DO_DIFFERENCE = 4 /* Compute difference file1 - file2 */
  ,DO_XOR = 5 /* Compute XOR file1 vs file2 */
};

QisMBoolFilesWindows

Object to store a set of windows

xxxxxxxxxx
class QisMBoolFilesWindows { ... };

Object_name

Get implementation name and version

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

Version Control (QisMBoolFilesWindows)

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* QisMBoolFilesWindows_cast(const int version) = 0;
virtual const void* QisMBoolFilesWindows_cast(const int version) const = 0;
virtual int QisMBoolFilesWindows_latest_version() const = 0;

Reset

Clear all the windows

xxxxxxxxxx
virtual void Reset() = 0;

Add

Add a new window to this set

• base_name : Name to identify this window

• llx, lly, urx, ury : Min-max X,Y co-ordinates of the window extents in file units

• grid : Smallest measurable distance in file units. urx > (llx + grid), ury > (lly + grid)

• Success : true

• Failure : false, invalid window extents

xxxxxxxxxx
virtual bool Add(
  const char* base_name, const double llx, const double lly, 
  const double urx, const double ury, const double grid = 0.0
  ) = 0;

Random_shuffle

Randomize the order of the windows in this set

xxxxxxxxxx
virtual void Random_shuffle() = 0;

Count

Get the number of windows in this set

xxxxxxxxxx
virtual size_t Count() const = 0;

Get

Get a specific window from this set

• index : Window position >= 0 and < QisMBoolFilesWindows::Count()

• llx, lly, urx, ury : Buffer to get the min-max X,Y co-ordinates of the window extents in file units

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

QisMBoolFilesParams

Object to store options for boolean ops between two files

xxxxxxxxxx
class QisMBoolFilesParams { ... };

Object_name

Get implementation name and version

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

Version Control (QisMBoolFilesParams)

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* QisMBoolFilesParams_cast(const int version) = 0;
virtual const void* QisMBoolFilesParams_cast(const int version) const = 0;
virtual int QisMBoolFilesParams_latest_version() const = 0;

Reset

Reset options to default values

xxxxxxxxxx
virtual void Reset() = 0;

Set_operation

Get_operation

Set/Get the operation code

• Default: QisMBoolFilesFlags::DO_OR

xxxxxxxxxx
virtual void Set_operation(const QisMBoolFilesFlags::Operation op) = 0;
virtual QisMBoolFilesFlags::Operation Get_operation() const = 0;

Set_clip

Get_clip

Set/Get window clipping to ON (true)/OFF (false)

• Default: ON

Set_threads

Get_window_threads

Get_threads_per_window

Set/Get the number of windows to be processed in parallel (n_window_threads) and the number of threads per window for boolean operations (n_threads_per_window)

• Default: 0 (Auto-set), 1

xxxxxxxxxx
virtual void Set_threads(
  const int n_window_threads, const int n_threads_per_window
  ) = 0;
virtual int Get_window_threads() const = 0;
virtual int Get_threads_per_window() const = 0;

Set_sliver

Get_sliver

Set/Get sliver value (smallest acceptable size in file units for output polygons).

• Default: 0.0 (No sliver removal)

xxxxxxxxxx
virtual void Set_sliver(const double value) = 0;
virtual double Get_sliver() const = 0;

Set_max_output_vertices

Get_max_output_vertices

Set/Get max. number of vertices per polygon ( >= 4 and <= 8190)

• Default: 8190

xxxxxxxxxx
virtual void Set_max_output_vertices(const int n) = 0;
virtual int Get_max_output_vertices() const = 0;

Set_dynamic_windows

Get_dynamic_windows

Turn Dynamic-windowing ON/OFF

• Default: 0 (OFF)

• When n_vert_per_win > 0, every window that has more than n_vert_per_win*2 vertices will be split into four quads and re-processed. This can lead to siginificant performance improvement

• This should not be used if window extents of the output needs to be same as the input

xxxxxxxxxx
virtual void Set_dynamic_windows(const int n_vert_per_win) = 0;
virtual int Get_dynamic_windows() const = 0;

QisMBoolFilesClient

A callback to recieve output of boolean operations

xxxxxxxxxx
class QisMBoolFilesClient { ... };

Version Control (QisMBoolFilesClient)

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

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

• The version of the topmost base class is 1. E.g if QisMBoolFilesClient is the topmost base class (version 1), QisMBoolFilesClientV2 QisMBoolFilesClientV3 etc. would be the future extensions of QisMBoolFilesClient

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

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

On_qismboolfiles_message_mt

Intercept an informational message from QisMBoolFiles

xxxxxxxxxx
virtual void On_qismboolfiles_message_mt(
  const char* pre, const char* msg, const char* post
  ) {}

On_qismboolfiles_warning_mt

Intercept a warning message from QisMBoolFiles. Return non-zero to interrupt execution

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

On_qismboolfiles_window_mt

Notification that a specific window has been processed

• window_name : Name of the window in question

• extents : FOUR doubles representing min-max X,Y co-ordinates of the extents of the window in question

• n1, n2, n0 : Number of polygons in input set 1, 2 and output. This is also the size of (xy1, xy2, xy0) and (nv1, nv2, nv0) arrays

• nv1, nv2, nv0 : Array of no. vertices for each polygon in the input set 1, 2 and output respectively

• xy1, xy2, xy0 : Array of arrays of x,y co-ordinates for each polygon in the input set 1, 2 and output respectively

• zero to continue execution

• non-zero to interrupt execution (will result in an error message: Client interrupt [code ])

• A set of polygons is represented by THREE parameters

  • n is the number of polygons in this set

  • nv is the array of number of vertices per polygon in this set. For 0 <= i < n, nv[i] represents the number of vertices for polygon i

  • xy is the array of arrays, one per polygon containing the x,y co-ordinates of that polygon. For 0 <= i < n; xy[i] represents a single polygon i and contains nv[i] x,y pairs or nv[i]*2 integers

• CAUTION This notification can originate from multiple threads simultaneously. It is the responsibility of the client to ensure that any operations performed inside this notification is done in a thread-safe manner

xxxxxxxxxx
virtual int On_qismboolfiles_window_mt(
  const char* window_name, const double* extents, 
  const int* const* xy1, const int* nv1, const int n1,
  const int* const* xy2, const int* nv2, const int n2,
  const int* const* xy0, const int* nv0, const int n0,
  const double grid
  ) { return 0; }

Advanced options for QisMBoolFiles::Booleanize_two_files (argc, argt, argv)

• Use this argument to directly specify the QisMBoolSettings object that controls the boolean operations

• argv is of type QisMBoolSettings* (qismbool.h)

• This is an advanced feature. It is assumed that the client understands it's implications on the results

• The following QisMBoolSettings features will be overriden by QisMBoolFiles::Booleanize_two_files

  • QisMBoolSettings::Set_pass_through_mode

  • QisMBoolSettings::Set_max_points

  • QisMBoolSettings::Set_sliver

  • QisMBoolSettings::Set_clip_window

• Requires the QisMBoolSettings* object to support QisMBoolSettingsV2

xxxxxxxxxx
#define ARGT_QISMBOOLOPTS "QisMBoolSettings"  

QisMBoolFiles

Primary interface to the QisMBoolFiles extension

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

Version Control (QisMBoolFiles)

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* QisMBoolFiles_cast(const int version) = 0;
virtual const void* QisMBoolFiles_cast(const int version) const = 0;
virtual int QisMBoolFiles_latest_version() const = 0;

Get_last_error_msg

Get_last_error_code

Get 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/Destroy objects of specific classes

• class_name : Name of the class whose object is to be created/destroyed. Valid names are:

  • QisMBoolFilesWindows

  • QisMBoolFilesParams

• handle: Handle to the object to be destroyed

• Success : non-NULL pointer to a new object

• Failure : NULL (Invalid/Unrecognized class name)

• Each object created by this method MUST be type-casted to that specific class only and MUST be eventually destroyed using Delete_object(..) to avoid memory/resource leak

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

Booleanize_two_files

Perform boolean operation between sets of polygons of two files

• file_1, file_2 : Handle to the two QisMFile databases already loaded using QisMLib::Load_file

• cell_1, cell_2 : Names of the view cells for both files. If cell_1 is empty/null, the default top cell is used. If cell_2 is empty/null, it is set to cell_1

• layers_1, layers_2 : Comma-separated list of layers from each file to be used. If layers_1 is empty/null/"ALL", all layers of file_1 are used. If layers_2 is empty/null, layers_2 is set to layers_1. If layers_2 is ALL, all layers of file_2 are used

• window_set : Set of windows to be processed. If this set is empty/null, the extents of the first file's view cell are used as the only window

• options : Various options to for processing these windows. If null, default values are used

• client : Pointer to an object that will handle various notifications while the operation is in progress. The handler MUST implement the QisMBoolFilesClient interface and override relevant notification methods

• argc, argt, argv : See Advanced options for QisMBoolFiles::Booleanize_two_files above

• Success : non-NULL pointer to a new object

• Failure : NULL (Invalid/Unrecognized class name)

• This method creates QisMBoolFilesParams::Get_window_threads() processor threads which simultaneously extracted polygons for a specific window from both files and then performs boolean operations between those polygons.

• The resulting data set is served up to the client in form of the QisMBoolFilesClient::On_qismboolfiles_window_mt notification

• Each processor/window thread fetches a new window from a shared queue. The function returns when there is no more window to be processed

xxxxxxxxxx
virtual bool Booleanize_two_files(
  NsQisMLib::QisMFile* file_1, const char* cell_1, const char* layers_1, 
  NsQisMLib::QisMFile* file_2, const char* cell_2, const char* layers_2,
  const QisMBoolFilesWindows* window_set, const QisMBoolFilesParams* options,
  QisMBoolFilesClient* client, const int argc = 0,
  const char* const* argt = 0, const void* const* argv = 0
  ) = 0;

QisMBoolFiles commands

• Requires the QisMBoolFiles extension to be installed and loaded

• Some commands may require licenses

• Refer to qismboolfiles.h for C++ API

twofiles.xor

xxxxxxxxxx
twofiles.xor
  $filedb={id1},{id2}
  [cell={cell1},{cell2}]
  [layers={layers_string}]
  [limit={count}]
  [thrnum={n_tiles},{n_per_tile}]
  [gds={output_gds_path}]
  [sliver={value}[,{unit}]]
  [complexity={n_vertices_per_tile}]
  [partial=TILES,{pct_tiles}]
  [partial=LAYERS,{pct_layers}]
  [margin={extents_error}[,{unit}]]
  [xorinput={l},{d}]

• Compare two databases by performing a layer-wise geometric XOR between their polygons by breaking up the region of interest into smaller tiles

• {id1},{id2} are names of variables of type QisMFile* associated with the databases to be compared

• {cell1},{cell2} if specified are the names of the view cells of each database to be compared (default: deepest/largest top cell of each db)

• {layers_string} if specified is a comma-separated list of layers of interest. Only the specified layers will be compared (default: ALL layers from the first db). Each layer of interest MUST be present in both databases

• {count} if specified terminates the comparison as soon as the computed differences exceed the specified limit. If {count} == 0, the comparison computes all the differences (default: 1)

• {n_tiles} represents the no. threads to be created to process one tile of the view at a time (default: no. processors in the system). {n_per_tile} is the no. threads per tile to perform XOR (default: 1)

• {output_gds_path} if specified writes the computed XOR to a GDSII file (default: no GDSII output)

• sliver if specified removes XOR results smaller than the specified value. {unit} if specified indicates the units of the value supplied. Allowed units are m, cm, mm, um, nm, in, mils, dbu. Default units : source file units

• {n_vertices_per_tile} if specified determines how the per-layer space is broken up into tiles for parallel computation (default: 5000). The larger the value of {n_vertices_per_tile}, the more intensive the XOR computation is and should be matched with an appropriate no. threads ({n_per_tile})

• {pct_tiles} if specified limits the no. tiles to be compared per layer to the specified percentage of the total no. of tiles allocated to that layer. The selection of tiles is random and therefore this can be used to do a quicker test (default: 100 -- full test)

• {pct_layers} if specified limits the no. layers to be compared to the specified percentage of the layers of interest (or all layers). The selection of layers is random and therefore this can be used to do a quicker test (default: 100 -- all of the specified/available layers)

• margin if specified allows the home view extents of the two files to have a difference up to the specified value. {unit} if specified indicates the units of the value supplied. Allowed units are m, cm, mm, um, nm, in, mils, dbu. Default units : source file units

• xorinput if specified writes the source data at a new layer and datatype that is an offset from the source by {l} and {d}

QisMBoolFiles Licensing (API)

Product name: QisMBoolFiles License code: 11071

QisMBoolFiles Licensing (SCRIPT)

Product name: QisMBoolFiles License code: 11071

QisMBoolFiles Version History

qismboolfiles dll/so v1.4 08-2022

• Improved script command twofiles.xor with new options margin and xorinput

qismboolfiles dll/so v1.3 02-2020

• Support for scripting with QisMScript

qismboolfiles dll/so v1.2 07-2019

• New advanced arg ARGT_QISMBOOLOPTS for Booleanize_two_files so that the client can flavor the output of the boolean operations beyond what is permitted by the API

qismboolfiles dll/so v1.1 06-2018

• Compatible with QisMLib 3.20 (API break)

• This extension will not load with earlier versions of QisMLib

qismboolfiles dll/so v1.0 02-2018

• First cut