[Artwork] / [QisMLib]

QisMLOA Extension

A QisMLib extension to define and add rich annotations (texts, bitmaps) to CAD data

QisMLOA C++ API (qismloa.h)

QisMLOAstream

Represents a callback handler that receives the annotation items as a GDS-style stream

class QisMLOAstream { ... };

Version control (QisMLOAstream)

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* QisMLOAstream_name(const int version) const = 0;
virtual void* QisMLOAstream_cast(const int version) = 0;
virtual const void* QisMLOAstream_cast(const int version) const = 0;
virtual int QisMLOAstream_latest_version() const = 0;

Begin_loa_stream

Signals the start of the stream for a given set of annotations

• units_m is the stream units in meter

• grid_m is the stream resolution in meter

• Return 0 to continue, non-zero to terminate the stream

xxxxxxxxxx
virtual int Begin_loa_stream(const double units_m, const double grid_m) { return 0; }

Begin_loa_pattern

Signals the start of a new cell (pattern) definition

• name is the name of this cell

• Return 0 to continue, non-zero to terminate the stream

xxxxxxxxxx
virtual int Begin_loa_pattern(const char* name) { return 0; }

Add_loa_boundaries

Represents a single annotation item converted to a set of boundaries

• n is the number of boundaries in the set

• nv is an array of n elements where each element 0 <= i < n is the number of vertices for the corresponding boundary in the set

• xy is an array of n xy-coordinates where each element 0 <= i < n corresponds to boundary i. Each element is in turn an array of x,y pairs. The number of pairs is determined by nv for i

• lnum and dnum represents the layer assigned to this annotation. It can be set during New_annotation_set. Default is 0:0

• Return 0 to continue, non-zero to terminate the stream

xxxxxxxxxx
virtual int Add_loa_boundaries(
  const int* const* xy, const int* nv, const int n, const unsigned short lnum, 
  const unsigned short dnum
  ) { return 0; }

Add_loa_reference

The annotation stream can be set to hierarchical or flat in Set_to_stream

• In hierarchical mode, annotations are separated into their own cell definitions and then aggregated in a TOP cell using cell references

• pattern_name is the name of the cell being referenced in TOP

• x and y represent the insertion point in database units (dbu)

• scale, angle and flip_y represent the transformation parameters for this reference. angle is in degrees

• Return 0 to continue, non-zero to terminate the stream

xxxxxxxxxx
virtual int Add_loa_reference(
  const char* pattern_name, const int x, const int y, const double scale, 
  const double angle, const bool flip_y
  ) { return 0; }

End_loa_pattern

Signals the end of a cell definition

• Return 0 to continue, non-zero to terminate the stream

xxxxxxxxxx
virtual int End_loa_pattern() { return 0; }

End_loa_stream

Signals the end of the annotation stream

• Return 0 to continue, non-zero to terminate the stream

xxxxxxxxxx
virtual int End_loa_stream() { return 0; }

Get_error_msg

In case the stream was abruptly terminated by returning a non-zero code via the callbacks, use this to return a suitable error message

xxxxxxxxxx
virtual const char* Get_error_msg(const int ret) const { return ""; }

QisMLOAsetPrm

Represents the options applied to the entire annotation set during creation

xxxxxxxxxx
struct QisMLOAsetPrm { enum Code { ... }; };

LOA_E_SETPRM_TTF_FNTDR

Option to specify the directory containing the font files

• If this is not used, the env. variable ACSLIB_TTF_FONTDIR MUST be set to such a directory. Otherwise, adding LOA_E_ANNTYP_TEXT annotations will fail

• MUST be followed by one const char* representing the directory path

xxxxxxxxxx
#define LOA_S_SETPRM_TTF_FNTDR "ttf_dir=%s"
LOA_E_SETPRM_TTF_FNTDR=1

LOA_E_SETPRM_FNTDR

Option to specify the writeable directory to be used to create intermediate font files

• If this is not used, the env. variable ACSLIB_FONTDIR MUST be set to such a directory. Otherwise, adding LOA_E_ANNTYP_TEXT annotations will fail

• MUST be followed by one const char* representing the directory path

xxxxxxxxxx
#define LOA_S_SETPRM_FNTDR "font_dir=%s"
,LOA_E_SETPRM_FNTDR

