feat: prevent Z-fighting/flicker in OpenSCAD preview

[spetzreborn]

This adds the constant EPSILON to prevent Z-fighting / Z-flicker. Could be conceded "code smell" but is well known OpenSCAD approach:

• https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/FAQ#What_are_those_strange_flickering_artifacts_in_the_preview?

• https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/CSG_Modelling (search for eps)

  This makes it easier for the eyes when working in OpenSCAD and preview.

[spetzreborn]

This PR is mostly a way to start discussion. I don't know if the added code crud of EPSILON out weights the added bonus of better OpenSCAD experience. This does not limit nor benefit users of Makerworld, only ppl locally using OpenSCAD.

[kellervater]

Thanks for this improvement.
I always took this "bad ui" for granted. Didn't know that this is a known issue with a broadly accepted workaround.
I'll get to it asap.

[Copilot]

Pull request overview

This PR introduces the EPSILON constant (0.001) to prevent Z-fighting/flickering artifacts in OpenSCAD preview mode. The constant is added to height/depth dimensions in CSG operations where geometric faces would otherwise be coplanar, following standard OpenSCAD best practices.

Key Changes

• Adds EPSILON constant to models/core/lib/constants.scad with clear documentation
• Applies EPSILON to prismoid heights and cuboid dimensions in connector arms and lock pin holes across all core component files
• Updates both lib files (which include constants.scad) and makerworld files (which embed constants inline)

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
models/core/lib/constants.scad	Defines EPSILON constant (0.001) with documentation explaining its purpose for preventing Z-fighting
models/core/lib/support.scad	Applies EPSILON to lock_pin_hole prismoid height to prevent coplanar faces
models/core/lib/lockpin.scad	Applies EPSILON to tension_hole_half dimension to eliminate Z-fighting in tension holes
models/core/lib/connector.scad	Applies EPSILON to connector arm cuboids and inner arm dimensions for clean preview rendering
models/core/makerworld/support.scad	Duplicates EPSILON definition and applies to lock pins, connector arms, and tension holes
models/core/makerworld/lockpin.scad	Duplicates EPSILON definition and applies to lock pins, connector arms, and tension holes
models/core/makerworld/connector.scad	Duplicates EPSILON definition and applies to lock pins, connector arms, and tension holes

[kellervater]

just tested it locally.
I think we should go an order of magnitude higher 0.001 -> 0.01. Otherwise I still have these weird artifacts.

Additionally it would be good to adapt the export_makerworld.py script to set EPSILON to 0. This way one has good DevEx while maintaining unaltered exports.
Or even better:
Just create a new folder in core called dev, alter the lib modules so they accept EPSILON as param which defaults to 0.
And the dev folder contains just the module calls similar to the presets or makerworld ones which then sets epsilon to a viewer-friendly value.
This way we leave the actual lib and exports vanilla while having a better devex when developing.
wdyt?

[spetzreborn]

Yeah, 0.01 is the example from the documentation, it's just me that used a smaller in my template, so should be good to change.

The purpose is only to offset a small part that won't show in the final part.

I have no experience with alter the epsilon for rendering, only $fn. I think that is doable, but I'm not sure if it might create bugs down the line when rendering. I'm guessing but like a thin wall that gets solid in render but not preview.

Maybe doing it as simple as a tenary check? It is common to do for $fn:

$fn = $preview ? 32 : 64;

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Other_Language_Features#$fn

Maybe do the same for the value for EPSILON?
(Not at my computer right now so can't test it)

[kellervater]

there's a $preview var??? 🤯
noicest!
this is of course extremely awesome and helpful, and clean.
very good idea to have that for epsilon, yes.
something like

EPSILON = $preview ? 0.01 : 0; # we don't want any changes whatsoever on the real deal
``

[spetzreborn]

Made a commit that difference the epsilon value depending if preview or rendering. I'm not sure that actually is beneficial or just a static value. The epsilon value in preview is now a magnitude bigger, still very small.

I did some tries to setting the epslion to 0, but that generated errors in BOSL2 math.scad so I think that is a nogo.

[spetzreborn]

there's a $preview var???

yes, it is most commonly used for the $fn setting as in my example. The library might benefit from setting a lower $fn in preview and a higher in render. Thinking of moving that to constants.scad or main.scad

It might make gridfinity/base.scad render quicker. Have mostly looked in core and not the models yet so not sure.

[kellervater]

yes, it is most commonly used for the $fn setting as in my example. The library might benefit from setting a lower $fn in preview and a higher in render. Thinking of moving that to constants.scad or main.scad

imho settings like $fn or EPSILON shouldn't be actively tweaked in library files. They should be agnostic to that.
If we want we can add the Epsilon parameter to the lib modules, but the actual setting and $preview toggling should happen in orchestration files (e.g. makerworld exports or presets).

It might make gridfinity/base.scad render quicker. Have mostly looked in core and not the models yet so not sure.

Just a fair warning: This one is faulty! The filetting on the edges are not quite right, so the base plate generated from this doesn't 100% adhere to the Gridfinity standard.
tl;dr: still WIP

[spetzreborn]

imho settings like $fn or EPSILON shouldn't be actively tweaked in library files. They should be agnostic to that. If we want we can add the Epsilon parameter to the lib modules, but the actual setting and $preview toggling should happen in orchestration files (e.g. makerworld exports or presets).

Yes, that seems correct, and the parts/ files. So it get set by the correct caller in respective use case. This is on me, but I always forget makerworld. As you might have noticed I'm mostly for local generated ^^

It might make gridfinity/base.scad render quicker. Have mostly looked in core and not the models yet so not sure.

Just a fair warning: This one is faulty! The filetting on the edges are not quite right, so the base plate generated from this doesn't 100% adhere to the Gridfinity standard. tl;dr: still WIP

Yeah, I got that. Was just me trying to familiarise myself with the codebase and look around.

I am no OpenSCAD expert, but the cases I'll seen regarding epsilon and the cousin "use a bigger piece to difference()" has been to over cut and dont care between preview and render. If the object that is differneced is a submodule it does not mater that the "diff object" is to big as the submodule will be used as a solid.
In the other case the epsilon is so small so the slicer and 3dprinter just ignore it and it is floored/roofed to the correct altitude.

I don't know which way is better. Anyhow I'm happy if the general concept is brought in as it makes the customisation in OpenSCAD a better user experience.

[spetzreborn]

Is there anything more to discuss or changes I need to do? I would like this to be merged unless it breaks makerworld (which I doubt).

Regards
Björn

[kellervater]

I would like to see EPSILON as a named parameter in the modules it is being used and ideally set to 0 per default. If that's not possible due to some bosl2 shenanigans, then it shall be set to the smallest value possible as default.

e.g.

module connectorArmOuter(is_foot=false)
---> module connectorArmOuter(is_foot=false, EPSILON=0)  # or something very close to 0

This is to prevent a breaking change for the pure purpose of devex while giving everyone the opportunity to set the value higher.