particled 0.9.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
particled/README.md ADDED
@@ -0,0 +1,381 @@
1
+ # Particled Package Structure
2
+
3
+ This package contains the audio-reactive particle visualizer, now organized into modular components with multiple visualization styles.
4
+
5
+ ## Directory Structure
6
+
7
+ ```
8
+ particled/
9
+ ├── __init__.py # Package initialization, exports main classes
10
+ ├── config.py # Configuration dataclass
11
+ ├── audio.py # Audio input processing (AudioMeter)
12
+ ├── cli.py # Interactive CLI configuration
13
+ └── visuals/ # Visualization modules
14
+ ├── __init__.py # Visuals package exports
15
+ ├── base.py # Base visualization utilities and abstract class
16
+ ├── particle_cloud/ # Particle Cloud modes
17
+ │ ├── __init__.py # Particle Cloud exports
18
+ │ ├── base.py # Shared Particle Cloud functionality
19
+ │ ├── impact.py # Impact mode (breathing animation)
20
+ │ └── gravitas.py # Gravitas mode (physics-based expansion)
21
+ └── torus_knot.py # Torus Knot visualization
22
+
23
+ ../main.py # Application entry point
24
+ ```
25
+
26
+ ## Modules
27
+
28
+ ### `config.py`
29
+ Contains the `Config` dataclass with all visualization parameters:
30
+ - Window settings
31
+ - Particle geometry parameters
32
+ - Motion and rotation settings
33
+ - Audio reactivity settings
34
+ - Visual style settings
35
+ - Audio input settings
36
+ - Particle Cloud specific parameters
37
+ - Gravitas mode specific parameters (push strength, return mechanics, frequency bands)
38
+ - Torus Knot specific parameters
39
+
40
+ ### `audio.py`
41
+ Contains the `AudioMeter` class for real-time audio input processing:
42
+ - Background microphone monitoring
43
+ - RMS level calculation
44
+ - Smoothed audio level output
45
+
46
+ ### `visuals/base.py`
47
+ Contains the base visualization infrastructure:
48
+ - `BaseVisualization`: Abstract base class for all visualizations
49
+ - `_project_to_screen()`: Shared 3D to 2D projection with FOV
50
+ - `_compute_brightness()`: Gamma-corrected brightness calculation
51
+ - `_render_points()`: Shared pygame rendering logic
52
+ - `draw()`: Abstract method for visualization implementations
53
+ - `fade_surface()`: Motion trail effect utility
54
+
55
+ ### `visuals/torus_knot.py`
56
+ Contains the `TorusKnotField` visualization:
57
+ - Complex mathematical knot patterns
58
+ - Methods:
59
+ - `_compute_torus_knot_positions()`: Base 3D torus-knot geometry
60
+ - `_apply_distortion()`: Audio-driven wobble effects
61
+ - `_rotate_3d()`: 3D rotations around X and Y axes
62
+ - `_compute_sizes()`: Brightness-based particle sizing
63
+ - `draw()`: Main orchestration method
64
+
65
+ ### `visuals/particle_cloud/`
66
+ Package containing Particle Cloud visualization modes with shared base functionality.
67
+
68
+ #### `visuals/particle_cloud/base.py`
69
+ Contains `ParticleCloudBase` - shared functionality for all Particle Cloud modes:
70
+ - Gaussian spherical particle distribution
71
+ - Phase offset generation for drift animations
72
+ - Density weight calculation
73
+ - Common rotation and sizing methods
74
+ - Methods:
75
+ - `_initialize_base_particles()`: Creates base spherical distribution
76
+ - `_apply_rotation()`: Rotation around X and Y axes
77
+ - `_compute_sizes()`: Density-based particle sizing
78
+
79
+ #### `visuals/particle_cloud/impact.py`
80
+ Contains `ParticleCloudImpact` visualization:
81
+ - Dense particle cloud with soft, nebula-like density gradient
82
+ - Whole-cloud breathing animation with audio reactivity
83
+ - Pure white particles on black background
84
+ - Methods:
85
+ - `_apply_gentle_motion()`: Drift and breathing animation
86
+ - `_compute_sizes_with_audio()`: Audio-reactive particle sizing
87
+ - `draw()`: Main orchestration method
88
+
89
+ #### `visuals/particle_cloud/gravitas.py`
90
+ Contains `ParticleCloudGravitas` visualization:
91
+ - Gravity-centered particle cloud with outward expansion on audio impact
92
+ - Three configurable return mechanics (spring/linear/exponential)
93
+ - Frequency-based particle mapping (bass/mid/treble)
94
+ - Idle behavior with drift and rotation only (no breathing)
95
+ - Audio noise threshold to prevent ambient sound jitter
96
+ - Methods:
97
+ - `_initialize_particles()`: Spherical cloud with displacement tracking
98
+ - `_apply_audio_push()`: Radial push from center based on audio
99
+ - `_apply_return_mechanic()`: Return-to-center physics
100
+ - `_apply_spring_return()`: Spring oscillation mechanics
101
+ - `_apply_linear_return()`: Linear damped return
102
+ - `_apply_exponential_return()`: Exponential decay return
103
+ - `_apply_idle_motion()`: Gentle drift without breathing
104
+ - `draw()`: Main orchestration method
105
+
106
+ ### `cli.py`
107
+ Contains interactive configuration functions:
108
+ - `get_visualization_style()`: Select between visualization styles
109
+ - `get_particle_cloud_mode()`: Select between Gravitas and Impact modes
110
+ - `configure_gravitas()`: Gravitas mode specific configuration
111
+ - `configure_impact()`: Impact mode specific configuration
112
+ - `configure_torus_knot()`: Torus Knot specific configuration
113
+ - `configure_interactively()`: Routes to style and mode-specific configuration
114
+ - `prompt_for_interactive_config()`: Ask user for interactive mode
115
+
116
+ ### `../main.py`
117
+ Application entry point that:
118
+ - Prompts user to select visualization style ("Torus Knot" or "Particle Cloud")
119
+ - For Particle Cloud, prompts to select mode ("Gravitas" or "Impact")
120
+ - Prompts for interactive or default configuration
121
+ - Initializes pygame window with resizable support
122
+ - Sets up the selected visualization and audio meter
123
+ - Runs the main event loop with keyboard (ESC) and window controls
124
+ - Handles window resize events dynamically
125
+ - Displays mode name in window caption if applicable
126
+
127
+ ## Usage
128
+
129
+ ### Running the Application
130
+
131
+ Execute the visualizer from the command line:
132
+
133
+ ```bash
134
+ # From the project root directory
135
+ python main.py
136
+ ```
137
+
138
+ Or using poetry:
139
+
140
+ ```bash
141
+ poetry run python main.py
142
+ ```
143
+
144
+ The application will prompt you to:
145
+ 1. **Select visualization style**: Choose between "Torus Knot" (complex mathematical patterns) or "Particle Cloud" (nebula-like density gradient)
146
+ 2. **Select Particle Cloud mode** (if applicable): Choose between "Gravitas" (physics-based expansion) or "Impact" (breathing animation)
147
+ 3. **Configure parameters**: Optionally customize parameters interactively
148
+
149
+ ### Visualization Styles
150
+
151
+ #### Torus Knot
152
+ Complex mathematical knot patterns with intricate 3D geometry. Features:
153
+ - Dynamic torus-knot mathematics
154
+ - Audio-driven distortion and rotation
155
+ - Configurable knot complexity (μ and ν parameters)
156
+
157
+ #### Particle Cloud
158
+ Minimal, nebula-like particle cloud with soft density gradients. Two distinct modes:
159
+
160
+ ##### Gravitas Mode (Default)
161
+ Gravity-centered particle physics with audio-reactive expansion:
162
+ - **Audio Reactivity**: Particles push radially outward from center on audio impact
163
+ - **Audio Threshold**: Configurable noise baseline (default: 0.05) prevents ambient jitter
164
+ - **Return Mechanics**: Three configurable physics models:
165
+ - **Exponential** (default): Fast-then-slow natural decay (organic feel)
166
+ - **Spring**: Bouncy oscillation with overshoot (lively, dynamic)
167
+ - **Linear**: Constant-speed damped return (predictable, smooth)
168
+ - **Frequency Mapping**: Particles respond based on radial distance:
169
+ - Bass band (0.0-0.3): Outer particles, 70% base + 30% audio response
170
+ - Mid band (0.3-0.7): Middle particles, 100% audio response
171
+ - Treble band (0.7-1.0): Inner particles, 50% base + 50% audio response
172
+ - **Idle Motion**: Gentle drift and rotation only (no breathing)
173
+
174
+ ##### Impact Mode
175
+ Whole-cloud breathing animation with soft expansion:
176
+ - Gaussian spherical distribution for natural density falloff
177
+ - Gentle breathing and drift animations
178
+ - Audio-reactive size and motion with configurable boost
179
+ - Pure white particles on black background for a clean aesthetic
180
+
181
+ ### Using as a Library
182
+
183
+ ```python
184
+ from particled import (
185
+ AudioMeter,
186
+ Config,
187
+ ParticleCloudGravitas,
188
+ ParticleCloudImpact,
189
+ TorusKnotField,
190
+ )
191
+ from particled.cli import configure_interactively, prompt_for_interactive_config
192
+ from particled.visuals import fade_surface
193
+
194
+ # Use default configuration
195
+ config = Config()
196
+
197
+ # Or use interactive configuration with style-specific parameters
198
+ style = "Particle Cloud" # or "Torus Knot"
199
+ config, mode = configure_interactively(style) # Returns (config, mode)
200
+
201
+ # Create a visualization
202
+ torus_field = TorusKnotField(config)
203
+ # or
204
+ gravitas_cloud = ParticleCloudGravitas(config)
205
+ # or
206
+ impact_cloud = ParticleCloudImpact(config)
207
+
208
+ # Programmatic Gravitas configuration example
209
+ config = Config()
210
+ config.audio_noise_threshold = 0.05
211
+ config.gravitas_push_strength = 2.0
212
+ config.gravitas_return_mechanic = "exponential"
213
+ config.gravitas_exponential_decay_rate = 0.15
214
+
215
+ # For spring mechanic:
216
+ # config.gravitas_return_mechanic = "spring"
217
+ # config.gravitas_spring_strength = 0.5
218
+ # config.gravitas_spring_damping = 0.8
219
+ # config.gravitas_spring_mass = 1.0
220
+
221
+ # Initialize components
222
+ field = ParticleCloudGravitas(config)
223
+ audio_meter = AudioMeter(config)
224
+ ```
225
+
226
+ ## Interactive Configuration Parameters
227
+
228
+ When running with interactive configuration, you can customize parameters specific to your selected visualization style.
229
+
230
+ ### Common Parameters (Both Styles)
231
+
232
+ #### Number of Particles (100-20000, default: 5500)
233
+ Controls the density and detail of the visualization.
234
+ - **Lower values (100-1000)**: Sparse, minimal particle field with visible individual points. Faster performance on slower systems.
235
+ - **Medium values (2000-8000)**: Balanced density with good visual detail and smooth appearance.
236
+ - **Higher values (10000-20000)**: Dense, cloud-like appearance with rich detail. May impact performance.
237
+
238
+ #### Audio Reactivity Gain (0.0-200.0, default: 50.0)
239
+ Amplifies the microphone input's effect on the visualization.
240
+ - **0.0**: No audio reaction - visualization is purely time-based animation.
241
+ - **10-30**: Subtle audio response, gentle pulsing with loud sounds.
242
+ - **40-70**: Moderate response, clear visual reaction to music and speech.
243
+ - **80-120**: Strong response, dramatic changes with audio input.
244
+ - **120-200**: Extreme sensitivity, even quiet sounds cause major visual shifts.
245
+ - **Note**: Higher values may cause clipping; adjust based on your environment's noise level.
246
+
247
+ #### Trail Fade Alpha (0-255, default: 25)
248
+ Controls how quickly particle trails fade, creating motion blur effects.
249
+ - **0**: No fading - particles leave permanent trails, creating a persistent drawing effect. Screen gradually fills with white.
250
+ - **1-10**: Very slow fade - long, flowing trails that persist for seconds. Dreamy, ethereal appearance.
251
+ - **15-40**: Medium fade - balanced trails that show recent motion paths clearly.
252
+ - **50-100**: Fast fade - short trails, snappy motion with minimal blur.
253
+ - **150-254**: Very fast fade - almost no trails, sharp particle positions.
254
+ - **255**: Instant clear - no trails at all, particles disappear immediately. Cleanest, most precise look.
255
+
256
+ #### Brightness Gamma (0.5-3.0, default: 1.8)
257
+ Adjusts the contrast and brightness distribution using gamma correction.
258
+ - **0.5-1.0**: Lower gamma - more even brightness, brings out dimmer particles. Flatter, more uniform appearance.
259
+ - **1.0-1.5**: Balanced - natural brightness distribution with good depth perception.
260
+ - **1.5-2.2**: Enhanced contrast - brighter highlights, darker shadows. More dramatic, punchy look (default: 1.8).
261
+ - **2.2-3.0**: High contrast - extreme brightness variation. Very bright centers fade quickly to dark edges.
262
+
263
+ ### Particle Cloud Specific Parameters
264
+
265
+ Parameters shared across both Impact and Gravitas modes:
266
+
267
+ #### Density Sigma (0.1-5.0, default: 1.0)
268
+ Controls the Gaussian distribution spread of particles (affects density gradient).
269
+ - **0.1-0.5**: Very tight cluster - extremely dense center with sharp falloff. Compact, star-like core.
270
+ - **0.5-1.5**: Moderate spread - soft nebula-like gradient with natural density falloff (default: 1.0).
271
+ - **1.5-3.0**: Wide spread - more diffuse cloud with gentle gradient. Expansive, ethereal appearance.
272
+ - **3.0-5.0**: Very diffuse - particles spread far from center. Sparse, galaxy-like distribution.
273
+
274
+ #### Drift Speed (0.0-1.0, default: 0.1)
275
+ Speed of the gentle, organic drift motion.
276
+ - **0.0**: No drift - particles maintain their base positions.
277
+ - **0.05-0.15**: Slow, subtle drift - barely perceptible organic movement (default: 0.1).
278
+ - **0.2-0.4**: Medium drift - noticeable floating, cloud-like motion.
279
+ - **0.5-1.0**: Fast drift - active swirling and flowing movement.
280
+
281
+ #### Rotation Speed Y-axis (0.0-0.5, default: 0.05)
282
+ Horizontal rotation speed around the Y-axis.
283
+ - **0.0**: No rotation - cloud maintains orientation.
284
+ - **0.01-0.08**: Very slow rotation - subtle spatial awareness (default: 0.05).
285
+ - **0.1-0.2**: Gentle rotation - noticeable but still calm.
286
+ - **0.2-0.5**: Moderate rotation - more dynamic view of the cloud structure.
287
+
288
+ #### Rotation Speed X-axis (0.0-0.5, default: 0.03)
289
+ Vertical rotation speed around the X-axis.
290
+ - **0.0**: No vertical rotation.
291
+ - **0.01-0.05**: Subtle tumbling motion (default: 0.03).
292
+ - **0.05-0.15**: Gentle vertical rotation.
293
+ - **0.15-0.5**: More active vertical tumbling.
294
+
295
+ ### Impact Mode Specific Parameters
296
+
297
+ #### Breathing Speed (0.0-2.0, default: 0.3)
298
+ Speed of the expansion/contraction breathing animation.
299
+ - **0.0**: No breathing - cloud maintains constant size.
300
+ - **0.1-0.4**: Slow breathing - gentle, meditative pulsing (default: 0.3).
301
+ - **0.5-1.0**: Medium breathing - noticeable rhythmic expansion/contraction.
302
+ - **1.0-2.0**: Fast breathing - rapid pulsing, energetic feel.
303
+
304
+ ### Gravitas Mode Specific Parameters
305
+
306
+ #### Audio Noise Threshold (0.0-0.5, default: 0.05)
307
+ Baseline noise level to ignore, preventing jitter from ambient sound.
308
+ - **0.0**: No threshold - all audio input affects particles (may be jittery).
309
+ - **0.02-0.08**: Low threshold - filters quiet ambient noise (default: 0.05).
310
+ - **0.1-0.2**: Medium threshold - requires moderate sound for reaction.
311
+ - **0.3-0.5**: High threshold - only loud sounds trigger particle movement.
312
+
313
+ #### Audio Push Strength (0.5-10.0, default: 2.0)
314
+ Force applied to push particles outward from center on audio impact.
315
+ - **0.5-1.5**: Gentle push - subtle expansion with soft audio response.
316
+ - **1.5-3.0**: Medium push - balanced, noticeable outward movement (default: 2.0).
317
+ - **3.0-5.0**: Strong push - dramatic expansion with audio peaks.
318
+ - **5.0-10.0**: Extreme push - explosive particle dispersion.
319
+
320
+ #### Return Mechanic (exponential/spring/linear, default: exponential)
321
+ Physics model for how particles return to their base positions after push.
322
+
323
+ **Exponential (default)**:
324
+ - Fast-then-slow natural decay for organic feel
325
+ - **Decay Rate** (0.05-0.5, default: 0.15): Controls return speed
326
+ - Lower values = slower, longer-lasting expansion
327
+ - Higher values = faster return to center
328
+
329
+ **Spring**:
330
+ - Bouncy oscillation with overshoot for lively, dynamic movement
331
+ - **Spring Strength** (0.1-2.0, default: 0.5): Force pulling back to center
332
+ - **Spring Damping** (0.1-1.0, default: 0.8): Reduces oscillation amplitude
333
+ - **Spring Mass** (0.1-5.0, default: 1.0): Inertia of particles
334
+
335
+ **Linear**:
336
+ - Constant-speed damped return for predictable, smooth motion
337
+ - **Return Speed** (0.1-1.0, default: 0.3): Speed of return movement
338
+ - **Damping Factor** (0.5-1.0, default: 0.9): Gradual slowdown rate
339
+
340
+ ### Torus Knot Specific Parameters
341
+
342
+ #### Torus Knot Parameter μ (mu) (1-10, default: 2)
343
+ Defines how many times the knot loops around the torus longitudinally.
344
+ - **μ = 1**: Simple ring/circle shape.
345
+ - **μ = 2**: Figure-eight pattern with two loops.
346
+ - **μ = 3-5**: Increasingly complex braided patterns.
347
+ - **μ = 6-10**: Very intricate, highly detailed knot structures.
348
+ - **Note**: The relationship between μ and ν creates the knot's unique topology.
349
+
350
+ #### Torus Knot Parameter ν (nu) (1-10, default: 3)
351
+ Defines how many times the knot loops around the torus meridionally.
352
+ - **ν = 1**: Minimal vertical complexity.
353
+ - **ν = 2-3**: Classic trefoil and cinquefoil knot appearances.
354
+ - **ν = 4-6**: Complex interweaving patterns with multiple crossings.
355
+ - **ν = 7-10**: Extremely intricate structures with many overlapping paths.
356
+ - **Tip**: Try (μ=2, ν=3), (μ=3, ν=2), (μ=3, ν=5), or (μ=5, ν=7) for beautiful patterns.
357
+
358
+ #### Base Rotation Speed Y-axis (0.0-2.0, default: 0.25)
359
+ Controls horizontal (left-right) rotation speed of the entire structure.
360
+ - **0.0**: No horizontal rotation - structure appears stationary side-to-side.
361
+ - **0.1-0.5**: Slow, graceful rotation good for observation and screenshots.
362
+ - **0.5-1.0**: Medium speed rotation providing good spatial awareness.
363
+ - **1.0-2.0**: Fast rotation that emphasizes the 3D nature and creates motion blur effects.
364
+ - **Negative values**: Reverses rotation direction.
365
+
366
+ #### Base Rotation Speed X-axis (0.0-2.0, default: 0.13)
367
+ Controls vertical (up-down) rotation speed of the entire structure.
368
+ - **0.0**: No vertical rotation - structure maintains fixed vertical orientation.
369
+ - **0.1-0.3**: Subtle tumbling motion that reveals vertical complexity.
370
+ - **0.3-0.8**: Noticeable tumbling that shows all angles of the structure.
371
+ - **0.8-2.0**: Rapid spinning that creates dynamic, ever-changing views.
372
+ - **Tip**: Different X and Y speeds create complex Lissajous-like rotation patterns.
373
+
374
+ ### Brightness Gamma (0.5-3.0, default: 1.8)
375
+ Adjusts the contrast and brightness distribution based on particle depth.
376
+ - **0.5-0.9**: Low contrast - particles at all depths appear similarly bright, flat appearance.
377
+ - **1.0**: Linear brightness - natural depth perception without enhancement.
378
+ - **1.2-1.8**: Medium enhancement - good depth perception with brighter foreground.
379
+ - **1.9-2.5**: High contrast - dramatic depth, distant particles very dim, close ones very bright.
380
+ - **2.6-3.0**: Extreme contrast - only nearest particles visible, creates sharp focus effect.
381
+ - **Effect**: Higher values make the structure appear more three-dimensional with dramatic lighting.
particled/__init__.py ADDED
@@ -0,0 +1,43 @@
1
+ """Particled - Audio Reactive Particle Visualizer."""
2
+
3
+ import os
4
+ from importlib import import_module
5
+ from typing import TYPE_CHECKING, Any
6
+
7
+ # Suppress pygame welcome message
8
+ os.environ["PYGAME_HIDE_SUPPORT_PROMPT"] = "1"
9
+
10
+ if TYPE_CHECKING:
11
+ from particled.audio import AudioMeter
12
+ from particled.config import Config
13
+ from particled.visuals import (
14
+ BaseVisualization,
15
+ ParticleCloudGravitas,
16
+ ParticleCloudImpact,
17
+ TorusKnotField,
18
+ )
19
+
20
+ __all__ = [
21
+ "AudioMeter",
22
+ "BaseVisualization",
23
+ "Config",
24
+ "ParticleCloudGravitas",
25
+ "ParticleCloudImpact",
26
+ "TorusKnotField",
27
+ ]
28
+
29
+
30
+ def __getattr__(name: str) -> Any:
31
+ """Lazily resolve public API symbols to avoid heavyweight import side effects."""
32
+ if name == "Config":
33
+ return import_module("particled.config").Config
34
+ if name == "AudioMeter":
35
+ return import_module("particled.audio").AudioMeter
36
+ if name in {
37
+ "BaseVisualization",
38
+ "ParticleCloudGravitas",
39
+ "ParticleCloudImpact",
40
+ "TorusKnotField",
41
+ }:
42
+ return getattr(import_module("particled.visuals"), name)
43
+ raise AttributeError(f"module 'particled' has no attribute {name!r}")
particled/__main__.py ADDED
@@ -0,0 +1,7 @@
1
+ """python -m particled launcher."""
2
+
3
+ from particled.app import main
4
+
5
+
6
+ if __name__ == "__main__":
7
+ raise SystemExit(main())
particled/app.py ADDED
@@ -0,0 +1,52 @@
1
+ """Command-line entry point for particled."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+
7
+
8
+ VERSION = "0.1.0"
9
+
10
+
11
+ def _build_parser() -> argparse.ArgumentParser:
12
+ parser = argparse.ArgumentParser(
13
+ prog="particled",
14
+ description="Audio-reactive particle visualizer",
15
+ )
16
+ parser.add_argument(
17
+ "--version",
18
+ action="version",
19
+ version=f"particled {VERSION}",
20
+ )
21
+ parser.add_argument(
22
+ "-s",
23
+ "--selective",
24
+ action="store_true",
25
+ help="Interactively select style and configure parameters before starting",
26
+ )
27
+ return parser
28
+
29
+
30
+ def main(argv: list[str] | None = None) -> int:
31
+ """Run the particled application entry point."""
32
+ parser = _build_parser()
33
+ args = parser.parse_args(argv)
34
+
35
+ # Import heavyweight rendering/audio modules only when actually running.
36
+ from main import main as run_main
37
+
38
+ run_main_args = []
39
+ if args.selective:
40
+ run_main_args.append("--selective")
41
+
42
+ # main.py parses sys.argv internally; patch argv-style behavior by reusing
43
+ # subprocess-free invocation through argparse-compatible globals.
44
+ import sys
45
+
46
+ old_argv = sys.argv
47
+ try:
48
+ sys.argv = [old_argv[0], *run_main_args]
49
+ run_main()
50
+ finally:
51
+ sys.argv = old_argv
52
+ return 0