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 +381 -0
- particled/__init__.py +43 -0
- particled/__main__.py +7 -0
- particled/app.py +52 -0
- particled/assets/fonts/JetBrainsMonoNLNerdFont-Regular.ttf +0 -0
- particled/assets/fonts/ShureTechMonoNerdFont-Regular.ttf +0 -0
- particled/audio.py +319 -0
- particled/cli.py +856 -0
- particled/compat.py +443 -0
- particled/config.py +225 -0
- particled/logger.py +321 -0
- particled/visuals/__init__.py +18 -0
- particled/visuals/base.py +314 -0
- particled/visuals/gl_renderer.py +544 -0
- particled/visuals/imgui_overlay.py +306 -0
- particled/visuals/overlay.py +860 -0
- particled/visuals/param_panels.py +335 -0
- particled/visuals/particle_cloud/__init__.py +7 -0
- particled/visuals/particle_cloud/base.py +189 -0
- particled/visuals/particle_cloud/gravitas.py +355 -0
- particled/visuals/particle_cloud/impact.py +152 -0
- particled/visuals/penrose.py +359 -0
- particled/visuals/torus_knot.py +187 -0
- particled-0.9.0.dist-info/METADATA +283 -0
- particled-0.9.0.dist-info/RECORD +28 -0
- particled-0.9.0.dist-info/WHEEL +4 -0
- particled-0.9.0.dist-info/entry_points.txt +3 -0
- particled-0.9.0.dist-info/licenses/LICENSE +21 -0
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
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
|
|
Binary file
|
|
Binary file
|