LOA_E_SETPRM_STRK_WGHT

Option to set the stroke weight for polygons generated from fonts with path data. The width of stroked text is 1/stroke_weight the height of the text.

• MUST be followed by one double

• Used for LOA_E_ANNTYP_TEXTtions

• Default : 10.0 user units

xxxxxxxxxx
#define LOA_S_SETPRM_STRK_WGHT "stroke_weight=%lf"
,LOA_E_SETPRM_STRK_WGHT

LOA_E_SETPRM_LN_SPCNG

Option to set the spacing (>0.001 user units) for annotation with multiple lines for LOA_E_ANNTYP_TEXT annotations

• MUST be followed by one double

• Line spacing scales based on the text height

• Default : 1.2 user units

xxxxxxxxxx
#define LOA_S_SETPRM_LN_SPCNG "line_spacing=%lf"
,LOA_E_SETPRM_LN_SPCNG

LOA_E_SETPRM_SLNT

Option to set the slant in degrees for the LOA_E_ANNTYP_TEXT annotations

• MUST be followed by one double

• Must be between -45.0 and 45.0 degrees inclusive

• Default : 0.0 degrees

xxxxxxxxxx
#define LOA_S_SETPRM_SLNT "slant=%lf"
,LOA_E_SETPRM_SLNT

LOA_E_SETPRM_ASPCT

Option to set the x/y aspect ratio for the LOA_E_ANNTYP_TEXT annotations

• MUST be followed by one double

• Values above 1 will widen the content

• values below 1 will narrow the content

• Must be > 0.0

• Default : 1.0

xxxxxxxxxx
#define LOA_S_SETPRM_ASPCT "aspect=%lf"
,LOA_E_SETPRM_ASPCT

LOA_E_SETPRM_CRCLR

Toggle to smooth out fonts with arcs. This works in conjunction with LOA_E_SETPRM_ARCRES and LOA_E_SETPRM_CHRDERR

• MUST be followed by one int -- 1 (on) or 0 (off)

• Default : 1 (on)

xxxxxxxxxx
#define LOA_S_SETPRM_CRCLR "circularize=%d"
,LOA_E_SETPRM_CRCLR

LOA_E_SETPRM_ARCRES

Sets the arc resolution for a particular set. This setting will keep reconstituted arcs within a certain distance of the original arc. Works in conjunction with LOA_E_SETPRM_CHRDERR

• MUST be followed by one double

• Default : 45.0 degrees

xxxxxxxxxx
#define LOA_S_SETPRM_ARCRES "arcres=%lf"
,LOA_E_SETPRM_ARCRES

LOA_E_SETPRM_CHRDERR

Sets the arc recovery and chord error values

• MUST be followed by two double -- font arc recovery and font chord error

• Default : 2.5,1.0

xxxxxxxxxx
#define LOA_S_SETPRM_CHRDERR "arcsag=%lf,%lf"
,LOA_E_SETPRM_CHRDERR

LOA_E_SETPRM_PXLSZ_FCTR

Sets the pixel size conversion factor

• MUST be followed by one double

• Default : 1.0

xxxxxxxxxx
#define LOA_S_SETPRM_PXLSZ_FCTR "pixel_size_factor=%lf"
,LOA_E_SETPRM_PXLSZ_FCTR

LOA_E_SETPRM_BUF_PRST

Toggles if bitmaps added via a buffer (LOA_E_ANNTYP_BUFR) will have the image buffer persist during the execution or not

• MUST be followed by one int -- 1 or 0

• 1 (yes) means that the library will not copy the buffer passed because it will remain persistent during the life of the set

• 0 (no) means that the library will copy the buffer because the passed buffer might expire during execution

• Default : 0 (no)

xxxxxxxxxx
#define LOA_S_SETPRM_BUF_PRST "buffer_persist=%d"
,LOA_E_SETPRM_BUF_PRST

LOA_E_SETPRM_UNION

Set the union mode for annotations

• MUST be followed by one 'const char*' -- "on" or "off" or "cutline" or "butting"

• "on" / "cutline" indicates unionization with cutlines

• "butting" indicates unionization with butting edges

• "off" indicates unionization is off for bitmap and stroke annotations (font based annotations are always unionized)

• Default : "on"

