Metadata-Version: 2.4
Name: cap3d-viz
Version: 1.0.0
Summary: High-Performance 3D Visualization for CAP3D Files
Home-page: https://github.com/andykofman/RWCap_view
Author: Ahmed Ali
Author-email: Ahmed Ali <ali.a@aucegypt.edu>
Maintainer-email: Ahmed Ali <ali.a@aucegypt.edu>
License: MIT License
        
        Copyright (c) 2025 Ahmed Ali & Ahmed El-Sousy
        
        
        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.
        
Project-URL: Homepage, https://github.com/andykofman/RWCap_view
Project-URL: Documentation, https://cap3d-viz.readthedocs.io/
Project-URL: Repository, https://github.com/andykofman/RWCap_view
Project-URL: Issues, https://github.com/andykofman/RWCap_view/issues
Keywords: 3D visualization,CAP3D,capacitance,integrated circuits,EDA,scientific computing,plotly,parsing,state machine
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: matplotlib>=3.3.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Provides-Extra: performance
Requires-Dist: scipy>=1.7.0; extra == "performance"
Requires-Dist: pandas>=1.3.0; extra == "performance"
Requires-Dist: numba>=0.56.0; extra == "performance"
Provides-Extra: all
Requires-Dist: cap3d-viz[dev,docs,performance]; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# CAP3D-Viz: High-Performance 3D Visualization for CAP3D Files

