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

QisMGerber API (BETA)

API to create a QisM database from a Gerber file

• Header file : qismgerber.h
• Extension : qismgerber64.dll
• Platform: Win64

interface QisMGerber

class QisMGerber: public NsQisMLib::QisMExtensionAPI { .. };

• The main interface to the QisMGerber extension

• Obtained by calling QisMLib::Get_extension_api as follows:

  ​x
  #include "qismlib.h"
  #include "qismgerber.h"
  using namespace NsQisMLib;
  using namespace NsQisMGerber;
  ​
  QisMGerber* QisMGerber_get_api(QisMLib* qismlib)
  {
    assert(qismlib != NULL);
    QisMExtensionAPI* extn = qismlib->Get_extension_api(QISMEXTENSION_GERBER);
    if(NULL == extn) {
      fprintf(stderr, "error: failed to locate the extension %s", QISMEXTENSION_GERBER);
      return NULL;
    }
    return (QisMGerber*)(extn->Extension_class_ptr());
  }
  

method Load_gerber

method Unload_gerber

xxxxxxxxxx
virtual int Load_gerber(
    QisMGerberFile*& filedb, 
    NsQisMLib::QisMLib* lib_handle, 
    const char* gerber_path, 
    const char* working_dir = 0, 
    const QisMGerberOpts* options = 0, 
    QisMGerberNotify* progress_updates = 0,
    const int argc = 0, 
    const char* const* argt = 0, 
    void* const* argv = 0
    ) = 0;

• Create a database from a Gerber file

  • filedb will contain a handle to the newly created db on success
  • lib_handle is the handle to the QisMLib obtained via QisMLib_initialize_once (qismlib.h)
  • gerber_path is the path to a valid Gerber (RS274X) file
  • working_dir if specified is path to a valid readable/writable directory
  • options if specified is handle to an object carrying various import options
  • progress_updates if specified returns progress messages to the client app via C++ callbacks while the Gerber file is being processed
  • argc, argt, argv are reserved for internal/future use
  • Returns 0 on success. Otherwise call Get_error_msg, Get_error_tag for error information
  • Every QisMFile database created using Load_gerber(..) MUST be eventually destroyed using Unload_gerber(..) only
  • Requires ONE license of QISMCODE_GERBER (2756) per call. The license is released once the database is created (The database itself does not require a license)
  • Multiple databases can co-exist and are only limited by system resources

method New_object

method Delete_object

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

• Create/Destroy an instance of an object

  • class_name is name of the class whose object is to be created. Acceptable types are:

    • QisMGerberOpts

  • Returns handle to the newly created object. MUST be type-casted to the specified class before use

  • Every object created this way MUST be eventually destroyed using Delete_object(..) to avoid memory/resource leak

method Get_error_msg

method Get_error_tag

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

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

  • code is a non-zero integer that represents the failure of one of the methods of this interface

interface QisMGerberFile

xxxxxxxxxx
class QisMGerberFile { .. };

• Represents a database created from a Gerber file
• Created via a call to QisMGerber::Load_gerber and destroyed via QisMGerber::Unload_gerber

method File_db

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

• Get the underlying QisMFile handle so that it can be used along with other APIs in the QisMLib system

method Save_to_gdsii

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

• 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

method Get_error_msg

method Get_error_tag

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

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

  • code is a non-zero integer that represents the failure of one of the methods of this interface

interface QisMGerberOpts

xxxxxxxxxx
class QisMGerberOpts { .. };

• Represents an object to store options for importing Gerber
• Created using QisMGerber::New_object and destroyed using QisMGerber::Delete_object

enum UnitType

xxxxxxxxxx
enum UnitType {
   UNT_SOURCE=0 //same units as the source Gerber file
   ,UNT_IN 
   ,UNT_MIL 
   ,UNT_CM 
   ,UNT_MM
   ,UNT_UM
  };

• Codes to indicate the unit type for various parameters

enum ParamType

xxxxxxxxxx
enum ParamType {
  PRM_ARCRES=1 
  ,PRM_ARCSAG 
  ,PRM_ARCSAG_UNIT 
  ,PRM_POLY_BUTTING 
  ,PRM_POLY_BUTTING_OVERLAP 
  ,PRM_POLY_BUTTING_OVERLAP_UNIT 
  ,PRM_THRNUM 
  ,PRM_ADV_ARGS 
  ,PRM_DBG_MODE 
  ,PRM_OUTPUT_UNIT 
};

