How to properly use imported FeatureScript in my own FeatureScript

Andrew_Barolet

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. 

Jake_Rosenfeld

Hi @Andrew_Barolet

Once the import is set up, you should be able to reference any symbols from the other Feature Studio that are marked as `export`.

If you choose, you can also add a namespace to your import:

OtherStudio::import(...);

and then reference the symbols using the namespace:

const myFoo = OtherStudio::FOO;

But, normal practice is to just leave the namespace off, and access the symbols as if they were global:

import(...);
...
const myFoo = FOO; // where foo is defined as an exported symbol the imported feature studio

This is the surface text feature studio:
https://cad.onshape.com/documents/cfec40e2b66bb4ddb2f3414b/w/24132f252a02825eb0606641/e/7a70ac021729253c4df9d213

So if you are importing that feature studio you should be able to just call:

surfaceText(context, id + "surfaceText", {
    "baseLine" : ...,
    "surface" : ...,
    ...
});

from inside of your code.

Let us know if this is not working for you.

A side note that may help your mental model:
All the functions you are already using in FeatureScript are coming from that import of `geometry.fs` at the top of the file.  There is nothing special about importing another Feature Studio that is not `geometry.fs`, except that your custom import is not importing from the standard library.

Jake_Rosenfeld

Hi @Andrew_Barolet

Once the import is set up, you should be able to reference any symbols from the other Feature Studio that are marked as `export`.

If you choose, you can also add a namespace to your import:

OtherStudio::import(...);

and then reference the symbols using the namespace:

const myFoo = OtherStudio::FOO;

But, normal practice is to just leave the namespace off, and access the symbols as if they were global:

import(...);
...
const myFoo = FOO; // where foo is defined as an exported symbol the imported feature studio

This is the surface text feature studio:
https://cad.onshape.com/documents/cfec40e2b66bb4ddb2f3414b/w/24132f252a02825eb0606641/e/7a70ac021729253c4df9d213

So if you are importing that feature studio you should be able to just call:

surfaceText(context, id + "surfaceText", {
    "baseLine" : ...,
    "surface" : ...,
    ...
});

from inside of your code.

Let us know if this is not working for you.

A side note that may help your mental model:
All the functions you are already using in FeatureScript are coming from that import of `geometry.fs` at the top of the file.  There is nothing special about importing another Feature Studio that is not `geometry.fs`, except that your custom import is not importing from the standard library.

owen_sparks

@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.

Jake_Rosenfeld

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!

Andrew_Barolet

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_Rosenfeld

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!

MBartlett21

Jake_Rosenfeld said:

[...]
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

ilya_baran

@MBartlett21
In that case, you can make a part studio with the feature, and extract the parameters and types from the generated source.

Jake_Rosenfeld

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.

nir_naron

Jake_Rosenfeld said:

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?