VisionPlus_V3.0/Include/halcon/hdevengine/HDevEngineCpp.h

/*****************************************************************************
 * HDevEngineCpp.h
 *****************************************************************************
 *
 * Description: Interface for executing HDevelop programs and procedures
 *              within a C++ application using the HALCON/C++ interface.
 *
 * (c) 1996-2021 by MVTec Software GmbH
 *                  www.mvtec.com
 *
 *****************************************************************************/

#ifndef H_DEV_ENGINE_CPP_H
#define H_DEV_ENGINE_CPP_H

// include the HALCON 11 C++ interface
#include "halconcpp/HalconCpp.h"


#ifndef HDEV_PD
#  define HDEV_PD                                                                                                     \
  private:                                                                                                            \
    class Data;                                                                                                       \
    Data* mData
#endif

namespace HDevEngineCpp
{
// Forward declarations
class HDevEngine;
class HDevProgram;
class HDevProgramCall;
class HDevProcedure;
class HDevProcedureCall;
class HDevEngineException;
class HDevOperatorImplCpp;


/*****************************************************************************
 *****************************************************************************
 ** class HDevEngine
 **===========================================================================
 ** Class for managing global engine settings:
 **  + external procedure path
 **  + implementation of dev_ operators (HDevOperatorImpl)
 **  + Attention: all changes made to one HDevEngine instance are global
 **    for all .dev programs or .dvp procedure that are executed in one
 **    application
 *****************************************************************************
 *****************************************************************************/
class LIntExport HDevEngine
{
public:
  HDevEngine();

  // Via engine attributes the behavior of the engine can be configured
  // currently the following flags are supported:
  //  "ignore_unresolved_lines"  [default: false, 0]
  //     - if set to true (or "true"), program lines that refer to an
  //       unresolved procedure are ignored, i.e., the program or procedure is
  //       executed without the corrupted program line;
  //       this may lead to an unexpected behavior or an error during the
  //       program execution
  //     - as the default an exception is thrown while creating the program or
  //       procedure instance
  //  "ignore_invalid_lines"  [default: false, 0]
  //     - if set to true (or "true"), invalid program lines  are ignored,
  //       i.e., the program or procedure is executed without the corrupted
  //       program line;
  //       this may lead to an unexpected behavior or an error during the
  //       program execution
  //     - as the default an exception is thrown while creating the program or
  //       procedure instance
  //  "ignore_invalid_results"  [default: true, 1]
  //     - if set to false (or "false") throw an exception if the accessed
  //       procedure output parameter or program variable is invalid
  //     - the following methods are concerned:
  //         HenProgramCall::GetIconicVarObject()
  //         HenProgramCall::GetCtrlVarTuple()
  //         HenProcedureCall::GetOutputIconicParamObject()
  //         HenProcedureCall::GetOutputCtrlParamTuple()
  //     - as the default an empty region object or an empty tuple is returned
  //       if the object was not set within the program or procedure
  //  "docu_language"  [default: "" -> en_US]
  //     - could be set to "en_US","de_DE",  other languages
  //  "docu_encoding"  [default: "" -> "utf8"]
  //     - if set to "native" all natural language strings are converted
  //       to native encoding
  //  "execute_procedures_jit_compiled"  [default: false, 0]
  //     - if set to true (or "true"), procedures are tried to being compiled
  //       with a just-in-time compiler for faster execution
  //  "debug_port"  [default: 57786]
  //     - specifies the port number of the socket where the debug server
  //       waits for incoming connections
  //  "debug_password"  [default: ""]
  //     - specifying a password provides a basic layer of protection
  //       against misuse. For security reasons, it is highly recommended
  //       to always supply a password. If a password is set, it must be
  //       entered in HDevelop to allow the connection
  //  "debug_wait_for_connection"  [default: false]
  //     - if set to true, the engine switches into "stopped state"
  //       after starting the debug server (see below). This has the effect
  //       that any application thread that enters procedure execution
  //       via HDevEngine will stop on the first line of script code.
  //       This way, you can start debugging from the beginning of your code
  //       upon connecting from HDevelop
  void              SetEngineAttribute(const char* name, const HalconCpp::HTuple& value);
  HalconCpp::HTuple GetEngineAttribute(const char* name);