xxxxxxxxxx
#define LOA_S_SETPRM_UNION "union=%s" //off | butting | (cutline | on)
,LOA_E_SETPRM_UNION

LOA_E_SETPRM_SRT_SZ

Set the size interval which sorting will be triggered for entries

• MUST be followed by one int

• Default : 100,000. Sort or re-sort every 100,000 entries

xxxxxxxxxx
#define LOA_S_SETPRM_SRT_SZ "sort_size=%d"
,LOA_E_SETPRM_SRT_SZ

LOA_E_SETPRM_OUT_LYR

Set the layer:datatype for the annotations in the output stream

• MUST be followed by two int -- 0 <= lnum < 65536 and 0 <= dnum < 65536

• Default : 0:0

xxxxxxxxxx
#define LOA_S_SETPRM_OUT_LYR "out_layer=%d:%d"
,LOA_E_SETPRM_OUT_LYR

LOA_E_SETPRM_THRNUM

Sets the no. of threads to be used during Set_to_stream

• Default : 0 (no. cpus)

xxxxxxxxxx
#define LOA_S_SETPRM_THRNUM "thrnum=%d"
,LOA_E_SETPRM_THRNUM

QisMLOAnnTyp

Represents the various types of annotations that can be defined

xxxxxxxxxx
struct QisMLOAnnTyp { enum Code { ... }; };

LOA_E_ANNTYP_FILE

Annotation defined by a bitmap file on disk

• MUST be followed by one const char* representing the file path

• Only Artwork's RAW format is supported at the moment

xxxxxxxxxx
#define LOA_S_ANNTYP_FILE "ann_file=%s"
LOA_E_ANNTYP_FILE=1

LOA_E_ANNTYP_TEXT

Annotation defined by a text string

• MUST be followed by two const char* - text string, font name followed by one double - font height (user units) (>0.0)

• Font name is the name of the file (.ttf, .shx) representing the font

• The font file MUST be present in the path set by LOA_E_SETPRM_TTF_FNTDR or the env. variable ACSLIB_TTF_FONTDIR

• LOA_E_SETPRM_FNTDR or the environment variable ACSLIB_FONTDIR MUST be set to a writable directory where intermediate font files will be created

• A line feed can be inserted in the text string using two characters \\ (backslash) and r

• Text string can contain spaces

xxxxxxxxxx
#define LOA_S_ANNTYP_TEXT "ann_text=%s,%s,%lf"
,LOA_E_ANNTYP_TEXT

LOA_E_ANNTYP_BUFR

Annotation defined by an image in a memory buffer

• MUST be followed by one unsigned char* representing the buffer pointer, two int representing width and height in pixels

• Depending on the LOA_E_SETPRM_BUF_PRST setting applied during the creation of the set, either the image will be copied (default) or the buffer will be expected to persist until the destruction of the set

xxxxxxxxxx
#define LOA_S_ANNTYP_BUFR "ann_bufr=%p,%d,%d"
,LOA_E_ANNTYP_BUFR

QisMLOAnnItm

Represents options used to flavor annotations

xxxxxxxxxx
struct QisMLOAnnItm { enum Code { ... }; };

LOA_E_ANNITM_TXY

Option to translate the annotation along X and Y axes

• MUST be followed by two double representing x and y offsets respectively in user units

• Default : 0,0

xxxxxxxxxx
#define LOA_S_ANNITM_TXY "translate=%lf,%lf"
LOA_E_ANNITM_TXY=1

LOA_E_ANNITM_ANGLE

Option to rotate the annotation about a point

• MUST be followed by three double representing the angle (degrees), x and y anchor point in user units

• Default : 0,0,0

xxxxxxxxxx
#define LOA_S_ANNITM_ANGLE "angle=%lf,%lf,%lf"
,LOA_E_ANNITM_ANGLE

LOA_E_ANNITM_MIRROR_X

Option to mirror the annotation about the Y axis (along X)

• MUST be followed by one double representing the anchor point

• Default : No mirroring

xxxxxxxxxx
#define LOA_S_ANNITM_MIRROR_X "mirror_x=%lf"
,LOA_E_ANNITM_MIRROR_X

LOA_E_ANNITM_MIRROR_Y

Option to mirror the annotation about the X axis (along Y)

• MUST be followed by one double representing the anchor point

• Default : No mirroring

