Collecting a list of good and well documented OpenSCAD libraries

classic Classic list List threaded Threaded
13 messages Options
tp3
Reply | Threaded
Open this post in threaded view
|

Collecting a list of good and well documented OpenSCAD libraries

tp3
I'm starting with some of the more widely known ones:


BOSL
----
The Belfry OpenScad Library - A library of tools, shapes,
and helpers to make OpenScad easier to use.

Link: https://github.com/revarbat/BOSL
License: BSD-2-Clause

dotSCAD
-------
Helpful modules and functions when playing OpenSCAD

Link: https://openhome.cc/eGossip/OpenSCAD/index.html
Link: https://github.com/JustinSDK/dotSCAD
License: LGPL-3.0-only

BOLTS
-----
BOLTS is an Open Library for Technical Specifications.

Link: https://github.com/boltsparts/BOLTS
License: LGPL-2.1-or-later ??



_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
tp3
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

tp3
And this is how it looks on the web site:

  https://www.openscad.org/libraries.html

Now hoping for some more interesting libraries to add..

ciao,
  Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

shadowwynd
In reply to this post by tp3
tp3, apologies for hijacking but I really like this idea and the way you have
started.   Moderators, would it be possible to make this post (or something
similar) sticky so that is always on top, not lost and buried,  and at the
same time, still editable?

I have sat through all the arguments about libraries, and namespaces, and
built-in package management, and handling derivative branches and how lack
of better libraries is driving away new users, how real users should write
everything from scratch, etc.  Without adding package management or touching
OpenSCAD itself (thus letting the vitriolic fighting over purism of language
and namespace collisions and rounded polygons continue) can we use this
forum that we already have as an aid/springboard to discovering libraries
and code?  I have been using OpenSCAD for six years and routinely encounter
useful links to libraries and other code in the forums.

At the very least - there is not a single, cohesive place to find good
libraries, or even just good snippets of code (for example, I have the
occasional useful piece of code that is shareable, but not library worthy).
Some libraries are in github, some are in thingiverse, some are linked to
random dropbox or google drive accounts or other third party sites, some are
coded by gods and others by monkeys, some don't appear to work or are so
badly documented that even getting started is hard.  While most of the
information is in the forum, searching it and finding the useful information
is difficult; many users here do not have English as a first language and so
may not search for the right word, or the useful information about a library
is five pages into another discussion.

*I envision two sticky posts:  one for libraries, one for "short useful
code".  (perhaps a 3rd for useful trainings, youtube videos, etc.)   *

*Sticky Rules: *
*1) No discussion / help requests.*  If code becomes broken or unlinked,
there should not be a big discussion of what needs to happen to get it to
build correctly, no back-and-forth, it either works or it it doesn't (and
the mods erase it); Discussion should take place in the rest of the forums.
Keep this thread clean.

*2) No theoretical codes*; everything should be tested and working (perhaps
a "Tested On" version x, y,...).

*3) One library or useful code per post.*

*4) Picture(s) of what the code snippet / library produces.*  For example,
the BOSL library has no pictures in the main page (the manuals have lots),
but just a few example photos would help a new user understand why they
might want to try it out.

*5) Short description, 1 paragraph or less.*  In tp3's example, dotSCAD is
listed as "Helpful modules and functions when playing OpenSCAD".   I would
like another three or four sentences describing how it is "helpful", but not
another ten.

*6) Link(s)*

*7) License(s)*




--
Sent from: http://forum.openscad.org/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
tp3
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

tp3
On 02.06.19 21:56, shadowwynd wrote:
> At the very least - there is not a single, cohesive place to find good
> libraries, or even just good snippets of code (for example, I have the
> occasional useful piece of code that is shareable, but not library worthy).

Snippets could go on the Tips&Tricks page (if they match the CC0
requirement which I feel is very important for that kind of things).
In case it grows too big we can just split it into multiple pages
later.

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Tips_and_Tricks

> *Sticky Rules: *
> *1) No discussion / help requests.*

Having a sticky post could be nice so it's not buried after two weeks.