  // Set path(s) for external procedures
  //  - several paths can be passed together separating them by ';' or ':'
  //    on Windows or UNIX-like systems resp.
  //  - NULL removes all procedure paths and unloads all external procedures
  //    (Attention: procedures that are used by programs (HDevProgram) or
  //    procedures (HDevProcedures) remain unchanged until the program or
  //    procedure is reloaded explicitly.  The appropriate calls must be
  //    recreated or reassigned by the reloaded program or procedure.)
  //  - additional calls of SetProcedurePath will remove paths set before
  //    and unload all external procedures
  void SetProcedurePath(const char* path);
  void AddProcedurePath(const char* path);
#ifdef _WIN32
  void SetProcedurePath(const wchar_t* path);
  void AddProcedurePath(const wchar_t* path);
#endif
  // Get names of all available external procedures
  HalconCpp::HTuple GetProcedureNames() const;
  // Get names of all loaded external procedures
  HalconCpp::HTuple GetLoadedProcedureNames() const;
  // Unload a specific procedure <proc_name>
  void UnloadProcedure(const char* proc_name);
  // Unload all external procedures
  void UnloadAllProcedures();

  // Starts the debug server that allows to attach HDevelop as
  // as debugger to step through engine code. With default settings
  // server waits on port 57786 and engine runs normally until HDevelop
  // is connected and F9 is pressed to stop execution.
  void StartDebugServer();

  // Stops the debug server (resuming execution if stopped)
  void StopDebugServer();

  // global variable access
  HalconCpp::HTuple GetGlobalIconicVarNames() const;
  HalconCpp::HTuple GetGlobalCtrlVarNames() const;
  // get dimension of a global variable
  int GetGlobalIconicVarDimension(const char* var_name) const;
  int GetGlobalCtrlVarDimension(const char* var_name) const;
  // get value of a global variable
  HalconCpp::HObject       GetGlobalIconicVarObject(const char* var_name);
  HalconCpp::HTuple        GetGlobalCtrlVarTuple(const char* var_name);
  HalconCpp::HObjectVector GetGlobalIconicVarVector(const char* var_name);
  HalconCpp::HTupleVector  GetGlobalCtrlVarVector(const char* var_name);
  // these method is provided for efficiency:
  // the results are copied directly into the tuple variable provided by
  // the user without additional copying
  void GetGlobalCtrlVarTuple(const char* var_name, HalconCpp::HTuple* tuple);
  // set global variable
  void SetGlobalIconicVarObject(const char* var_name, const HalconCpp::HObject& obj);
  void SetGlobalCtrlVarTuple(const char* var_name, const HalconCpp::HTuple& tuple);
  void SetGlobalIconicVarVector(const char* var_name, const HalconCpp::HObjectVector& vector);
  void SetGlobalCtrlVarVector(const char* var_name, const HalconCpp::HTupleVector& vector);


  // Set implementation for HDevelop internal operators
  void SetHDevOperatorImpl(HDevOperatorImplCpp* hdev_op_impl);
};


/*****************************************************************************
 *****************************************************************************
 ** class HDevProgram
 **===========================================================================
 ** Class for managing HDevelop programs
 *****************************************************************************
 *****************************************************************************/
class LIntExport HDevProgram
{
  HDEV_PD;

public:
  // Create a program from a .dev program file
  HDevProgram(const char* file_name = NULL);

#ifdef _WIN32
  HDevProgram(const wchar_t* file_name);
#endif

  // Copy constructor
  HDevProgram(const HDevProgram& hdev_prog);
  HDevProgram(const Data& data);

  // Assignment operation
  HDevProgram& operator=(const HDevProgram& hdev_prog);

  // Destructor
  virtual ~HDevProgram();

  // Load a program if not yet done during construction
  void LoadProgram(const char* file_name);

#ifdef _WIN32
  void LoadProgram(const wchar_t* file_name);
#endif