xxxxxxxxxx
#define LOA_S_ANNITM_MIRROR_Y "mirror_y=%lf"
,LOA_E_ANNITM_MIRROR_Y

LOA_E_ANNITM_INVERT

Option to invert the annotation

• MUST be followed by one int 1 (on) or 0 (off)

• Default : 0 (off)

xxxxxxxxxx
#define LOA_S_ANNITM_INVERT "invert=%d"
,LOA_E_ANNITM_INVERT

LOA_E_ANNITMFILE_SCALE

Option to scale the annotation (only for LOA_S_ANNTYP_FILE and LOA_S_ANNTYP_BUFR types)

• MUST be followed by one double representing the scaling (>0.0)

• Default : 1.0

xxxxxxxxxx
#define LOA_S_ANNITMFILE_SCALE "scale=%lf"
,LOA_E_ANNITMFILE_SCALE

LOA_E_ANNITMTEXT_JSTFY

Option to justify a text annotation (type LOA_S_ANNTYP_TEXT)

• MUST be followed by two int representing the justification as follows

  • first int represents horizontal justification

  • second int represents vertical justification

• Horizontal justification : 0 (left) or 1 (center) or 2 (right)

• Vertical justification : 0 (top) or 1 (middle) or 2 (bottom) or 3 (baseline of the first line)

• Default : 0,0 (left, top)

xxxxxxxxxx
#define LOA_S_ANNITMTEXT_JSTFY "justify=%d,%d"
,LOA_E_ANNITMTEXT_JSTFY

LOA_E_ANNITMTEXT_BORDER

Option to add border to a text annotation (type LOA_S_ANNTYP_TEXT)

• MUST be followed by two double representing the margin and frame thickness in user units

• Default : no border

xxxxxxxxxx
#define LOA_S_ANNITMTEXT_BORDER "border=%lf,%lf"
,LOA_E_ANNITMTEXT_BORDER

QisMLOAmerge

Represents the options to be used for merging a set of annotations with a source database

• At the moment, can only be used in string format

xxxxxxxxxx
struct QisMLOAmerge { enum Code { ... }; };

LOA_E_MERGE_VCELL

Set the view cell (from the source database)

• MUST be followed by a const char* representing the cell name

• Default : deepest top cell of the source db QisMFile::Get_default_top_cell()

xxxxxxxxxx
#define LOA_S_MERGE_VCELL "viewcell=%s" //string format
LOA_E_MERGE_VCELL=1 //enum code

LOA_E_MERGE_LYRS

Set a list of comma-separated layers (and optionally datatypes) indicating that only the specified layers will be extracted from the source

• MUST be followed by a const char* representing the layer string

• e.g "1,2:2,3,4:4,4:8"

• Default : "ALL"

xxxxxxxxxx
#define LOA_S_MERGE_LYRS "layers=%s" //string format
,LOA_E_MERGE_LYRS //enum code

LOA_E_MERGE_TOP

Set the name of the output top cell

• MUST be followed by a const char* representing the cell name

• Default : Same name as a view cell from the source

xxxxxxxxxx
#define LOA_S_MERGE_TOP "top=%s" //string format
,LOA_E_MERGE_TOP //enum code

LOA_E_MERGE_OAS

Set the output file format to OASIS

• No additional values needed

• Default : LOA_E_MERGE_GDS or "gdsii"

xxxxxxxxxx
#define LOA_S_MERGE_OAS "oasis" //string format
,LOA_E_MERGE_OAS //enum code

LOA_E_MERGE_GDS

Set the output file format to GDSII

• No additional values needed

• Default : LOA_E_MERGE_GDS or "gdsii"

xxxxxxxxxx
#define LOA_S_MERGE_GDS "gdsii" //string format
,LOA_E_MERGE_GDS //enum code

QisMLOAset

Represents the interface to a set of annotations

xxxxxxxxxx
class QisMLOAset { ... };

Version control (QisMLOAset)

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* QisMLOAset_name(const int version) const = 0;
virtual void* QisMLOAset_cast(const int version) = 0;
virtual const void* QisMLOAset_cast(const int version) const = 0;
virtual int QisMLOAset_latest_version() const = 0;

Get_error_msg (QisMLOAset)

Get_error_tag (QisMLOAset)

Get_error_context (QisMLOAset)