But I don't know if the "no discussion" will work without lots of
moderation, there's always some discussion going on and at some point
it just gets long and cumbersome to go through all the posts.

All it needs is 2 or 3 people who care enough to just copy&paste
those links into one of the wiki pages when something interesting
gets mentioned.

E.g. the "Libraries" page on wikibooks:

  https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Libraries

That makes it much easier for new people to go though and has a stable
link to pass around. Not as good as a package manager but probably
still very helpful.

> *4) Picture(s) of what the code snippet / library produces.*  For example,
> the BOSL library has no pictures in the main page (the manuals have lots),
> but just a few example photos would help a new user understand why they
> might want to try it out.

Yep, that bothered me too :-). The result can be seen on github:

  https://github.com/openscad/image-generator

This simply uses 4 example scripts from each of the libraries and
uses OpenSCAD + ImageMagick to convert that into a simple animated
gif like:

  https://www.openscad.org/images/bosl.gif

(10 Seconds delay between transitions, so be patient... better
examples welcome...)

> *5) Short description, 1 paragraph or less.*  In tp3's example, dotSCAD is
> listed as "Helpful modules and functions when playing OpenSCAD".   I would
> like another three or four sentences describing how it is "helpful", but not
> another ten.

True, for now it's just the subtitle posted on the library pages.
A short single paragraph introduction would be great. Maybe also
listing the main topics the library covers in case of multi-topic
ones like those 3 already mentioned.
Ideally we could ask the library owners to help with that, at least
for the bigger and more comprehensive ones where it's very useful
to have a summary of what the focus of the library is.

ciao,
  Torsten.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

adrianv
In reply to this post by shadowwynd
shadowwynd wrote

> *4) Picture(s) of what the code snippet / library produces.*  For example,
> the BOSL library has no pictures in the main page (the manuals have lots),
> but just a few example photos would help a new user understand why they
> might want to try it out.
>
> *5) Short description, 1 paragraph or less.*  In tp3's example, dotSCAD is
> listed as "Helpful modules and functions when playing OpenSCAD".   I would
> like another three or four sentences describing how it is "helpful", but
> not
> another ten.

I can divide libraries for OpenSCAD into perhaps three basic categories.
One type of library is that which provides some standard part, gears,
screws, other sorts of specific things that one might want to model.  For
this type of library, perhaps a few pictures can identify what the library
does.  So for example there is a knurling library on thingiverse.  One
picture suffices.  For screws and gears just a few pictures capture the
essence of the matter.   A second category are libraries which provide some
new but more general CAD function.  Perhaps a library for making rounded
cubes, or other roundings such as the fillet library, or the sweep() and
skin() modules from list-comprehension-demos and re-implemented elsewhere by
everybody in typical wheel-reinvention fashion.  The round_corners and
rounded_extrude functions I wrote would also be in this category.  Beziers.
Then the final category are libraries that extend the underlying
computations in OpenSCAD.  Things like this can't be documented in pictures:
computation of line intersection, determinant, sinh, cosh, sorting,
functions for converting lists in various ways.  These are the basic utility
functions that make it easier to write the other stuff.  

The dotSCAD library is about 4000 lines of code; BOSL is about 16000 lines
of code.  I feel like it's pretty hard to capture what dotSCAD does in 4
sentences and probably hopeless to describe BOSL usefully in 4 sentences.
I'm not sure what the answer is for how to describe libraries in a way that
is truly useful.  

What makes a snippet of code useful, shareable, but not library worthy?  I
would suggest that the main difference I would imagine is the code interface
and generality, but you might be treating yourself too harshly.  I mean, if
you find a particular capability useful, other people probably would too.
If the snippet isn't library-worthy by itself it probably is could be
developed into a function suitable for a library.  Ideally people can read
the libraries to learn code coding practice.  I think if you want to
introduce short code snippets in a useful way some sort of tutorial would
make more sense, though I'm not sure how to organize and write it.  

I searched around for libraries, trying to figure out what capabilities I
thought a good general OpenSCAD library should have.  I was personally
specifically trying to figure out of BOSL had any "holes", so I could
contribute "plugs" to BOSL, since this seemed to me like the best way
forward (as opposed to trying to use a disparate set of unmaintained (?)
libraries).  