  // check whether the program was successfully loaded
  bool IsLoaded() const;

  // Get the program name
  const char* GetName() const;

  // Get the names of all local and the used external procedures
  HalconCpp::HTuple GetUsedProcedureNames() const;
  HalconCpp::HTuple GetLocalProcedureNames() const;

  // Compile all procedures that are used by the program and that can be
  // compiled with a just-in-time compiler.
  // The method returns true when all used procedures could be compiled by the
  // just-in-time compiler.
  // Procedures that could not be compiled are called normally by the
  // HDevEngine interpreter.
  // To check which procedure could not be compiled and what the reason is for
  // that start HDevelop and check there the compilation states.
  bool CompileUsedProcedures();

  // create a program call for execution
  HDevProgramCall CreateCall() const;

  // This is a method provided for convenience:
  // execute the program and return the program call for
  // accessing the variables of the program's main procedure
  HDevProgramCall Execute() const;

  // get some information about the variables of the program's main procedure:
  //  - get the variable names as a tuple
  HalconCpp::HTuple GetIconicVarNames() const;
  HalconCpp::HTuple GetCtrlVarNames() const;

  //  - get the number of iconic and control variables
  size_t GetIconicVarCount() const;
  size_t GetCtrlVarCount() const;

  //  - get the names of the variables
  //   (indices of the variables run from 1 to count)
  const char* GetIconicVarName(size_t var_idx) const;
  const char* GetCtrlVarName(size_t var_idx) const;

  //  - get the dimensions of the variables
  //   (indices of the variables run from 1 to count)
  int GetIconicVarDimension(size_t var_idx) const;
  int GetCtrlVarDimension(size_t var_idx) const;
};


/*****************************************************************************
 *****************************************************************************
 ** class HDevProgramCall
 **===========================================================================
 ** Class for managing the execution of an HDevelop program
 *****************************************************************************
 *****************************************************************************/
class LIntExport HDevProgramCall
{
  HDEV_PD;

public:
  // Create an empty HDevelop program call instance
  HDevProgramCall();
  // Create an HDevelop program call from a program
  HDevProgramCall(const HDevProgram& prog);
  // Copy constructor
  HDevProgramCall(const HDevProgramCall& hdev_prog_call);
  HDevProgramCall(const Data& data);
  // Assignment operation
  HDevProgramCall& operator=(const HDevProgramCall& hdev_prog_call);
  // Destructor
  virtual ~HDevProgramCall();

  // Get the program
  HDevProgram GetProgram() const;

  // Execute program
  void Execute();

  // Stop execution on first line of program. This is intended for debugging
  // purposes when you wish to step through a specific program call. It only
  // has an effect when a debug server is running and it will only stop once.
  void SetWaitForDebugConnection(bool wait_once);

  // Clear program and reset callstack
  //  - this method stops the execution of the program after the current
  //    program line
  void Reset();

  // Get the objects / values of the variables by name or by index
  //   (indices of the variables run from 1 to count)
  HalconCpp::HObject GetIconicVarObject(size_t var_idx);
  HalconCpp::HObject GetIconicVarObject(const char* var_name);

  HalconCpp::HObjectVector GetIconicVarVector(size_t var_idx);
  HalconCpp::HObjectVector GetIconicVarVector(const char* var_name);

  HalconCpp::HTuple GetCtrlVarTuple(size_t var_idx);
  HalconCpp::HTuple GetCtrlVarTuple(const char* var_name);

  HalconCpp::HTupleVector GetCtrlVarVector(size_t var_idx);
  HalconCpp::HTupleVector GetCtrlVarVector(const char* var_name);

