fluxplot 0.1.0__py3-none-any.whl

fluxplot/__init__.py

@@ -0,0 +1,115 @@
+"""FluxPlot — matplotlib, but every meaningful thing has a name.
+
+A thin, additive semantic-tagging layer over matplotlib. Plot in real matplotlib (using the
+``fp.*`` convenience helpers or by tagging raw artists), then :func:`save` emits a semantic SVG +
+``*.fluxplot.json`` manifest + ``*.recipe.json``.
+
+See ``Flux_SemanticSVG_Spec.md`` for the conceptual spec.
+"""
+
+from . import (
+    colorcheck,  # noqa: E402,F401  (accessibility lint — colorcheck.check_palette, simulate, contrast, …)
+    colors,  # noqa: E402,F401  (canonical palette/colormaps — colors.green400, colors.maps.emerald, …)
+    colorscale,  # noqa: E402,F401  (the portable colour-scale law — colorscale.apply(record, values))
+    stats,  # noqa: E402,F401  (tests behind the plots — stats.welch_hedges(a, b), …)
+    style,  # noqa: E402,F401  (house plotting style — fx.use_light(), fx.FLEXOKI, …)
+)
+from .api import (  # noqa: E402,F401
+    annotation,
+    area,
+    band,
+    bar,
+    barh,
+    box,
+    errorbar,
+    hist,
+    legend,
+    line,
+    reference_line,
+    save,
+    scatter,
+    secondary_axis,
+    significance_bracket,
+    stem,
+    step,
+    tag,
+    tag_points,
+    tag_seaborn,
+    violin,
+)
+from .recipe import (
+    params,  # noqa: E402,F401  (overridable tunables for rerun-plot/Regenerate)
+)
+from .surface import (  # noqa: E402,F401
+    surface,
+)
+from .signature_fluxplots import (  # noqa: E402,F401  (preset plot types unique to Flux)
+    fluxbox,
+    glowbar,
+    hexmatrix,
+)
+from .style import (  # noqa: E402,F401  (re-exported for convenience)
+    use_dark,
+    use_light,
+    use_paper,
+)
+from .scene3d import Scene3D, scene3d, SCENE3D_SPEC_VERSION
+from .mesh3d import mesh3d, can_morph
+from .surface3d import surface3d
+from .fields import heatmap, contour, contourf, colorbar, color_scale
+from .brackets import brackets
+from .images import image, scalebar
+from .fits import regression, kde
+from .panels import panel
+from .version import SPEC_VERSION, __version__  # noqa: F401
+
+__all__ = [
+    "__version__",
+    "Scene3D", "scene3d", "mesh3d", "surface3d", "can_morph", "SCENE3D_SPEC_VERSION",
+    "surface",
+    "glowbar",
+    "fluxbox",
+    "hexmatrix",
+    "panel",
+    "heatmap",
+    "contour",
+    "contourf",
+    "colorbar",
+    "color_scale",
+    "brackets",
+    "image",
+    "scalebar",
+    "regression",
+    "kde",
+    "SPEC_VERSION",
+    "colors",
+    "colorcheck",
+    "colorscale",
+    "stats",
+    "style",
+    "use_light",
+    "use_dark",
+    "use_paper",
+    "params",
+    "legend",
+    "line",
+    "scatter",
+    "secondary_axis",
+    "step",
+    "stem",
+    "bar",
+    "barh",
+    "errorbar",
+    "area",
+    "band",
+    "box",
+    "violin",
+    "hist",
+    "tag",
+    "tag_points",
+    "tag_seaborn",
+    "significance_bracket",
+    "reference_line",
+    "annotation",
+    "save",
+]

fluxplot/_fieldmap.py

