Metadata-Version: 2.4
Name: topovision
Version: 0.1.1
Summary: TopoVision - 3D Topographic Analysis System for Calculus II
Author-email: TopoVision Team <code.with.botina@gmail.com>
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
        "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
        
        "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
        
        "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity.
        
        "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
        
        "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
        
        "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
        
        "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work.
        
        "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship.
        
        "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
        
        "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
        
        2. Grant of Copyright License.
        
        Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
        
        3. Grant of Patent License.
        
        Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
        
        4. Redistribution.
        
        You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
        
           a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
           b) You must cause any modified files to carry prominent notices stating that You changed the files; and
           c) You must retain, in the Source form of any Derivative Works, all copyright, patent, trademark, and attribution notices from the Source form of the Work; and
           d) If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works must include a readable copy of the attribution notices contained within such NOTICE file, excluding those that do not pertain to any part of the Derivative Works.
        
        5. Submission of Contributions.
        
        Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work shall be under the terms of this License.
        
        6. Trademarks.
        
        This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for describing the origin of the Work.
        
        7. Disclaimer of Warranty.
        
        Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
        
        8. Limitation of Liability.
        
        In no event and under no legal theory shall any Contributor be liable for damages arising in any way out of the use of the Work.
        
        9. Accepting Warranty or Additional Liability.
        
        While redistributing the Work, You may choose to offer support, warranty, indemnity, or other liability obligations, but only on Your own behalf and not on behalf of any Contributor.
        
        END OF TERMS AND CONDITIONS
        
        ---------------------------------------
        
        Copyright 2025 TopoVision Team (Alejandro Botina Herrera, Andreina Olivares Cabrera, Jonathan Joel Ruviño, Kiara Vanessa Muñoz Bayter, Víctor Manuel Barrero Acosta)
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at:
        
           http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and limitations under the License.
        
Project-URL: Homepage, https://github.com/JalaU-Capstones/topovision
Project-URL: Documentation, https://github.com/JalaU-Capstones/topovision/blob/main/README.md
Project-URL: Repository, https://github.com/JalaU-Capstones/topovision
Project-URL: Issues, https://github.com/JalaU-Capstones/topovision/issues
Keywords: computer-vision,calculus,topography,3d-analysis,education
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy==1.26.4
Requires-Dist: scipy==1.14.1
Requires-Dist: opencv-python==4.10.0.84
Requires-Dist: Pillow==10.3.0
Requires-Dist: matplotlib==3.9.2
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: numba==0.60.0
Requires-Dist: psutil==6.1.0
Provides-Extra: dev
Requires-Dist: pytest==8.3.3; extra == "dev"
Requires-Dist: pytest-cov==5.0.0; extra == "dev"
Requires-Dist: flake8==7.1.1; extra == "dev"
Requires-Dist: black==24.8.0; extra == "dev"
Requires-Dist: isort==5.13.2; extra == "dev"
Requires-Dist: mypy==1.13.0; extra == "dev"
Requires-Dist: pre-commit==4.0.1; extra == "dev"
Requires-Dist: pdoc==14.4.0; extra == "dev"
Requires-Dist: ipython==8.28.0; extra == "dev"
Provides-Extra: light
Requires-Dist: numpy==1.26.4; extra == "light"
Requires-Dist: opencv-python-headless==4.10.0.84; extra == "light"
Requires-Dist: Pillow==10.3.0; extra == "light"
Requires-Dist: matplotlib==3.9.2; extra == "light"
Dynamic: license-file

# 🛰️ **TopoVision — 3D Topographic Analysis System**

> A Python-based system for topographic data visualization, real-time analysis, and calculus-based gradient computation.