  // these methods are provided for efficiency:
  // the results are copied directly into the tuple variable provided by
  // the user without additional copying
  void GetCtrlVarTuple(size_t var_idx, HalconCpp::HTuple* tuple);
  void GetCtrlVarTuple(const char* var_name, HalconCpp::HTuple* tuple);
};


/*****************************************************************************
 *****************************************************************************
 ** class HDevProcedure
 **===========================================================================
 ** Class for managing HDevelop procedures
 *****************************************************************************
 *****************************************************************************/
class LIntExport HDevProcedure
{
  HDEV_PD;

public:
  // Create HDevelop procedure from external or local procedure
  HDevProcedure(const char* proc_name = NULL);
  HDevProcedure(const char* prog_name, const char* proc_name);
  HDevProcedure(const HDevProgram& prog, const char* proc_name);

#ifdef _WIN32
  HDevProcedure(const wchar_t* prog_name, const char* proc_name);
#endif

  // Copy constructor
  HDevProcedure(const HDevProcedure& hdev_proc);
  HDevProcedure(const Data& data);
  // Assignment operation
  HDevProcedure& operator=(const HDevProcedure& proc);
  // Destructor
  ~HDevProcedure();

  // Load a procedure if not yet done during construction
  void LoadProcedure(const char* proc_name);
  void LoadProcedure(const char* prog_name, const char* proc_name);
  void LoadProcedure(const HDevProgram& prog, const char* proc_name);

#ifdef _WIN32
  void LoadProcedure(const wchar_t* prog_name, const char* proc_name);
#endif

  // Check whether the procedure was successfully loaded
  bool IsLoaded() const;

  // Get the name of the procedure
  const char* GetName() const;

  // Get the short description of the procedure. The encoding of the
  // description will be in local 8 bit or utf-8, depending on the
  // HALCON/C++ interface encoding. Note there is no wchar_t overload for
  // Windows applications compiled with UNICODE support; however, you can
  // access the description using GetInfo("short").S().TextW() instead.
  const char* GetShortDescription() const;

  // Get all refered procedures
  HalconCpp::HTuple GetUsedProcedureNames() const;

  // Compile all procedures that are used by the procedure and that can be
  // compiled with a just-in-time compiler.
  // The method returns true when all used procedures could be compiled by the
  // just-in-time compiler.
  // Procedures that could not be compiled are called normally by the
  // HDevEngine interpreter.
  // To check which procedure could not be compiled and what the reason is for
  // that start HDevelop and check there the compilation states.
  bool CompileUsedProcedures();

  // Create a program call for execution
  HDevProcedureCall CreateCall() const;

  // Get name of input/output object/control parameters
  HalconCpp::HTuple GetInputIconicParamNames() const;
  HalconCpp::HTuple GetOutputIconicParamNames() const;
  HalconCpp::HTuple GetInputCtrlParamNames() const;
  HalconCpp::HTuple GetOutputCtrlParamNames() const;

  // Get number of input/output object/control parameters
  int GetInputIconicParamCount() const;
  int GetOutputIconicParamCount() const;
  int GetInputCtrlParamCount() const;
  int GetOutputCtrlParamCount() const;

  // Get name of input/output object/control parameters
  //   (indices of the parameters run from 1 to count)
  const char* GetInputIconicParamName(int par_idx) const;
  const char* GetOutputIconicParamName(int par_idx) const;
  const char* GetInputCtrlParamName(int par_idx) const;
  const char* GetOutputCtrlParamName(int par_idx) const;

  // Get dimension of input/output object/control parameters
  //   (indices of the parameters run from 1 to count)
  int GetInputIconicParamDimension(int par_idx) const;
  int GetOutputIconicParamDimension(int par_idx) const;
  int GetInputCtrlParamDimension(int par_idx) const;
  int GetOutputCtrlParamDimension(int par_idx) const;

  // Get info of procedure documentation
  HalconCpp::HTuple GetInfo(const char* slot) const;
  // Get info of parameter documentation by name
  HalconCpp::HTuple GetParamInfo(const char* par_name, const char* slot) const;
  // Get info of parameter documentation by index
  //   (indices of the parameters run from 1 to count)
  HalconCpp::HTuple GetInputIconicParamInfo(int par_idx, const char* slot) const;
  HalconCpp::HTuple GetOutputIconicParamInfo(int par_idx, const char* slot) const;
  HalconCpp::HTuple GetInputCtrlParamInfo(int par_idx, const char* slot) const;
  HalconCpp::HTuple GetOutputCtrlParamInfo(int par_idx, const char* slot) const;

