##

    Last update: 2013-02-25

    RemoteControl gCAD3D

    What is RemoteControl

    PRI(text)            // print text (into messagewindow)
    ADD(code)            // process and store source-objects
    ADDFILE(filNam)      // process and store cad-objects in file
    MOD(code)            // modify cad-code, update
    NEW                  // save active model if modified, then clear whole model
    CLEAR                // clear whole model - do not save model if modified
    MODSIZ(newsize)      // change modelsize; use 'END' to update.
    END                  // reprocess whole model

    GETSYMDIR(sym)       // returns path for symbolic-directory
    SETSYMDIR(sym,path)  // set new symbolic-directory
    DELSYMDIR(sym)       // delete symbolic-directory

    LOAD(modelname)      // clear and load new model (native, step, iges, dxf ..)
    LOADSM(submodel)     // load submodel (can only load native models (.gcad))

    SAVE                 // save model with current modelname
    SAVE(new_modelname)  // save model with given modelname

    ZOOMALL              // set zoomfactor to view all objects
    VIEW(center, scale, rotAng, tiltAng)  // define view;
    SHOW(obj,off)        // hide object
    SHOW(obj)            // show hidden object
    ATTL(linetypNr,objects) // change linetype for objects
    ATTS("code",objects) // change surface-attribute
    LOADTEX(texFilNam)   // load texturefile (image)

    ERRCLR               // returns errcode and clears error; 0=OK
    GETMODSIZ            // get current modelsize
    GETOBJINDNXT(P)      // get next free object-index
    GETLNR               // get current lineNr
    DELFOLL(lnr)         // delete all lines following lineNr'
    USER                 // get object from user (selection); Esc: empty.
    DUMP(list)           // dump list to console-window
    MODE(widget,off|on)  // hide or show subwindows: browser, menu, toolbars ..
    WAIT_ESC             // stop until ESC - key becomes pressed
    SYSTEM               // do operating-system command, wait; eg "SYSTEM(pluma /tmp/t1)"
    EXIT                 // shut down gcad3d

    __________________________________________________________________________

    What is RemoteControl

    With RemoteControl you can control the cad-program gCAD3D from programs.
    All programming languages can be used, even shell-scripts.
    For input and output 2 pipes (Linux; MS-Windows: Files) are used.
    Input/outputpipe are created in directory {tmpdir}.
    The temp-directory of gcad is indicated at strtup in the console-window -
      (eg Unix " basdir = |/mnt/serv2/devel/gcad3d/|")
      for default-installation this is:
    Linux:
      the inputpipe is ${HOME}/gCAD3D/tmp/CTRLpin;
      the outputpipe is ${HOME}/gCAD3D/tmp/CTRLpout.
    MS_Windows:
      Input from %APPDATA%\gCAD3D\tmp\CTRLpin
      Output to %APPDATA%\gCAD3D\tmp\CTRLpout

    A system-variable can be set -
      Unix "RCTL=/mnt/serv2/devel/gcad3d/CTRLpin"
        Command scan be sent now to $RCTL
      MS-Win: set RCTL="%APPDATA%\gCAD3D\tmp\CTRLpin"
        Command scan be sent now to %RCTL%

    Input and output is done with textcodes, not binary.
    You can send commands from a terminalprogram (Linux: xterm oder gnome-terminal; MS-Windows: cmd)
      to gcad (example: clear active model):
    Linux:
      echo 'new' > ~/gCAD3D/tmp/CTRLpin
      or
      echo 'new' > $RCTL
    MS_Windows:
      echo new>"%APPDATA%\gCAD3D\tmp\CTRLpin"
      or
      echo new>%RCTL%

    Send a commandfile to remoteControl:
     - put the following 4 lines into  file t1.cmd:
    new
    add(P1=P(100 0 0))
    add(C1=P1 50)
    #eof

    Send the file:
    Linux:
      cat t1.cmd > ~/gCAD3D/tmp/CTRLpin
      or
      cat t1.cmd > $RCTL
    MS_Windows:
      copy t1.cmd "%APPDATA%\gCAD3D\tmp\CTRLpin"
      or
      copy t1.cmd %RCTL%

    Receiving output from gcad (eg display the output in a terminal-window):
    Linux (keeps connection):
      cat  ~/gCAD3D/tmp/CTRLpout
    MS_Windows (new file after each remote-command):
      type %APPDATA%\gCAD3D\tmp\CTRLpout

    Gcad sends after each command at least a new-line-character (ascii 10).

    If you want to activate the program from "Remote/ Select-Start":
      Put start-scripts into directory /remote
      Put executables into directory

    Programming Examples:
    VB.Net (MS-Windows): Demo1gCadRemoteControl.zip
    Java: DemoRC1.java

    All following examples are linux-examples.

    Please send improved examples or examples for other programming-languages to
     support at gcad3d.org

    __________________________________________________________________________

    PRI(text)              // print text (into messagewindow)

    Objects (points, vectors, variables) are decoded.

    Example:
    echo 'pri("TestPrint 1")' > ~/gCAD3D/tmp/CTRLpin
    # display coordinates of point p1 and vector D1 with:
    echo 'pri("P20 = ",P20," D20 = ",D20)' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    GETLNR               // get current lineNr
    DELFOLL(lnr)         // delete all lines following lineNr

    # lineNr from GETLNR can eg later be used for DELFOLL
    #   (delete all objects created after getting 'GETLNR')

    __________________________________________________________________________

    GETOBJINDNXT(typ)     // get next free object-index for points

    # example: get next free DB-index for type point:
    echo 'GETOBJINDNXT(P)' > ~/gCAD3D/tmp/CTRLpin
    # See list of objecttypes

    __________________________________________________________________________

    __________________________________________________________________________

    ADD(code)            // process and store source-objects

    # code is any valid gcad-text; see Codes
    # eg create a point with:
    echo 'add(P1=P(100 0 20))' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    ADDFILE(filNam)      // process and store cad-objects in file

    echo 'addfile("t1")' > ~/gCAD3D/tmp/CTRLpin

    Example for file t1:
    MODE(MEN,off)
    MODE(BRW,off)
    MODE(BAR1,off)
    MODE(BAR2,off)
    new
    add(P1=P(100 0 0))
    add(C1=P1 50)
    zoomall
    #eof

    __________________________________________________________________________

    MOD(code)            // modify cad-code, update

    Example:
    echo 'MOD(V1=70)' > ~/gCAD3D/tmp/CTRLpin

    # modifies the line "V1=50" in the existing code:
    # and updates the variable V1 and the circle C1.

    P1=P(100 100 0)
    V1=50
    C1=P1 V1

    __________________________________________________________________________

    GETSYMDIR(sym)       // returns path for symbolic-directory
    SETSYMDIR(sym,path)  // set new symbolic-directory
    DELSYMDIR(sym)       // delete symbolic-directory

    # get absolute path for (existing) symbol "Data"
    echo 'GETSYMDIR("Data")' > ~/gCAD3D/tmp/CTRLpin

    # set new symbol "myPath" to path "/tmp/gcad/"
    echo 'SETSYMDIR("myPath","/tmp/gcad/")' > ~/gCAD3D/tmp/CTRLpin

    # delete symbol "myPath"
    echo 'DELSYMDIR("myPath")' > ~/gCAD3D/tmp/CTRLpin

    # clear error
    echo 'ERRCLR' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    LOAD(modelname)      // clear and load new model (native, step, iges, dxf ..)

    Load models; filename can be symbolic, relativ or absolut.
    # Example symbolic-filename:
    echo 'load("Data/sample_area1.gcad")' > ~/gCAD3D/tmp/CTRLpin
    # Example relative-filename (using current symbolic directory):
    echo 'load("../dat/sample_area2.gcad")' > ~/gCAD3D/tmp/CTRLpin
    # Example absolute-filename:
    echo 'load("/tmp/test1.gcad")' > ~/gCAD3D/tmp/CTRLpin

    echo 'MODSIZ(10000)' > ~/gCAD3D/tmp/CTRLpin
    echo 'END' > ~/gCAD3D/tmp/CTRLpin

    LOADSM(submodel)     // load submodel (can only load native models (.gcad))

    # submodels need to be in a symbolic directory. See SETSYMDIR.
    # Example load submodels, use submodels:
    echo 'new' > ~/gCAD3D/tmp/CTRLpin
    echo 'loadsm("Data/sample_mod_blech1.gcad")' > $RCTL
    echo 'loadsm("Data/sample_mod_screw1.gcad")' > $RCTL
    echo 'loadsm("Data/sample_mod_nut1.gcad")' > $RCTL
    echo 'add(M20="Data/sample_mod_blech1.gcad" P(0 10 0))' > $RCTL
    echo 'add(M21="Data/sample_mod_screw1.gcad" P(30 36.5 67))' > $RCTL
    echo 'add(M22="Data/sample_mod_nut1.gcad" P(36 36.5 67))' > $RCTL

    or copy into file test.cmd:
    new
    loadsm("Data/sample_mod_blech1.gcad")
    loadsm("Data/sample_mod_screw1.gcad")
    loadsm("Data/sample_mod_nut1.gcad")
    add(M20="Data/sample_mod_blech1.gcad" P(0 10 0))
    add(M21="Data/sample_mod_screw1.gcad" P(30 36.5 67))
    add(M22="Data/sample_mod_nut1.gcad" P(36 36.5 67))
    # eof

    and execute with -
    Unix:
      cat test.cmd > $RCTL
    MS-Win:
      copy test.cmd %RCTL%

    __________________________________________________________________________

    SAVE                 // save model with current modelname
    SAVE(new_modelname)  // save model with given modelname

    # save active model as "test1.gcad" in symbolic direcory "Data". See SETSYMDIR.
    echo 'save("Data/test1.gcad")' > ~/gCAD3D/tmp/CTRLpin

    # quick-save
    echo 'save' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    VIEW(center, scale, rotAng, tiltAng)  // define view;

    # change view-scale
    echo 'view(0.25)' > ~/gCAD3D/tmp/CTRLpin

    # change view by rotation-angle and tilt-angle (degrees)
    echo 'view(ang(45) ang(30))' > ~/gCAD3D/tmp/CTRLpin

    # move view (change center-of-screen-point)
    echo 'view(P(38 49 7))' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    SHOW(obj,off)        # hide object
    SHOW(obj)            # show hidden object

    # hide line L21
    echo 'show(L21,off)' > ~/gCAD3D/tmp/CTRLpin

    # show hidden line L21
    echo 'show(L21)' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    DUMP()    # Dump geometric structure of database-object

    DUMP("GA")           # dump Grafic_Attributes_list
    DUMP("DL")           # dump display-list
    DUMP("AT")           # dump linetypetable
    DUMP("TX")           # dump textures
    DUMP("SD")           # dump all symbolic directories

    Examples:
    echo 'DUMP(C20)' > ~/gCAD3D/tmp/CTRLpin
    echo 'DUMP("GA")' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    MODE(widget,off|on)    // Hide/restore menu, browser, upper toolbar, messagebar.

    # menu off
    echo 'MODE(MEN,off)' > ~/gCAD3D/tmp/CTRLpin

    # browser off
    echo 'MODE(BRW,off)' > ~/gCAD3D/tmp/CTRLpin

    # upper toolbar off
    echo 'MODE(BAR1,off)' > ~/gCAD3D/tmp/CTRLpin

    # messagewindow off
    echo 'MODE(BAR2,off)' > ~/gCAD3D/tmp/CTRLpin

    # Restore messagewindow.
    echo 'MODE(BAR2,on)' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    ATTL(linetypNr,objects)             // apply predefined linetype to object

    # linetypNr 0 - 12 are predefined in file ~/gCAD3D/cfg_{os}/ltyp.rc
    # See Defaultsettings

    # use linetypNr=8 for L21 and L22
    echo 'ATTL(8,L21,L22)' > ~/gCAD3D/tmp/CTRLpin

    # change/create linetype (G = color,linetyp,thick)
    # create linetype G13: green, full-line, thick=4 with:
    echo 'add(G13=3,0,4))' > ~/gCAD3D/tmp/CTRLpin

    # set linetypNr=13 for L21 and L22
    echo 'ATTL(13,L21,L22)' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    ATTS("code",objects)                          // change surface-attribute

    Examples:
    # set surface A21 symbolic (not shaded)
    echo 'ATTS("S" A21)' > ~/gCAD3D/tmp/CTRLpin

    # reset previous color (default-colour)
    echo 'ATTS("C" A21)' > ~/gCAD3D/tmp/CTRLpin

    # set color green (red-share-0, green-share-255, blue-share-0)
    echo 'ATTS("C00ff00" A21)' > ~/gCAD3D/tmp/CTRLpin

    # set transparent  (T0=reset, T1=half transparent, T2=full transparent)
    echo 'ATTS("T2" A21)' > ~/gCAD3D/tmp/CTRLpin

    # load texture and make active. Textures must be in symbolic directory.
    echo 'LOADTEX("DIR_BMP/Ziegel1.bmp")' > ~/gCAD3D/tmp/CTRLpin

    # apply texture to surface A21; set hor./vert.scales to "0.5,0.5".
    # ATTS("Xscale,offset,angle",objects) // apply active texture
    echo 'ATTS("X0.5,0.5" A21)' > ~/gCAD3D/tmp/CTRLpin

    __________________________________________________________________________

    USER                                // get object from user (selection); Esc: empty.

    # get user-selection;
    echo 'USER' > ~/gCAD3D/tmp/CTRLpin
    # returns "SEL(P(-3.244327 -10.077265 0.000000))"  for indicate position or
    # returns "SEL(C16)"                               for selection of obj C16 or
    # returns "SEL()"                                  for key esc pressed.