Get the error message, tag and context for the specified error condition represented by code returned by the corresponding 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;

Begin_annotation_item

Begin the definition of a new annotation item in the set

• anntyp_code is an integer code that represents the type of annotation using one of the QisMLOAnnTyp enums.

• ... represents the additional arguments required to define this type. The number, types and order of these arguments are described next to the corresponding enum

• Returns 0 on success. Otherwise use Get_error... for details

xxxxxxxxxx
virtual int Begin_annotation_item(const int anntyp_code, ...) = 0;

Add_item_param

Add_item_param_str

Add optional parameters corresponding to the annotation being defined

• anntyp_code is an integer code that represents the parameter to be added using one of the QisMLOAnnItm enums.

• ... represents the additional values for this parameter. The number, types and order of these values are described next to the corresponding enum

• One can add a set of parameters at once in form of a string params. The individual parameters are separated by spaces and those with spaces in them are bounded by " double quotes

• Returns 0 on success. Otherwise use Get_error... for details

xxxxxxxxxx
virtual int Add_item_param(const int annitm_code, ...) = 0;
virtual int Add_item_param_str(const char* params) = 0;

Commit_annotation_item

End and commit (save) the annotation being defined

• Any options added this point on will be disregarded

• An annotation is not saved to the set unless committed

• Returns 0 on success. Otherwise use Get_error... for details

xxxxxxxxxx
virtual int Commit_annotation_item() = 0;

Set_to_stream

Receive all annotations from the set as a GDSII-like stream

• flat set the stream mode.

  • true implies no hierarchy. i.e there is only one cell TOP that contains all the boundaries representing all the annotations.

  • false implies hierarchical. i.e, annotations have their own cell definitions. they are aggregated (referenced) in the TOP cell

• client is a handle to the stream handler

• opts is reserved for future use

• Returns 0 on success. Otherwise use Get_error... for details

xxxxxxxxxx
virtual int Set_to_stream(
  const bool flat, QisMLOAstream* client, const char* opts
  ) = 0;

Version control (QisMLOAfile)

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* QisMLOAfile_name(const int version) const = 0;
virtual void* QisMLOAfile_cast(const int version) = 0;
virtual const void* QisMLOAfile_cast(const int version) const = 0;
virtual int QisMLOAfile_latest_version() const = 0;

File_db

Get handle to the underlying QisMFile db so that it can be used with other APIs in the QisM system.

• DO NOT destroy this handle using QisMLib::Unload_file. Use QisMTemplate::Unload instead

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

Get_error_msg

Get_error_tag

Get error message and tag (error code as a string) for a recent error

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

Save_to_gdsii

Export the database to a GDSII file on disk at the specified path gds_output_path (dir + filename + extension)

• Returns 0 on success. Otherwise call Get_error_msg/Get_error_tag for more information

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

LOAD_DBG

Preserve the working files and temporary directory created by Merge_and_load even after the database has been destroyed

• Append to opts string

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

LOAD_WORK_DIR

Specify the directory where the temporary folder will be created during Merge_and_load

• Append to opts string

xxxxxxxxxx
static const char* LOAD_WORK_DIR() { return "workdir="; } //workdir=%s

LOAD_SNP

Inform Merge_and_load that the database to be merged and loaded is paint&scratch

• Append to opts string

xxxxxxxxxx
static const char* LOAD_SNP() { return "p&s"; } //p&s

QisMLOA

Represents the primary interface to the QisMLOA extension

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

Version control (QisMLOA)

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* QisMLOA_name(const int version) const = 0;
virtual void* QisMLOA_cast(const int version) = 0;
virtual const void* QisMLOA_cast(const int version) const = 0;
virtual int QisMLOA_latest_version() const = 0;

Get_error_msg (QisMLOA)

Get_error_tag (QisMLOA)

Get_error_context (QisMLOA)

Get the error message, tag and context for the specified error condition represented by code returned by the corresponding 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;

Reset_set_params

Reset the parameters used to initialize an annotation set

xxxxxxxxxx
virtual void Reset_set_params() = 0;

Add_set_param

Add a parameter to initialize an annotation set

• setprm_code is an integer code that represents the parameter to be added using one of QisMLOAsetPrm enums.

• ... represents the additional values for this parameter. The number, types and order of these values are described next to the corresponding enum

