Metadata-Version: 2.4
Name: topovision
Version: 0.2.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 :: Apache Software 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.

---

## ✨ **What's New in Version 0.2.1**

This version introduces a complete unit conversion and perspective calibration system, making TopoVision a more accurate and user-friendly tool for real-world analysis.

*   **Unit Conversion System**: All calculations and measurements can now be displayed in various units (meters, feet, etc.).
*   **Perspective Calibration**: A new calibration tool allows you to correct for perspective distortion by defining a real-world rectangle, ensuring all measurements are dimensionally accurate.
*   **Interactive Tutorials**: A new event-driven tutorial system guides first-time users through the application's key features.
*   **Improved UI**: The user interface has been refactored for a more stable and responsive layout.
*   **Enhanced Visualizations**: The gradient heatmap and 3D plot now correctly handle perspective and aspect ratio, providing clearer and more accurate visualizations.

---

## ⚙️ **Key Features**

*   🎥 Real-time video capture using OpenCV
*   📏 **Unit Conversion**: Display results in meters, feet, kilometers, etc.
*   📐 **Perspective Calibration**: Correct for perspective distortion for accurate measurements.
*   🧮 Numerical computation of partial derivatives, gradients, arc length, and volume.
*   ✨ **Dynamic 3D Surface Plots**: Interactive visualization of topographic data.
*   🗺️ **Gradient Heatmaps**: Clear visualization of slope and steepness.
*   🖱️ Interactive region selection on the GUI.
*   🧠 **Interactive Tutorials**: Guides first-time users through the application.
*   📦 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)

---

## 🚀 **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 a welcome tutorial guiding you to press the **"Open Camera"** button.

---

## 📋 **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
│       ├── app.py
│       ├── core/
│       │   ├── interfaces.py
│       │   └── models.py
│       ├── capture/
│       │   └── ...
│       ├── calculus/
│       │   ├── calculus_module.py
│       │   └── strategies.py
│       ├── visualization/
│       │   ├── visualizers.py
│       │   └── plot3d.py
│       ├── gui/
│       │   ├── gui_module.py
│       │   ├── analysis_panel.py
│       │   └── ...
│       ├── services/
│       │   └── task_queue.py
│       ├── utils/
│       │   ├── math.py
│       │   ├── units.py
│       │   └── perspective.py
│       └── tests/
│           └── ...
├── docs/
│   ├── architecture.md
│   ├── user-guide.md
│   └── ...
├── pyproject.toml
├── README.md
└── ...
```

---

## 🧰 **Tech Stack**

| Layer                | Technology           |
| -------------------- | -------------------- |
| Language             | Python 3.11          |
| GUI                  | Tkinter              |
| Computer Vision      | OpenCV               |
| Numerical Analysis   | NumPy                |
| Visualization        | Matplotlib           |
| Documentation        | Markdown             |
| 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
```

---

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

| Feature                   | Description                                         | Method                      |
| :------------------------ | :-------------------------------------------------- | :-------------------------- |
| Partial Derivatives       | Calculated using finite difference methods          | Central Difference Scheme   |
| Gradient Vector           | Visualized as a heatmap                             | Sobel Operator              |
| Volume Calculation        | Computed with discrete Riemann sums                 | Trapezoidal Rule            |
| Arc Length Calculation    | Calculated as the sum of Euclidean distances        | Vectorized NumPy operations |
| 3D Surface Visualization  | Dynamic and interactive 3D plots of topographic surfaces | Matplotlib + NumPy          |
| Perspective Correction    | Uses a 4-point homography to correct for perspective | OpenCV `getPerspectiveTransform` |

---

## 🧩 **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>
```

---

## 🧪 **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    |

---

## 🧾 **License**

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

---

## 🔗 **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.*

---