[![PyPI version](https://badge.fury.io/py/cap3d-viz.svg)](https://badge.fury.io/py/cap3d-viz)
[![Python Support](https://img.shields.io/pypi/pyversions/cap3d-viz.svg)](https://pypi.org/project/cap3d-viz/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16406690.svg)](https://doi.org/10.5281/zenodo.16406690)

**CAP3D-Viz** is a high-performance Python package for parsing and visualizing 3D geometry from CAP3D files generated by capacitance solvers. It features state-machine parsing, memory-efficient streaming, and interactive 3D visualization optimized for large datasets in integrated circuit design workflows.

## Key Features

- **State-Machine Parser**: 70-80% reduction in condition checking with dispatch tables
- **Memory Efficient**: Handles 10,000+ blocks with <8MB memory usage
- **High Performance**: Parse speed of 9,882+ blocks/second
- **Interactive 3D Visualization**: Real-time filtering and exploration
- **Batched Rendering**: Smooth visualization of 50k+ blocks
- **Professional IC Features**: Industry-standard layer colors and visualization modes
- **Comprehensive Format Support**: Blocks, polygons, layers, windows, and tasks

## Performance Benchmarks

| Metric                   | Performance                           |
| ------------------------ | ------------------------------------- |
| **Parse Speed**    | 9,882 blocks/second                   |
| **Memory Usage**   | <8MB for 10k blocks                   |
| **Filter Latency** | <500ms for interactive operations     |
| **Rendering**      | 50k+ blocks with batched optimization |

## Installation

### From PyPI (Recommended)

```bash
pip install cap3d-viz
```

### Development Installation

```bash
git clone https://github.com/your-repo/cap3d-viz.git
cd cap3d-viz
pip install -e .[dev]
```

### Dependencies

- Python ≥3.8
- NumPy ≥1.19.0
- Plotly ≥5.0.0
- Matplotlib ≥3.3.0

## Quick Start

### Basic Usage

```python
from cap3d_viz import load_and_visualize

# Load and visualize a CAP3D file  
fig = load_and_visualize("your_file.cap3d")
fig.show()
```

### Advanced Usage

```python
from cap3d_viz import OptimizedCap3DVisualizer

# Create visualizer with custom settings
visualizer = OptimizedCap3DVisualizer(max_blocks_display=50000)
visualizer.load_data("large_file.cap3d")

# Create interactive visualization
fig = visualizer.create_optimized_visualization(
    show_mediums=True,
    show_conductors=True, 
    show_polys=True,
    use_batched_rendering=True,  # For large datasets
    z_slice=5.0,                 # Cross-section view
    opacity_mediums=0.3,
    opacity_conductors=0.9
)

fig.show()
```

### Performance-Optimized Parsing

```python
from cap3d_viz import StreamingCap3DParser

# Parse large files efficiently
parser = StreamingCap3DParser("massive_file.cap3d")
data = parser.parse_complete()

print(f"Parsed {len(data.blocks)} blocks")
print(f"Found {len(data.poly_elements)} polygonal elements")
print(f"Layers: {len(data.layers)}")
```

## CAP3D File Format Support

CAP3D-Viz provides comprehensive support for all CAP3D elements:

### Structural Elements

- **`<block>`**: 3D rectangular volumes with basepoint and vectors
- **`<poly>`**: Complex polygonal elements with custom 2D coordinates
- **`<medium>`/`<conductor>`**: Material sections with dielectric properties

### Advanced Elements

- **`<layer>`**: IC layer definitions (interconnect, via, metal, poly, contact)
- **`<window>`**: Simulation boundary definitions
- **`<task>`**: Capacitance calculation targets
- **`<coord>`**: 2D coordinate data for polygonal shapes

### Example CAP3D Block

```xml
<block>
    name block1
    basepoint(-2, -2, 0)    <!-- Starting corner -->
    v1(4, 0, 0)             <!-- Edge vector 1 -->
    v2(0, 4, 0)             <!-- Edge vector 2 --> 
    hvector(0, 0, 0.3)      <!-- Height/thickness -->
</block>
```

## Visualization Features

### Interactive 3D Controls

- **Mouse Controls**: Rotate, zoom, pan with intuitive interaction
- **Component Toggling**: Show/hide mediums, conductors, polygons independently
- **Layer Filtering**: Focus on specific IC layers with professional colors
- **Z-Slice Views**: Cross-sectional visualization at any height
- **Real-time Statistics**: Block counts, volume analysis, dimensional info

### Professional IC Design

- **Industry-Standard Colors**: Metal, via, poly, contact layer visualization
- **Level of Detail (LOD)**: Intelligent prioritization for large datasets
- **Batch Rendering**: Optimized trace grouping for smooth interaction
- **Export Options**: Save visualizations as interactive HTML files

## Architecture

CAP3D-Viz uses a modular architecture for optimal performance and maintainability:

```
cap3d_viz/
├── data_models.py      # Core data structures (Block, Layer, etc.)
├── parser.py          # State-machine parser with streaming support
├── visualizer.py      # 3D visualization engine with caching
├── utils.py           # Convenience functions and utilities
└── __init__.py        # Main package interface
```

### State-Machine Parser

- **Context-Aware**: Only checks relevant conditions per parsing state
- **Dispatch Tables**: Direct function mapping eliminates conditional chains
- **Streaming Architecture**: Memory-efficient line-by-line processing
- **Pre-compiled Patterns**: Cached operations for maximum speed

## Scientific Applications

CAP3D-Viz is designed for researchers and engineers working with:

- **Integrated Circuit Design**: Visualization of IC layouts and parasitic structures
- **Capacitance Analysis**: 3D exploration of capacitive coupling effects
- **EDA Tool Integration**: Workflow enhancement for design automation
- **Research Publications**: High-quality figures for academic papers
- **Design Verification**: Visual validation of 3D geometry structures

## Documentation

- **API Reference**: [https://cap3d-viz.readthedocs.io/](https://cap3d-viz.readthedocs.io/)
- **Tutorials**: [docs/tutorials/](docs/tutorials/)
- **Examples**: [examples/](examples/)
- **Performance Guide**: [docs/performance.md](docs/performance.md)

## Testing

Run the test suite to verify installation:

```bash
# Install development dependencies
pip install -e .[dev]

# Run all tests
pytest

# Run with coverage
pytest --cov=cap3d_viz

# Run performance benchmarks
python -m cap3d_viz.benchmarks
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
git clone https://github.com/your-repo/cap3d-viz.git
cd cap3d-viz
pip install -e .[dev]
pre-commit install
```

### Running Tests

```bash
pytest tests/
black cap3d_viz/
flake8 cap3d_viz/
mypy cap3d_viz/
```

## 📄 Citation

If you use CAP3D-Viz in your research, please cite:

```bibtex
@software{cap3d_viz_2025,
  author    = {Ahmed Ali},
  title     = {{CAP3D-Viz}: High-Performance {3D} Visualization for {CAP3D} Files},
  version   = {1.0.0},
  date      = {2025-07-24},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.16406690},
  url       = {https://doi.org/10.5281/zenodo.16406690},
  repository= {https://github.com/andykofman/RWCap_view},
  type      = {software}
}

```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- **RWCap Development Team**: For the CAP3D file format specification

## Support

- **Issues**: [GitHub Issues](https://github.com/andykofman/RWCap_view/issues)

---

*CAP3D-Viz: Advancing 3D visualization for integrated circuit design and capacitance analysis.*