@@ -0,0 +1,97 @@
+"""One value-to-color law shared by 2D surface and Scene3D; no geometry or rendering."""
+from __future__ import annotations
+import numpy as np
+from matplotlib.colors import Normalize, to_hex, to_rgba
+
+
+def _normalise_missing(values, missing_below=None, missing_values=()):
+    """Normalize explicit sentinel codes; zero remains a real observation."""
+    v=np.asarray(values,dtype=float).copy()
+    if missing_below is not None: v[v<missing_below]=np.nan
+    for mv in missing_values: v[v==mv]=np.nan
+    return v
+
+
+def _resolve_range(finite,color_range,percentile):
+    if color_range is not None: return float(color_range[0]),float(color_range[1])
+    if percentile is not None: return float(np.percentile(finite,percentile[0])),float(np.percentile(finite,percentile[1]))
+    return float(np.min(finite)),float(np.max(finite))
+
+
+def category_name(code, categories=None):
+    """Name of one integer label code: ``categories[code]``, else ``category-<code>``.
+
+    Negative codes are spelled ``category-m<abs>`` (``-1`` -> ``category-m1``). A plain
+    ``category--1`` would slugify to ``category-1`` and collide with code ``+1``, so the
+    id of one category would shift depending on whether the other is present.
+    """
+    code = int(code)
+    if categories and code in categories:
+        return categories[code]
+    return f'category-{code}' if code >= 0 else f'category-m{-code}'
+
+
+def categorical_colors(names,palette=None,categories=None):
+    """Resolve the fixed category-name/code palette in stable sorted-name order.
+
+    A category the palette does not name takes its colour from the registry
+    (``fp.colors.categories``): pinned, or the next free slot of the active cycle, remembered —
+    so ``'b'`` is the same colour whether or not ``'a'`` is present, in every figure.
+    """
+    from .colors import categories as _registry
+    resolved={}
+    for name in sorted(names):
+        color=None
+        if palette:
+            color=palette.get(name)
+            if color is None and categories:
+                for code,nm in categories.items():
+                    if nm==name and code in palette:
+                        color=palette[code]; break
+        if color is None: color=_registry.get(name)
+        rgba=to_rgba(color)
+        resolved[name]=to_hex(rgba, keep_alpha=rgba[3] < 1)  # an opaque colour stays #rrggbb
+    return resolved
+
+
+def continuous_mapping(finite,cmap=None,color_range=None,percentile=None):
+    """Return the shared matplotlib colormap and Normalize, including all-missing fallback."""
+    if finite.size==0 and color_range is None: lo,hi=0.,1.
+    else: lo,hi=_resolve_range(finite,color_range,percentile)
+    if not np.isfinite([lo,hi]).all() or lo>hi: raise ValueError('color_range must be finite and nondecreasing')
+    return resolve_colormap(cmap),Normalize(vmin=lo,vmax=hi)
+
+
+def resolve_colormap(cmap=None):
+    """A Colormap from ``None`` (the style default), a Colormap, or a name.
+
+    Names resolve through matplotlib first (so existing names keep their exact maps),
+    then through fluxplot's shipped collections: ``'emerald'``, ``'crameri.batlow'``,
+    ``'batlow_r'``, or a map added with ``fp.colors.maps.register``.
+    """
+    import matplotlib as mpl
+    if cmap is None:
+        return mpl.colormaps[mpl.rcParams['image.cmap']]
+    if not isinstance(cmap, str):
+        return cmap
+    try:
+        return mpl.colormaps[cmap]
+    except KeyError:
+        pass
+    from .colors import maps
+    try:
+        return maps.get(cmap)
+    except KeyError:
+        raise ValueError(f"unknown colormap {cmap!r}: use a matplotlib name ('viridis') or a "
+                         "fluxplot map ('emerald', 'crameri.batlow'); list them with "
+                         "fp.colors.maps.collections()") from None
+
+
+def infer_kind(finite,kind):
+    if kind=='categorical': kind='label'
+    if kind=='auto':
+        if not finite.size: raise ValueError("every vertex is missing and kind='auto' cannot infer label vs continuous; pass kind explicitly")
+        uniq=np.unique(finite)
+        kind='label' if uniq.size<=32 and np.allclose(uniq,np.round(uniq)) else 'continuous'
+    if kind not in ('label','continuous'): raise ValueError("kind must be 'label', 'continuous', or 'auto'")
+    return kind

fluxplot/_mesh_reduce.py

