FreeCAD-Spring testing

[grumpyinca]

This issue is intended to capture test results associated with development efforts on FreeCAD-Spring. The initial (July 27) set of comments have been transferred from ODOP issue #1083.

[grumpyinca]

Transferred from Slack conversation of May 9, 2026 9:03am Pacific (avoid aging off)

I pulled the latest FreeCAD-Spring, did the build & install and ran a bunch of tests. My stress-test inputs triggered a variety of errors messages to appear in the user interface. This is a definite step forward. As you remarked, perhaps the wording on a few of those could be improved. A few more checks remain to be implemented. When it comes to rendering with artifacts, PigtailClosed&Ground seems to be the most sensitive end type.

We should talk about clearing the rendering (or perhaps substituting some sort of "Work in progress" or "Look at xxx for messages" notice) before starting the process of generating a new one. This would prevent the current situation where after an error, the error message clears and the rendered image appearing on-screen does not match the parameters showing in the Data panel.

On Friday afternoon, I just noticed that a PigtailClosed&Ground spring with default parameters (Coils_T = 10, L_Free=80, OD_Free=28, Wire_Dia=2.8) renders with one ground end and one closed end, not ground. Changing Coils_T to 6 gets both ends properly ground with all tested values of L_Free and Wire_Dia.

A PigtailClosed&Ground spring with parameters: Coils_T = 2.95, L_Free=60, OD_Free=28, Wire_Dia=2.8 renders properly. Changing Coils_T to 2.94 causes no rendering to appear and no error messages.

Depending on end type, Spring_Index = 2.0 (example: Coils_T=10, L_Free=60, OD_Free=8.4, Wire_Dia=2.8) will render correctly (open, Open&Ground) or with an artifact (most other types). No message.

The message:
"CompressionSpring: Computed middle helix coil count must be positive"
May be unnecessarily conservative. The transition coils mean that FreeCAD-Spring will not render compression springs with less than or equal to one active coil. ODOP just produces a warning level alert when active coils are strictly less than one.

[grumpyinca]

Initially render a spring boundary

Consider a feature that initially renders a simple boundary for the spring before being replaced by the full detail. This approach may mitigate the human factors of long render times of springs with a large number of coils.

It may also mitigate the "stale" rendered image that is left on-screen after a numeric error or out-of-bounds set of inputs.

FreeCAD-style validation and invalid-state display

• Change Free Length, Outside Diameter, and Wire Diameter from App::PropertyFloat to App::PropertyLength.

  • Provides unit-aware editing.
  • Prevents persistent negative values.
  • Zero is still allowed, so semantic validation remains necessary.
  • Existing saved springs will require property-type migration.
  • Convert length quantities to millimetre floats at the calculation/C++ boundary.

• Continue validating spring-specific rules:

  • Wire diameter must be greater than zero.
  • Outside diameter must be greater than two wire diameters.
  • Free length must be greater than wire diameter.
  • Other geometry and manufacturing constraints remain semantic checks.

• FreeCAD normally preserves the last valid shape after recomputation fails and adds a red error badge in the Model tree. This creates a stale display, where the visible geometry does not match the current invalid parameters.

• A possible Spring-specific improvement is to hide the stale shape and display a translucent red wireframe representing the nominal coil envelope.

  • Implement this in the ViewProvider using Coin3D nodes such as SoMaterial and SoCylinder.
  • Do not assign the diagnostic cylinder to obj.Shape, because exports and downstream operations would treat it as real geometry.
  • Remove the diagnostic envelope after a successful recompute.
  • This is more likely to be accepted as an optional Spring-specific diagnostic than as replacement geometry or global FreeCAD behavior.

• Coil count is a dimensionless quantity.

  • App::PropertyQuantityConstraint is conceptually correct and is used by FreeCAD C++ features for values such as rotations.
  • Python FeaturePython objects cannot conveniently configure its constraints.
  • App::PropertyFloatConstraint is therefore the practical choice for the current Python implementation.
  • Its constraint tuple is (value, minimum, maximum, step).
  • The step controls spinner increments only; it does not quantize typed input. For example, a step of 0.1 still permits 0.05.
  • Required coil increments must be enforced separately through semantic validation.

[grumpyinca]

Summary of testing of early July changes in FreeCAD-Spring.

