Miscellaneous mathematical utilities. More...

Collaboration diagram for Utilities:

Files
file	utility.scad
	Miscellaneous mathematical utilities.

Functions and/or Modules
function	get_fn (r=0)
	Return facets number for the given arc radius. More...

function	histogram (v, m=0, cs, cb, cp, ca, cf, d=false)
	Generate a histogram for the elements of a list of values. More...

Usage Details

Miscellaneous mathematical utilities.

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
math/utility.scad	Utilities	Script	Results	2	0	0	0	0

No Failures

See complete validation results.

Requires:
include <omdl-base.scad>;

Conventions

The following conventions apply to all functions in this group.

OpenSCAD special variables $fn, $fa, and $fs are read directly at the call site and are never passed as parameters; their values at the point of call control fragment counts.
grid_fine is an omdl library-level constant defining the minimum meaningful geometry size. Inputs below this threshold are treated as degenerate and return safe fallback values.
Bit-field parameters (e.g. m in histogram()) are documented with an explicit bit-table in the function's

block. Bit 0 always selects the primary output mode (0 = numerical, 1 = string). Higher bits select sub-modes within the string path.
HTML passthrough parameters (cb, cp, ca, cf, d) follow the interface of strl_html() exactly; see its documentation for type and semantics. They are ignored in non-html modes.
tau is an omdl library constant equal to 2*PI.
No input validation is performed unless an explicit assert is present. Out-of-range or wrongly-typed inputs produce undef, nan, or inf without warning.

Function and/or Module Documentation

◆ get_fn()

function get_fn ( r = 0 )

Return facets number for the given arc radius.

Parameters

r	<decimal> The arc radius. Must be >= 0. Defaults to 0, which returns 3 (the minimum facet count).

Returns: <integer> The number of facets.

This function approximates the get_fragments_from_r() code that is used by OpenSCAD to calculate the number of fragments in a circle or arc. The arc facets are controlled by the special variables $fa, $fs, and $fn. The three branches are:

r < grid_fine: returns 3 (minimum). grid_fine is the library-level constant for the minimum meaningful geometry size; radii below it are treated as degenerate.
$fn > 0: returns $fn clamped to a minimum of 3, respecting the caller's explicit fragment count override.
otherwise: returns ceil(max(min(360/$fa, r*tau/$fs), 5)), where tau = 2*PI is an omdl library constant.

Note: Passing a negative r is invalid and caught by an internal assert. If $fa is 0, 360/$fa produces inf; min() then selects the r*tau/$fs term, which is the correct fallback behaviour.

Here is the caller graph for this function:

◆ histogram()

function histogram	(	v	,
		m	= `0`,
		cs	,
		cb	,
		cp	,
		ca	,
		cf	,
		d	= `false`
	)

Generate a histogram for the elements of a list of values.

Parameters

v	<data> A list of values.
m	<integer> The output mode (a 5-bit encoded integer).
cs	<string-list-4> A list of strings [cs[0], cs[1], cs[2], cs[3]] used only with custom formatting (m = 15), mapping to `s1`, `s2`, `s3`, and `fs` respectively in the output template: `s1`, value, `s2`, frequency, `s3`, `fs`.
cb	<string-list> Bold tag specifiers passed to strl_html(). Only used in html and custom string modes. See strl_html() for type and semantics.
cp	<string-list> HTML tag-pair specifiers passed to strl_html(). Only used in html and custom string modes. See strl_html() for type and semantics.
ca	<string-list> HTML attribute specifiers passed to strl_html(). Only used in html and custom string modes. See strl_html() for type and semantics.
cf	<string-list> Font specifiers passed to strl_html(). Only used in html and custom string modes. See strl_html() for type and semantics.
d	<boolean> When true, emit HTML debug output via strl_html(). Default false.

Returns: <decimal-list | string> The occurrence frequencies of v. When m bit 0 = 0 (numerical mode), returns a list of [value, count] pairs. When m bit 0 = 1 (string mode), returns a single concatenated string, except for m = 1 which returns a list of bare "NxM" strings.

The custom formatting strings are inserted in the output stream as follows:

  s1, value, s2, value-frequency, s3, fs

See strl_html() for description of the html formatting parameters cb, cp, ca, cf, and d.

Output mode selection:

bit	Description	0	1
0	output mode	numerical	string
1-3	string mode format	see table	see table
4	field separator mode	not at end	all

String output modes:

	B3	B2	B1	B0	Description
1	0	0	0	1	list of bare strings, each "NxM"
3	0	0	1	1	text format 1
9	1	0	0	1	html format 1
15	1	1	1	1	custom formatting (uses `cs`)

Example outputs for v = ["a","b","a","c","a","b"]:

m=0 (numerical): [["a",3],["b",2],["c",1]]
m=1 (bare strings): ["3xa","2xb","1xc"]
m=3 (text format): "3<a> 2<b> 1<c>"
m=9 (html format): formatted as superscript-count + italic-value pairs

Note: histogram() uses unique() followed by a find() scan per unique value. Both are O(n) per call over the full list, making the combined complexity O(n*k) where k is the number of unique values — effectively O(n^2) in the worst case. Avoid passing very large lists.