In this hunt I found quite a few small libraries that in many cases did
interesting things, but rarely was anything well documented.  It's not
really clear whether things are maintained or not.  Most of the things I
found did not show signs of recent development.  Unfortunately, I didn't
keep a list of everything.  Mainly I did not find a lot of things that
seemed interesting.  When I found dotSCAD it appeared to be abandoned,
though we have seen a recent update, so it is not.  That is probably the
best and also most broad library I encountered after BOSL.  There is
list-comprehension-demos, which has the sweep and skin functions.   A
capability that I think looks very important is some kind of
attachment/relative positioning, since in my design experience I feel that I
spend a bunch of time fiddling with this (trial and error) instead of having
things just show up where I intend.  (Maybe others have better visualization
skills?)   This is provided by obiscad (which appears unmaintained, but is
documented), and also the relativity library which also looks abandoned, but
has documentation.  (And BOSL2 has implemented an attachment capability as
well.)    

There is this list:  https://github.com/openscad/openscad/wiki/Libraries

I don't think my searching was particularly thorough, as I keep stumbling
upon other things.  Especially thingiverse is difficult to search.  (If you
search for openscad you find 11400 hits, but of course most are just things,
not libraries---it's difficult to imagine a worse system for disseminating
libraries.)  It seems like I mainly find out about interesting new stuff on
thingiverse by seeing someone report it on the forum.   Someone mentioned
puzzlecut a while ago, which seems interesting, for example.   I was just
trying to find the fillet library (which is listed at the above site) and
looked on thingiverse and instead found a bunch of other fillet libraries.  

https://www.thingiverse.com/thing:35834
https://www.thingiverse.com/thing:32122

Things like this don't seem in the same category as dotSCAD or BOSL.  
Perhaps it makes sense to have a list of "one trick" libraries vs
multi-capability librarires.   The former can have brief descriptions and
the latter can have long descriptions.

I think another thing which is a pretty big annoyance is suppose I want to
make gears, as the recent poster.  So I look for libraries to make gears.
What can I find?  Well, so there's MCAD.  There's BOSL.    Then there is
more stuff to be found in thingiverse and perhaps elsewhere.  So how do I
decide which gear library to use?  It seems that there are some basic
possibilities:  library A is simply better than B.  It provides more
function, is more correct, or some such.  Another possibility is that the
libraries provide different capabilities, where A provides gears of one type
and B another.   And so both libraries serve a purpose.  (One might ask if
they can be merged.)  And the last possibility is that the libraries are
equivalent, but have different interfaces, and perhaps no compelling
argument can be made that one is superior.  But for a user, it is annoying
to be presented with this decision.  It is better if there is just ONE gear
library, or perhaps two but with a clear way to pick which one to use.  I
suppose this gets back to probably of consensus.  But having lots of choices
is not necessarily an asset, especially to the new person who just wants to
make some gears.  And then when that person tries to share code the
recipient must download yet another gear library, even if he already has
four of them at hand.

So it appears that if we are listing libraries and we list ones that do the
same thing, we need to provide some hint to the user about what the
difference is---how to pick, or which one to try first.  And this does seem
ultimately to mean making a judgement call about which libraries are better.  



--
Sent from: http://forum.openscad.org/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

adrianv
In reply to this post by tp3
tp3 wrote

>> *4) Picture(s) of what the code snippet / library produces.*  For
>> example,
>> the BOSL library has no pictures in the main page (the manuals have
>> lots),
>> but just a few example photos would help a new user understand why they
>> might want to try it out.
>
> Yep, that bothered me too :-). The result can be seen on github:
>
>   https://github.com/openscad/image-generator
>
> This simply uses 4 example scripts from each of the libraries and
> uses OpenSCAD + ImageMagick to convert that into a simple animated
> gif like:
>
>   https://www.openscad.org/images/bosl.gif
>
> (10 Seconds delay between transitions, so be patient... better
> examples welcome...)

