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 to properly use imported FeatureScript in my own FeatureScript

Andrew_BaroletAndrew_Barolet Member Posts: 5
I'm just starting to learn FeatureScript and have been able to use it in creating some simple geometry. Now I want to add in functionality of other FeatureScripts and have tried following the information in the imports section of the documentation.

The FeatureScript I am trying to use is [Feature] Surface Text, and I would like to know how to properly initialize its preconditions or access the variables of the FeatureScript. 

Best Answer

Answers

  • owen_sparksowen_sparks Member, Developers Posts: 2,660 PRO
    edited February 2020
    @Jake_Rosenfeld
    These comments are worth their weight in gold.
    Is there any chance you could take a few days vacation from your normal role and just write a bunch of this stuff down?!

    I bet there is a ton of stuff you take for granted with FS that the average punter doesn't have a clue that it even exists.

    It wouldn't need to be a polished tutorial, just a bunch of paragraphs of ideas, recommendations, pitfalls, explanations of what does what and why etc. Anything that brings FS to a wider audience has got to be a good thing.
    Owen S.
    Business Systems and Configuration Controller
    HWM-Water Ltd
  • Jake_RosenfeldJake_Rosenfeld Moderator, Onshape Employees, Developers Posts: 1,646
    Would that I could... I appreciate the sentiment though :) 

    Often with that sort of thing the trouble is knowing what people are wondering about, so the more questions asked here the more knowledge I can dole out!

    Jake Rosenfeld - Modeling Team
  • Andrew_BaroletAndrew_Barolet Member Posts: 5
    Hi @Jake_Rosenfeld ,

    Thanks for the help, that was definitely clearer and showed me that I was importing the other FeatureStudio incorrectly.

    As a followup to this question, how should I know which function definitions I need to define when I call the surfaceText function in my FeatureScript. 

    As an example, earlier I was trying to figure out how to use the revolve function, vs opRevolve, in an effort to make a symmetric revolve with an angle (still not sure how to do this). For both the revolve function and the sketchText function, how can I figure out what exactly to define when I call the function. In both cases I have gone through the associated FeatureScript but have been able to call the function with a proper definition.

    Let me know if the question is too vague.

  • Jake_RosenfeldJake_Rosenfeld Moderator, Onshape Employees, Developers Posts: 1,646
    edited February 2020
    Hi @Andrew_Barolet !

    The best way find the parameters for built-in Onshape standard library functions is by reading the documentation:
    https://cad.onshape.com/FsDoc/library.html#opRevolve-Context-Id-map

    For a revolve as you have described, it seems you would do:
    opRevolve(context, id + "revolve", {
        "entities" : ...,
        "axis" : ...,
        "angleForward" : yourAngle,
        "angleBack" : -yourAngle
    });

    As for revolve vs opRevolve, "revolve" is the Onshape feature.  It is what you are interacting with when you are actually using the revolve tool in an Onshape part studio.  "opRevolve" is the low-level operation that powers the revolve feature.  "opRevolve" (and other similar "op" functions) are designed to be powerful FeatureScript functions for manipulating geometry.  The Onshape features are designed for UI interaction, and are usually undocumented, and hard to use from inside of FeatureScript.  It would always be recommended to use the "op" function over an Onshape feature.



    For non-Onshape or undocumented Onshape calls that have a "precondition" there are a few ways to check what you should be passing into them.  The first that comes to mind is just reading the precondition.  It will list out the fields you need to pass in, and in what cases they are needed.  Taking an except from surface text:
            annotation { "Name" : "BaseLine","Filter" : EntityType.EDGE, "MaxNumberOfPicks" : 1 }
            definition.baseLine is Query;
    
            annotation { "Name" : "Base Surface","Filter" : EntityType.FACE ,  "MaxNumberOfPicks" : 1}
            definition.surface is Query;
    
            annotation { "Name" : "Text Align", "Default": Alignment.JUSTIFY, "UIHint": "SHOW_LABEL" }
            definition.alignment is Alignment;
            
            if ( definition.alignment != Alignment.JUSTIFY ){
                annotation { "Name" : "Text Height" }
                isLength(definition.height, TEXT_HEIGHT_BOUNDS);                          
            }
    You must pass in a "baseLine", it should be a Query for an edge.  You must pass in a "surface", it should be a face.  You must pass in an "alignment", it should be an Alignment (which seems to be an enum defined in a different imported file).  If "alignment" is not set to "JUSTIFY", you must pass in a "height", which is a length.  A call with these parameters would look like:
    surfaceText(context, id + "st", {
        "baseLine" : baseLineQuery,
        "surface" : surfaceQuery,
        "alignment" : Alignment.LEFT,
        "height" : 1 * inch,
        ...
    });
    I got the values of Alignment by hovering with my mouse:





    The other way figure out the parameters is a bit more trial-and-error.  Instead of trying to read the precondition, you can just start with an empty map, and see what the program asks you for.  So if I start off with code like this:
    surfaceText(context, id + "st", {});
    I can open up the FeatureScript console (the "{!}" button at the top right of the Onshape window), add my feature to a part studio, and see what it complains its missing:

    Here we see that it is complaining that the precondition failed because it was expecting to find that "definition.baseLine" was a Query, but it was not. Once I go and set definition.baseLine to a query, I will probably get another failure saying "definition.surface is Query", which means it was expecting that definition.surface was a Query, but it did not find a query with that key in the map.  And you just keep going like this until all the required fields are filled out.

    Hope that helps!
    Jake Rosenfeld - Modeling Team
  • MBartlett21MBartlett21 Member, OS Professional, Developers Posts: 2,034 EDU
    [...]
    The other way figure out the parameters is a bit more trial-and-error.  Instead of trying to read the precondition, you can just start with an empty map, and see what the program asks you for.  So if I start off with code like this:
    surfaceText(context, id + "st", {});
    I can open up the FeatureScript console (the "{!}" button at the top right of the Onshape window), add my feature to a part studio, and see what it complains its missing:

    Here we see that it is complaining that the precondition failed because it was expecting to find that "definition.baseLine" was a Query, but it was not. Once I go and set definition.baseLine to a query, I will probably get another failure saying "definition.surface is Query", which means it was expecting that definition.surface was a Query, but it did not find a query with that key in the map.  And you just keep going like this until all the required fields are filled out.

    Hope that helps!

    @Jake_Rosenfeld
    This does not work for nested preconditions, such as some of @dave_cowden 's other FeatureScripts, whose whole precondition is somePrecondition(definition);
    It then just says that somePrecondition failed
    mb - draftsman - also FS author: View FeatureScripts
    IR for AS/NZS 1100
  • ilya_baranilya_baran Onshape Employees, Developers, HDM Posts: 1,173
    @MBartlett21
    In that case, you can make a part studio with the feature, and extract the parameters and types from the generated source.
    Ilya Baran \ VP, Architecture and FeatureScript \ Onshape Inc
  • Jake_RosenfeldJake_Rosenfeld Moderator, Onshape Employees, Developers Posts: 1,646
    Also, I think that the nested precondition should show a full stack trace now, so that you can dig back and see the original failure.  @kevin_o_toole_1
    did that work a few months ago, but maybe it doesn't work in this case.
    Jake Rosenfeld - Modeling Team
  • nir_naronnir_naron Member Posts: 16 EDU

    As for revolve vs opRevolve, "revolve" is the Onshape feature.  It is what you are interacting with when you are actually using the revolve tool in an Onshape part studio.  "opRevolve" is the low-level operation that powers the revolve feature.  "opRevolve" (and other similar "op" functions) are designed to be powerful FeatureScript functions for manipulating geometry.  The Onshape features are designed for UI interaction, and are usually undocumented, and hard to use from inside of FeatureScript.  It would always be recommended to use the "op" function over an Onshape feature.
    Is this stil the case? I'm having a hard time wrapping my head around it.

    I'm trying to work with the Helix feature. I have managed to code a script that produces a circle where I want it, and if I could just feed that circle into the Helix feature (and provide a Helix hight) I would be pretty much done. Trying to work with opHelix is much more complicated.

    Seeing I am able to import the feature, why can't I implement it?


Sign In or Register to comment.