ACIS Architecture

[#1]

One of the pieces of feedback I heard from the European Forum last month was that a lot of customers had questions about “The Four Reses” – SPAresabs, SPAresfit, SPAresnor, and SPAresmch.  (I’ll be leaving the “SPA” out below.)  The two big questions seem to be

1. What do they mean?
2. What do I need to worry about when changing them?

Question #2 breaks down into

    2a. "Permanent" changes, by which I mean choosing values for a particular model and sticking with them

    2b. "Temporary" changes, by which I mean temporarily changing the values while performing a modeling operation (such as a Boolean) on a body

I'll give you my quick opinion on question #2 right away - you're better off leaving these values at their defaults, since ACIS is almost certainly most robust at the default values.  The long version follows.

But first, let’s deal with question #1 – What do all these tolerances mean? (Further explanation can be found in the “Tolerance Variables and Units” section of online help.)

resabs – this is the primary tolerance value in ACIS, otherwise known as the “modeler resolution”.  If two points A and B are separated by a distance less than resabs, then the answer ACIS gives to the question “are these two points coincident” is “yes”.

The most important thing to know about resabs is that it should be much smaller (something like 1000x) than any distance that is important to the end user.  If the end user’s manufacturing process requires models with precisions of 0.1 mm, then a good choice for the resabs  is at most 1.e-4 mm; if resabs is 1.e-6 in model units (the default), then this would correspond to a choice of units of 100 mm per model unit.  If the application is using default resabs (1.e-6) with units of 1 mm per model unit (so resabs is 1.e-6 mm) this is still ok; the important customer scales are 100,000 times larger than resabs.  The default value of resabs (1.e-6) with model units of 1 meter, however, is beginning to approach the risky regime – important scales are only 100 times resabs in this case.

resfit – ACIS maintains an internal B-Spline approximation for most of its geometry.  These approximations are then used by internal algorithms.  Resfit is the parameter that controls how accurate this approximation is.  By default, resfit is 1000x resabs.  This value is intended to trade off between the performance and memory costs of very precise approximations and the accuracy of the approximation.  It also takes account of the concept expressed above – that important distances should be much bigger than resabs, which means that an approximation that is much looser than resabs should still capture all the important geometric information in a curve or surface.  It can be argued that resfit shouldn’t be exposed to client code (customers), since it’s controlling internal approximations.

resnor- this fills two related roles: it is the modeler’s angular resolution (the smallest angular difference that is significant to the modeler) and it represents the dynamic range of the model – the ratio between the largest allowed position and the modeler resolution (resabs).  The reason these two are related is trigonometry; the angular resolution of the modeler corresponds to the angle subtended by a line of length resabs when viewed at the maximum distance allowed by the modeler.  This angle is just the ratio of the two length scales.

resmch – this is intended to be a dimensionless number associated with the inaccuracy induced by floating point arithmetic.  In other words it’s intended to be the relative tolerance used when comparing two floating point numbers.  In practice, it is often used as an absolute tolerance for distances much smaller than resabs, which means that ACIS will loose robustness if resabs is changed too far from its default value.

And now for question #2 - "Should I change tolerances?"  The bottom line is that changing any of the parameters away from their defaults will probably lead to lower ACIS robustness, but there are varying degrees of risk.  I’ve roughly ordered the Q&A below from what I consider the most risky changes to the least risky:

“Should I ever change resnor or resmch?” – NO!!!!!  Both of these are intended to be dimensionless values tied to the dynamic range of 64-bit floating point numbers.  Even though they’re exposed out as non-const, they shouldn’t be changed.

“When should I change resfit?” – Only when you’re changing resabs (but see below).  Resfit is the accuracy attempted when approximating geometry; like resabs it is a distance. By default, resfit is 1000 times larger than resabs; it’s probably best to keep it in the 100x to 1000x range.  It’s especially risky to push resabs bigger than resfit.

“Should I temporarily change resabs?” – This is probably not a good idea, especially now that we’ve introduced fuzzy Booleans.  We do it internally, but it’s a kludge that ACIS wasn’t really designed for and we’re trying to move away from it in favor of tolerant intersections.  The problem for customers trying to temporarily change resabs is that there are subtle corruptions that can go into the model when resabs is temporarily changed – it would be very difficult for a customer to correct all of these.  Note that by “temporarily”, I mean performing an operation on a body at a resabs other than that used to generate the body.

If any of you feel you need to change resabs temporarily in your applications as a workaround for some problem, please let us know - there's probably an enhancement to ACIS hiding there that would make us more robust against dirty data.

“Should I permanently change resabs” – This is the least risky of the changes – you can probably get away with taking it down to 1.e-8 or up to 1.e-4 (with appropriate scaling of resfit, of course).  That being said, you should consider the following:

1)      If resabs is set to 1.e-30, ACIS will break

2)      If resabs is set to 1.e+30, ACIS will break

3)      ACIS is most heavily exercised (both within Spatial and by customers) with The Four Reses at their default values.

In a perfect world, all numbers within the ACIS code which represent distances would be multiplied by the appropriate factor of resabs/1.e-6.  In reality, “magic numbers” have crept in which assume that resabs is O(1.e-6), models sizes are O(1),  and parametric velocities are O(1).  The fact that ACIS is mostly run with The Four Reses at their default values means that is the “sweet spot” for ACIS robustness.  Rather than change resabs, it is better to leave it at its default value of 1.e-6 and adjust the model units so that the smallest distance the end user cares about is roughly 1.e-3 (1000*resabs)  in model units.

PS - My initial version of this post had an in-depth explanation of why it's so important that resabs be tiny compared to user distances - it's basically a separation of scales argument that involving the non-intuitive things that happen at the resabs scale ("are coincident" is not a transitive operator).  If enough people want to hear it, I'll polish it up and post it.

[#2]

Among these, what is the tolerance used for the parametric space? Assuming 1D, sometimes the parameter returned by acis is slightly off the parametric range of the edge. How much can it be off by? If the curve is periodic, and the returned parameter is several periods away, how would that affect the tolerance?

[#3]

That's a great question!! In principle, it's about 1.e-4*resabs. In practice, the internal ACIS code compares parameter values using either resnor or resmch (this is what I meant when I said "it is often used as an absolute tolerance for distances much smaller than resabs" in the resmch discussion). To say it a different way, if two parameter values are separated by more than 1.e-10, they will generally be classified as "distinct". If the separation is 1.e-11, they will usually be classified as "coincident". For intermediate values, the classification will vary in different parts of the code.

The reason this is such a good question is because it brings up something I didn't discuss in the article, which is separation of scales. Essentially, you want the granularity at which your geometry objects (such as curves) stop behaving like mathematical functions on the real numbers (let's call this length scale "respar") to be a much smaller than the granularity of your geometric objects (resabs), in the same way that resabs should be much smaller than any distance that's important to the user. Choosing a dynamic range of 1.e+10 between the maximum allowed position and resabs allows us to separate the resabs and respar scales by a factor of 1.e+4 and still have a respar be a couple of orders of magnitude bigger than floating point noise.

Just to be clear - there is no "respar" variable in ACIS. It's just a name I'm attaching to the length scale at which parameter values are considered to be different. Note that I've also glossed over the effects of parametric velocities here.

[#4]

Nice explaination of the Four Reses