How would i find out what the properties of a face are?

dave_cowden

Hi, everyone!

I'm very new to FS, I apologize in advice is this question is dumb.

I have had no problem creating a basic feature, and I've learned the basics of parameters.  

Suppose I have a feature in which the user selects a Face,  like this:

        annotation { "Name" : "Target Face", "Filter" : EntityType.FACE, "MaxNumberOfPicks" : 1 }
        definition.targetFace is Query;

Now, I'd like to compute a point at represents the geometric center of the face.  So i started with this code:

        for ( var theFace in evaluateQuery(context, definition.targetFace ){
            theFace.<what>   
        }

But now I'm stuck on several levels:

   (1) i have no idea what properties or methods are available on this object.. No intellisense help in the IDE.

   (2) i cannot seem to find any reference documentation to tell me

   (3) I cannot find any functions for center computations.

  (4) i found the debug libraries, but according to the documentation here ( https://cad.onshape.com/FsDoc/library.html#module-debug.fs), it doesn't appear that throwing a face reference in there would work.

In short, i feel like i must be missing some set of documentation other than FsDoc that describes the 'core' api. Where might I find that? 

Regards, and thanks!

Dave

kevin_o_toole_1

Just to be clear: evFaceTangentPlane (along with other parameter-based evaluations) uses a bounding box of the surface in parameter space. For non-planar surfaces, this makes a bounding box around a version of the surface that's been flattened and stretched down to two dimensions, then finds the center, then unflattens and unstretches.

The Plane type's documentation is in surfaceGeometry. Soon, all mentions of types and enums in the library docs will have hyperlinks to the documentation for that type. In the meantime, you can search the doc page for e.g. "Plane type" or "EntityType enum".

For debugging, you can use "debug" to show the plane in red in the Part Studio. Perhaps more usefully, you can use "println(Plane)", which will (I think) give you a list of the fields contained in a Plane.

On the "starting programmer's perspective" question:
One thing we have planned is a "FeatureScript cookbook": a set of Onshape documents with FS features that do one or a few simple things. So, for your question, we might have a module for planar faces which just prints out information you can evaluate from that face, and debugs the result of some queries that use a face. Then another module for general surfaces, another for distance evaluation, another for walking through topological adjacencies, etc. To see the code that produces the results, you'd then look at the Feature Studio in that document to see what functions are used. Would this address the need you bring up?

kevin_o_toole_1

Hi Dave!

We're glad to see you using FeatureScript and looking through the documentation for answers.

The point of confusion you're hitting is one we suspect a lot of others will hit as well: In FeatureScript, there are two completely separate ways of representing geometry:

1. Queries are lightweight objects which specify criteria for finding a particular entity or set of entities in the part studio. These are just specifications, and they contain no information about the geometric or topological properties of those entities.
2. Geometric objects, like Vectors, Planes, CoordSytems, and more, contain data about positions and orientations. These are just data, and are not contextually associated with any entities in the Part Studio.

To create a language that is capable of expressing fully parametric modeling, this is a necessary and useful distinction to maintain. We do agree that, from a programmer's perspective, this additional layer of abstraction takes some time to fully come to terms with. As you said, you can't just say query.thePointINeed, since queries don't directly know anything about the geometry they specify (and they don't specify anything without a Context)

To get geometric information from a query, use an evaluate function. These functions can be found in the evaluate module. For instance, if I have a query myVertex that refers to one vertex, I would call evVertexPoint(context, {"vertex": myVertex}) to get a Vector with the 3D location of that point.

Sidebar: It is admittedly tempting to think that evaluateQuery() would return geometric objects, but it actually returns a list of Queries. evaluateQuery() is for separating a query into individual, transient Queries (each of which refer to one entity). In your case (and, in fact, in many cases), evaulateQuery() is unnecessary: theFace and defintion.targetFace could both be passed into evaluate functions with the same results.



For finding a "geometric center", there's another issue: How do you define the "center" of a face? For planar circles and rectangles, the answer seems obvious, but where is the center of a cylindrical face? Or a surface like this or this?

If you're looking for the center of mass (which won't necessarily be on the face), there should and could be an evaluation function like evCenterOfMass (but there currently isn't )

However, one thing an Onshape surface will always have is a parameterization, which defines an equation that maps a 2D unit square onto any given surface. This unit square is defined from [0, 0] to [1, 1] (in unitless parameter space), so to get the center of the surface's parameterization, you could say:

var centerPoint = evFaceTangentPlane(context, {
        "face" : definition.targetFace,
        "parameter" : vector(0.5, 0.5)
}).origin

For the reasons discussed above, the concept of "center" here is necessarily somewhat arbitrary, but this should at least return the obvious thing in trivial cases.

In general, though, relying on the parameterization can give unexpected results for the end user. Perhaps the better question is: What behavior you trying to achieve? Are there perhaps a better set of inputs that define that geometry?

dave_cowden

Ah ok thank you for the clarification. Yep, your code sample is what i'd expect. the two reasonable definitions for 'center' would be the bounding box and the center of mass-- I can see from the docs that your code sample is bounding box based.

I understand the philosophy of need to separate the queries from the underlying objects.  

From a 'starting programmers' perspective, it would help a lot if you had a document that sort of 'cross-references' the evaluate functions from the query direction. IE: given a query that has selected a certain type of entity-- EntityType.FACE -- then what are my options in terms of evaluate functions? It is pretty hard to make that leap, even after I understand the abstractions.  As an OO programmer, I expected to be able to access properties and methods.  You have exposed a set of functions instead, which I use to get that same information-- the evaluate functions.  I understand the rationale-- but it is hard to find all of the functions that help me extract the info i need. As an example: with your help, i know that i can use evaluate functions to get various geometric constructs from a Face. But what else can I do with a Face? it appears that i can move it or delete it ( moveFace and deleteFace or opOffsetFace).

Another question that presented itself : where is the documentation of the Plane object? I searched in FSdoc and couldnt find its definition. IE, once i have the return value of evFaceTangentPlane, ( type Plane), i cannot find what i can do with that object. I'd expect to be able to get its normal vector, eg.  Then perhaps i want to offset it and make another offset Plane-- does the plane object have methods on it, or are there functions to move those around? 
or, will debug(plane) print out what properties and/or methods a Plane has on it?

Before i can write any useful code, i definitely need to learn a lot more about the basic constructs and assumptions of the FS system. The difference in the language itself is also something I need to learn as well. 

Thanks for the help! 

kevin_o_toole_1

Just to be clear: evFaceTangentPlane (along with other parameter-based evaluations) uses a bounding box of the surface in parameter space. For non-planar surfaces, this makes a bounding box around a version of the surface that's been flattened and stretched down to two dimensions, then finds the center, then unflattens and unstretches.

The Plane type's documentation is in surfaceGeometry. Soon, all mentions of types and enums in the library docs will have hyperlinks to the documentation for that type. In the meantime, you can search the doc page for e.g. "Plane type" or "EntityType enum".

For debugging, you can use "debug" to show the plane in red in the Part Studio. Perhaps more usefully, you can use "println(Plane)", which will (I think) give you a list of the fields contained in a Plane.

On the "starting programmer's perspective" question:
One thing we have planned is a "FeatureScript cookbook": a set of Onshape documents with FS features that do one or a few simple things. So, for your question, we might have a module for planar faces which just prints out information you can evaluate from that face, and debugs the result of some queries that use a face. Then another module for general surfaces, another for distance evaluation, another for walking through topological adjacencies, etc. To see the code that produces the results, you'd then look at the Feature Studio in that document to see what functions are used. Would this address the need you bring up?

dave_cowden

Yes, i think a cookbook would help. I think no matter how they materialize, examples are incredibly valuable.  The documentation improvements you describe would be a big help too.

I'm still learning.  FS has a particularly difficult learning curve: its is a new language, a new documentation structure, and a new set of concepts. Its quite a bit less approachable at this point than many other apis and systems I have worked with. A lot of examples, documentation, and training is required to simultaneously absorb all that's necessary.