@@ -0,0 +1,54 @@
+"""Optional collapse replay; named-part boundaries never share a simplification pass."""
+from __future__ import annotations
+import warnings
+import numpy as np
+
+
+def face_budgets(counts, total):
+    """Apportion one triangle per part, then remaining capacity by largest remainder."""
+    counts=[int(n) for n in counts]
+    if total is None: return [None]*len(counts)
+    if total<len(counts): raise ValueError('max_faces must allow at least one triangle per part')
+    if any(n<1 for n in counts): raise ValueError('mesh parts must contain triangles')
+    target=min(int(total),sum(counts)); remaining=target-len(counts)
+    capacity=sum(n-1 for n in counts)
+    if not capacity: return counts
+    portions=[divmod(remaining*(n-1),capacity) for n in counts]
+    result=[1+q for q,r in portions]
+    for i in sorted(range(len(counts)),key=lambda i:(-portions[i][1],i))[:target-sum(result)]: result[i]+=1
+    return result
+
+
+def reduce_part(part, *, max_faces=None, collapses=None):
+    try: import fast_simplification as fs
+    except ImportError as exc:
+        raise ImportError('max_faces needs the optional fluxplot[mesh] extra (fast-simplification); omit max_faces to save full resolution') from exc
+    vertices=part.vertices.copy(); faces=part.faces.copy()
+    if collapses is None:
+        _,_,collapses=fs.simplify(vertices,faces,target_count=int(max_faces),return_collapses=True)
+    collapses=np.asarray(collapses,dtype=np.int32)
+    out, outfaces, mapping=fs.replay_simplification(vertices.astype(np.float32),faces,collapses)
+    mapping=np.asarray(mapping,dtype=np.int64)
+    if len(outfaces)==0: raise ValueError(f'{part.id}: max_faces removed every triangle; choose a larger budget')
+    if max_faces is not None and len(outfaces)>max_faces:
+        warnings.warn(f'{part.id}: simplifier retained {len(outfaces)} faces above requested max_faces={max_faces}',stacklevel=3)
+    # Some backends leave unused output vertices. Compact by index only, in the
+    # same order for all states and fields; this bounds stored vertices by 3F.
+    used=np.unique(outfaces)
+    for name,target in list(part.states.items()):
+        sv,sf,_=fs.replay_simplification(target.astype(np.float32),faces,collapses)
+        if not np.array_equal(outfaces,sf): raise ValueError(f'state {name}: collapse replay changed topology')
+        part.states[name]=np.asarray(sv,dtype=float)[used]
+    def remap(array):
+        a=np.asarray(array,dtype=float); scalar=a.ndim==1
+        if scalar: a=a[:,None]
+        valid=np.isfinite(a); good=(mapping>=0)&(mapping<len(out))
+        sums=np.zeros((len(out),a.shape[1])); count=np.zeros_like(sums)
+        np.add.at(sums,mapping[good],np.where(valid[good],a[good],0))
+        np.add.at(count,mapping[good],valid[good].astype(float))
+        result=np.divide(sums,count,out=np.full_like(sums,np.nan),where=count>0)
+        return result[:,0] if scalar else result
+    if part.values is not None: part.values=remap(part.values)[used]
+    if part.colors is not None: part.colors=remap(part.colors)[used]
+    part.vertices=np.asarray(out,dtype=float)[used]; part.faces=np.searchsorted(used,outfaces).astype(np.int64)
+    part.collapses=collapses.copy()

fluxplot/_scene3d_size.py