The video form doesn't seem very good to me.  I would rather see 50 images
in a web page that I could quickly scan and then say HA!  That's kind of
like the thing I want to make!   Could it make more sense to have libraries
have a link to one page per library where that page has as many examples as
are appropriate for the library?  For some libraries the page could be very
short with just a couple examples, and for others longer, with many
examples.  

This doesn't address the question about how to explain libraries whose
function is not visual, though.




--
Sent from: http://forum.openscad.org/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
tp3
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

tp3
On 03.06.19 00:37, adrianv wrote:
> The video form doesn't seem very good to me.  I would rather
> see 50 images in a web page that I could quickly scan and
> then say HA!  That's kind of like the thing I want to make!

That would be a nice thing to see, but it's something which
belongs on the page of the library, not on an index at the
OpenSCAD site (or later a package manager listing). Also it's
certainly not something I'm going to maintain for multiple
libraries.

ciao,
  Torsten.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
tp3
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

tp3
In reply to this post by adrianv
On 03.06.19 00:30, adrianv wrote:
> It is better if there is just ONE gear library, or perhaps
> two but with a clear way to pick which one to use.  I suppose
> this gets back to probably of consensus.

Maybe it's better in theory, I don't know. In reality it's
just not going to happen for likely a wide variety of reasons
(want a different interface, don't agree on hosting provider,
just want to try new things, did not look for existing ones,
tabs vs. spaces ;-), ...).

There's one of those reasons that worries me though, and
that is something along the lines: "Oh, you can have libraries?"
or "Oh, I did not know that a gear library even existed!".

People should at least be aware that there are libraries
out there and have a chance to look for themselves. So
far the OpenSCAD web site did not do a good job at that.

> So it appears that if we are listing libraries and we list
> ones that do the same thing, we need to provide some hint
> to the user about what the difference is---how to pick, or> which one to try first.  And this does seem ultimately to
> mean making a judgement call about which libraries are better.

Yes, so maybe one of the plus points for adding a library
to the list would be the report by someone "I've used that
in a project of mine and it was great" vs. just "I found
that link in a 5 years old reddit thread.

But there's no need to like vote for a final list that will
have to stay for the next 10 years. We can see how to improve
and change as we go.

ciao,
  Torsten.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

caterpillar
In reply to this post by tp3
This thread reminds me of one reason why I like to use OpenSCAD and what
dotSCAD recently focuses on. I rewrite the short description for it:

- Reduce the burden of 3D modeling in mathematics.



-----
http://openhome.cc
--
Sent from: http://forum.openscad.org/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

shadowwynd
In reply to this post by tp3
In real life, the value of a library or a museum is not necessarily the
collection, but the curation.  It is less valuable to know that there are
twelve gear libraries than to know that here is a good (not necessarily
"best", whatever that means) gear library that many of us use have used.

I like the "Libraries" link on the main site, that is helpful and makes it
more visible.

The "rules" for the sticky page are simply suggestions for discussion.  

I agree that Thingiverse is a bad platform for distribution.  The search is
clunky, and the site is often very slow (victim of its own success).


In terms of dividing libraries into parts (screws, gears), geometric
functions (sweep, bezier), and math(arcsin) - there are always going to be
things that don't represent pictorially - it is easy to represent a dog or
an apple in any language, harder but doable to show "run" in a picture (uses
learned conventions like motion lines), and impossible to show "was" or
"have".




--
Sent from: http://forum.openscad.org/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

adrianv
In reply to this post by caterpillar
caterpillar wrote
> This thread reminds me of one reason why I like to use OpenSCAD and what
> dotSCAD recently focuses on. I rewrite the short description for it:
>
> - Reduce the burden of 3D modeling in mathematics.

I understand and appreciate this description as your basic intention.  But
this description is quite vague, so I think a new user really doesn't
understand what this means at all.  Something more about *how* the burden is
reduced seems necessary.   A year ago my understanding of what was even
possible in OpenSCAD was dramatically limited.  I just had no idea that
certain kinds of things could be done, and certainly no idea how they could
be done.  




--
Sent from: http://forum.openscad.org/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

