CoCreate Modeling code examples: Controlling model clipping planes

topic end
<!--
   * Set TOPICTITLE = <nop>CoCreate Modeling code examples: Controlling model clipping planes
-->

<style type="text/css">
pre { background-color:#FFEECC; }
</style>


#ModelClipping
---++ <nop>CoCreate Modeling: Controlling model clipping planes

This simple code example defines two functions which enable model clipping
in the current viewport. The clipping plane position is derived from the 
current workplane. Thanks to J&ouml;rg Antweiler for the 
[[http://ww3.cad.de/foren/ubb/Forum29/HTML/001337.shtml][inspiration]] 
and the original code snippet in the German user forum.

<pre>
(defun clipping-on ()
  (set_vp_model_clipping (oli:sd-inq-current-vp) :on)
  (set_vp_capping (oli:sd-inq-current-vp) :on)
  (set_vp_capping (oli:sd-inq-current-vp) :part-color)
  (model_clipplane :plane1 :off :plane1 :on
    :plane1_positioning :par_wp :ref_wp (oli::sd-inq-curr-wp) :done 
    :flip_plane :done)
)

(defun clipping-off ()
  (model_clipplane :plane1 :off)
  (set_vp_model_clipping (oli:sd-inq-current-vp) :off)
)
</pre>

<img src="%ATTACHURLPATH%/recorder.png" alt="recorder.png" style="float:right;" />
The interesting part of this example is not so much the end result,
but how you get there, starting from a command sequence captured by
the =recorder= tool.

Remember, the recorder utility can be loaded
by enter =(load "recorder")= in the user input line. Then go to the Toolbox
and select the "Recorder" entry. This opens a dialog which looks like in the screenshot.
Click "Start" in the dialog, then step through the modeling commands which you want to 
record. When you're done, click "Stop" in the Recorder dialog.

In our particular example, the original sequence looked roughly like this:

<pre>
set_vp_model_clipping "1"  :on set_vp_capping "1"  :on set_vp_capping "1"  
:part-color model_clipplane  :plane1  :off  :plane1  :on  
:plane1_positioning  :par_wp 
:ref_wp "/s" :done :flip_plane :done
(PROGN
  (RESET-TOGGLE "MODIFY_CLIPPLANE_SA-VAR-GROUP-1-OPT-CONT-DONE-TB")
  NIL)
complete
</pre>

As you can see, the =recorder= tool writes quite a bit of gobbledigook,
and you need to massage it into a format which lends itself more easily
to be used in real programs.

The first observation is that the =RESET-TOGGLE= command is only a UI
by-product which can be simply omitted.  The reasons why it's in the
recorder file are quite internal, and in general you don't want to know .-)
In any case, let's remove that from the sequence; I'll also throw in
some formatting for free:

<pre>
set_vp_model_clipping "1" :on 
set_vp_capping "1" :on 
set_vp_capping "1" :part-color 
model_clipplane :plane1 :off :plane1 :on 
                :plane1_positioning :par_wp :ref_wp "/s" :done 
                :flip_plane :done complete
</pre>

Ahhh, that's much easier on the eyes now.

When looking at the above, any Lisp programmer who is worth his salt will
start to shiver because of acute parentheses deprivation: "Where have all my
beloved =(= and =)= characters gone?" In fact, the above doesn't even look
like Lisp, rather like some... well... macro language, right?

Exactly. On top of <nop>CoCreate Modeling's Lisp subsystem runs a so-called 
_action routine interpreter_. This interpreter understands syntax such 
as the above. If you are familiar with the macro language in CoCreate
Drafting, it will probably dawn on you quite quickly why the
designers of <nop>CoCreate Modeling chose to implement such an interpreter - they wanted to
provide similar macro entry capabilities for OSDM. (That funny =complete=
token should definitely give it away...)

All the high-level commands in <nop>CoCreate Modeling, such as <i>extrude</i>, <i>load_package</i>,
<i>load_session</i> and even <i>exit</i> are implemented in this manner,
i.e. they can be entered without using any parentheses - and that is also
the way those commands are captured by the =recorder=. Any functionality
implemented via =sd-defdialog= can also be used in parentheses-free
notation or, as we sometimes say, in _action routine syntax_.

High-level commands such as the above are also automatically endowed with
certain services, such as recordability, UNDO handling, and automatic
UI synchronization. But I'm mentioning this only to confuse you even
more. The real reason why we're discussing this here is to show you
how to convert recorder file syntax into something that can be used
programmatically.

In fact, we're almost done. You need to know only a few things:
   * High-level commands also work if you remove the trailing
     =complete= and enclose them in parentheses
   * Arbitrary Lisp expressions can be used as an input
     for parameters of commands.

This leads us immediately to:

<pre>
(defun clipping-on ()
  (set_vp_model_clipping (oli:sd-inq-current-vp) :on) 
  (set_vp_capping (oli:sd-inq-current-vp) :on) 
  (set_vp_capping (oli:sd-inq-current-vp) :part-color) 
  (model_clipplane :plane1 :off :plane1 :on 
                :plane1_positioning :par_wp :ref_wp "/s" :done 
                :flip_plane :done)
)
</pre>

Which is almost the program presented at the beginning, except that 
we do not use =oli:sd-inq-current-wp= to inquire
the current workplane, and that we do not have the code to disable clipping
yet.

If you already read the Integration Kit documentation and especially
the sections on =sd-defdialog= and =sd-call-cmds=, you will probably
ask why =set_vp_model_clipping= and friends are not encapsulated in
=sd-call-cmds= in the code above. Answer: They are, in this particular case,
not part of any =sd-defdialog= code. Instead, the code is expected to be
called directly from the user input line. In that case, you cannot
use =sd-call-cmds= - but you _must_ do this when calling/executing
code such as the above in dialog context. That's a topic for another
rainy day...

-- Main.ClausBrod

---
To have it really comfortable we will have a third tiny function to realize a toggle behaviour and finally to create an "Available Command" to have a tool bar icon for quick access to our new function (in 2 different languages).

<pre>
(in-package :sd-tools)
(use-package :oli)

;; insert the two known functions from above here..

(defvar *clipping-on-off* NIL)
(defun clipping-on-off ()
 (if *clipping-on-off*
   (progn
     (setq *clipping-on-off* NIL)
     (clipping-on)
     )
   (progn
     (setq *clipping-on-off* T)
     (clipping-off)
     )
   ) ;; end if
 ) ;; end defun

(sd-define-available-command
 "All" "Miscellaneous" "Clipping-On-Off"
 :groupTitle   (sd-multi-lang-string  "Miscellaneous" :german "Verschiedenes")
 :commandTitle (sd-multi-lang-string  "Clipping toggle" :german "Schneiden")
 :action       "(sd-tools::clipping-on-off)"
 :image        "SolidDesigner/View/clipping"
 )
</pre>

Well, the icon (=:image=) is an already existing one. Create a new one if you like.

The complete example [[%ATTACHURL%/clipping_on_off.lsp][clipping_on_off.lsp]] can be loaded from the attachment area.

-- Main.DerWolfgang - 25 Nov 2004


%COMMENT{type="below" nonotify="on"}%
to top
End of topic
Skip to action links | Back to top
You are here: CoCreateModeling > MacroModelClipping

r1.6 - 24 Jul 2009 - 19:57 - ClausBrod to top
CoCreateModeling
Welcome
