Welcome to the Onshape forum! Ask questions and join in the discussions about everything Onshape.

First time visiting? Here are some places to start:
  1. Looking for a certain topic? Check out the categories filter or use Search (upper right).
  2. Need support? Ask a question to our Community Support category.
  3. Please submit support tickets for bugs but you can request improvements in the Product Feedback category.
  4. Be respectful, on topic and if you see a problem, Flag it.

If you would like to contact our Community Manager personally, feel free to send a private message or an email.

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

dave_cowdendave_cowden Member, Developers Posts: 465 ✭✭✭
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 ){

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!


Best Answer


  • kevin_o_toole_1kevin_o_toole_1 Onshape Employees, Developers, HDM Posts: 552
    edited January 2016
    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 :frowning:)

    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)

    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_cowdendave_cowden Member, Developers Posts: 465 ✭✭✭
    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! 

  • dave_cowdendave_cowden Member, Developers Posts: 465 ✭✭✭
    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.

Sign In or Register to comment.