  // Query possible slots for procedure/parameter info
  HalconCpp::HTuple QueryInfo() const;
  HalconCpp::HTuple QueryParamInfo() const;
};


/*****************************************************************************
 *****************************************************************************
 ** class HDevProcedureCall
 **===========================================================================
 ** Class for executing an HDevelop procedure and managing the parameter
 ** values
 *****************************************************************************
 *****************************************************************************/
class LIntExport HDevProcedureCall
{
  HDEV_PD;

public:
  // Create an empty HDevelop procedure call instance
  HDevProcedureCall();
  // Create HDevelop procedure call instance
  HDevProcedureCall(const HDevProcedure& hdev_proc);
  // Copy constructor
  HDevProcedureCall(const HDevProcedureCall& hdev_proc_call);
  HDevProcedureCall(const Data& data);
  // Assignment operation
  HDevProcedureCall& operator=(const HDevProcedureCall& hdev_proc_call);
  // Destructor
  ~HDevProcedureCall();

  // Get the procedure
  HDevProcedure GetProcedure() const;

  // Execute program
  void Execute();

  // Stop execution on first line of procedure. This is intended for debugging
  // purposes when you wish to step through a specific procedure call. It only
  // has an effect when a debug server is running and it will only stop once.
  void SetWaitForDebugConnection(bool wait_once);

  // Clear procedure and reset callstack
  //  - this method stops the execution of the procedure after the current
  //    program line
  void Reset();

  // Set input object/control parameter
  void SetInputIconicParamObject(int par_idx, const HalconCpp::HObject& obj);
  void SetInputIconicParamObject(const char* par_name, const HalconCpp::HObject& obj);
  void SetInputIconicParamVector(int par_idx, const HalconCpp::HObjectVector& vector);
  void SetInputIconicParamVector(const char* par_name, const HalconCpp::HObjectVector& vector);

  void SetInputCtrlParamTuple(int par_idx, const HalconCpp::HTuple& tuple);
  void SetInputCtrlParamTuple(const char* par_name, const HalconCpp::HTuple& tuple);
  void SetInputCtrlParamVector(int par_idx, const HalconCpp::HTupleVector& vector);
  void SetInputCtrlParamVector(const char* par_name, const HalconCpp::HTupleVector& vector);

  // Get the objects / values of the parameters by name or by index
  //   (indices of the variables run from 1 to count)
  HalconCpp::HObject       GetOutputIconicParamObject(int par_idx) const;
  HalconCpp::HObject       GetOutputIconicParamObject(const char* par_name) const;
  HalconCpp::HObjectVector GetOutputIconicParamVector(int par_idx) const;
  HalconCpp::HObjectVector GetOutputIconicParamVector(const char* par_name) const;
  HalconCpp::HTuple        GetOutputCtrlParamTuple(int par_idx) const;
  HalconCpp::HTuple        GetOutputCtrlParamTuple(const char* par_name) const;
  HalconCpp::HTupleVector  GetOutputCtrlParamVector(int par_idx) const;
  HalconCpp::HTupleVector  GetOutputCtrlParamVector(const char* par_name) const;

  // These methods are provided for efficiency:
  // the results are copied directly into the tuple variable provided by
  // the user without additional copying
  void GetOutputCtrlParamTuple(int par_idx, HalconCpp::HTuple* tuple) const;
  void GetOutputCtrlParamTuple(const char* par_name, HalconCpp::HTuple* tuple) const;
};


/*****************************************************************************
 *****************************************************************************
 ** class HDevEngineException
 **===========================================================================
 ** Class for HDevelop engine exceptions
 *****************************************************************************
 *****************************************************************************/
class LIntExport HDevEngineException
{
  HDEV_PD;

public:
  // Exception categories
  enum ExceptionCategory
  {
    Exception,           // Generic
    ExceptionInpNotInit, // Error input parameters not initialized
    ExceptionCall,       // Error HALCON or HDevelop operator call
    ExceptionFile        // Error opening or reading HDevelop file
  };

