diffusion-cartogram 0.2.0__tar.gz → 0.2.1__tar.gz

{diffusion_cartogram-0.2.0/diffusion_cartogram.egg-info → diffusion_cartogram-0.2.1}/PKG-INFO

@@ -1,9 +1,29 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: diffusion-cartogram
-Version: 0.2.0
+Version: 0.2.1
 Summary: Volumetric Density-Equalizing Reference Map — 3D shape deformation and 2D cartogram generation
 Author-email: Jonah Spector <spector.jo@northeastern.edu>
-License-Expression: MIT
+License: MIT License
+        
+        Copyright (c) 2026 Jonah Spector
+        
+        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.
 Project-URL: Homepage, https://github.com/jspector792/diffusion-cartogram
 Project-URL: Repository, https://github.com/jspector792/diffusion-cartogram
 Project-URL: Issues, https://github.com/jspector792/diffusion-cartogram/issues
@@ -36,7 +56,6 @@ Requires-Dist: geopandas>=0.12; extra == "all"
 Requires-Dist: rasterio>=1.3; extra == "all"
 Requires-Dist: shapely>=2.0; extra == "all"
 Requires-Dist: pymeshlab>=2023.12; extra == "all"
-Dynamic: license-file
 
 # diffusion-cartogram 
 [![PyPI version](https://badge.fury.io/py/diffusion-cartogram.svg)](https://badge.fury.io/py/diffusion-cartogram)

{diffusion_cartogram-0.2.0 → diffusion_cartogram-0.2.1}/README.md

@@ -253,8 +253,8 @@ If you use this package in academic work, please cite the appropriate original p
 And optionally, this implementation:
 ```bibtex
 @software{vderm2026,
-  title={diffusion-cartogram: A Python implementation of Volumetric Density-Equalizing Reference Map},
-  author={Jonah Spector},
+  title={diffusion-cartogram: A Python package for diffusion deformations in 2 and 3 dimensions},
+  author={Jonah Spector and Albert-László Barabási},
   year={2026},
   url={https://github.com/jspector792/diffusion-cartogram}
 }

{diffusion_cartogram-0.2.0 → diffusion_cartogram-0.2.1}/diffusion_cartogram/__init__.py

@@ -29,13 +29,14 @@ cartogram deformation from GeoJSON / Shapefile inputs.
 >>> vd.plot_map_2d(deformed, title='Population Cartogram')
 """
 
-__version__ = '0.2.0'
+__version__ = '0.2.1'
 
 # Core VDERM classes and algorithms
 from .core import (
     VDERMGrid,
     run_VDERM,
     run_VDERM_with_tracking,
+    animate_surface_posthoc,
 )
 
 # I/O functions
@@ -85,7 +86,8 @@ __all__ = [
     'VDERMGrid',
     'run_VDERM',
     'run_VDERM_with_tracking',
-    
+    'animate_surface_posthoc',
+
     # I/O
     'write_xyz',
     'read_xyz',
@@ -126,6 +128,7 @@ if _has_visualization:
 from .core_2d import (
     VDERMGrid2D,
     run_VDERM_2d_with_tracking,
+    animate_map_posthoc,
 )
 
 # 2-D grid utilities
@@ -172,7 +175,8 @@ __all__ += [
     # 2-D classes and algorithms
     'VDERMGrid2D',
     'run_VDERM_2d_with_tracking',
-    # 2-D grid utilities
+    'animate_map_posthoc',
+# 2-D grid utilities
     'compute_grid_dimensions_2d',
     'make_initial_grid_2d',
     'print_grid_info_2d',

{diffusion_cartogram-0.2.0 → diffusion_cartogram-0.2.1}/diffusion_cartogram/core.py

@@ -1018,7 +1018,172 @@ def run_VDERM_with_tracking(grid, surface_points,
     
     return grid
 
-    
+
+def _interpolate_field_to_points(points, grid_params, field):
+    """Interpolate a scalar field defined on the (L, M, N) grid to arbitrary points."""
+    L, M, N = grid_params['shape']
+    h = grid_params['h']
+    min_bounds = grid_params['min_bounds']
+
+    x = min_bounds[0] + np.arange(L) * h
+    y = min_bounds[1] + np.arange(M) * h
+    z = min_bounds[2] + np.arange(N) * h
+
+    interp = RegularGridInterpolator((x, y, z), field, bounds_error=False, fill_value=0)
+    return interp(points)
+
+
+def animate_surface_posthoc(grid, surface_points, n_frames=30,
+                             output_folder='vderm_posthoc_exports',
+                             initial_densities=None, tau=0.3,
+                             surface_folder='vderm_surface'):
+    """
+    Generate an approximate surface animation from a completed VDERM run
+    without re-running the (expensive) vector-field interpolation at
+    every intermediate step.
+
+    Only the initial and final surfaces are ever interpolated from the
+    grid's displacement field. Intermediate frames are produced by
+    linearly interpolating point positions (and, if provided, densities)
+    between those two surfaces along an eased timescale that starts fast
+    and decelerates (``1 - exp(-t/tau)``), which visually approximates
+    the true VDERM motion (fast initial advection, slowing as the
+    density field equalizes) without needing to know it exactly.
+
+    This is a display tool, not a physically accurate reconstruction of
+    intermediate states — see the warning printed when this function
+    runs, and use ``run_VDERM_with_tracking`` if intermediate accuracy
+    matters.
+
+    Parameters
+    ----------
+    grid : VDERMGrid
+        A grid that has already been deformed (e.g. via run_VDERM or
+        run_VDERM_with_tracking). Its current positions are treated as
+        the final state.
+    surface_points : ndarray, shape (n_points, 3)
+        Original (undeformed) surface point cloud.
+    n_frames : int, default=30
+        Number of frames to export, including the initial and final
+        frames. Must be >= 2.
+    output_folder : str, default='vderm_posthoc_exports'
+        Base directory for exports.
+    initial_densities : callable or ndarray, optional
+        Density field assigned to the grid before deformation, in the
+        same form accepted by ``VDERMGrid.set_density``: either a
+        callable ``density_func(x, y, z) -> density`` or an array of
+        shape (L, M, N). If given, per-point densities are eased from
+        this initial field to the grid's current (final) density field
+        and each frame is colored accordingly. If omitted, every frame
+        is colored using only the final density field.
+    tau : float, default=0.3
+        Time constant of the easing curve ``1 - exp(-t/tau))``, evaluated
+        over a normalized t in [0, 1] and renormalized so the curve runs
+        exactly from 0 to 1. Smaller values front-load more of the motion
+        into the earliest frames.
+    surface_folder : str, default='vderm_surface'
+        Subfolder (under output_folder) that exports are written to.
+        Matches the default subfolder expected by
+        ``animate_surface_deformation``, so the output of this function
+        can be fed directly into it.
+
+    Returns
+    -------
+    frame_paths : list of str
+        Paths to the exported .xyz files, in frame order.
+
+    Notes
+    -----
+    Exported files use the same 7-column (x y z n_x n_y n_z rho) format
+    as run_VDERM_with_tracking's surface exports, and the same
+    'surface_iteration_NNNN.xyz' / 'surface_final_iteration_NNNN.xyz'
+    naming convention, so they can be visualized with
+    animate_surface_deformation() without any extra arguments. The
+    normal-vector columns are not real per-frame velocities (none are
+    computed in this approximation) — they hold the net displacement
+    direction of each point, provided only so downstream tools that
+    expect a normals column keep working.
+
+    Examples
+    --------
+    >>> final_grid = vd.run_VDERM(grid, n_max=500)
+    >>> vd.animate_surface_posthoc(final_grid, points, n_frames=40,
+    ...                            output_folder='my_deformation_posthoc',
+    ...                            initial_densities=head_density)
+    >>> vd.animate_surface_deformation('my_deformation_posthoc')
+    """
+    print("=" * 70)
+    print("POST-HOC ANIMATION NOTICE")
+    print("=" * 70)
+    print("This post-hoc animation tool is meant for display purposes only and")
+    print("may not be faithful to the real deformation during intermediate")
+    print("steps. If you are interested in viewing the process of the real")
+    print("deformation, use the run_VDERM_with_tracking function, which is")
+    print("slower, but is guaranteed to be accurate at each frame.")
+    print("=" * 70)
+
+    if n_frames < 2:
+        raise ValueError("n_frames must be >= 2 (need at least an initial and final frame)")
+    if tau <= 0:
+        raise ValueError(f"tau must be > 0, got {tau}")
+
+    out_dir = os.path.join(output_folder, surface_folder)
+    os.makedirs(out_dir, exist_ok=True)
+
+    params = {'shape': (grid.L, grid.M, grid.N), 'h': grid.h, 'min_bounds': grid.min_bounds}
+    displacement_field = grid.get_displacement_field()
+
+    initial_surface = surface_points
+    final_surface = interpolate_to_surface(surface_points, params, displacement_field)
+    net_displacement = final_surface - initial_surface
+
+    # Eased timescale: fast at first, decelerating; renormalized to hit exactly 0 and 1
+    t = np.linspace(0.0, 1.0, n_frames)
+    ease = (1.0 - np.exp(-t / tau))
+    ease = ease / ease[-1]
+
+    final_surface_densities = interpolate_densities(surface_points, grid)
+
+    if initial_densities is not None:
+        if callable(initial_densities):
+            xs = grid.min_bounds[0] + np.arange(grid.L) * grid.h
+            ys = grid.min_bounds[1] + np.arange(grid.M) * grid.h
+            zs = grid.min_bounds[2] + np.arange(grid.N) * grid.h
+            initial_rho = np.zeros_like(grid.rho)
+            for i, x in enumerate(xs):
+                for j, y in enumerate(ys):
+                    for k, z in enumerate(zs):
+                        initial_rho[i, j, k] = initial_densities(x, y, z)
+        else:
+            initial_rho = np.asarray(initial_densities, dtype=float)
+            if initial_rho.shape != grid.rho.shape:
+                raise ValueError(
+                    f"initial_densities array shape {initial_rho.shape} must match "
+                    f"grid shape {grid.rho.shape}"
+                )
+        initial_surface_densities = _interpolate_field_to_points(surface_points, params, initial_rho)
+    else:
+        initial_surface_densities = final_surface_densities
+
+    frame_paths = []
+    for frame_idx, alpha in enumerate(ease):
+        positions_i = initial_surface + alpha * net_displacement
+        densities_i = initial_surface_densities + alpha * (final_surface_densities - initial_surface_densities)
+
+        if frame_idx == n_frames - 1:
+            filename = f'surface_final_iteration_{frame_idx:04d}.xyz'
+        else:
+            filename = f'surface_iteration_{frame_idx:04d}.xyz'
+
+        filepath = os.path.join(out_dir, filename)
+        write_xyz(filepath, positions_i, normals=net_displacement, densities=densities_i)
+        frame_paths.append(filepath)
+
+    print(f"\n{n_frames} post-hoc animation frames saved to: {out_dir}/")
+
+    return frame_paths
+
+
 def interpolate_densities(surface_points, grid):
     """
     Interpolate density values from grid to surface points.

{diffusion_cartogram-0.2.0 → diffusion_cartogram-0.2.1}/diffusion_cartogram/core_2d.py

@@ -829,3 +829,163 @@ def run_VDERM_2d_with_tracking(
             print(f"  Map point states (x y rho): {map_folder}/")
 
     return grid
+
+
+def _interpolate_field_to_points_2d(points, grid_params, field):
+    """Interpolate a scalar field defined on the (L, M) grid to arbitrary points."""
+    L, M = grid_params['shape']
+    h = grid_params['h']
+    mb = grid_params['min_bounds']
+
+    x = mb[0] + np.arange(L) * h
+    y = mb[1] + np.arange(M) * h
+
+    interp = RegularGridInterpolator((x, y), field, bounds_error=False, fill_value=0.0)
+    return interp(points)
+
+
+def animate_map_posthoc(grid, map_points, n_frames=30,
+                         output_folder='vderm_2d_posthoc_exports',
+                         initial_densities=None, tau=0.3,
+                         map_folder='vderm_map'):
+    """
+    Generate an approximate 2-D map animation from a completed VDERM run
+    without re-running the (expensive) vector-field interpolation at
+    every intermediate step.
+
+    Mirrors animate_surface_posthoc() from core.py — only the initial and
+    final map states are ever interpolated from the grid's displacement
+    field. Intermediate frames are produced by linearly interpolating
+    point positions (and, if provided, densities) between those two
+    states along an eased timescale that starts fast and decelerates
+    (``1 - exp(-t/tau)``), approximating the true VDERM motion (fast
+    initial advection, slowing as the density field equalizes).
+
+    This is a display tool, not a physically accurate reconstruction of
+    intermediate states — see the warning printed when this function
+    runs, and use ``run_VDERM_2d_with_tracking`` if intermediate accuracy
+    matters.
+
+    Parameters
+    ----------
+    grid : VDERMGrid2D
+        A grid that has already been deformed (e.g. via run_VDERM or
+        run_VDERM_2d_with_tracking). Its current positions are treated
+        as the final state.
+    map_points : ndarray, shape (n_points, 2)
+        Original (undeformed) map point set.
+    n_frames : int, default=30
+        Number of frames to export, including the initial and final
+        frames. Must be >= 2.
+    output_folder : str, default='vderm_2d_posthoc_exports'
+        Base directory for exports.
+    initial_densities : callable or ndarray, optional
+        Density field assigned to the grid before deformation, in the
+        same form accepted by ``VDERMGrid2D.set_density``: either a
+        callable ``density_func(x, y) -> density`` or an array of shape
+        (L, M). If given, per-point densities are eased from this
+        initial field to the grid's current (final) density field and
+        each frame is colored accordingly. If omitted, frames are
+        exported without a density column.
+    tau : float, default=0.3
+        Time constant of the easing curve ``1 - exp(-t/tau)``, evaluated
+        over a normalized t in [0, 1] and renormalized so the curve runs
+        exactly from 0 to 1. Smaller values front-load more of the motion
+        into the earliest frames.
+    map_folder : str, default='vderm_map'
+        Subfolder (under output_folder) that exports are written to.
+        Matches the default subfolder expected by
+        ``animate_map_deformation_2d``, so the output of this function
+        can be fed directly into it.
+
+    Returns
+    -------
+    frame_paths : list of str
+        Paths to the exported .csv files, in frame order.
+
+    Notes
+    -----
+    Exported files use the same CSV format ('x y' or 'x y rho') and the
+    same 'map_iteration_NNNN.csv' / 'map_final_iteration_NNNN.csv' naming
+    convention as run_VDERM_2d_with_tracking's map exports, so they can be
+    visualized with animate_map_deformation_2d() without any extra
+    arguments.
+
+    Examples
+    --------
+    >>> final_grid = vd.run_VDERM(grid, n_max=500)
+    >>> vd.animate_map_posthoc(final_grid, pts, n_frames=40,
+    ...                        output_folder='my_cartogram_posthoc',
+    ...                        initial_densities=grid.rho.copy())
+    >>> vd.animate_map_deformation_2d('my_cartogram_posthoc')
+    """
+    print("=" * 70)
+    print("POST-HOC ANIMATION NOTICE")
+    print("=" * 70)
+    print("This post-hoc animation tool is meant for display purposes only and")
+    print("may not be faithful to the real deformation during intermediate")
+    print("steps. If you are interested in viewing the process of the real")
+    print("deformation, use the run_VDERM_2d_with_tracking function, which is")
+    print("slower, but is guaranteed to be accurate at each frame.")
+    print("=" * 70)
+
+    if n_frames < 2:
+        raise ValueError("n_frames must be >= 2 (need at least an initial and final frame)")
+    if tau <= 0:
+        raise ValueError(f"tau must be > 0, got {tau}")
+
+    out_dir = os.path.join(output_folder, map_folder)
+    os.makedirs(out_dir, exist_ok=True)
+
+    params = {'shape': (grid.L, grid.M), 'h': grid.h, 'min_bounds': grid.min_bounds}
+    displacement_field = grid.get_displacement_field()
+
+    initial_map = map_points
+    final_map = interpolate_to_map_2d(map_points, params, displacement_field)
+
+    # Eased timescale: fast at first, decelerating; renormalized to hit exactly 0 and 1
+    t = np.linspace(0.0, 1.0, n_frames)
+    ease = (1.0 - np.exp(-t / tau))
+    ease = ease / ease[-1]
+
+    have_densities = initial_densities is not None
+    if have_densities:
+        final_map_densities = interpolate_densities_2d(map_points, grid)
+
+        if callable(initial_densities):
+            xs = grid.min_bounds[0] + np.arange(grid.L) * grid.h
+            ys = grid.min_bounds[1] + np.arange(grid.M) * grid.h
+            initial_rho = np.zeros_like(grid.rho)
+            for i, x in enumerate(xs):
+                for j, y in enumerate(ys):
+                    initial_rho[i, j] = initial_densities(x, y)
+        else:
+            initial_rho = np.asarray(initial_densities, dtype=float)
+            if initial_rho.shape != grid.rho.shape:
+                raise ValueError(
+                    f"initial_densities array shape {initial_rho.shape} must match "
+                    f"grid shape {grid.rho.shape}"
+                )
+        initial_map_densities = _interpolate_field_to_points_2d(map_points, params, initial_rho)
+
+    frame_paths = []
+    for frame_idx, alpha in enumerate(ease):
+        positions_i = initial_map + alpha * (final_map - initial_map)
+
+        if have_densities:
+            densities_i = initial_map_densities + alpha * (final_map_densities - initial_map_densities)
+        else:
+            densities_i = None
+
+        if frame_idx == n_frames - 1:
+            filename = f'map_final_iteration_{frame_idx:04d}.csv'
+        else:
+            filename = f'map_iteration_{frame_idx:04d}.csv'
+
+        filepath = os.path.join(out_dir, filename)
+        write_csv_2d(filepath, positions_i, densities_i)
+        frame_paths.append(filepath)
+
+    print(f"\n{n_frames} post-hoc animation frames saved to: {out_dir}/")
+
+    return frame_paths

{diffusion_cartogram-0.2.0 → diffusion_cartogram-0.2.1/diffusion_cartogram.egg-info}/PKG-INFO

@@ -1,9 +1,29 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: diffusion-cartogram
-Version: 0.2.0
+Version: 0.2.1
 Summary: Volumetric Density-Equalizing Reference Map — 3D shape deformation and 2D cartogram generation
 Author-email: Jonah Spector <spector.jo@northeastern.edu>
-License-Expression: MIT
+License: MIT License
+        
+        Copyright (c) 2026 Jonah Spector
+        
+        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.
 Project-URL: Homepage, https://github.com/jspector792/diffusion-cartogram
 Project-URL: Repository, https://github.com/jspector792/diffusion-cartogram
 Project-URL: Issues, https://github.com/jspector792/diffusion-cartogram/issues
@@ -36,7 +56,6 @@ Requires-Dist: geopandas>=0.12; extra == "all"
 Requires-Dist: rasterio>=1.3; extra == "all"
 Requires-Dist: shapely>=2.0; extra == "all"
 Requires-Dist: pymeshlab>=2023.12; extra == "all"
-Dynamic: license-file
 
 # diffusion-cartogram 
 [![PyPI version](https://badge.fury.io/py/diffusion-cartogram.svg)](https://badge.fury.io/py/diffusion-cartogram)

{diffusion_cartogram-0.2.0 → diffusion_cartogram-0.2.1}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "diffusion-cartogram"
-version = "0.2.0"
+version = "0.2.1"
 description = "Volumetric Density-Equalizing Reference Map — 3D shape deformation and 2D cartogram generation"
 readme = "README_pypi.md"
 requires-python = ">=3.8"
-license = "MIT"
+license = {file = "LICENSE"}
 authors = [
     {name = "Jonah Spector", email = "spector.jo@northeastern.edu"}
 ]