• Returns true if the setprm_code is recognized and accepted

xxxxxxxxxx
virtual bool Add_set_param(const int setprm_code, ...) = 0;

Get_set_params_str

Get the entire list of parameters used to initialize the annotation set as a c-string

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

New_annotation_set

Delete_annotation_set

Create and destroy a new annotation set

• units_m and grid_m represents the units and resolution for the set in meter

• loa_setprm_str is a string of parameters separated by spaces

• ecode is address to store the error code (on failure)

• Requires ONE license of QisMLOA (4250) for each call to New_annotation_set

• The acquired license is released by Delete_annotation_set

• Returns a handle to the newly created set on success. Otherwise, use ecode and Get_error... for details

• Every annotation set MUST be eventually destroyed to avoid resource leaks

xxxxxxxxxx
virtual QisMLOAset* New_annotation_set(
  const double units_m, const double grid_m, const char* loa_setprm_str, 
  int* ecode
  ) = 0;
virtual void Delete_annotation_set(QisMLOAset* handle) = 0;

Merge_annotations_and_db

Merge the specified annotation set with a source DB in form of a GDSII/OASIS file on disk

• filedb is a handle to a valid QisMLib DB. Cannot be NULL or empty

• annotations is a handle to the set of annotations to be added (can be NULL or empty)

• output_base is the path (dir + name) of the output file. extension (.gds or .oas) will be automatically added based on the format

• merge_opts is a string of parameters separated by spaces. See QisMLOAmerge for a list of parameters and their syntax

• Returns 0 on success. Otherwise, use Get_error... for details

xxxxxxxxxx
virtual int Merge_annotations_and_db(
  NsQisMLib::QisMFile* filedb, QisMLOAset* annotations, 
  const char* output_base, const char* merge_opts
  ) = 0;

QisMLOAv2

Extension-2 to QisMLOA

xxxxxxxxxx
class QisMLOAv2: public QisMLOA { ... };

Merge_annotations_and_snp_db

Merge the specified annotation set with a source paint&scratch DB created from Gerber or ODB++ data. The output GDSII/OASIS file preserves the paint&scratch format

• filedb is a handle to a valid QisMLib DB. Cannot be NULL or empty. MUST be paint&scratch

• annotations is a handle to the set of annotations to be added (can be NULL or empty)

• output_base is the path (dir + name) of the output file. extension (.gds or .oas) will be automatically added based on the format

• merge_opts is a string of parameters separated by spaces. Only LOA_S_MERGE_OAS and LOA_S_MERGE_GDS are supported at the moment

• Returns 0 on success. Otherwise, use Get_error... for details

xxxxxxxxxx
virtual int Merge_annotations_and_snp_db(
  NsQisMLib::QisMFile* filedb, QisMLOAset* annotations, 
  const char* output_base, const char* merge_opts
  ) = 0;

Merge_and_load

Unload_db

Merge the specified annotation set with a source standard or paint&scratch DB and load it back into QisMLib to create a new database

• filedb is a handle to a valid QisMLib DB. Cannot be NULL or empty. MUST be paint&scratch

• annotations is a handle to the set of annotations to be added (can be NULL or empty)

• opts is a string of parameters separated by spaces. See QisMLOAfile for some of the options

• On success, returns a non-NULL handle. Otherwise use Get_error... for details

• The database created here MUST be destroyed eventually using Unload_db to avoid resource leaks

xxxxxxxxxx
virtual QisMLOAfile* Merge_and_load(
  NsQisMLib::QisMFile* filedb, QisMLOAset* ann_set, const char* opts, int* ecode
  ) = 0;
virtual void Unload_db(QisMLOAfile* db) = 0;

QisMLOA Commands

QisMScript Commands to define and add rich annotations (texts, bitmaps) to CAD data

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

• Some commands require a license (QISMLOA - 4250)

loa.create_ann_set

xxxxxxxxxx
loa.create_ann_set
  &ann={id} 
  units={meter} 
  grid={meter} 
  [ttf_dir={path}] 
  [font_dir={path}] 
  [stroke_weight={value}] 
  [line_spacing={value}] 
  [slant={value}] 
  [aspect={value}] 
  [circularize={1 | 0}] 
  [arcres={deg}] 
  [chord_error={arc_recov},{chord_err}] 
  [pixel_size_factor={value}] 
  [buffer_persist={1 | 0}] 
  [union={off | on | cutline | butting}] 
  [sort_size={value}] 
  [out_layer={lnum}:{dnum}] 
  [thrnum={value}]