• Codes to indicate the parameter type for the Set_param and Get_param methods

  • PRM_ARCRES indicates arc resolution for converting arcs to line segments

    • value type: double (Set_param), double* (Get_param)

    • Default: 45.0

      xxxxxxxxxx
      double value = 45.0;
      this->Set_param(QisMGerberOpts::PRM_ARCRES, value);
      this->Get_param(QisMGerberOpts::PRM_ARCRES, &value);
      

  • PRM_ARCSAG indicates chord-error for converting arcs to line segments in the specified unit (PRM_ARCSAG_UNIT)

    • value-type: double (Set_param), double* (Get_param)

    • default: 1.0

      xxxxxxxxxx
      double value = 1.0;
      this->Set_param(QisMGerberOpts::PRM_ARCSAG, value);
      this->Get_param(QisMGerberOpts::PRM_ARCSAG, &value);
      

  • PRM_ARCSAG_UNIT indicates units for specifying chord error. To be used with PRM_ARCSAG

    • value-type: int (Set_param), int* (Get_param) (one of QisMGerberOpts::UnitType)

    • default: QisMGerberOpts::UNT_UM

      xxxxxxxxxx
      int value = QisMGerberOpts::UNT_UM;
      this->Set_param(QisMGerberOpts::PRM_ARCSAG_UNIT, value);
      this->Get_param(QisMGerberOpts::PRM_ARCSAG_UNIT, &value);
      

  • PRM_POLY_BUTTING indicates to output polygons with holes as butting polygons

    • value-type: int (Set_param), int* (Get_param) (1 or 0)

    • default: 1 (on)

      xxxxxxxxxx
      int value = 1;
      this->Set_param(QisMGerberOpts::PRM_POLY_BUTTING, value);
      this->Get_param(QisMGerberOpts::PRM_POLY_BUTTING, &value);
      

  • PRM_POLY_BUTTING_OVERLAP indicates amount of overlap value for butting polygons in the specified units (PRM_POLY_BUTTING_OVERLAP_UNIT)

    • value-type: double (Set_param), double* (Get_param)

    • default: 0.0

      xxxxxxxxxx
      double value = 0.0;
      this->Set_param(QisMGerberOpts::PRM_POLY_BUTTING_OVERLAP, value);
      this->Get_param(QisMGerberOpts::PRM_POLY_BUTTING_OVERLAP, &value);
      

  • PRM_POLY_BUTTING_OVERLAP_UNIT indicates unit for butting overlap value

    • value-type: int (Set_param), int* (Get_param) (one of QisMGerberOpts::UnitType)

    • default: QisMGerberOpts::UNT_SOURCE

      xxxxxxxxxx
      int value = QisMGerberOpts::UNT_SOURCE;
      this->Set_param(QisMGerberOpts::PRM_POLY_BUTTING_OVERLAP_UNIT, value);
      this->Get_param(QisMGerberOpts::PRM_POLY_BUTTING_OVERLAP_UNIT, &value);
      

  • PRM_THRNUM indicates no. threads to be used for various stages of Gerber translation

    • value-type: int (Set_param), int* (Get_param)

    • default: 0 (use no. cpus)

      xxxxxxxxxx
      int value = 0;
      this->Set_param(QisMGerberOpts::PRM_THRNUM, value);
      this->Get_param(QisMGerberOpts::PRM_THRNUM, &value);
      

  • PRM_ADV_ARGS indicates advanced arguments (reserved for internal use/debugging)

    • value-type: const char* (Set_param), const char** (Get_param)

    • default: ""

      xxxxxxxxxx
      const char* value = "";
      this->Set_param(QisMGerberOpts::PRM_ADV_ARGS, value);
      this->Get_param(QisMGerberOpts::PRM_ADV_ARGS, &value);
      

  • PRM_DBG_MODE indicates enable/Disable diagnostic mode

    • value-type: int (Set_param), int* (Get_param) (1 or 0)

    • default: 0 (off)

      xxxxxxxxxx
      int value = 0;
      this->Set_param(QisMGerberOpts::PRM_DBG_MODE, value);
      this->Get_param(QisMGerberOpts::PRM_DBG_MODE, &value);
      

  • PRM_OUTPUT_UNIT indicates units for the output db

    • value-type: int (Set_param), int* (Get_param) (one of QisMGerberOpts::UnitType)

    • default: QisMGerberOpts::UNT_UM

      xxxxxxxxxx
      this->Set_param(QisMGerberOpts::PRM_OUTPUT_UNIT, value);
      this->Get_param(QisMGerberOpts::PRM_OUTPUT_UNIT, &value);
      

method Set_param

method Get_param

xxxxxxxxxx
virtual bool Set_param(const int type, ...) = 0;
virtual bool Get_param(const int type, ...) const = 0;

• Set/Get value for a specific option

  • type is a code for the option type. It can be any one of QisMGerberOpts::ParamType
  • ... is used to pass the variable holding the value. It's type and count depends on the parameter in question. See QisMGerberOpts::ParamType for usage details
  • Returns true if the parameter type was recognized and processed. false implies unknown/unsupported parameter type

method Reset

xxxxxxxxxx
virtual void Reset() = 0;

• Reset options to default values

method Clone

xxxxxxxxxx
virtual QisMGerberOpts* Clone() const = 0;

• Create a clone from the current object. MUST be eventually destroyed using QisMGerber::Delete_object("QisMGerberOpts", ..)

method Copy

xxxxxxxxxx
virtual bool Copy(const QisMGerberOpts* obj) = 0;

• Copy settings from another object

callback interface QisMGerberNotify

xxxxxxxxxx
class QisMGerberNotify { .. };

• Represents the interface to be implemented by an client object to receive notifications from QisMGerber during relevant operations

callback On_qismgerber_progress

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

• Callback to get progress message while Gerber is being processed during QisMGerber::Load_gerber

  • Return 0 to continue, non-zero to terminated the load