1. Confirmed that PigtailClosed&Ground with default parameters (Coils_T = 10, L_Free=80, OD_Free=28, Wire_Dia=2.8) renders with both ends rendered properly. Previously it rendered with one end ground and one end not ground. Now both ends are shown with ground ends. There is no issue, this is just to confirm that a previously failing case was successful.
2. Confirmed that all end types render properly with Coils_T=6.5 (a non-integer number of coils) and other independent variables at their defaults. There is no issue, this is just to confirm that a previously untested case was successful.
3. With Coils_T=5.5 (<5.97) DoubleClosed (Coils_A=1.5?) produces:

 pyException: Traceback (most recent call last):
  File "/home/mike/git/FreeCAD/build/debug/Mod/Spring/Features/Compression/Spring.py", line 176, in execute
    spring = springocct.compression_spring_solid(
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
<class 'RuntimeError'>: compression_spring_solid std::exception: Produced an invalid final shape: shapeType=2 solids=1 volume=2809.54 bbox=(-22.5714,-22.0051,-1.2585 -> 24.2271,22.0117,81.3116) 

With Coils_T=5.5 (<6.04) DoubleClosed&Ground (Coils_A=1.5?) produces:

  pyException: Traceback (most recent call last):
  File "/home/mike/git/FreeCAD/build/debug/Mod/Spring/Features/Compression/Spring.py", line 176, in execute
    spring = springocct.compression_spring_solid(
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
<class 'RuntimeError'>: compression_spring_solid std::exception: Produced a final shape with unusable bounding box: shapeType=0 solids=0 volume=0 bbox=void 

4. With Coils_T=4.5 DoubleClosed and DoubleClosed&Ground produce:

  File "/home/mike/git/FreeCAD/build/debug/Mod/Spring/Features/Compression/Spring.py", line 176, in execute
    spring = springocct.compression_spring_solid(
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
<class 'RuntimeError'>: compression_spring_solid std::exception: Computed middle helix coil count must be positive

See the last paragraph of the June 7 comment (captured from Slack May 9 original).

5. With default parameters except L_Free=60 and Coils_T=2.95: Open and Open&Ground succeed.
   Closed, Closed&Ground, TaperedClosed and TaperedClosed&Ground produce the "Computed middle helix coil count must be positive" message above.
   DoubleClosed and DoubleClosed&Ground produce:

  pyException: Traceback (most recent call last):
  File "/home/mike/git/FreeCAD/build/debug/Mod/Spring/Features/Compression/Spring.py", line 174, in execute
    CoreUtils.raise_for_alert_errors(obj)
  File "/home/mike/git/FreeCAD/build/debug/Mod/Spring/Features/Utils.py", line 169, in raise_for_alert_errors
    raise ValueError("; ".join(errors))
<class 'ValueError'>: Inactive coils must be between zero and total coils. 

With L_Free=60 and Coils_T=2.95 PigtailClosed and PigtailClosed&Ground produce:
<class 'RuntimeError'>: compression_spring_solid std::exception: Produced an invalid final shape: shapeType=2 solids=1 volume=1063.1 bbox=(-18.715,-15.9657,-1.26016 -> 12.0393,16.6502,61.2555)

With L_Free=30 and Coils_T=2.95 PigtailClosed & PigtailClosed&Ground succeed.

6. Confirmed that Spring_Index = 2.0 (example: Coils_T=10, L_Free=60, OD_Free=8.4, Wire_Dia=2.8) renders correctly for all end types except PigtailClosed and PigtailClosed&Ground which explicitly require Spring_Index>4.

7. Confirmed that all end types render properly with Coils_T=200. The time to render 200 coils on my VM was somewhat variable, but never greater than ~10 seconds.

[grumpyinca]

UserSpecified, Hide/remove variables

Is this the right time to reopen conversation about UserSpecified ? See Feb 22 entry above. I propose a single entry (as opposed to the current four) that has Grind Amount and Taper Amount open for user input.

Is this the right time to reopen conversation about hiding variables in the FreeCAD-Spring UI ? I believe that we once spoke of hiding everything related to Force, Stress, Factor of Safety, Materials/Material Properties, Rate, Cycle Life, Stroke, Energy, etc. This would leave only geometry related stuff including Total/Active/Inactive coils, Inside/Mean/Outside diameters (at free), Wire diameter, Spring Index, Slenderness, Free/Solid Lengths, Pitch (at free), Taper/Grind amount, etc. Helix angle (from Report2) is a possible addition.

[grumpyinca]

L_Solid calculation for the PigTail end types (part 1; End Type=PigtailClosed)

These images illustrate my concern about the L_Solid calculation for the PigTail end types.

The Spring is End Type=PigtailClosed, Coils Total=6, Length At Free=19.6 with the usual Outside Diameter At Free=28 and Wire Diameter=2.8. It calculates (I believe incorrectly) Length at Solid=19.6. The Cylinder is Height=19.6. By visual inspection of the image, the spring is nowhere near the solid condition. I am not able to either reduce the Length At Free or increase the Coils Total because I get the message "Free length must not be less than solid length."

When using End Type=UserSpecifiedClosed and setting Coils Inactive to a value of zero, I get the message:
"CompressionSpring: compression_spring_solid std::exception: Closed-style spring ends require at least 2 inactive coil"

[grumpyinca]

How to handle US Customary units?

[grumpyinca]

Summary of testing of mid-July changes in FreeCAD-Spring.

Many of the previous corner-case failures are now fixed; no error message and a plausible spring is rendered.

However, there remains further edge cases to be considered for repair:

• Some corner-cases produce an appropriate message and leave the stale rendering (example: pigtail with Spring_Index less than 4).
• It is still possible for extreme cases (example: # 5 above, TC&G) to produce exception messages like: "Produced an invalid final shape".
• In general, it is possible to produce messages like "no geometry" when approaching the lower limit of Coils_T and slightly above solid height.

In summary my opinion is... these remaining not-exactly-perfect behaviors when approaching the limits of valid springs are a low priority for repair.

I am much more concerned about the PigTail solid height calculation mentioned in the July 19, 2026 6:58pm PDT comment above. That must be resolved in order to include this branch in a V6.3 release of ODOP.

[grumpyinca]

L_Solid calculation for the PigTail end types (part 2; End Type=PigtailClosed&Ground)

A comparison of the L_Solid calculation on:

• staging system (Pig-tail)
• current branch 1083 (PigtailClosed&Ground)
• current FreeCAD-Spring (PigtailClosed&Ground)

At first glance, agreement on the L_Solid = 16.8 mm calculation seems to be a good thing. As with the PigtailClosed example of July 19, 2026 6:58pm PDT above, visual inspection of the rendered version (see below in this comment) shows that the body coils are not in contact and thus each L_Solid calculation must be incorrect.

PigTail_L_SolidComparison.json was created on the staging system (v6.3.1) and imported into the now current dev system branch 1083. It contains the variables used in the comparison. The cylinder height represents the (incorrect?) 16.8 mm dimension.

PigTail_L_SolidComparison.json

These images were rendered by FreeCAD-Spring with those variables.

[grumpyinca]

In order to preserve the comment chronology, I am using this comment to provide a link to:
Next iteration of end table; Possible bug in how ODOP opens end type related fields for user input.
ODOP issue #1083.

[grumpyinca]

New artifact with end_type=TaperedClosed&Ground

FreeCAD-Spring Compression, metric units, End Type=TaperedClosed, Coils Total=6, Length at free=19.6, Outside Diameter=28, Wire Diameter=2.8.

On further investigation:

• Using End Type=TaperedClosed, keeping the other numbers constant but changing Length at Free=29.90 shows the artifact where 29.91 and greater does not show the artifact.
• These numbers are approximate. By decreasing the Length at Free, I was able to trigger the same artifact with TC&G with Length at Free in the ranges:

    28 - 24 mm
    18 - 17.5 

The artifact does not appear in the ranges:

    29 mm and above 
    22 -19 
    17.1 - 16.8

I believe that for the tapered end types, the Length at Solid is calculated incorrectly. For TC&G it should be less than 16.8, likely 15.4.

[grumpyinca]

Render update fails on value update of Grind_Amount, End Type=UserSpecifiedClosed&Ground

In FreeCAD-Spring, setting End Type=UserSpecifiedClosed&Ground allows me to enter a value (not=1.0) into the Grind_Amount field, but the rendered image does not update to reflect that new value.

[grumpyinca]

FreeCAD-Spring auto-test generation creates a spring with an artifact

It appears that the current FreeCAD-Spring auto-test generation creates a spring with an artifact but still considers the result to be a PASS.

I did some experimenting with DoubleClosed. I don't know how to exactly match the parameters used in the auto-test, but I was able to generate rendering artifacts in DoubleClosed as the value of Coils Total was reduced such that Coils Active fell below a value of 0.5. I suspect that the exact form of the artifact (sometimes it appears as a missing transition segment in either top or bottom) and whether or not it appears at all are strongly dependent on the exact numbers (OD_Free, Wire_Dia, L_Free, Coils_T, etc.). Just because an artifact appears with Coils Active = 0.5 does not mean that there will be an artifact with Coils Active = 0.4.

Does the FreeCAD-Spring code check for Active Coils less than zero ? Should there be such a test ? How about a test for Active Coils less than 0.5 ?

Just as an aside, ODOP has a warning level alert for any spring with less than one active coil. It has an err level alert for the specific case of
"Total coils exactly equals inactive coils; Active coils is zero".