Scheme Extensions

Scheme Extensions
Technical Article

Scheme is a public domain programming language, based on the LISP language, that uses an interpreter to run commands. ACIS provides extensions (written in C++) to the native Scheme language that can be used by an application to interact with ACIS through its Scheme Interpreter. The C++ source files for ACIS Scheme extensions are provided with the product. Spatial's Scheme based demonstration application, Scheme ACIS Interface Driver Extension (Scheme AIDE), also uses these Scheme extensions and the Scheme Interpreter.

entity:edg-stch-options
entity:exact-stch-options
entity:repair-tedges
entity:stch-get-coin-faces
entity:stch-options
entity:stitch
entity:stitch-nonmanifold
stitch:edges

entity:edg-stch-options

Action

This extension returns an object of edg-stch-options.

Filename

SPAScmExt/stch_scm/scm_stch.cpp

APIs

None

Syntax

(entity:edg-stch-options "name-of-option" {value(s)} {options})

Arg Types

"name-of-option"	`string`
value	`integer`
options	`stch-options`

Returns

edg-stch-options

Errors
          max_stitch_tol option requires a real number as argument.
          identify_coincident_faces option requires an integer value 0, 1, or 2 as an argument.
          identify_coincident_faces option requires integer argument.
          fix_body_orientation option requires boolean argument.
          Incorrect stitch option.

Description
This extension returns an edg-stch-options object for use in stitch:edges. This allows the user to set the max_stitch tolerance, and the option of switching ON/OFF coincident faces clustering.

Some of the possible name-of-option and value pairs are:

name-of-option	value	Result
identify_coincident_faces	0 (Default)	SPASTITCH_COIN_ERROR: The stitcher immediately terminates with a sys_error. The state of the model is rolled back to the unstitched state.
identify_coincident_faces	1	SPASTITCH_COIN_STITCH: The faces are stitched together along the edge and stitching continues. The coincident face pair is recorded internally and the stitcher throws a warning. Because this produces back-to-back faces, it is likely downstream ACIS operations will fail. This option is strongly discouraged.
identify_coincident_faces	2	SPASTITCH_COIN_SKIP: The faces are NOT stitched together along the edge, and stitching continues. The coincident face pair is recorded internally and the stitcher throws a warning. This is the recommended setting.
fix_body_orientation	#t (Default)	Set to #t if the possibility exists that one or more of the unstitched face normals point inwards (which would result in the stitched model becoming a void).
fix_body_orientation	#f	Set to #f if the stitch is being performed on faces that are known to have correctly pointing face normals (because of an unhook operation, for example).

edg-stch-options object sets the parameters that govern the functionality of stitch:edges. The parameters are:

max_stitch_tol Default value is -1.

identify_coincident_faces Allowed values are 0, 1, and 2. Default value is 0.

fix_body_orientation Allowed values are #t, #f. Default value is #t. Set fix_body_orientation to #t if one or more of the unstitched face normals may be pointing inwards (which would result in the stitched model becoming a void). Set fix_body_orientation to #f if stitch is to be performed on faces known to have correctly pointing face normals (because of an unhook operation, for example).

Arguments: "name-of-option" is a string containing the name of the option.; value is an integer value containing the value of option.; options sets a particular edg-stch-options.

