<p align="center">
<b>English</b> | <a href="README_zh.md"><b>δΈζ</b></a>
</p>
# boviz
**boviz** is a modular and extensible scientific plotting toolkit designed for researchers, scientists, and engineers. It offers a clean, consistent API for generating high-quality, publication-ready figuresβincluding curve plots, particle schematics, heatmaps, and residual analysis. With minimal dependencies and a focus on usability, boviz streamlines the process of visualizing complex data for both quick exploration and formal presentation.
---
## β¨ Features
- **Modular Design**: Well-organized modules for curves, schematics, styles, utilities, and configuration.
- **Unified Aesthetics**: Consistent visual themes with predefined colors, markers, and line styles.
- **Flexible Curve Plotting**: Support for multiple curves, residual comparison, log/scientific scale, truncation, axis customization, and multi-format legends.
- **Schematic Plotting**: Easily create particle distributions and domain diagrams.
- **Heatmap Visualization**: Generate particle-based heatmaps for spatial data analysis.
- **Batch Plotting**: Plot multiple datasets or figures in a single call for efficient workflow.
- **Smart File Naming**: Auto-generated filenames in the format `boviz_<timestamp>_<title>.png`.
- **Minimal Dependencies**: Built on top of Matplotlib, NumPy, and Pandas.
- **Easy Integration**: Can be used as a standalone package or imported into larger Python-based workflows.
- **Customizable Styles**: Easily adjust plot styles, color palettes, and legend layouts.
- **Publication-Ready Output**: High-resolution figures suitable for academic papers and presentations.
- **Test-Driven Development**: Comes with robust test cases to ensure stability and correctness.
- **Comprehensive Examples**: Includes example scripts and data for quick start and advanced usage.
- **Command-Line Project Initialization**: Instantly scaffold a new plotting project with example scripts and data using the CLI (`boviz init <project_name>`).
- **Residual Analysis**: Easily plot and compare residuals between multiple curves.
- **Direct Data Plotting**: Support for plotting directly from numpy arrays or lists, not just CSV files.
- **Particle Heatmap & Schematic**: Visualize initial particle distributions and generate particle-based heatmaps for spatial analysis.
- **Smart Output Management**: Auto-naming of output files with timestamps and titles, unified output directory.
- **Global Style & Config**: Easily customize global color palettes, font styles, DPI, and figure sizes for publication-ready output.
---
## π¦ Installation
```bash
pip install boviz
```
Or, to install the development or latest version from source:
```bash
# Clone the repository
git clone https://github.com/bo-qian/boviz.git
cd boviz
# (Optional) Create a virtual environment
python -m venv venv && source venv/bin/activate
# Install the package from source
pip install .
```
---
## π Usage
You can quickly scaffold a new boviz-based project using the built-in CLI:
```bash
boviz init my_project
```
This command creates a new directory `my_project` with a recommended structure, including example scripts and configuration files. It helps you get started with best practices for organizing your plotting workflow.
**Generated structure:**
```
my_project/
βββ data/
β βββ example.csv
βββ plot.py
```
After initialization, you can immediately start adding your data and scripts, and use boviz's plotting functions as shown below.
---
## π Quick Example
```python
from boplot import *
# Plot initial particle distribution schematic
plot_initial_particle_schematic(
coordinates=[[90, 90], [150, 90]],
radii=[30, 30],
domain=[240, 180],
title="Initial Particle Distribution",
show=True,
save=True
)
# Multiple feature curve plotting
plot_curves_csv(
path=["example/data/test_plotkit_multifeature_data.csv"] * 4,
label=["Exp 800K", "Exp 900K", "Sim 800K", "Sim 900K"],
x=[0, 0, 0, 0],
y=[1, 2, 3, 4],
xy_label=["Time (s)", "Shrinkage Ratio"],
title_figure="Shrinkage Comparison at Two Temperatures",
use_marker=[True, True, False, False],
legend_ncol=2,
save=True,
show=False
)
# Single curve plotting: Plot a single simulation curve
x = np.linspace(0, 4*np.pi, 200)
y = np.sin(x)
plot_curves(
data=[(x, y)],
label=["$\sin(x)$"],
xy_label=("$x$", "$\sin(x)$"),
title_figure="Sine Wave Example",
save=True,
show=True
)
# Particle heatmap example
plot_heatmap_particle(
particle_x_num=2,
particle_y_num=1,
particle_radius=30,
border=1,
cmap='coolwarm',
title_figure="Particle Heatmap Example",
save=True,
show=False
)
```
<table align="center">
<tr>
<td align="center">
<img src="https://github.com/bo-qian/boviz/blob/main/figures/ShowExample/boviz_InitialParticleDistribution.png" alt="εε§η²εεεΈη€ΊζεΎ" height="240"/><br/>
<sub><b>Initial Particle Distribution</b></sub>
</td>
<td align="center">
<img src="https://github.com/bo-qian/boviz/blob/main/figures/ShowExample/boviz_ShrinkageComparisonatTwoTemperatures.png" alt="δΈεζΈ©εΊ¦δΈηζΆηΌ©ηε―Ήζ―" height="240"/><br/>
<sub><b>Shrinkage Comparison</b></sub>
</td>
</tr>
<tr>
<td align="center">
<img src="https://github.com/bo-qian/boviz/blob/main/figures/ShowExample/boviz_SineWaveExample.png" alt="ζ£εΌ¦ζ³’η€ΊδΎ" height="240"/><br/>
<sub><b>Sine Wave Example</b></sub>
</td>
<td align="center">
<img src="https://github.com/bo-qian/boviz/blob/main/figures/ShowExample/boviz_ParticleHeatmapExample.png" alt="η²εηεΎη€ΊδΎ" height="240"/><br/>
<sub><b>Particle Heatmap Example</b></sub>
</td>
</tr>
</table>
---
## π§ͺ Testing
To run all tests, use:
```bash
python -m pytest
```
> **Note:** On Windows, if you installed boviz in a Conda environment, make sure to run this command from the Conda terminal (Anaconda Prompt or your activated Conda shell), not from the default system terminal.
All core plotting functions are covered by unit tests under the `tests/` directory, including:
- Curve plotting (single and multi-feature)
- Schematic particle distribution
- Residual comparison
- Style and legend configurations
---
## π Project Structure
```
boviz/
βββ src/
β βββ boviz/
β βββ __init__.py
β βββ __main__.py # Main entry point for the package
β βββ cli.py # Command-line interface for plotting
β βββ config.py # Global parameters and color sets
β βββ curves.py # Core curve plotting functions
β βββ schematic.py # Particle schematic functions
β βββ heatmap.py # Particle heatmap plotting
β βββ style.py # Default plot styling
β βββ utils.py # Filename generator and helpers
βββ tests/ # Pytest-based test cases
βββ example/ # Example scripts and CSV data
β βββ data/
β βββ test_example_plot.py
βββ figures/ # Output figures (auto-generated)
β βββ ShowExample/ # Example figures for documentation
βββ requirements.txt # Required dependencies
βββ pyproject.toml # Build configuration
βββ setup.py # Legacy install config
βββ LICENSE
βββ README.md
βββ README_zh.md # Chinese version of the README
```
---
## π Dependencies
```txt
matplotlib>=3.0
numpy>=1.18
pandas>=1.0
pytest>=6.0
pathlib>=1.0
argparse>=1.4.0
```
Install via:
```bash
pip install -r requirements.txt
```
---
## π Contributing
Feel free to contribute by:
- Reporting issues and bugs
- Improving documentation and examples
- Submitting pull requests with enhancements or new plotting modules
All contributions are welcome and appreciated.
---
## π License
GNU General Public License v3 (GPLv3) License Β© 2025 Bo Qian
---
For advanced examples and API documentation, please refer to the `tests/` and `example/` directories, or explore the docstrings inside the `src/boviz/` module.
Raw data
{
"_id": null,
"home_page": "https://github.com/bo-qian/boviz",
"name": "boviz",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Bo Qian",
"author_email": "Bo Qian <bqian@shu.edu.cn>",
"download_url": "https://files.pythonhosted.org/packages/2d/b2/e0c88205ff88cc40add5fa2d461a6385e0490ef0237f6fd9f1b7afcabb36/boviz-0.1.9.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <b>English</b> | <a href=\"README_zh.md\"><b>\u4e2d\u6587</b></a>\n</p>\n\n# boviz\n\n**boviz** is a modular and extensible scientific plotting toolkit designed for researchers, scientists, and engineers. It offers a clean, consistent API for generating high-quality, publication-ready figures\u2014including curve plots, particle schematics, heatmaps, and residual analysis. With minimal dependencies and a focus on usability, boviz streamlines the process of visualizing complex data for both quick exploration and formal presentation.\n\n---\n\n## \u2728 Features\n\n- **Modular Design**: Well-organized modules for curves, schematics, styles, utilities, and configuration.\n- **Unified Aesthetics**: Consistent visual themes with predefined colors, markers, and line styles.\n- **Flexible Curve Plotting**: Support for multiple curves, residual comparison, log/scientific scale, truncation, axis customization, and multi-format legends.\n- **Schematic Plotting**: Easily create particle distributions and domain diagrams.\n- **Heatmap Visualization**: Generate particle-based heatmaps for spatial data analysis.\n- **Batch Plotting**: Plot multiple datasets or figures in a single call for efficient workflow.\n- **Smart File Naming**: Auto-generated filenames in the format `boviz_<timestamp>_<title>.png`.\n- **Minimal Dependencies**: Built on top of Matplotlib, NumPy, and Pandas.\n- **Easy Integration**: Can be used as a standalone package or imported into larger Python-based workflows.\n- **Customizable Styles**: Easily adjust plot styles, color palettes, and legend layouts.\n- **Publication-Ready Output**: High-resolution figures suitable for academic papers and presentations.\n- **Test-Driven Development**: Comes with robust test cases to ensure stability and correctness.\n- **Comprehensive Examples**: Includes example scripts and data for quick start and advanced usage.\n- **Command-Line Project Initialization**: Instantly scaffold a new plotting project with example scripts and data using the CLI (`boviz init <project_name>`).\n- **Residual Analysis**: Easily plot and compare residuals between multiple curves.\n- **Direct Data Plotting**: Support for plotting directly from numpy arrays or lists, not just CSV files.\n- **Particle Heatmap & Schematic**: Visualize initial particle distributions and generate particle-based heatmaps for spatial analysis.\n- **Smart Output Management**: Auto-naming of output files with timestamps and titles, unified output directory.\n- **Global Style & Config**: Easily customize global color palettes, font styles, DPI, and figure sizes for publication-ready output.\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install boviz\n```\n\nOr, to install the development or latest version from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/bo-qian/boviz.git\ncd boviz\n\n# (Optional) Create a virtual environment\npython -m venv venv && source venv/bin/activate\n\n# Install the package from source\npip install .\n```\n\n---\n\n## \ud83d\udcd6 Usage\n\nYou can quickly scaffold a new boviz-based project using the built-in CLI:\n\n```bash\nboviz init my_project\n```\n\nThis command creates a new directory `my_project` with a recommended structure, including example scripts and configuration files. It helps you get started with best practices for organizing your plotting workflow.\n\n**Generated structure:**\n```\nmy_project/\n\u251c\u2500\u2500 data/\n\u2502 \u2514\u2500\u2500 example.csv\n\u2514\u2500\u2500 plot.py\n```\n\nAfter initialization, you can immediately start adding your data and scripts, and use boviz's plotting functions as shown below.\n\n---\n\n## \ud83d\ude80 Quick Example\n\n```python\nfrom boplot import *\n\n# Plot initial particle distribution schematic\nplot_initial_particle_schematic(\n coordinates=[[90, 90], [150, 90]],\n radii=[30, 30],\n domain=[240, 180],\n title=\"Initial Particle Distribution\",\n show=True,\n save=True\n)\n\n# Multiple feature curve plotting\nplot_curves_csv(\n path=[\"example/data/test_plotkit_multifeature_data.csv\"] * 4,\n label=[\"Exp 800K\", \"Exp 900K\", \"Sim 800K\", \"Sim 900K\"],\n x=[0, 0, 0, 0],\n y=[1, 2, 3, 4],\n xy_label=[\"Time (s)\", \"Shrinkage Ratio\"],\n title_figure=\"Shrinkage Comparison at Two Temperatures\",\n use_marker=[True, True, False, False],\n legend_ncol=2,\n save=True,\n show=False\n)\n\n# Single curve plotting: Plot a single simulation curve\nx = np.linspace(0, 4*np.pi, 200)\ny = np.sin(x)\nplot_curves(\n data=[(x, y)],\n label=[\"$\\sin(x)$\"],\n xy_label=(\"$x$\", \"$\\sin(x)$\"),\n title_figure=\"Sine Wave Example\",\n save=True,\n show=True\n)\n\n# Particle heatmap example\nplot_heatmap_particle(\n particle_x_num=2,\n particle_y_num=1,\n particle_radius=30,\n border=1,\n cmap='coolwarm',\n title_figure=\"Particle Heatmap Example\",\n save=True,\n show=False\n)\n```\n\n<table align=\"center\">\n <tr>\n <td align=\"center\">\n <img src=\"https://github.com/bo-qian/boviz/blob/main/figures/ShowExample/boviz_InitialParticleDistribution.png\" alt=\"\u521d\u59cb\u7c92\u5b50\u5206\u5e03\u793a\u610f\u56fe\" height=\"240\"/><br/>\n <sub><b>Initial Particle Distribution</b></sub>\n </td>\n <td align=\"center\">\n <img src=\"https://github.com/bo-qian/boviz/blob/main/figures/ShowExample/boviz_ShrinkageComparisonatTwoTemperatures.png\" alt=\"\u4e0d\u540c\u6e29\u5ea6\u4e0b\u7684\u6536\u7f29\u7387\u5bf9\u6bd4\" height=\"240\"/><br/>\n <sub><b>Shrinkage Comparison</b></sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\">\n <img src=\"https://github.com/bo-qian/boviz/blob/main/figures/ShowExample/boviz_SineWaveExample.png\" alt=\"\u6b63\u5f26\u6ce2\u793a\u4f8b\" height=\"240\"/><br/>\n <sub><b>Sine Wave Example</b></sub>\n </td>\n <td align=\"center\">\n <img src=\"https://github.com/bo-qian/boviz/blob/main/figures/ShowExample/boviz_ParticleHeatmapExample.png\" alt=\"\u7c92\u5b50\u70ed\u56fe\u793a\u4f8b\" height=\"240\"/><br/>\n <sub><b>Particle Heatmap Example</b></sub>\n </td>\n </tr>\n</table>\n\n---\n\n## \ud83e\uddea Testing\n\nTo run all tests, use:\n\n```bash\npython -m pytest\n```\n\n> **Note:** On Windows, if you installed boviz in a Conda environment, make sure to run this command from the Conda terminal (Anaconda Prompt or your activated Conda shell), not from the default system terminal.\n\nAll core plotting functions are covered by unit tests under the `tests/` directory, including:\n\n- Curve plotting (single and multi-feature)\n- Schematic particle distribution\n- Residual comparison\n- Style and legend configurations\n\n---\n\n## \ud83d\udcc1 Project Structure\n\n```\nboviz/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 boviz/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 __main__.py # Main entry point for the package\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface for plotting\n\u2502 \u251c\u2500\u2500 config.py # Global parameters and color sets\n\u2502 \u251c\u2500\u2500 curves.py # Core curve plotting functions\n\u2502 \u251c\u2500\u2500 schematic.py # Particle schematic functions\n\u2502 \u251c\u2500\u2500 heatmap.py # Particle heatmap plotting\n\u2502 \u251c\u2500\u2500 style.py # Default plot styling\n\u2502 \u2514\u2500\u2500 utils.py # Filename generator and helpers\n\u251c\u2500\u2500 tests/ # Pytest-based test cases\n\u251c\u2500\u2500 example/ # Example scripts and CSV data\n\u2502 \u251c\u2500\u2500 data/\n\u2502 \u2514\u2500\u2500 test_example_plot.py\n\u251c\u2500\u2500 figures/ # Output figures (auto-generated)\n\u2502 \u2514\u2500\u2500 ShowExample/ # Example figures for documentation\n\u251c\u2500\u2500 requirements.txt # Required dependencies\n\u251c\u2500\u2500 pyproject.toml # Build configuration\n\u251c\u2500\u2500 setup.py # Legacy install config\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 README.md\n\u2514\u2500\u2500 README_zh.md # Chinese version of the README\n```\n\n---\n\n## \ud83d\udcda Dependencies\n\n```txt\nmatplotlib>=3.0\nnumpy>=1.18\npandas>=1.0\npytest>=6.0\npathlib>=1.0\nargparse>=1.4.0\n```\n\nInstall via:\n\n```bash\npip install -r requirements.txt\n```\n\n---\n\n## \ud83d\ude4c Contributing\n\nFeel free to contribute by:\n\n- Reporting issues and bugs\n- Improving documentation and examples\n- Submitting pull requests with enhancements or new plotting modules\n\nAll contributions are welcome and appreciated.\n\n---\n\n## \ud83d\udcdc License\n\nGNU General Public License v3 (GPLv3) License \u00a9 2025 Bo Qian\n\n---\n\nFor advanced examples and API documentation, please refer to the `tests/` and `example/` directories, or explore the docstrings inside the `src/boviz/` module.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "An advanced and flexible scientific plotting toolkit.",
"version": "0.1.9",
"project_urls": {
"Homepage": "https://github.com/bo-qian/boviz",
"Repository": "https://github.com/bo-qian/boviz"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf566955a6250dff8c5bfee974205198561e79423439b1d6f9718ee5e98f8888",
"md5": "7f5f9ef50ac4bed059d411045b24c69f",
"sha256": "b14b244cd59eeb7d351a6cfd72506610183192b6fb074f7ea364eebe78ea1e6f"
},
"downloads": -1,
"filename": "boviz-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f5f9ef50ac4bed059d411045b24c69f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 50648,
"upload_time": "2025-07-10T07:39:54",
"upload_time_iso_8601": "2025-07-10T07:39:54.507766Z",
"url": "https://files.pythonhosted.org/packages/cf/56/6955a6250dff8c5bfee974205198561e79423439b1d6f9718ee5e98f8888/boviz-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2db2e0c88205ff88cc40add5fa2d461a6385e0490ef0237f6fd9f1b7afcabb36",
"md5": "78e4337853a04cd9f6580f40fdcdab53",
"sha256": "f29a38c451a23ab846301766df474e0e71bc356a48b9278e95c6dd1b99faa478"
},
"downloads": -1,
"filename": "boviz-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "78e4337853a04cd9f6580f40fdcdab53",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 50933,
"upload_time": "2025-07-10T07:39:56",
"upload_time_iso_8601": "2025-07-10T07:39:56.073072Z",
"url": "https://files.pythonhosted.org/packages/2d/b2/e0c88205ff88cc40add5fa2d461a6385e0490ef0237f6fd9f1b7afcabb36/boviz-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 07:39:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bo-qian",
"github_project": "boviz",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "matplotlib",
"specs": [
[
">=",
"3.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.18"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "pathlib",
"specs": [
[
">=",
"1.0"
]
]
},
{
"name": "argparse",
"specs": [
[
">=",
"1.4.0"
]
]
},
{
"name": "meshio",
"specs": [
[
">=",
"4.0"
]
]
},
{
"name": "netCDF4",
"specs": [
[
">=",
"1.5"
]
]
}
],
"lcname": "boviz"
}
JSON