@@ -0,0 +1,95 @@
+"""Conservative, scene-specific face caps without running a simplifier."""
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+import struct
+
+WARN_BYTES = 50 * 1024**2
+WARN_TRIANGLES = 2_000_000
+
+
+def _json_bytes(value, *, upper):
+    # Counts/offsets are bounded by GLB's uint32 size; finite float32 bounds and
+    # Python float weights need at most 25 characters. Reserve 34, including
+    # quotes, so simple original bounds cannot underestimate collapsed bounds.
+    def numbers(item):
+        if isinstance(item, dict): return {k: numbers(v) for k, v in item.items()}
+        if isinstance(item, list): return [numbers(v) for v in item]
+        if isinstance(item, (int, float)) and not isinstance(item, bool):
+            return '0' * 32 if upper else 0
+        return item
+    size = len(json.dumps(numbers(value), sort_keys=True, separators=(',', ':'), allow_nan=False).encode())
+    return (size + 3) // 4 * 4
+
+
+def face_cap_recommendation(scene, glb, *, max_bytes=None, max_triangles=None):
+    """Return an actionable per-helper-call cap, or explain why none is safe.
+
+    Each part is bounded independently by min(original faces, cap), even when
+    a call apportions its cap among several parts. The byte bound uses at most
+    three referenced vertices per face, every attribute/state, uint32 indices,
+    and the actual JSON structure/strings with worst-case numeric widths.
+    This is a sufficient bound, not a prediction of backend simplification.
+    """
+    max_bytes = WARN_BYTES if max_bytes is None else max_bytes
+    max_triangles = WARN_TRIANGLES if max_triangles is None else max_triangles
+    # A scene may already have been simplified. The hint applies to rerunning
+    # the authored calls, so use their original face counts, not a prior quota.
+    counts = [len(part.source_faces) if part.source_faces is not None else len(part.faces)
+              for part in scene.parts]
+    total = sum(counts)
+    limit = f'{max_bytes / 1024**2:g} MiB / {max_triangles:,} triangles'
+    if len(counts) > max_triangles:
+        return f'No max_faces cap can fit {limit} while preserving all {len(counts):,} parts; split the scene or remove parts'
+    if total == len(counts) and len(glb) > max_bytes:
+        return f'No max_faces cap can fit {limit}: all {len(counts):,} parts already contain one triangle; use fewer parts or shape states, or split the scene'
+
+    size = struct.unpack_from('<I', glb, 12)[0]
+    document = json.loads(glb[20:20 + size])
+    # Even ignoring every buffer and shortening every number, these names,
+    # target lists and structural keys cannot be removed by a face cap.
+    required = deepcopy(document)
+    optional_accessors, optional_views = set(), set()
+    for mesh in required['meshes']:
+        for primitive in mesh['primitives']:
+            index = primitive['attributes'].pop('_VALID', None)
+            if index is not None:
+                optional_accessors.add(index)
+                optional_views.add(required['accessors'][index]['bufferView'])
+    required['accessors'] = [a for i, a in enumerate(required['accessors']) if i not in optional_accessors]
+    required['bufferViews'] = [v for i, v in enumerate(required['bufferViews']) if i not in optional_views]
+    for material in required['materials']: material.pop('alphaMode', None)
+    if 28 + _json_bytes(required, upper=False) > max_bytes:
+        return f'No max_faces cap can fit {limit}: fixed GLB part/state metadata alone exceeds the byte limit; use fewer parts or shape states, or split the scene'
+
+    # Averaging valid values cannot add a channel normally, but reserve _VALID
+    # even for presently all-valid data so the bound does not rely on that.
+    for part, mesh in zip(scene.parts, document['meshes']):
+        attrs = mesh['primitives'][0]['attributes']
+        if part.values is not None and '_VALID' not in attrs:
+            attrs['_VALID'] = len(document['accessors'])
+            document['accessors'].append({'bufferView': len(document['bufferViews']), 'componentType': 5121, 'count': 1, 'type': 'SCALAR'})
+            document['bufferViews'].append({'buffer': 0, 'byteOffset': 0, 'byteLength': 4, 'target': 34962, 'byteStride': 4})
+    for material in document['materials']: material['alphaMode'] = 'BLEND'
+    overhead = 28 + _json_bytes(document, upper=True)
+    costs = [24 + 24 * len(p.states) + (8 if p.values is not None else 0) + (4 if p.colors is not None else 0) for p in scene.parts]
+
+    def fits(cap):
+        faces = [min(count, cap) for count in counts]
+        # Compaction after reduction guarantees at most three vertices per face.
+        # Do not cap this by today's vertex count: a user may rerun an already
+        # simplified scene from its original meshes with the recommended cap.
+        binary = sum(3 * count * cost + 12 * count for count, cost in zip(faces, costs))
+        return sum(faces) <= max_triangles and overhead + binary <= max_bytes
+
+    low = max(1, scene._max_call_parts)
+    if not fits(low):
+        return f'No conservative max_faces cap can be recommended for {limit} while preserving every call\'s parts and shape states; use fewer parts or states, or split the scene'
+    high = max(counts)
+    while low < high:
+        middle = (low + high + 1) // 2
+        if fits(middle): low = middle
+        else: high = middle - 1
+    return (f'use max_faces={low} on each mesh3d/surface3d call to fit {limit} '
+            '(conservative bound if the simplifier reaches each requested face cap; retained-face warnings still apply)')

fluxplot/_viewer/THIRD-PARTY.txt

@@ -0,0 +1,23 @@
+three 0.186.1
+
+The MIT License
+
+Copyright © 2010-2026 three.js authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.