[Artwork] / [QisMLib]

QisMOasUtil Extension

A QisMLib extension to pre-process OASIS files for simplified loading

Overview

• QisMOasUtil is an OASIS pre-processor that can be used to --

  • Translate an OASIS file to various formats without creating a database (GDSII, GDSII.GZ, DBLOAD, ASCII)

  • Apply custom handling of certain OASIS data features before creating a database

  • Debug OASIS issues by displaying records in human-readable ASCII format

QisMOasUtil C++ API

Layermap Syntax

Oas2GdsOpts

OASIS to GDSII conversion options

​x
struct Oas2GdsOpts
{
  /* Specify the max. number of vertices in any output polygon (boundary or path)
   maxv={0 | 4 <= n <= 8190}

   * maxv=0 implies writing a polygon with vertices > 8190 with multiple GDSII XY records
   * maxv={n} where 4 <= n <= 8190 implies breaking such a polygon into smaller polygons to meet the max. limit
  */ 
  static const char* MAX_V() { return "maxv="; }

  /* Generate a compressed GDSII (.gz)
   gzip={path}

   * Where `{path}` is the location of the compression utility (gzip64.exe on Windows, gzip64 on Linux)
   * This utility can also be found in the installation directory's artwork folder
   * The decision to generate a compressed GDSII is a tradeoff between slower translation and saving disk space
  */ 
  static const char* GZIP() { return "gzip="; }

  /* Filter or re-map layers in the output
   layermap={str}

   where...

   {str} := {map}[,{map}]*
   {map} := {from}-{to}
   {from} := "ALL" | {layer} | {layer}:{datatype}
   {to} := "NULL" | {layer} | {layer}:{datatype}
   {layer},{datatype} >= 0

   * `ALL` implies all {layer}:{datatype} (`*:*`)
   * `NULL` implies OFF/dropped
   * `ALL-NULL` turns all layers OFF
   * `ALL-{layer}` re-maps all layer numbers to `{layer}` thereby merging all layers with the same datatype into a single {layer}:datatype
   * `ALL-{layer}:{datatype}` merges all layers to a single {layer}:{datatype}
   * Unless `ALL` is used already, any {layer}[:{datatype}] not present in the mapping remains unaffected
   * `{layer}` without `{datatype}` implies all datatypes (`{layer}:* for `{from}`) or ignore datatype (for `{to}`)
   * Layer mapping is cumulative. A `{map}` that appears later in `{str}` has the potential to override a previous `{map}`
   * NO whitespace characters allowed
  */ 
  static const char* LAYERMAP() { return "layermap="; }

  /* Do not output OASIS TEXT records
  */ 
  static const char* NOTEXT() { return "notext"; }

  /* Drop select cell (definition and references) based on regular expression
   dropcells={separator}{doslike_regex}[{separator}{doslike_regex}]*

   * `{separator}` is a char that delimits individual expressions
   * `{doslike_regex}` is a regular-expression in dos-like syntax (as opposed to unix-like)
   * Any cell whose name matches ANY of the expressions will be dropped from the output (definition and all references)
  */ 
  static const char* DROP_CELLS() { return "dropcells="; }
};

Oas2DBOpts

OASIS to DB conversion options

xxxxxxxxxx
struct Oas2DBOpts
{
  /* Specify the directory where the temporary folder will be created
   wordir={existing_dir_path}

   * `{existing_dir_path}` MUST exist and have write permissions for the user running the application
   * A folder called `qismoasutil.{number}` will be created in the working directory
  */
  static const char* WORK_DIR() { return "workdir="; }

  /* Keep temporary files (and folder) upon destroying the database
   */
  static const char* DBG() { return "dbg"; }

  /* Specify a base-name for the GDSII file that serves as the source of the database
     outname={basename}

   * This can be particularly useful if the database is then used to save memory maps (caches)
   */
  static const char* OUT_NAME() { return "outname="; }
};

OasUtilNotify

Represents a handler for recieving notifications related to select QisMOasUtil operations

xxxxxxxxxx
class OasUtilNotify { ... };