[![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![PyPI version](https://img.shields.io/pypi/v/topovision.svg)](https://pypi.org/project/topovision/)
[![Build](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/JalaU-Capstones/topovision/actions)

📦 **Repository:** [https://github.com/JalaU-Capstones/topovision.git](https://github.com/JalaU-Capstones/topovision.git)

---

## 🧭 **Overview**

**TopoVision** is a collaborative academic project developed as part of the **Calculus II course** at *Universidad Jala*.
The system combines **Computer Vision**, **Numerical Methods**, and **Topographic Analysis** to calculate and visualize slopes, gradients, and surface volumes in real time.

The main goal is to create a tool that connects mathematical theory with visual and spatial understanding — transforming multivariable calculus into an interactive experience.

---

## ⚙️ **Key Features**

*   🎥 Real-time video capture using OpenCV
*   🧮 Numerical computation of partial derivatives and gradients
*   ✨ **Dynamic 3D Surface Plots**: Interactive visualization of topographic data, including heatmaps and vector fields.
*   🖱️ Interactive point and region selection on GUI
*   🧠 Modular design following **SOLID** principles and **Design Patterns**
*   ⚡ Optimized for low-resource environments (Python 3.11 + NumPy vectorization)
*   📦 Easy installation via PyPI

---

## 🖼️ **Visualizations**

TopoVision offers rich and interactive 3D visualizations to help understand complex topographic data.

### Dynamic 3D Surface Plots

Experience real-time rendering of surfaces, allowing you to observe changes in elevation and features interactively.

![3D Surface Plot Screenshot](docs/images/3d_surface_plot.gif) <!-- Placeholder for a GIF or screenshot -->

### Gradient Vector Fields

Visualize the direction and magnitude of the steepest ascent across the terrain, providing insights into flow and slope.

![Gradient Vector Field Screenshot](docs/images/gradient_vector_field.png) <!-- Placeholder for a screenshot -->

---

## 🚀 **Quick Start**

### Installation from PyPI

```bash
pip install topovision
```

### Run the application

```bash
python -m topovision
```

Or simply:

```bash
topovision
```

You should see a GUI window with **"Open Camera"** and **"Exit"** buttons.

---

## 📋 **System Requirements**

### Required
- **Python 3.11** or higher
- **Tkinter** (GUI toolkit)

### Tkinter Installation

Tkinter comes pre-installed with Python on **Windows** and **macOS**.

On **Linux**, you may need to install it manually:

**Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install python3-tk
```

**Fedora/RHEL:**
```bash
sudo dnf install python3-tkinter
```

**Arch Linux:**
```bash
sudo pacman -S tk
```

---

## 🛠️ **Installation Options**

### Standard Installation
Includes all features and GUI support:
```bash
pip install topovision
```

### Development Installation
Includes testing, linting, and documentation tools:
```bash
pip install topovision[dev]
```

### Lightweight Installation
Minimal dependencies without OpenCV GUI components:
```bash
pip install topovision[light]
```

### Installation from Source

For developers who want to contribute or modify the code:

```bash
# Clone the repository
git clone https://github.com/JalaU-Capstones/topovision.git
cd topovision

# Create virtual environment
python3.11 -m venv .venv
source .venv/bin/activate      # macOS/Linux
# OR
.venv\Scripts\activate         # Windows

# Install in editable mode
pip install -e .

# Or install with dev dependencies
pip install -e .[dev]
```

---

## 🧩 **Project Structure**

```
topovision/
├── src/
│   └── topovision/
│       ├── __init__.py
│       ├── __main__.py          # Entry point for CLI execution
│       ├── app.py               # Main application logic
│       ├── core/
│       │   ├── interfaces.py
│       │   └── models.py
│       ├── capture/
│       │   ├── capture_module.py
│       │   ├── camera_backends.py
│       │   └── preprocessing.py
│       ├── calculus/
│       │   ├── calculus_module.py
│       │   └── methods/
│       │       ├── finite_diff.py
│       │       ├── gradient.py
│       │       └── riemann.py
│       ├── visualization/
│       │   ├── visualization_module.py
│       │   ├── heatmap.py
│       │   └── vector_overlay.py
│       │   └── plot3d.py          # Added 3D plotting capabilities
│       ├── gui/
│       │   └── gui_module.py
│       ├── services/
│       │   ├── cache.py
│       │   └── task_queue.py
│       ├── utils/
│       │   └── validators.py
│       └── tests/
│           ├── test_capture.py
│           ├── test_calculus.py
│           └── test_visualization.py
├── docs/
│   ├── architecture.md
│   ├── user-guide.md
│   └── github-flow-guide.md
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
├── LICENSE
└── README.md
```

---

## 🧰 **Tech Stack**

| Layer                | Technology           |
| -------------------- | -------------------- |
| Language             | Python 3.11          |
| GUI                  | Tkinter              |
| Computer Vision      | OpenCV               |
| Numerical Analysis   | NumPy, SciPy         |
| Visualization        | Matplotlib           |
| Performance          | Numba                |
| Documentation        | Markdown + pdoc      |
| Testing              | Pytest               |
| Linting / Formatting | Flake8, Black, Mypy  |
| Version Control      | GitHub (GitHub Flow) |
| Distribution         | PyPI                 |

---

## 🎯 **Usage Examples**

### Basic Usage

```python
# After installation, simply run:
python -m topovision

# Or use the command directly:
topovision
```

### Programmatic Usage

```python
from topovision.app import main

# Launch the application
main()
```

---

## 🧮 **Core Functionalities (Mathematical Overview)**

| Feature                   | Description                                         | Method                      |
| :------------------------ | :-------------------------------------------------- | :-------------------------- |
| Partial Derivatives       | Calculated using finite difference methods          | Central Difference Scheme   |
| Gradient Vector           | Visualized as direction + magnitude arrows          | Sobel Operator              |
| Double Integrals          | Computed with discrete Riemann sums                 | Trapezoidal Rule            |
| 3D Surface Visualization  | Dynamic and interactive 3D plots of topographic surfaces | Matplotlib + NumPy          |
| Real-time Processing      | Optimized numerical computations                    | Numba JIT Compilation       |

---

## 🧩 **Development Workflow — GitHub Flow**

### 🌿 Main Branches

| Branch      | Purpose                      |
| ----------- | ---------------------------- |
| `main`      | Stable release branch        |
| `develop`   | Integration branch           |
| `feature/*` | Individual development tasks |
| `hotfix/*`  | Urgent fixes                 |
| `docs/*`    | Documentation-only updates   |

### 💬 Commit Convention

Follow **Conventional Commits** format:

```
<type>(<scope>): <description>
```

**Examples:**

```bash
feat(capture): added OpenCVCamera backend
fix(gui): fixed window resize event
docs(readme): updated installation steps
```

**Types:**
- `feat` — new feature
- `fix` — bug fix
- `docs` — documentation changes
- `refactor` — code structure improvements
- `test` — test-related commits
- `chore` — build, CI, or maintenance

### 🔁 Typical Workflow

```bash
git checkout develop
git pull
git checkout -b feature/my-feature
# Make changes...
git add .
git commit -m "feat(scope): description"
git push origin feature/my-feature
# Open Pull Request → merge into develop → then into main
```

---

## 🧪 **Testing**

Run the test suite:

```bash
# Install with dev dependencies
pip install topovision[dev]

# Run tests
pytest

# Run with coverage
pytest --cov=topovision
```

---

## 👥 **Team Members**

| Name                             | Role                                |
| -------------------------------- | ----------------------------------- |
| **Alejandro Botina Herrera**     | Technical Lead & System Architect   |
| **Andreina Olivares Cabrera**    | Interface Developer & Documentation |
| **Jonathan Joel Ruviño**         | Testing & Numerical Computation     |
| **Kiara Vanessa Muñoz Bayter**   | Environment Setup & Visualization   |
| **Víctor Manuel Barrero Acosta** | Capture Systems & Demonstrations    |

---

## 🧱 **Project Roadmap**

| Week  | Focus                    | Key Deliverables                            |
| :---: | :----------------------- | :------------------------------------------ |
| **1** | Setup & Architecture     | Folder structure, interfaces, mock GUI      |
| **2** | Capture & Processing     | Camera module + preprocessing filters       |
| **3** | Calculus & Visualization | Derivatives, gradients, and heatmaps        |
| **4** | Testing & Publication    | PyPI release, documentation, and demo video |

---

## 🧾 **License**

This project is licensed under the **Apache License 2.0**.
See the [LICENSE](LICENSE) file for more details.

---

## 📚 **Acknowledgements**

* *Universidad Jala* — Department of Computer Science
* Course: **Calculus II — Applied Computational Analysis**
* Year: 2025

---

## 💡 **Contributing**

We welcome contributions!

1. Fork the repository
2. Create a new branch (`feature/your-feature`)
3. Install development dependencies: `pip install -e .[dev]`
4. Commit your changes using Conventional Commits
5. Run tests: `pytest`
6. Open a Pull Request

---

## 🐛 **Troubleshooting**

### Tkinter not found
**Error:** `ModuleNotFoundError: No module named '_tkinter'`

**Solution:** Install Tkinter for your system (see System Requirements section above)

### OpenCV camera issues
**Error:** Camera not opening or permission denied

**Solution:**
- Ensure your camera is not being used by another application
- On Linux, add your user to the `video` group: `sudo usermod -a -G video $USER`
- Restart your session after group changes

### Import errors after installation
**Error:** `ModuleNotFoundError: No module named 'topovision'`

**Solution:**
```bash
# Verify installation
pip list | grep topovision

# Reinstall if needed
pip uninstall topovision
pip install topovision
```

---

## 🧠 **Future Improvements**

* Add 3D mesh visualization using Plotly or Mayavi
* Implement topographic point cloud import (LAS/CSV)
* Integrate hardware sensors for live terrain capture
* Develop a lightweight Web-based viewer (Flask + WebGL)
* Machine learning integration for automatic feature detection
* Export functionality for analysis results (JSON, CSV, HDF5)

---

## 📊 **Performance**

TopoVision is optimized for real-time analysis:
- **Frame processing:** ~30 FPS on modern hardware
- **Gradient computation:** <50ms per frame
- **Memory usage:** ~200MB typical, <500MB peak

**Tested on:**
- CPU: Intel i5-8250U / AMD Ryzen 5 3600
- RAM: 8GB minimum, 16GB recommended
- OS: Windows 10/11, Ubuntu 20.04+, macOS 12+

---

## 🔗 **Links**

- **PyPI Package:** https://pypi.org/project/topovision/
- **GitHub Repository:** https://github.com/JalaU-Capstones/topovision
- **Issue Tracker:** https://github.com/JalaU-Capstones/topovision/issues
- **Documentation:** [docs/](docs/)

---

🎯 *TopoVision — bridging the gap between Calculus and reality, one frame at a time.*

---
