cicadc 0.1.0__tar.gz

cicadc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carsten Wulff Software, Norway
+
+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.

cicadc-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: cicadc
+Version: 0.1.0
+Summary: Interactive PySide6 + manim demonstration of how an ADC works
+Author-email: Carsten Wulff <carsten@wulff.no>
+License: MIT
+Project-URL: Homepage, https://github.com/wulffern/cicadc
+Project-URL: Bug Tracker, https://github.com/wulffern/cicadc/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: manim
+Requires-Dist: PySide6
+Requires-Dist: click
+Dynamic: license-file
+
+# cicadc
+
+An interactive desktop program that demonstrates how an analog-to-digital
+converter (ADC) works. It shows two side-by-side panels rendered with
+[manim](https://www.manim.community/) inside a [PySide6](https://doc.qt.io/qtforpython-6/)
+window:
+
+- **Left panel (analog)** - the analog signal drawn as a path that scrolls past
+  "now" (the middle line), with the future at the top and the past at the
+  bottom. Optional noise is added. A blue car drives along the signal and turns
+  to follow the path; a translucent gray "shadow" car marks the quantized value.
+- **Right panel (digital)** - the digital signal as a sample-and-hold staircase.
+  Gray is the unfiltered (raw) quantizer output and green is the optional
+  moving-average filtered output (normalised to unity gain at the signal
+  frequency). A green car follows the filtered output, trailing by the filter's
+  group delay so it lands back on the analog curve (delay-compensated).
+
+## Project layout
+
+```
+src/cicadc/          package (src layout, mirrors cicwave)
+  cli.py             click console entry point (`cicadc`)
+  app.py             QApplication bootstrap
+  main_window.py     PySide6 window + controls
+  manim_scene.py     offscreen manim renderer
+  signal_source.py   analog signal model (sinusoid + noise)
+  quantizer.py       N-bit quantizer
+  render_widget.py   Qt widget + animation loop
+  assets/car.png     car sprite
+tests/unittests/     unittest suite
+```
+
+## Requirements
+
+- Python 3.9-3.13 (manim does not yet support 3.14). A `python3.12` venv is used
+  by the setup steps below.
+- A working manim install (Cairo backend). On macOS you may need the system
+  libraries `pkg-config cairo pango` via Homebrew if the wheels do not cover your
+  platform.
+
+## Setup
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -e .          # or: pip install -r requirements.txt
+```
+
+`make dev-install` runs the editable install for you.
+
+## Run
+
+```bash
+cicadc                   # installed console script
+# or, from a checkout without installing:
+python main.py
+```
+
+## Controls
+
+- **Frequency / Amplitude** - the input sinusoid (amplitude is a fraction of full scale).
+- **Speed** - how fast the signal scrolls past "now".
+- **Bits** - resolution of the quantizer.
+- **Sample period** - the ADC sample clock interval.
+- **Noise** - additive analog noise amplitude.
+- **Avg** - moving-average filter length on the digital output (1 = off).
+- **Play / Pause** - start or stop the animation.
+
+## Development
+
+```bash
+make test     # run unit tests
+make check    # import and print version
+make lint     # ruff (if installed)
+make build    # build wheel + sdist
+```
+
+## Acknowledgements
+
+Big thanks to **Domen Visnar** for the idea behind this project!
+
+## Status
+
+Single/− sinusoid input, adjustable bit depth, noise, and a normalised
+moving-average filter with delay compensation are implemented. Random /
+multi-sinusoid inputs and a configurable bandwidth filter are planned follow-ups.

cicadc-0.1.0/README.md

@@ -0,0 +1,86 @@
+# cicadc
+
+An interactive desktop program that demonstrates how an analog-to-digital
+converter (ADC) works. It shows two side-by-side panels rendered with
+[manim](https://www.manim.community/) inside a [PySide6](https://doc.qt.io/qtforpython-6/)
+window:
+
+- **Left panel (analog)** - the analog signal drawn as a path that scrolls past
+  "now" (the middle line), with the future at the top and the past at the
+  bottom. Optional noise is added. A blue car drives along the signal and turns
+  to follow the path; a translucent gray "shadow" car marks the quantized value.
+- **Right panel (digital)** - the digital signal as a sample-and-hold staircase.
+  Gray is the unfiltered (raw) quantizer output and green is the optional
+  moving-average filtered output (normalised to unity gain at the signal
+  frequency). A green car follows the filtered output, trailing by the filter's
+  group delay so it lands back on the analog curve (delay-compensated).
+
+## Project layout
+
+```
+src/cicadc/          package (src layout, mirrors cicwave)
+  cli.py             click console entry point (`cicadc`)
+  app.py             QApplication bootstrap
+  main_window.py     PySide6 window + controls
+  manim_scene.py     offscreen manim renderer
+  signal_source.py   analog signal model (sinusoid + noise)
+  quantizer.py       N-bit quantizer
+  render_widget.py   Qt widget + animation loop
+  assets/car.png     car sprite
+tests/unittests/     unittest suite
+```
+
+## Requirements
+
+- Python 3.9-3.13 (manim does not yet support 3.14). A `python3.12` venv is used
+  by the setup steps below.
+- A working manim install (Cairo backend). On macOS you may need the system
+  libraries `pkg-config cairo pango` via Homebrew if the wheels do not cover your
+  platform.
+
+## Setup
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -e .          # or: pip install -r requirements.txt
+```
+
+`make dev-install` runs the editable install for you.
+
+## Run
+
+```bash
+cicadc                   # installed console script
+# or, from a checkout without installing:
+python main.py
+```
+
+## Controls
+
+- **Frequency / Amplitude** - the input sinusoid (amplitude is a fraction of full scale).
+- **Speed** - how fast the signal scrolls past "now".
+- **Bits** - resolution of the quantizer.
+- **Sample period** - the ADC sample clock interval.
+- **Noise** - additive analog noise amplitude.
+- **Avg** - moving-average filter length on the digital output (1 = off).
+- **Play / Pause** - start or stop the animation.
+
+## Development
+
+```bash
+make test     # run unit tests
+make check    # import and print version
+make lint     # ruff (if installed)
+make build    # build wheel + sdist
+```
+
+## Acknowledgements
+
+Big thanks to **Domen Visnar** for the idea behind this project!
+
+## Status
+
+Single/− sinusoid input, adjustable bit depth, noise, and a normalised
+moving-average filter with delay compensation are implemented. Random /
+multi-sinusoid inputs and a configurable bandwidth filter are planned follow-ups.

cicadc-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cicadc"
+version = "0.1.0"
+authors = [
+  { name="Carsten Wulff", email="carsten@wulff.no" },
+]
+dependencies = [
+    "numpy",       # Core data arrays
+    "scipy",       # Signal processing (filters)
+    "manim",       # Animation / rendering engine
+    "PySide6",     # Qt6 GUI framework
+    "click",       # CLI parsing
+]
+description = "Interactive PySide6 + manim demonstration of how an ADC works"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Education",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.scripts]
+cicadc = "cicadc.cli:main"
+
+[project.gui-scripts]
+cicadcw = "cicadc.cli:main"  # Windows no-console wrapper
+
+[project.urls]
+"Homepage" = "https://github.com/wulffern/cicadc"
+"Bug Tracker" = "https://github.com/wulffern/cicadc/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cicadc = ["assets/*.png"]

cicadc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cicadc-0.1.0/src/cicadc/__init__.py

@@ -0,0 +1,19 @@
+"""cicadc - an interactive PySide6 + manim demonstration of how an ADC works.
+
+Two side-by-side panels visualise analog-to-digital conversion: a scrolling
+analog signal (with optional noise) on the left and the resulting digital
+signal on the right, with an optional moving-average filter, quantization
+shadow, and little cars that drive along the signal paths.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Carsten Wulff"
+__email__ = "carsten@wulff.no"
+
+__all__ = [
+    "SignalSource",
+    "Quantizer",
+]
+
+from .signal_source import SignalSource
+from .quantizer import Quantizer

cicadc-0.1.0/src/cicadc/app.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+######################################################################
+##        Copyright (c) 2026 Carsten Wulff Software, Norway
+## ###################################################################
+##  The MIT License (MIT)
+##
+##  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.
+######################################################################
+"""Qt application bootstrap for the cicadc GUI."""
+
+from __future__ import annotations
+
+import sys
+
+
+def run() -> int:
+    """Create the QApplication, show the main window, and run the event loop."""
+    from PySide6.QtWidgets import QApplication
+
+    from .main_window import MainWindow
+
+    app = QApplication.instance() or QApplication(sys.argv)
+    window = MainWindow()
+    window.show()
+    return app.exec()

cicadc-0.1.0/src/cicadc/cli.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+######################################################################
+##        Copyright (c) 2026 Carsten Wulff Software, Norway
+## ###################################################################
+##  The MIT License (MIT)
+##
+##  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.
+######################################################################
+"""cicadc command-line entry point."""
+
+from __future__ import annotations
+
+import logging
+
+import click
+
+from .command import setup_logging
+
+
+@click.command()
+@click.option("--color/--no-color", default=True, help="Enable/disable color output")
+@click.option("--debug", is_flag=True, default=False, help="Enable debug logging")
+def main(color: bool, debug: bool) -> None:
+    """cicadc: an interactive demonstration of how an ADC works.
+
+    Launches a PySide6 + manim window with two side-by-side panels (analog and
+    digital), with controls for frequency, amplitude, bit depth, noise and a
+    moving-average filter.
+    """
+    setup_logging(color=color, level=logging.DEBUG if debug else logging.INFO)
+
+    from .app import run
+
+    raise SystemExit(run())
+
+
+if __name__ == "__main__":
+    main()

cicadc-0.1.0/src/cicadc/command.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+######################################################################
+##        Copyright (c) 2026 Carsten Wulff Software, Norway
+## ###################################################################
+##  The MIT License (MIT)
+##
+##  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.
+######################################################################
+"""Shared helpers (logging setup) for the cicadc CLI."""
+
+from __future__ import annotations
+
+import logging
+
+
+def setup_logging(color: bool = True, level: int = logging.INFO) -> None:
+    """Configure root logging for the application."""
+    fmt = "%(levelname)s: %(message)s"
+    logging.basicConfig(level=level, format=fmt)

cicadc-0.1.0/src/cicadc/main_window.py

@@ -0,0 +1,203 @@
+"""Main application window: the render view plus a panel of live controls."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import (
+    QComboBox,
+    QDoubleSpinBox,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QSlider,
+    QVBoxLayout,
+    QWidget,
+)
+
+from .manim_scene import AdcScene
+from .quantizer import Quantizer
+from .render_widget import RenderWidget
+from .signal_source import SignalSource
+
+
+class MainWindow(QWidget):
+    def __init__(self) -> None:
+        super().__init__()
+        self.setWindowTitle("ADC Intro - how an analog-to-digital converter works")
+
+        self.signal = SignalSource(frequency=0.6, amplitude=0.85, speed=1.0, window=4.0, sample_period=0.4)
+        self.quantizer = Quantizer(bits=3)
+        self.scene = AdcScene(signal=self.signal, quantizer=self.quantizer)
+        self.view = RenderWidget(self.scene, fps=24)
+
+        controls = self._build_controls()
+
+        layout = QHBoxLayout(self)
+        layout.addWidget(self.view, stretch=1)
+        layout.addWidget(controls, stretch=0)
+
+        self._apply_dark_theme()
+        self.resize(1280, 760)
+
+    # --------------------------------------------------------------- controls
+    def _build_controls(self) -> QWidget:
+        box = QGroupBox("Controls")
+        box.setMaximumWidth(280)
+        form = QFormLayout()
+
+        self.input_combo = QComboBox()
+        self.input_combo.addItem("Single sinusoid")
+        self.input_combo.setEnabled(False)  # only shape available in the MVP
+        form.addRow("Input", self.input_combo)
+
+        self.freq_spin = QDoubleSpinBox()
+        self.freq_spin.setRange(0.05, 5.0)
+        self.freq_spin.setSingleStep(0.05)
+        self.freq_spin.setValue(self.signal.frequency)
+        self.freq_spin.setSuffix(" Hz")
+        self.freq_spin.valueChanged.connect(self._on_freq)
+        form.addRow("Frequency", self.freq_spin)
+
+        self.amp_spin = QDoubleSpinBox()
+        self.amp_spin.setRange(0.0, 1.2)
+        self.amp_spin.setSingleStep(0.05)
+        self.amp_spin.setValue(self.signal.amplitude)
+        self.amp_spin.valueChanged.connect(self._on_amp)
+        form.addRow("Amplitude (FS)", self.amp_spin)
+
+        self.speed_spin = QDoubleSpinBox()
+        self.speed_spin.setRange(0.1, 4.0)
+        self.speed_spin.setSingleStep(0.1)
+        self.speed_spin.setValue(self.signal.speed)
+        self.speed_spin.setSuffix(" x")
+        self.speed_spin.valueChanged.connect(self._on_speed)
+        form.addRow("Scroll speed", self.speed_spin)
+
+        self.bits_slider = QSlider(Qt.Orientation.Horizontal)
+        self.bits_slider.setRange(1, 8)
+        self.bits_slider.setValue(self.quantizer.bits)
+        self.bits_slider.setTickPosition(QSlider.TickPosition.TicksBelow)
+        self.bits_slider.valueChanged.connect(self._on_bits)
+        self.bits_label = QLabel(self._bits_text())
+        form.addRow(self.bits_label, self.bits_slider)
+
+        self.sample_spin = QDoubleSpinBox()
+        self.sample_spin.setRange(0.05, 1.0)
+        self.sample_spin.setSingleStep(0.05)
+        self.sample_spin.setValue(self.signal.sample_period)
+        self.sample_spin.setSuffix(" s")
+        self.sample_spin.valueChanged.connect(self._on_sample)
+        form.addRow("Sample period", self.sample_spin)
+
+        self.noise_spin = QDoubleSpinBox()
+        self.noise_spin.setRange(0.0, 0.5)
+        self.noise_spin.setSingleStep(0.02)
+        self.noise_spin.setValue(self.signal.noise_amp)
+        self.noise_spin.valueChanged.connect(self._on_noise)
+        form.addRow("Noise (FS)", self.noise_spin)
+
+        self.filter_slider = QSlider(Qt.Orientation.Horizontal)
+        self.filter_slider.setRange(1, 16)
+        self.filter_slider.setValue(self.scene.filter_taps)
+        self.filter_slider.setTickPosition(QSlider.TickPosition.TicksBelow)
+        self.filter_slider.valueChanged.connect(self._on_filter)
+        self.filter_label = QLabel(self._filter_text())
+        form.addRow(self.filter_label, self.filter_slider)
+
+        self.play_button = QPushButton("Play")
+        self.play_button.setCheckable(True)
+        self.play_button.toggled.connect(self._on_play)
+
+        outer = QVBoxLayout(box)
+        outer.addLayout(form)
+        outer.addWidget(self.play_button)
+
+        hint = QLabel(
+            "Green = analog signal\nBlue car = analog now\n"
+            "Gray = unfiltered digital\nGreen = filtered digital\n"
+            "Yellow dots = samples"
+        )
+        hint.setWordWrap(True)
+        hint.setStyleSheet("color:#8aa0c8; font-size:11px;")
+        outer.addWidget(hint)
+        outer.addStretch(1)
+
+        thanks = QLabel("Big thanks to Domen Visnar for the idea!")
+        thanks.setWordWrap(True)
+        thanks.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        thanks.setStyleSheet("color:#f5c542; font-size:11px; font-style:italic;")
+        outer.addWidget(thanks)
+        return box
+
+    def _bits_text(self) -> str:
+        return f"Bits: {self.quantizer.bits}"
+
+    def _filter_text(self) -> str:
+        n = self.scene.filter_taps
+        return "Filter: off" if n <= 1 else f"Avg: {n}"
+
+    # ----------------------------------------------------------------- slots
+    def _refresh_if_paused(self) -> None:
+        if not self.view.is_running():
+            self.view.render_once()
+
+    def _on_freq(self, v: float) -> None:
+        self.signal.frequency = v
+        self._refresh_if_paused()
+
+    def _on_amp(self, v: float) -> None:
+        self.signal.amplitude = v
+        self._refresh_if_paused()
+
+    def _on_speed(self, v: float) -> None:
+        self.signal.speed = v
+
+    def _on_sample(self, v: float) -> None:
+        self.signal.sample_period = v
+        self._refresh_if_paused()
+
+    def _on_bits(self, v: int) -> None:
+        self.quantizer.bits = v
+        self.bits_label.setText(self._bits_text())
+        self._refresh_if_paused()
+
+    def _on_noise(self, v: float) -> None:
+        self.signal.noise_amp = v
+        self._refresh_if_paused()
+
+    def _on_filter(self, v: int) -> None:
+        self.scene.filter_taps = v
+        self.filter_label.setText(self._filter_text())
+        self._refresh_if_paused()
+
+    def _on_play(self, checked: bool) -> None:
+        if checked:
+            self.play_button.setText("Pause")
+            self.view.start()
+        else:
+            self.play_button.setText("Play")
+            self.view.stop()
+
+    # ----------------------------------------------------------------- theme
+    def _apply_dark_theme(self) -> None:
+        self.setStyleSheet(
+            """
+            QWidget { background-color: #0b0f1a; color: #e6f0ff; }
+            QGroupBox {
+                border: 1px solid #2b3a63; border-radius: 6px; margin-top: 14px;
+                font-weight: bold;
+            }
+            QGroupBox::title { subcontrol-origin: margin; left: 10px; padding: 0 4px; }
+            QPushButton {
+                background-color: #1a2440; border: 1px solid #2b3a63;
+                border-radius: 5px; padding: 8px; font-weight: bold;
+            }
+            QPushButton:checked { background-color: #1f7a3a; }
+            QDoubleSpinBox, QSpinBox, QComboBox {
+                background-color: #121a2e; border: 1px solid #2b3a63;
+                border-radius: 4px; padding: 3px;
+            }
+            """
+        )