  // Create HDevelop engine exception
  HDevEngineException(const char* message, ExceptionCategory category = Exception, const char* exec_proc_name = "",
                      int prog_line_num = -1, const char* prog_line_name = "", Herror h_err_nr = H_MSG_VOID,
                      const HalconCpp::HTuple& user_data = HalconCpp::HTuple());
  HDevEngineException(const HDevEngineException& exc);
  HDevEngineException(const Data& data);
  HDevEngineException& operator=(const HDevEngineException& exc);
  virtual ~HDevEngineException();

  // Error text
  const char* Message() const;
  // Category of exception
  ExceptionCategory Category() const;
  const char*       CategoryText() const;
  // Name of executed procedure
  const char* ExecProcedureName() const;
  // Number of executed procedure or operator program line
  int ProgLineNum() const;
  // Name of executed procedure or operator program line
  const char* ProgLineName() const;
  // HALCON error code
  Herror HalconErrorCode() const;
  HDEPRECATED(Herror HalconErrNum() const, "deprecated, please use HalconErrorCode instead.");

  HalconCpp::HTuple UserData() const;
  void              UserData(HalconCpp::HTuple& user_Data) const;
};


/*****************************************************************************
 *****************************************************************************
 ** class HDevOperatorImplCpp
 **===========================================================================
 ** Class for the implemention of HDevelop internal operators
 *****************************************************************************
 *****************************************************************************/
class LIntExport HDevOperatorImplCpp
{
  HDEV_PD;

public:
  HDevOperatorImplCpp();
  // Copy constructor
  HDevOperatorImplCpp(const HDevOperatorImplCpp& hdev_op_impl);
  HDevOperatorImplCpp(const Data& data);
  // Assignment operation
  HDevOperatorImplCpp& operator=(const HDevOperatorImplCpp& hdev_op_impl);
  // Destructor
  virtual ~HDevOperatorImplCpp();

  virtual int DevClearWindow();
  virtual int DevCloseWindow();
  virtual int DevSetWindow(const HalconCpp::HTuple& win_id);
  virtual int DevGetWindow(HalconCpp::HTuple* win_id);
  virtual int DevDisplay(const HalconCpp::HObject& obj);
  virtual int DevDispText(const HalconCpp::HTuple& string, const HalconCpp::HTuple& coordSystem,
                          const HalconCpp::HTuple& row, const HalconCpp::HTuple& column,
                          const HalconCpp::HTuple& color, const HalconCpp::HTuple& genParamName,
                          const HalconCpp::HTuple& genParamValue);
  virtual int DevSetWindowExtents(const HalconCpp::HTuple& row, const HalconCpp::HTuple& col,
                                  const HalconCpp::HTuple& width, const HalconCpp::HTuple& height);
  virtual int DevSetDraw(const HalconCpp::HTuple& draw);
  virtual int DevSetContourStyle(const HalconCpp::HTuple& style);
  virtual int DevSetShape(const HalconCpp::HTuple& shape);
  virtual int DevSetColored(const HalconCpp::HTuple& colored);
  virtual int DevSetColor(const HalconCpp::HTuple& color);
  virtual int DevSetLut(const HalconCpp::HTuple& lut);
  virtual int DevSetPaint(const HalconCpp::HTuple& paint);
  virtual int DevSetPart(const HalconCpp::HTuple& row1, const HalconCpp::HTuple& col1, const HalconCpp::HTuple& row2,
                         const HalconCpp::HTuple& col2);
  virtual int DevSetLineWidth(const HalconCpp::HTuple& width);
  virtual int DevOpenWindow(const HalconCpp::HTuple& row, const HalconCpp::HTuple& col, const HalconCpp::HTuple& width,
                            const HalconCpp::HTuple& height, const HalconCpp::HTuple& background,
                            HalconCpp::HTuple* win_id);
};
} // namespace HDevEngineCpp


#endif // #ifndef H_DEV_ENGINE_CPP_H