Create a new annotation set and associates it with a script variable name {id} of type QisMLOAset*

• Data units and grid MUST be specified in meter

• ttf_dir represents the directory containing the font files. By default, the env. variable ACSLIB_TTF_FONTDIR represents that directory

• font_dir represents the writeable directory to be used to create intermediate font files.If this is not used, the env. variable ACSLIB_FONTDIR MUST be set to such a directory. Otherwise, adding text annotations will fail

• stroke_weight sets the stroke weight for polygons generated from fonts with path data. The width of stroked text is 1/stroke_weight the height of the text.

• line_spacing sets the spacing (>0.001 user units) for annotation with multiple lines for text annotations

• slant sets the slant in degrees for the text annotations

• aspect sets the x/y aspect ratio for the text annotations

• circularize is a toggle to smooth out fonts with arcs. This works in conjunction with arcres and chord error

• arcres sets the arc resolution for a particular set. This setting will keep reconstituted arcs within a certain distance of the original arc. Works in conjunction with chord error

• chord_error sets the arc recovery and chord error values

• pixel_size_factor sets the pixel size conversion factor

• buffer_persist toggles if bitmaps added via a buffer will have the image buffer persist during the execution or not

• union sets the union mode for annotations

• sort_size sets the size interval which sorting will be triggered for entries

• out_layer sets the layer:datatype for the annotations in the output Set_to_stream

• thrnum sets the no. of threads to be used during Set_to_stream

• Requires and holds one license of QISMLOA (4250)

• Every annotation set created this way MUST be explicitly destroyed using loa.destroy_ann_set

loa.destroy_ann_set

xxxxxxxxxx
loa.destroy_ann_set $ann={id}

Destroys an annotation set represented by the script variable named {id} of type QisMLOAset*

• Releases the QISMLOA (4250) license held by this object

• C++ : QisMLOA::Delete_annotation_set

loa.add_ann_bitmap

xxxxxxxxxx
loa.add_ann_bitmap
  $ann={id} 
  file={path} 
  [translate={x},{y}]  
  [angle={deg},{x},{y}] 
  [mirror=x,{value}] 
  [mirror=y,{value}] 
  [invert={1 | 0}]  
  [scale={value}]

Add a bitmap based annotation item to the set

• {id} is the name of a script variable of type QisMLOAset* representing the annotation set

• The bitmap MUST be an Artwork RAW file at the specified {path}

• translate if specified moves the text to the specified location. Default: 0,0

• angle if specified rotates the text about a point {x},{y} by {deg} degrees. Default: no rotation

• mirror if specified reflects the text about x or y located at the specified line. Default: no mirroring

• invert if used (set to 1) inverts the rendered text polarity. Default: 0

• scale is used to scale the annotation uniformly by the specified amount

• All spatial values are file units

loa.add_ann_text

xxxxxxxxxx
loa.add_ann_text
  $ann={id} 
  text={str} 
  font={name} 
  height={value} 
  [translate={x},{y}]  
  [angle={deg},{x},{y}] 
  [mirror=x,{value}] 
  [mirror=y,{value}] 
  [invert={1 | 0}]  
  [justify={left | center | right},{top | middle | bottom | baseline}]  
  [border={margin},{frame}] 

Add a text string based annotation to the set

• {id} is the name of a script variable of type QisMLOAset* representing the annotation set

• {str} is a text string (single or multi-line)

• font specifies the font file name used to render this text

• height specifies the font height

• translate if specified moves the text to the specified location. Default: 0,0

• angle if specified rotates the text about a point {x},{y} by {deg} degrees. Default: no rotation

• mirror if specified reflects the text about x or y located at the specified line. Default: no mirroring

• invert if used (set to 1) inverts the rendered text polarity. Default: 0

• justify if specified sets a horizontal and vertical justification. Default: left, top

• border if specified adds a border of the specified thickness {frame} with a {margin} from the text. Default: no border

• All spatial values are file units

loa.create_ann_set_from_file

