Real vs ValueInput

[hpekristiansen]

When and why is a real used instead of a ValueInput object?

To create a simple extrusion(http://help.autodesk.com/view/fusion360/ENU/?guid=GUID-0F875632-0DCB-4F18-9176-9617783AE794), the distance is given by a ValueInput object (https://help.autodesk.com/view/fusion360/ENU/?guid=GUID-bdeb52e0-a6af-4909-93e8-3b13acd0e39c) :

extrudes.addSimple(profile, adsk.core.ValueInput.createByReal(5), adsk.fusion.FeatureOperations.NewBodyFeatureOperation)        

To add a circle(http://help.autodesk.com/view/fusion360/ENU/?guid=GUID-f52e70b8-4566-4944-9e57-be4f13f59e0e), the radius is given by a real:

sketchCircles.addByCenterRadius(adsk.core.Point3D.create(0, 0, 0), 5.0)

Why is that? Does one not need the benefits from the ValueInput object here?

[BrianEkins]

The reason you see a difference in the input is because of a difference in what Fusion is creating.  In the case of creating an extrusion and defining the extrude length of the extrude, the value you enter becomes the value of a parameter.  That value can be a simple number but can also be more complex.  For example, you can enter "5", "3 + 2", "Length", "Length / 2", "Length * sin(45)" and many more.  Whatever you type in, as long as Fusion can use it to define a length, becomes the value of the newly created parameter.

Even entering a simple value like "5" isn't so simple.  When you enter a number, what are the unit?  5 of what?  If you don't specify the units then Fusion assumes it's 5 of whatever the default units are for the document.  But even if the document is inches I can enter "5 cm" and override that.

When using the UI and entering values, you're essentially always entering a string, even when it's simple like "5" and then Fusion is interpreting that.  When using the API, that would be the equivalent of always using the createByString method of the ValueInput object.  However, that's not always the best when using the API because you're computing precise values using floating point numbers and would like to provide those directly rather than concoct an equivalent string.  That's why the API also supports createByReal method so you can pass in a precise number and use it directly.  In this case, it is always in centimeters.  Fusion will still create a parameter but its value will be the precise value you provided.

When you sketch a circle, there isn't a parameter created and Fusion just needs the size of the circle.  Internally, Fusion uses centimeters for all lengths so that's also what the API uses.  So, specifying a floating point number for the size of a circle is defining the radius in centimeters, regardless of the document default units.

[hpekristiansen]

Thank you - Your summary of the API units and the benefits of a ValueInput object is very good, but I already knew that. I did not consider, that creating an extrusion also creates a parameter - that explains a lot, but I am still confused.

If I want to create a circle with a radius of 2 inches in the API, is my only option to do the conversion by hand?

A naive thing like this does not work, as the object is created by a string:

#not legal code
radius = adsk.core.ValueInput.createByString("5 in").realValue

I do not fully understand why wherever a 'ValueInput object created by a real' is expected, the function does not also accept a real real 🙂 . Like this:

#Legal code 
extrudes.addSimple(profile, adsk.core.ValueInput.createByReal(5), adsk.fusion.FeatureOperations.NewBodyFeatureOperation)

#Not legal code 
extrudes.addSimple(profile, 5.0, adsk.fusion.FeatureOperations.NewBodyFeatureOperation) 

The function could be overloaded, and realize the real input by creating the ValueInput object itself!?

[BrianEkins · Accepted solution]

It does come down to whether the value being provided will be used to create a parameter or not.  If it is, then a ValueInput is needed to support the input of either a value or a string.  Ideally, we would have used overloaded functions but unfortunately, that wasn't possible.  The API is implemented internally in C++ and then that API is wrapped to support Python.  C++ supports true overloading by letting you create functions with the same name but differ in argument types and at compile time the compiler decides which of the two functions should be called.  Python doesn't support this type of overloading so it can't be simply wrapped.  The alternative was to create a new class type that can act as either a floating-point number or a string and pass that into the single function.