Version control

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

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<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 void* OasUtil_cast(const int version) = 0;
virtual const void* OasUtil_cast(const int version) const = 0;
virtual int OasUtil_latest_version() const = 0;

On_oasutil_progress

An update about the OASIS conversion

• Return 0 to continue. Otherwise the operation will be terminated (appropriately) with an error message

xxxxxxxxxx
virtual int On_oasutil_progress(const char* msg) { return 0; }

Oas2GdsFile

Represents a database object created from an OASIS file generated by Oasis_to_Gdsii

xxxxxxxxxx
class Oas2GdsFile { ... };

Version control

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

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<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 void* Oas2GdsFile_cast(const int version) = 0;
virtual const void* Oas2GdsFile_cast(const int version) const = 0;
virtual int Oas2GdsFile_latest_version() const = 0;

Get_error_msg

Get_error_tag

Get information for the error represented by the return code ecode

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

File_db

• Get a handle to the underlying file database

• DO NOT destroy this database using QisMLib::Unload_file. Only use Unload_DB for that

Save_to_gdsii

• Save the file database to a separate GDSII file on disk

• Returns 0 on success. Otherwise use Get_error_* with the return code to get error information

QisMOasUtil

Primary interface to use the QisMOasUtil extension

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

Version control

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

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<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* QisMOasUtil_name(const int version) const = 0;
virtual void* QisMOasUtil_cast(const int version) = 0;
virtual const void* QisMOasUtil_cast(const int version) const = 0;
virtual int QisMOasUtil_latest_version() const = 0;

Get_error_msg

Get_error_tag

Get_error_context

Get information for the error represented by the return code ecode

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

Oasis_to_Gdsii

Convert an OASIS file to GDSII on disk

• input is the path of a valid OASIS file

• output is the path where the GDSII file is to be created

• opts is a string of optional parameters separared by space

• progress is a callback to recieve progress updates with an opportunity to terminate the operation

• This operation does not require any additional licenses

• Returns 0 on success. Otherwise use Get_error_* with the return value for information about the error

xxxxxxxxxx
virtual int Oasis_to_Gdsii(const char* input, const char* output, const char* opts = 0, OasUtilNotify* progress = 0) = 0;

Oasis_to_DB

Unload_DB

Convert an OASIS file to GDSII and load it as a database in QisMLib

• input is the path of a valid OASIS file

• opts is a string of optional parameters GDSII,DB separared by space

• progress is a callback to recieve progress updates with an opportunity to terminate the operation

• Returns 0 on success with db pointing to a valid (non-NULL) handle to the newly created database. Otherwise use Get_error_* with the return value for information about the error

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

xxxxxxxxxx
virtual int Oasis_to_DB(const char* input, Oas2GdsFile*& db, const char* opts = 0, OasUtilNotify* progress = 0) = 0;
virtual void Unload_DB(Oas2GdsFile* db) = 0;

QisMOasUtil Commands

QisMScript Commands to pre-process OASIS files

oas2gdsii

xxxxxxxxxx
oas2gdsii
  oasis={path} 
  gdsii={path} 
  [maxv={4 <= n <= 8190} | 0]
  [gzip]
  [layermap={str}]
  [notext]
  [dropcells={sep}{regex}[{sep}{regex}]*]

• Create a GDSII file from OASIS

• oasis={path} specifies the source OASIS

• gdsii={path} specifies the target GDSII

• maxv controls how polygons with vertices greater than 8190 are handled --

  • if maxv == 0 (default), such polygons (boundaries and paths) are written to GDSII with multiple XY records per boundary/path. This format may work with some GDSII readers and may fail with some others

  • if 4 <= maxv <= 8190, such boundaries are broken up into smaller butting boundaries of max. maxv vertices and a single XY record per boundary. Paths are still written with multiple XY records per path

• gzip if specified generates a gzip compressed GDSII file with a .gz extension

• layermap if specified applies mapping to layers. See qismoasutil.h for syntax of {str}

• notext if specified will drop all TEXT records from the output