adrianv
In reply to this post by tp3
tp3 wrote
> People should at least be aware that there are libraries
> out there and have a chance to look for themselves. So
> far the OpenSCAD web site did not do a good job at that.

I think the libraries link on the site is good.  There is actually this link
in the "user manual" section:

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Libraries

This link then links to yet another list of libraries, which repeats some
and lists some new ones.  It's kind of a mess.  But also I do not think I
found this link when I was learning OpenSCAD, hence my question posted a few
months back of "where are the libraries?"   I think the "user manual" did
not appear very helpful so I had not examined it carefully and I was reading
the language reference, which never mentions the existence of any libraries.
Would it make sense to do one or both of:

* Add a link in the language reference section 9 to the libraries page
* Add a small number of examples of using existing real libraries to do
something that is really hard without the library (and where the examples
are short and simple)

I went back and was looking at the "user manual" some more.  In other cases
I think of the "user manual" as being something like a tutorial, the better
place to start learning the language, whereas the "language reference" is
the complete, but terse description of all language functions.  In the case
of OpenSCAD, the "user manual" seems that it cannot really be digested until
one has read the "language reference".   So what I think of as the normal
convention is not exactly followed here.   This observation for me
strengthens the idea that it might be reasonable to add some more content
about libraries to the "language reference".  


> Yes, so maybe one of the plus points for adding a library
> to the list would be the report by someone "I've used that
> in a project of mine and it was great" vs. just "I found
> that link in a 5 years old reddit thread.

This seems like a reasonable criterion.  I suppose if there was a simple way
to let people vote that they like a library that might also be good, but I
suspect this is not feasible.   (I don't mean a one-time round of voting on
the forum, but some automatic system where people could "like" a library.  I
am guessing this is probably not feasible...as there would have to be a way
to prevent multiple votes from the same person, so it seems complex.)  




--
Sent from: http://forum.openscad.org/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: Collecting a list of good and well documented OpenSCAD libraries

nophead
I will throw my hat into the ring with this:  https://github.com/nophead/NopSCADlib

This is what I use to make all my OpenSCAD projects and my reason for publishing it is so I can blog projects that use it, because I don't have any stand alone code nowadays.


On Mon, 3 Jun 2019 at 03:49, adrianv <[hidden email]> wrote:
tp3 wrote
> People should at least be aware that there are libraries
> out there and have a chance to look for themselves. So
> far the OpenSCAD web site did not do a good job at that.

I think the libraries link on the site is good.  There is actually this link
in the "user manual" section:

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Libraries

This link then links to yet another list of libraries, which repeats some
and lists some new ones.  It's kind of a mess.  But also I do not think I
found this link when I was learning OpenSCAD, hence my question posted a few
months back of "where are the libraries?"   I think the "user manual" did
not appear very helpful so I had not examined it carefully and I was reading
the language reference, which never mentions the existence of any libraries.
Would it make sense to do one or both of:

* Add a link in the language reference section 9 to the libraries page
* Add a small number of examples of using existing real libraries to do
something that is really hard without the library (and where the examples
are short and simple)

I went back and was looking at the "user manual" some more.  In other cases
I think of the "user manual" as being something like a tutorial, the better
place to start learning the language, whereas the "language reference" is
the complete, but terse description of all language functions.  In the case
of OpenSCAD, the "user manual" seems that it cannot really be digested until
one has read the "language reference".   So what I think of as the normal
convention is not exactly followed here.   This observation for me
strengthens the idea that it might be reasonable to add some more content
about libraries to the "language reference".   


> Yes, so maybe one of the plus points for adding a library
> to the list would be the report by someone "I've used that
> in a project of mine and it was great" vs. just "I found
> that link in a 5 years old reddit thread.

This seems like a reasonable criterion.  I suppose if there was a simple way
to let people vote that they like a library that might also be good, but I
suspect this is not feasible.   (I don't mean a one-time round of voting on
the forum, but some automatic system where people could "like" a library.  I
am guessing this is probably not feasible...as there would have to be a way
to prevent multiple votes from the same person, so it seems complex.) 




--
Sent from: http://forum.openscad.org/

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org