xxxxxxxxxx
loa.create_ann_set_from_file
  &ann={id} 
  file={txt_file_path} 
  units={meter} 
  grid={meter}

Create an annotation set from a file in an internal Artwork format (SFGen)

• &ann={id} specifies the name to be associated with the newly created annotation set

• file={txt_file_path} specifies the path of the spec. file to be imported

• units={meter} and grid={meter} specifies the data units and grid in meter

loaset.to_file

xxxxxxxxxx
loaset.to_file
  $ann={id} 
  file={path} 
  units={m} 
  grid={m}

Generate a GDSII file from the annotation set

• {id} is the name of a script variable of type QisMLOAset* representing the annotation set

• {path} is the path of the output GDSII

• units={m} and grid={m} is the file units and grid in meter

loa.merge_ann_with_db

xxxxxxxxxx
loa.merge_ann_with_db
  $filedb={id} 
  $ann={id} 
  out={base_path}  
  [viewcell={name}] 
  [top={name}] 
  [layers={str}] 
  [oasis | gdsii]

Merge annotation set with the specified db and create a new CAD file on disk

• {id} is the name of a script variable of type QisMLOAset* representing the annotation set

• {base_path} is the directory + filename of the output file. Extension .gds or .oas will be added based on the format

• viewcell is the name of the cell from the source db to become the top cell in the output. Default: deepest top cell in the source

• top is the name of the top cell in the output (if not to be the same as the viewcell which is the default)

• layers specifies the layers of interest (comma-separated list of lnum(s) and/or lnum:dnum(s)). Default: "ALL"

• oasis generates an OASIS file. gdsii is the default.

loa.merge_ann_with_snp_db

xxxxxxxxxx
loa.merge_ann_with_snp_db
  $filedb={id} 
  $ann={id} 
  out={base_path}  
  [oasis | gdsii]

Merge annotation set with the specified paint&scratch db and create a new paint&scratch CAD file on disk

• {id} is the name of a script variable of type QisMLOAset* representing the annotation set

• {base_path} is the directory + filename of the output file. Extension .gds or .oas will be added based on the format

• oasis generates an OASIS file. gdsii is the default.

loa.merge_and_load

xxxxxxxxxx
loa.merge_and_load
  $filedb={id} 
  $ann={id}
  &loadb={id}
  [p&s]
  [viewcell={name}]
  [layers={str}]
  [top={name}]
  [dbg]
  [workdir={path}]

Create a new db from the merger of an existing db and one or more annotatition sets

• $filedb={id} is the name of an exisitng QisMFile database

• $ann={id} is the annotation set ready to be merged

• &loadb={id} provides the name for the DB to be created

• p&s if specified implies that $filedb={id} is a paint&scratch database (see loa.merge_ann_with_snp_db)

• viewcell=, layers= and top= are used for merging with a standard (paint-only) database (see loa.merge_ann_with_db)

• dbg if specified, will cause the temporary directory and files to be retained even after the database is destroyed

• workdir={path} if specified will cause the temporary directory to be created in the specified location instead of CWD

• This database MUST be eventually destroyed using loa.unload_db to avoid resource leaks

loa.unload_db

xxxxxxxxxx
loa.unload_db
  $loadb={id} 

Destroy a database created by loa.merge_and_load

• $loadb={id} is the name of the db to be destroyed

QisMLOA Licensing (API)

Product name : QisMLOA License code : 4250

• The following commands require ONE license of QisMLOA per call that is held until the corresponding END command

QisMLOA Licensing (Script)

Product name : QisMLOA License code : 4250

• The following commands require ONE license of QisMLOA per call that is held until the corresponding END command

QisMLOA Version History

qismloa dll/so v1.4 2025-07-16

• New API/command to merge annotations with a paint&scratch DB to create a paint&scratch file

• New API/command to merge annotations and load the output to a new DB

qismloa dll/so v1.3 2023-11-27

• Bug fix - Crash when New_annotation_set was called repeatedly a certain number of times

qismloa dll/so v1.2 2023-05-04

• Text strings can containing commas now

• New command create_ann_set_from_file that reads the annotation text file format

qismloa dll/so v1.1 2022-07-22

• Bug fix - single pixel at the very end of a row was dropped

• Improved TTF font support

qismloa dll/so v1.0 2022-06-08

• First cut