• dropcells if specified will drop any cell (definition and reference) that matches any of the specified dos-like regular expression {regex}. {sep} is a char used to separate the expressions

• progress={tag} is specified appends progress messages with [{tag}] for easy parsing

oas2dbload

xxxxxxxxxx
oas2dbload
  oasis={path} 
  name={basename} 
  [outdir={dir_path}]
  [maxv={4 <= n <= 8190} | 0]
  [layermap={str}]
  [notext]
  [dropcells={sep}{regex}[{sep}{regex}]*]
  [workdir={dir_path}]
  [dbg]

• Create a DBLOAD memory maps (caches) from the OASIS file

• oasis={path} specifies the source OASIS

• name={basename} specifies the base-name of the dbload maps (.dbload.l64 and .scan.l64 will be automatically added)

• outdir={dir_path} specified the output directory (MUST exist and have write permissions). Defualt: CWD

• maxv controls how polygons with vertices greater than 8190 are handled --

  • if maxv == 0 (default), such polygons (boundaries and paths) are written to GDSII with multiple XY records per boundary/path. This format may work with some GDSII readers and may fail with some others

  • if 4 <= maxv <= 8190, such boundaries are broken up into smaller butting boundaries of max. maxv vertices and a single XY record per boundary. Paths are still written with multiple XY records per path

• layermap if specified applies mapping to layers. See qismoasutil.h for syntax of {str}

• notext if specified will drop all TEXT records from the output

• dropcells if specified will drop any cell (definition and reference) that matches any of the specified dos-like regular expression {regex}. {sep} is a char used to separate the expressions

• workdir={dir_path} if specified generates the temporary working folder in the specified dir. instead of the CWD. This folder has the format qismoasutil.{number}

• dbg if specified keeps the temporary working folder and it's contents even after the operation has been completed successfully. The temporary file(s) can be very large. So exercise this option only when necessary. Better to use oas2gdsii instead

• progress={tag} is specified appends progress messages with [{tag}] for easy parsing

oas2ascii

xxxxxxxxxx
oas2ascii
  oasis={path} 
  [ascii={path}] 
  [no_details] 
  [ignore=all | none | {rec}[,{rec}]*] 
  [only={rec}[,{rec}]*] 
  [jump={offset}] 
  [limit={n_records}]

• Create an ASCII (human-readable) dump of the OASIS file based on the OASIS spec.

• oasis={path} specifies the source OASIS

• ascii={path} is the path of the target ascii (text) file. If not specified, the text is written to QisMLib system log

• no_details if specified, prints only the record names and offsets. Record contents are omitted

• ignore=... if specified skips the specified records based on their record-number {rec}. E.g {rec}=21 represents POLYGON. Overrides any previous only

• only=... if specified processes only the specified record-numbers. This is complement of ignore. Overrides any previous ignore

• jump={offset} if specified jumps straight to the specified offset. This offset MUST be the start of a record as listed in the default ASCII report

• limit={n_records} outputs only the next {n_records} records

Oas2Gdsii Applet

Generate GDSII files from an OASIS file

xxxxxxxxxx
oas2gdsii.cmd <required>+ <optional>*

Required

+oasis:{oasis_path}

• Specify path of a valid OASIS file

+gdsii:{gdsii_path}

• Specify path where the output GDSII file will be created

Optional

[-maxv:{4 <= n <= 8190}]

• If specified, any polygon larger than the specified number of vertices will be broken up into smaller polygons

• If -maxv:0 is used, any polygon larger than 8190 vertices will be writen using multiple XY records as part of the same polygon definition

[-layermap:{str}]

• If specified, layers will be mapped/filtered as per the specified syntax

[-dropcells:{sep}{regex}{{sep}{regex}}*]

• If specified, all cells whose name matches any {regex} will be dropped (definition and references)

• {sep} is a char used to separate individual expressions

[-gzip]

• If specified, the output will be a compressed (GZIP) GDSII

• The compression happens on-the-fly

• A .gz extension will be added automatically

[-notext]