; Load the body (part:load "xxx.sat") ; Make the edge stitch options object "edg-stch-options" (define so (entity:edg-stch-options "identify_coincident_faces" 2 "max_stitch_tol" 0.001 "fix_body_orientation" #f)) ; To check the values of parameters of edg-stch-options, ; type the option's name on the prompt acis> so ; tolerant_max_stitch_tol : 0.001 ; identify_coincident_faces : 2 ; Number of coincident_faces_clusters : Default ; fix_body_orientation : 0 ; For updating the parameters of an existing edg-stch-options object, ; the same scheme command (entity:edg-stch-options) ; can be used by passing the options object as the last argument, for example, ; (entity:edg-stch-options "identify_coincident_faces" 1 so)

[Top]

entity:exact-stch-options

Action

This extension returns an object of type exact-stitch-options.

Filename

scm/scmext/stch/scm_stch.cpp

APIs

None

Syntax

(entity:exact-stch-options ["name-of-option" value(s)] ... [exact-stitch-opt])

Arg Types

"name-of-option"	`string`
value	`integer`
exact-stitch-opt	`exact-stitch-options`

Returns

exact-stitch-options

Errors
"split_option" requires 0 or 1 as an argument.
Incorrect stitch option.

Description
This extension returns an exact-stitch-options object for use in entity:stitch. This allows to the user to set the split option in EXACT_STITCH mode. The exact-stitch-opt object sets the parameters that govern the entity:stitch in EXACT_STITCH mode. At the moment, the only parameter is "split_option". It can takes the values 0, 1. The default value is 0.

If "split_option" is 1, it indicates that the edges of faces that are stitched are split in order to match coincident edges. Coincident edges on single-sided faces and of incompatible orientation (opposite coedge sense) are not split.

Arguments: "name-of-option" is a string containing the name of the option.; value is an integer value containing the value of option.; exact-stitch-opt is an existing exact-stitch-options.

; Load the body (part:load "xxx.sat") ; Make the stitch options object "exact-stitch-options" (define so (entity:exact-stch-options "split_option" 1)) ;; so ; To check the values of parameters of exact-stitch-options ; just type the option's name on the prompt so ;; split_option : 1 ; For updating an existing exact-stitch-options object ; the same command (entity:exact-stch-options) can be ; used by passing the options object as the last argument. (entity:exact-stch-options "split_option" 0 so)

[Top]

entity:repair-tedges

Action

Attempts to fix level 30 check errors in TEDGEs in an entity but does not guarantee that these errors will be fixed.

Filename

scm/scmext/stch/scm_tedrep.cpp

APIs

api_check_and_fix_tedge

Syntax

(entity:repair-tedges entity [acis-opts])

Arg Types

entity	`entity`
acis-opts	`acis-options`

Returns

entity | (entity...)

Errors
Could not find any edge in the entity.

Description
The input to this command is any entity containing TEDGEs, like BODY, FACE or a TEDGE itself. This scheme command internally calls api_check_and_fix_tedge for all the TEDGEs in the body. It returns a list of TEDGEs that have been repaired. This scheme command attempts to fix level 30 check errors in TEDGEs in an entity but does not guarantee that these errors will be fixed. For more details refer to the documentation of api_check_and_fix_tedge in Quick Reference Guide.

Arguments: entity is any entity containing TEDGEs, like BODY, FACE or a TEDGE.; acis-opts contains versioning and journaling information.
Limitations: Refer limitations of API api_check_and_fix_tedge.

; Load the body (part:load "xxx.sat") ;; (#[entity 1 1]) ; Check the entity for error at level 30 (entity:check (entity 1) 30 'ERROR) ;; entid 394240: Error: TCOEDGE and TEDGE geometry appear to be incompatible ;; at edge parameter 4.802094125547, coedge parameter 4.781382099055 ;; checked: ;; 1 lumps ;; 1 shells ;; 0 wires ;; 1 faces ;; 1 loops ;; 3 coedges ;; 3 edges ;; 3 vertices ;; (#[entity 2 1]) ; Call the repair scheme command. (entity:repair-tedges (entity 1)) ;; (#[entity 3 1]) ; Check the body again to confirm there is no error. (entity:check (entity 1) 30 'ERROR) ;; checked: ;; 1 lumps ;; 1 shells ;; 0 wires ;; 1 faces ;; 1 loops ;; 3 coedges ;; 3 edges ;; 3 vertices ;; ()

[Top]

entity:stch-get-coin-faces

Action

This extension returns coincident faces cluster list.

Filename

scm/scmext/stch/scm_stch.cpp

APIs

None

Syntax

(entity:stch-get-coin-faces options)

Arg Types

options

stch-options

Returns

coincident faces cluster list

Errors
Incorrect argument, requires a stitch options object.

Description
This extension returns the list of clusters of coincident faces which got created during the stitch process.

Arguments: options are the different stch-options.

Example 1 ; Load the body (part:load "xxx.sat") ; Make the tolerant stitch options object "stch-options" (define so (entity:stch-options "identify_coincident_faces" 2 "max_stitch_tol" 0.001)) ;; so ; To check the values of parameters of stch-options ; just type the option's name on the prompt so ;; tolerant_max_stitch_tol : 0.001 ;; identify_coincident_faces : 2 ;; Number of coincident_faces_clusters : Default ; For updating the parameters of an existing stch-options ; object the same scheme command (entity:stch-options ) ; can be used by passing the options object as the last argument (entity:stch-options "identify_coincident_faces" 1 so) ; Call entity:stitch with the stch-options object "so"
(entity:stitch (part:entities) so)
; To get the number of coincident faces cluster list identified by entity:stitch
so
;; tolerant_max_stitch_tol : 0.001 ;; identify_coincident_faces : 1 ;; Number of coincident_faces_clusters : 3 ;To get the clusters of coincident faces
(define coin_list (entity:stch-get-coin-faces so))
;; coin_list

Example 2 ; Load the body (part:load "yyy.sat") ; Make edge stitch options object "stch-options" (define so (entity:edg-stch-options "identify_coincident_faces" 2 "max_stitch_tol" 0.001)) ;; so ; To check the values of parameters of stch-options ; just type the option's name on the prompt so ;; tolerant_max_stitch_tol : 0.001 ;; identify_coincident_faces : 2 ;; Number of coincident_faces_clusters : Default ; For updating the parameters of an existing stch-options ; object the same scheme command (entity:edg-stch-options ) ; can be used by passing the options object as the last argument (entity:edg-stch-options "identify_coincident_faces" 1 so) ; Call entity:stitch with the stch-options object "so"
(entity:stitch (part:entities) so)
; To get the number of coincidet faces cluster list identified by entity:stitch
so;; tolerant_max_stitch_tol : 0.001 ;; identify_coincident_faces : 1 ;; Number of coincident_faces_clusters : 2 ;To get the clusters of coincident faces
(define coin_list (entity:stch-get-coin-faces so))
;; coin_list

[Top]

entity:stch-options

Action

This extension returns an object of stch-options.

Filename

scm/scmext/stch/scm_stch.cpp

APIs

None

Syntax

(entity:stch-options "name-of-option" {value(s)} {options})

Arg Types

"name-of-option"	`string`
value	`integer`
options	`stch-options`

Returns

stch-options

Errors
         max_stitch_tol option requires a real number as argument.
         identify_coincident_faces option requires an integer value 0, 1 or 2 as an argument.
         identify_coincident_faces option requires integer argument.
         Incorrect stitch option.

Description
This extension returns an edg-stch-options object for use in entity:stitch. This allows to the user to set the max_stitch tolerance, and the option of switching ON/OFF coincident faces clustering.

Some of the possible name-of-option and value pairs are:

name-of-option	value	Result
`identify_coincident_faces`	0 (Default)	SPASTITCH_COIN_ERROR: The stitcher immediately terminates with a sys_error. The state of the model is rolled back to the unstitched state. The behavior of stitcher in this mode is not affected by the value set to "careful" option.
`identify_coincident_faces`	1	SPASTITCH_COIN_STITCH: The faces are stitched together along the edge and stitching continues. The coincident face pair is recorded internally and the stitcher throws a warning. Since this produces back-to-back faces, it is likely downstream ACIS operations will fail. This option will be strongly discouraged. In R12 and later versions, the behavior of this mode when the "careful" option is FALSE (default) is as mentioned above. However when the "careful" option is set to TRUE, with `SPASTITCH_COIN_STITCH` mode stitcher will behave same as when the "careful" option is FALSE except that it will roll the model back to its initial state before exiting. So, with this mode when the "careful" option is set to TRUE, stitcher keeps the model unstitched, but provides the coincident face information.
`identify_coincident_faces`	2	SPASTITCH_COIN_SKIP: The faces are NOT stitched together along the edge, and stitching continues. The coincident face pair is recorded internally and the stitcher throws a warning. This is the recommended setting. In R12 and later versions, the behavior of this mode when the "careful" option is FALSE (default) is as mentioned above. However when the "careful" option is set to TRUE, with `SPASTITCH_COIN_SKIP` mode stitcher will behave same as when the "careful" option is FALSE except that it will roll the model back to its initial state before exiting. So, with this mode when the "careful" option is set to TRUE, stitcher keeps the model unstitched, but provides the coincident face information.

stch-options object sets the parameters that govern the functionality of entity:stitch. The parameters are:

max_stitch_tol If this is not set, an internal algorithm will be used to set its value.

identify_coincident_faces Allowed values are 0, 1, 2. Default value is 0.

Arguments: name-of-option is a string containing the name of the option.; value is an integer value containing the value of option.; options are the different stch-options.

; Load the body (part:load "xxx.sat") ; Make the stitch options object "stch-options" (define so (entity:stch-options "identify_coincident_faces" 2 "max_stitch_tol" 0.001)) ;; so ; To check the values of parameters of stch-options ; just type the option's name on the prompt so ;; tolerant_max_stitch_tol : 0.001 ;; identify_coincident_faces : 2 ;; Number of coincident_faces_clusters : Default ; For updating the parameters of an existing stch-options ; object the same scheme command (entity:stch-options ) ; can be used by passing the options object as the last argument. (entity:stch-options "identify_coincident_faces" 1 so)

[Top]

entity:stitch

Action

Attempts to tolerantly stitch a list of faces and bodies into a single body.

Filename

scm/scmext/stch/scm_stch.cpp

APIs

api_body, api_pm_remove_entity, api_stitch, api_separate_body, api_pm_add_entity, api_get_active_part, api_delent, api_part_start_state, api_part_note_state

Syntax

(entity:stitch list [stch-opts] ["use_old_api"] [acis-opts])

Arg Types

list	`entity` \| (`entity` ...)
stch-opts	`stitch-options`
"use_old_api"	`string`
acis-opts	`acis-options`

Returns

body | (body...)

Description
This extension attempts to stitch all the entities in the entity list. The extension can work in 2 modes - EXACT_STITCH, TOLERANT_STITCH. In EXACT_STITCH mode, entity:stitch stitches together edges only if they are close within SPAresabs. In this mode, only BODYs can be passed into entity:stitch.

In TOLERANT_STITCH mode, entity:stitch attempts to stitch edges that are not close within SPAresabs, but are close within the user-specified maximum stitch tolerance. The scheme extension may make certain edges tolerant in this mode whenever needed. In this mode, only BODYs or free FACEs can be passed into entity:stitch. A free FACE is a FACE that is a top-level entity and has no owner.

Arguments: list contains a list of entities to be stitched. In TOLERANT_STITCH mode, the list should contain only pointers to BODYs or free FACEs. A free FACE is a FACE that is a top-level entity and has no owner. Note that free FACEs are not legal in ACIS, but the scheme extension still accepts them. It is recommended though that the scheme extension be passed only BODYs. In EXACT_STITCH mode, the list should contain only pointers to BODYs.

stch-opts is an optional argument. stch-opts is a scheme object of a C++ object of class exact_stitch_options, or class tolerant_stitch_options.
If stch-opts is of class exact_stitch_options type, then entity:stitch will operate in EXACT_STITCH mode. The stch-opts object in EXACT_STITCH mode contains a "split_option" data, that indicates that the edges of faces that are stitched are split in order to match coincident edges. To create stch-opts object of class exact_stitch_options, the user will need to call the scheme command entity:exact-stch-options with appropriate arguments. For details on this refer to the documentation of entity:exact-stch-options.
If stch-opts is of class tolerant_stitch_options type, then entity:stitch will operate in TOLERANT_STITCH mode. The stch-opts object in TOLERANT_STITCH mode contains the max_stitch_tol parameter and the option of switching ON/OFF coincident faces clustering. To create stch-opts object of class tolerant_stitch_options, the user will need to call the scheme command entity:stch-options with appropriate arguments. For details on this refer to the documentation of entity:stch-options.
If stch-opts is not passed then entity:stitch will operate in TOLERANT_STITCH mode.; "use_old_api" is an optional argument. By default ( "use_old_api" string is not passed), entity:stitch will use the new API introduced in R13 having the following signature:
outcome api_stitch ( const ENTITY_LIST& to_be_stitched, ENTITY_LIST& output_bodies, ENTITY_LIST& new_bodies, stitch_options* sopts, AcisOptions* aopts )
If "use_old_api" string is passed, then entity:stitch will use the deprecated pre-R13 API having the following signature:
outcome api_stitch ( BODY* body ENTITY_LIST & to_be_stitched, stitch_options* sopts, AcisOptions* aopts )
followed by api_separate_body.
The string "use_old_api" recovers the pre-R13 behavior of entity:stitch. Customers passing acis-opts with a version before R13 should also pass the string "use_old_api" into entity:stitch.; acis-opts contains versioning and journaling information.
Limitations: Tolerant stitching can not be used to create non-manifold (i.e. more than 2 coedges per edge) bodies.
All the incoming entities must be checked.
In EXACT_STITCH mode, the scheme extension will operate only on BODYs.
In TOLERANT_STITCH mode, the scheme extension will operate only on BODYs or free FACEs. A free FACE is a FACE that is a top-level entity and has no owner. Note that free FACEs are not legal in ACIS, but the scheme extension still accepts them. It is recommended though that the scheme extension be passed only BODYs.

; entity:stitch ; Stitch faces into a single lump body if possible. ; Load a file containing a bad part (part:load "heal1.sat") ;; (#[entity 2 1] #[entity 3 1] #[entity 4 1] ;; #[entity 5 1]) ; Zoom the view in order to see the part (zoom-all) ;; #[view 1076700200] (entity:stitch (part:entities)) ;; #[entity 6 1]

[Top]

entity:stitch-nonmanifold

Action

Performs non-manifold stitching between parting faces and primary bodies.

Filename

scm/scmext/stch/scm_stch_nonmanifold.cpp

APIs

api_body, api_pm_remove_entity, api_stitch_nonmanifold

Syntax

(entity:stitch-nonmanifold list list [stch-opts] [acis-opts])

Arg Types

list	`entity` \| (`entity` ...)
list	`entity` \| (`entity` ...)
stch-opts	`tolerant stitch-options`
acis-opts	`acis-options`

Returns

list body | (body...)

Description
This scheme extension performs non-manifold stitching between entities of one list (parting faces) with entities in the other (primary bodies).

Arguments

list contains only pointers to BODYs or free FACEs. A free FACE is a FACE that is a top-level entity and has no owner. Note that free FACEs are not legal in ACIS, but api_stitch_nonmanifold still accepts them. We recommend that BODYs be passed to this API.

list contains only pointers to BODYs or free FACEs.

stch-opts is an optional argument. stch-opts is a scheme object of a C++ object of class tolerant_stitch_options.
The stch-opts object can be used to set:

the max_stitch tolerance
option of coincident faces clustering
option of allowing void shell

To create stch-opts object of class tolerant_stitch_options, call entity:stch-options with the appropriate arguments.

If stch-opts object is not passed, then entity:stitch-nonmanifold will create an object of class tolerant_stitch_options.

acis-opts contains versioning and journaling information.

;entity: stitch-nonmanifold

; A solid block stitched with a face to form a non-manifold body.
(define primary-body (solid:block (position 0 0 0) (position 10 10 10)))
(define w1 (wire-body(list (edge:linear (position 10 0 0) (position 20 0 0)))))
(define w2 (wire-body(list (edge:linear (position 10 10 0) (position 20 10 0)))))
(define s1 (sheet:skin-wires (list w1 w2)))

(entity:delete (list w1 w2))
(define parting-face (sheet:2d s1))

(define so (entity:stch-options ))
; display stch-options
so
; #[Stch_Options ]
; tolerant_max_stitch_tol                 :   To be computed internally
; Identify_Coincident_Faces               :   Default
; Number of coincident_faces_clusters     :   Default
; Allow_Void_Shells                       :   Default
; do non manifold stitching
(define stch_bodies (entity: stitch-nonmanifold parting-face primary-body so))
(define obj (list-ref stch_bodies 0))
(option:set 'check_level 70)
(entity:check obj)

Figure. Non-manifold Stitching

[Top]

stitch:edges

Action

Attempts to stitch together the given entities.

Filename

scm/scmext/stch/scm_stch_edges.cpp

APIs

api_body, api_stitch, api_separate_body, api_part_start_state, api_part_note_state

Syntax

(stitch:edges list [stch-opts] ["use_old_api"] [acis-opts])

Arg Types

list	`edge` \| (`edge`...)
stch-opts	`stitch-options`
"use_old_api"	`string`
acis-opts	`acis-options`

Returns

body | (body...)

Description
Attempts to stitch together the given entities. stitch:edges works in EDGE_TOLERANT_STITCH mode. In this mode, the list must contain a list of EDGEs and only the EDGEs appearing in the list are chosen as candidates for stitching. The extension will operate only on sheet EDGEs. A sheet EDGE is an edge which is associated with only one FACE and hence has only one COEDGE. Further the top level owner of each given sheet EDGE should either be a free FACE or should be a BODY.

stitch:edges will attempt to stitch edges that are not close within SPAresabs, but are close within the user-specified maximum stitch tolerance and may make certain edges tolerant in this mode whenever needed.

Arguments: list contains the list of edges in the entity list. The list should contain only pointers to sheet EDGEs. A sheet EDGE is an edge which is associated with only one FACE and hence has only one COEDGE. Further the top level owner of each given sheet EDGE should either be a free FACE or should be a BODY.; stch-opts argument is optional. stch-opts is a scheme object of a C++ object of class edge_tolstitch_options. To create "stch-opts" object of class edge_tolstitch_options, the user will need to call the scheme command entity:edg-stch-options with appropriate arguments. For details on this refer to the documentation of entity:edg-stch-options.
The object stch-opts contains the max_stitch_tol parameter, and the option for switching ON/OFF coincident faces clustering. User will need to pass this object into stitch:edges when stitching needs to be done at a user specidied tolerance or when the user needs the coincident-faces information.; "use_old_api" is an optional argument. By default ( "use_old_api" string is not passed), stitch:edges will use the new API introduced in R13 having the following signature:
outcome api_stitch ( const ENTITY_LIST& to_be_stitched, ENTITY_LIST& output_bodies, ENTITY_LIST& new_bodies, stitch_options* sopts, AcisOptions* aopts )
If "use_old_api" string is passed, then stitch:edges will use the deprecated pre-R13 API having the following signature:
outcome api_stitch ( BODY* body ENTITY_LIST & to_be_stitched, stitch_options* sopts, AcisOptions* aopts )
followed by api_separate_body.
The string "use_old_api" recovers the pre-R13 behavior of stitch:edges. Customers passing acis-opts with a version before R13 should also pass the string "use_old_api" into stitch:edges.; acis-opts contain versioning and journaling information.
Limitations: Tolerant stitching can not be used to create non-manifold (i.e. more than 2 coedges per edge) bodies.
All the incoming entities must be checked.
The extension will operate only on sheet EDGEs. A sheet EDGE is an edge which is associated with only one FACE and hence has only one COEDGE. Further the top level owner of each given sheet EDGE should either be a free FACE or should be a BODY.

; stitch:edges ; Stitch edges with the other edges in the list. ; prepare block with unhooked face as example (define b1 (solid:block 0 0 0 10 10 10)) ;; b1 ; grab 1st face in block (define f1 (car (entity:faces b1))) ;; f1 ; get original edges (define e1 (entity:edges f1)) ;; e1 ; Unhook the face (define f2 (entity:faces (face:unhook f1))) ;; f2 ; check that b only has 5 faces (entity:check b1) ;; checked: ;; 1 lumps ;; 1 shells ;; 0 wires ;; 5 faces ;; 5 loops ;; 20 coedges ;; 12 edges ;; 8 vertices ;; () ; get new edges (define e2 (entity:edges f2)) ;; e2 ; setup over - now perform stitch, see the edges to be stitched (define edge_list (append e1 e2)) ;; edge_list ; Store the stitched edges (define b2 (car (stitch:edges edge_list))) ;; b2 ; b now has 6 faces and 12 edges, so is fully stitched (entity:check b2) ;; checked: ;; 1 lumps ;; 1 shells ;; 0 wires ;; 6 faces ;; 6 loops ;; 24 coedges ;; 12 edges ;; 8 vertices ;; ()

[Top]