Welcome to the reference page for QisMBoolFiles, an extension of QisMLib, Artwork Conversion's CAD processing framework.
QisMBoolFiles performs boolean operations between the polygons of two separate layout files, which may be in GDSII, OASIS or the framework's own loaded-database form. A boolean operation treats each file as a set of shapes and combines them: it can simply collect both sets together, merge them into one, keep only where they overlap, subtract one from the other, or compute the exclusive-or, which keeps only the places where the two files differ. That last operation is the most common use, because it turns the extension into a comparison tool that highlights every difference between two versions of a design.
To handle very large layouts, the work is divided into rectangular windows that are processed in parallel by several processor threads. The results for each window are delivered to the calling program as they finish, and the extension can also write them to a GDSII file.
This page is the complete reference for the extension. Here is what you will find, in the order it appears:
C++ programming interface. The operation codes for the five boolean operations; a container for the set of windows to be processed, which can be shuffled into random order; a parameter object controlling the operation, clipping, thread counts, sliver removal, maximum vertices per polygon and an optional dynamic subdivision of busy windows; a callback interface through which the program receives messages, warnings and the input and output polygons of each finished window; an advanced argument for passing the framework's own boolean settings object; and the main interface that creates the helper objects, reports errors and runs the operation between two loaded files.
Script commands. A single command for the framework's scripting system that compares two databases layer by layer using exclusive-or, breaking each layer into tiles. Its options cover the cells and layers to compare, a difference limit that stops early, thread counts, GDSII output, sliver removal, tile complexity, random partial testing of a percentage of tiles or layers, a tolerance for mismatched file extents, and writing the source data alongside the differences.
Licensing. One license per parallel window or tile thread, held only for the duration of the operation, for both the programming interface and the script command.
Version history. A release log from the first release in February 2018 through version 1.4 in August 2022, adding advanced boolean settings, scripting support, and new comparison options.
If you just want to compare two files, go straight to the script command. Developers integrating the extension should start with the C++ programming interface.
QisMBoolFiles ExtensionQisMBoolFiles C++ API (qismboolfiles.h)QisMBoolFilesFlagsOperation QisMBoolFilesWindowsObject_nameVersion Control (QisMBoolFilesWindows)ResetAddRandom_shuffleCountGetQisMBoolFilesParamsObject_nameVersion Control (QisMBoolFilesParams)ResetSet_operationGet_operationSet_clipGet_clipSet_threadsGet_window_threadsGet_threads_per_windowSet_sliverGet_sliverSet_max_output_verticesGet_max_output_verticesSet_dynamic_windowsGet_dynamic_windowsQisMBoolFilesClientVersion Control (QisMBoolFilesClient)On_qismboolfiles_message_mtOn_qismboolfiles_warning_mtOn_qismboolfiles_window_mtAdvanced options for QisMBoolFiles::Booleanize_two_files (argc, argt, argv)QisMBoolFilesVersion Control (QisMBoolFiles)Get_last_error_msgGet_last_error_codeNew_objectDelete_objectBooleanize_two_filesQisMBoolFiles commandstwofiles.xorQisMBoolFiles Licensing (API)QisMBoolFiles Licensing (SCRIPT)QisMBoolFiles Version Historyqismboolfiles dll/so v1.4 08-2022qismboolfiles dll/so v1.3 02-2020qismboolfiles dll/so v1.2 07-2019qismboolfiles dll/so v1.1 06-2018qismboolfiles dll/so v1.0 02-2018
Various flags used by QisMBoolFiles
struct QisMBoolFilesFlags { ... };Op. codes for boolean operations
xxxxxxxxxxenum 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 */};Object to store a set of windows
xxxxxxxxxxclass QisMBoolFilesWindows { ... };Get implementation name and version
xxxxxxxxxxvirtual const char* Object_name() const = 0;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
The topmost base class is version 1 (V1 implied).
The cast returns NULL if a version number is not recognized/implemented
xxxxxxxxxxvirtual void* QisMBoolFilesWindows_cast(const int version) = 0;virtual const void* QisMBoolFilesWindows_cast(const int version) const = 0;virtual int QisMBoolFilesWindows_latest_version() const = 0;Clear all the windows
xxxxxxxxxxvirtual void Reset() = 0;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
xxxxxxxxxxvirtual bool Add( const char* base_name, const double llx, const double lly, const double urx, const double ury, const double grid = 0.0 ) = 0;Randomize the order of the windows in this set
xxxxxxxxxxvirtual void Random_shuffle() = 0;Get the number of windows in this set
xxxxxxxxxxvirtual size_t Count() const = 0;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
xxxxxxxxxxvirtual const char* Get( const int index, double& llx, double& lly, double& urx, double& ury ) const = 0;Object to store options for boolean ops between two files
xxxxxxxxxxclass QisMBoolFilesParams { ... };Get implementation name and version
xxxxxxxxxxvirtual const char* Object_name() const = 0;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
The topmost base class is version 1 (V1 implied)
The cast returns NULL if a version number is not recognized/implemented
xxxxxxxxxxvirtual 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 options to default values
xxxxxxxxxxvirtual void Reset() = 0;Set/Get the operation code
Default: QisMBoolFilesFlags::DO_OR
xxxxxxxxxxvirtual void Set_operation(const QisMBoolFilesFlags::Operation op) = 0;virtual QisMBoolFilesFlags::Operation Get_operation() const = 0;Set/Get window clipping to ON (true)/OFF (false)
Default: ON
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
xxxxxxxxxxvirtual 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/Get sliver value (smallest acceptable size in file units for output polygons).
Default: 0.0 (No sliver removal)
xxxxxxxxxxvirtual void Set_sliver(const double value) = 0;virtual double Get_sliver() const = 0;Set/Get max. number of vertices per polygon ( >= 4 and <= 8190)
Default: 8190
xxxxxxxxxxvirtual void Set_max_output_vertices(const int n) = 0;virtual int Get_max_output_vertices() const = 0;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
xxxxxxxxxxvirtual void Set_dynamic_windows(const int n_vert_per_win) = 0;virtual int Get_dynamic_windows() const = 0;A callback to recieve output of boolean operations
xxxxxxxxxxclass 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
xxxxxxxxxxvirtual 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} */Intercept an informational message from QisMBoolFiles
xxxxxxxxxxvirtual void On_qismboolfiles_message_mt( const char* pre, const char* msg, const char* post ) {}Intercept a warning message from QisMBoolFiles. Return non-zero to interrupt execution
xxxxxxxxxxvirtual int On_qismboolfiles_warning_mt( const char* pre, const char* msg, const char* post ) { return 0; }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
xxxxxxxxxxvirtual 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; }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
xxxxxxxxxxPrimary interface to the QisMBoolFiles extension
xxxxxxxxxxclass QisMBoolFiles: public NsQisMLib::QisMExtensionAPI { ... };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
The topmost base class is version 1 (V1 implied). The cast returns NULL if a version number is not recognized/implemented
xxxxxxxxxxvirtual 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 message/code for the last error condition
xxxxxxxxxxvirtual const char* Get_last_error_msg() const = 0;virtual int Get_last_error_code() const = 0;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
xxxxxxxxxxvirtual void* New_object(const char* class_name) = 0;virtual void Delete_object(const char* class_name, void* handle) = 0;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
xxxxxxxxxxvirtual 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;Requires the QisMBoolFiles extension to be installed and loaded
Some commands may require licenses
Refer to qismboolfiles.h for C++ API
xxxxxxxxxxtwofiles.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}
Product name:
QisMBoolFilesLicense code:11071
| Operation | No. Licenses | Notes |
|---|---|---|
| Booleanize_two_files | Get_window_threads (via options) | license is held only for the duration of the operation |
Product name:
QisMBoolFilesLicense code:11071
| Operation | No. Licenses | Notes |
|---|---|---|
| twofiles.xor | {ntiles} (via thrnum parameter) | license is held only for the duration of the operation |
Improved script command twofiles.xor with new options margin and xorinput
Support for scripting with QisMScript
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
Compatible with QisMLib 3.20 (API break)
This extension will not load with earlier versions of QisMLib
First cut
Last Updated -- Thu Oct 1 19:07:26 UTC 2026