• If specified, all TEXT records will be ignored during OASIS processing

[-progress:{tag}]

• Prepend progress messages with [{tag}] for programatic parsing

Oas2Dbload Applet

Generate QisMLib DBLOAD (.scan.l64 and .dbload.l64) files for an OASIS file

xxxxxxxxxx
oas2dbload.cmd <required>+ <optional>*

Required

+oasis:{oasis_path}

• Specify path of a valid OASIS file

Optional

[-maxv:{4 <= n <= 8190}]

• If specified, any polygon larger than the specified number of vertices will be broken up into smaller polygons

[-layermap:{str}]

• If specified, layers will be mapped/filtered as per the specified syntax

[-notext]

• If specified, all TEXT records will be ignored during OASIS processing

[-dropcells:{sep}{regex}[{sep}{regex}]*]

• If specified, all cells whose name matches any {regex} will be dropped (definition and references)

• {sep} is a char used to separate individual expressions

[-outdir:{dir_path}]

• If specified, the cache files (.dbload.l64 and .scan.l64) will be created in the specified {dir_path}

• {dir_path} MUST exist and be write OK

• By default, cache files will be created in the current working directory

[-name:{basename}]

• If specified, the base name of the cache files will be changed to the one specified

• Default base name is {file}.oas.gds where {file} is the OASIS file name

[-workdir:{dir_path}]

• Specify the location of the working directory (not the output directory)

• A temporary folder called qismoasutil.{number} will be created in the working directory while the OASIS file is being processed

• By default, working directory is the current working directory

• By default, the temp. folder will be deleted upon cache file creation unless there is an error

[-dbg]

• If specified, the temp. folder qismoasutil.{number} will be preserved even after the cache files have been generated

• By default, the temp. folder will be deleted upon cache file creation unless there is an error

[-progress:{tag}]

• Prepend progress messages with [{tag}] for programatic parsing

Oas2Ascii Applet

Generate human-readable ASCII transcript for an OASIS file

xxxxxxxxxx
oas2ascii.cmd <required>+ <optional>*

Required

+oasis:{oasis_path}

• Specify path of a valid OASIS file

+ascii:{ascii_path}

• Specify path of the ASCII file to be created

Optional

[-no_details]

• If specified, only print record names and offset. Do not write any record members

[-ignore:{all | none | {rec}[,{rec}]*}]

• If specified, ignore ALL, NONE or the specified record-numbers

• By default, all records will be processed

• If CBLOCK (34) are ignored, all contents of CBLOCKs will also be ignored regardless of their record numbers

[-only:{{rec}[,{rec}]*}]

• If specified, process only the specified record-numbers. All other records will be ignored

• By default, all records will be processed

• If CBLOCK (34) are ignored, all contents of CBLOCKs will also be ignored regardless of their record numbers

[-jump:{offset}]

• Jump to the specified offset

• The offset MUST be a valid file-level-offset at the start of the record as displayed in the normal ASCII output

• Does not work with CBLOCK level offsets

[-limit:{n_records}]

• Print only the next specified number of records

QisMOasUtil Version History

qismoasutil dll/so v1.5 02-2026

• Bug fix: GDS writer for multiple XY records

qismoasutil dll/so v1.4 03-2025

• Bug fix: Installation path with spaces caused failure

• Bug fix: Returning a non-zero code from OasUtilNotify did not terminate the processing

qismoasutil dll/so v1.3 02-2025

• Bug fix: Inconsistent progress updates. Some messages were being written to stderr

qismoasutil dll/so v1.2 01-2025

• Bug fix: Processing TRAPEZOIDs

qismoasutil dll/so v1.1.1 10-2024

• New options workdir, dbg for oas2dbload command

qismoasutil dll/so v1.1 09-2024

• C++ API for QisMOasUtil

• Ability to map layers, drop texts and drop cells by names/regular expressions

• Ability to generate .gds.gz

• Ability to create a filedb (QisMFile*) from OASIS

• Script command to create dbload memory maps from OASIS file

qismoasutil dll/so v1.0 06-2024

• First Cut