VisualTorch

https://github.com/willyfh/visualtorch
Admin
VisualTorch helps visualize PyTorch neural network architectures in layered-style, graph-style, and...
Tokens:5,887
Snippets:71
Trust Score:7.5
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install VisualTorch from Source

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/get_started/installation.md

Install VisualTorch directly from its GitHub repository to use the latest development version. This method also installs necessary dependencies.

```bash
pip install git+https://github.com/willyfh/visualtorch
```

```bash
pillow>=10.0.0
numpy>=1.18.1
aggdraw>=1.3.11
torch>=2.0.0
```

--------------------------------

### Install and Configure Pre-commit Hooks

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/developer_guides/contributing.md

Install pre-commit to automatically run code quality checks on each commit.

```bash
pre-commit install
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/willyfh/visualtorch/blob/main/docs/README.md

Installs project dependencies using pip. Ensure you have pip installed and are in the project's root directory.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install VisualTorch via PyPI

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/get_started/installation.md

Use this command to install the latest stable release of VisualTorch from the Python Package Index.

```bash
pip install visualtorch
```

--------------------------------

### Install Development Requirements

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/developer_guides/contributing.md

Install the project's development dependencies in editable mode using pip.

```bash
pip install -e .[dev]
```

--------------------------------

### Layered Style Visualization of a Sequential Model

Source: https://github.com/willyfh/visualtorch/blob/main/paper/paper.md

Generates a layered visualization for a PyTorch Sequential model. Ensure Matplotlib is installed for display. This is useful for understanding the overall structure of a feedforward network.

```python
import matplotlib.pyplot as plt
import visualtorch
from torch import nn

model = nn.Sequential(
    nn.Conv2d(3, 16, kernel_size=3, padding=1),
    nn.ReLU(),
    nn.MaxPool2d(2, 2),
    nn.Conv2d(16, 32, kernel_size=3, padding=1),
    nn.ReLU(),
    nn.MaxPool2d(2, 2),
    nn.Conv2d(32, 64, kernel_size=3, padding=1),
    nn.ReLU(),
    nn.MaxPool2d(2, 2),
    nn.Flatten(),
    nn.Linear(64 * 28 * 28, 256),
    nn.ReLU(),
    nn.Linear(256, 10),
)

input_shape = (1, 3, 224, 224)

img = visualtorch.layered_view(model, input_shape=input_shape, legend=True)

plt.axis("off")
plt.tight_layout()
plt.imshow(img)
plt.show()
```

--------------------------------

### Build Documentation

Source: https://github.com/willyfh/visualtorch/blob/main/docs/README.md

Builds the HTML documentation using Sphinx. This command generates the documentation in the 'build' directory.

```bash
sphinx-build -b html source build
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/developer_guides/contributing.md

Use this command to create a new Conda environment for VisualTorch development with Python 3.10 and then activate it.

```bash
conda create -n visualtorch_env python=3.10
conda activate visualtorch_env
```

--------------------------------

### Run Tests and Quality Checks

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/developer_guides/contributing.md

Execute all pre-commit checks and run the pytest test suite to ensure code quality and that all tests pass.

```bash
pre-commit run --all-files
pytest tests/
```

--------------------------------

### LeNet Style Visualization of a Sequential Model

Source: https://github.com/willyfh/visualtorch/blob/main/paper/paper.md

Creates a LeNet-style visualization for a PyTorch Sequential model. This style is particularly suited for Convolutional Neural Networks (CNNs). Matplotlib is required for rendering the output.

```python
import matplotlib.pyplot as plt
import visualtorch
from torch import nn

model = nn.Sequential(
    nn.Conv2d(3, 8, kernel_size=3, padding=1),
    nn.MaxPool2d(2, 2),
    nn.Conv2d(8, 16, kernel_size=3, padding=1),
    nn.MaxPool2d(2, 2),
)

input_shape = (1, 3, 128, 128)

img = visualtorch.lenet_view(model, input_shape=input_shape)

plt.axis("off")
plt.tight_layout()
plt.imshow(img)
plt.show()
```

--------------------------------

### Run Pre-commit Checks Manually

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/developer_guides/contributing.md

Execute all pre-commit checks across all files in the repository to ensure code quality and consistency.

```bash
pre-commit run --all-files
```

--------------------------------

### lenet_view

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/api_references/lenet_style.md

Generates a LeNet style architecture visualization for a given PyTorch model. This function takes a model and input shape, and can optionally save the visualization to a file.

```APIDOC
## lenet_view

### Description
Generate a LeNet style architecture visualization for a given torch model.

### Method
`lenet_view(
    model: ~torch.nn.modules.module.Module | ~torch.nn.modules.container.Sequential | ~torch.nn.modules.container.ModuleList,
    input_shape: tuple[int, ...],
    to_file: str | None = None,
    min_z: int = 1,
    min_xy: int = 10,
    max_xy: int = 2000,
    scale_z: float = 1,
    scale_xy: float = 1,
    type_ignore: list | None = None,
    index_ignore: list | None = None,
    color_map: dict | None = None,
    one_dim_orientation: str = 'z',
    background_fill: str | tuple[int, ...] = 'white',
    padding: int = 10,
    spacing: int = 10,
    draw_funnel: bool = True,
    shade_step: int = 10,
    font: <module 'PIL.ImageFont' from '/usr/local/lib/python3.11/site-packages/PIL/ImageFont.py'> = None,
    font_color: str | tuple[int, ...] = 'black',
    opacity: int = 255,
    max_channels: int = 100,
    offset_z: int = 10
) -> <module 'PIL.Image' from '/usr/local/lib/python3.11/site-packages/PIL/Image.py'>

### Parameters
* **model** (*torch.nn.Module*) – A torch model that will be visualized.
* **input_shape** (*tuple*) – The shape of the input tensor (default: (1, 3, 224, 224)).
* **to_file** (*str* *,* *optional*) – Path to the file to write the created image. Overwrite if exist.
  Image type is inferred from the file extension. Providing None will disable writing.
* **min_z** (*int* *,* *optional*) – Minimum size in pixels that a layer will have along the z-axis.
* **min_xy** (*int* *,* *optional*) – Minimum size in pixels that a layer will have along the x and y axes.
* **max_channels** (*int* *,* *optional*) – Maximum number of channels.
* **max_xy** (*int* *,* *optional*) – Maximum size in pixels that a layer will have along the x and y axes.
* **scale_z** (*float* *,* *optional*) – Scalar multiplier for the size of each layer along the z-axis.
* **scale_xy** (*float* *,* *optional*) – Scalar multiplier for the size of each layer along the x and y axes.
* **type_ignore** (*list* *,* *optional*) – List of layer types in the torch model to ignore during drawing.
* **index_ignore** (*list* *,* *optional*) – List of layer indexes in the torch model to ignore during drawing.
* **color_map** (*dict* *,* *optional*) – Dictionary defining fill and outline colors for each layer by class type.
  Will fallback to default values for unspecified classes.
* **one_dim_orientation** (*str* *,* *optional*) – Axis on which one-dim layers should be drawn. E.g., ‘x’, ‘y’, or ‘z’.
* **background_fill** (*str* *or* *tuple* *,* *optional*) – Background color for the image. A string or a tuple (R, G, B, A).
* **padding** (*int* *,* *optional*) – Distance in pixels before the first and after the last layer.
* **spacing** (*int* *,* *optional*) – Spacing in pixels between two layers.
* **draw_funnel** (*bool* *,* *optional*) – If True, a funnel will be drawn between consecutive layers.
* **shade_step** (*int* *,* *optional*) – Deviation in lightness for drawing shades (only in volumetric view).
* **font** (*PIL.ImageFont* *,* *optional*) – Font that will be used for the legend. If None, default font will be used.
* **font_color** (*str* *or* *tuple* *,* *optional*) – Color for the font if used. Can be a string or a tuple (R, G, B, A).
* **opacity** (*int*) – Transparency of the color (0 ~ 255).
* **offset_z** (*int*) – control the offset of overlapping between channels.

### Returns
An Image object representing the generated architecture visualization.

### Return type
PIL.Image
```

--------------------------------

### visualtorch.graph.graph_view

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/api_references/graph.md

Generates an architecture visualization for a given linear PyTorch model in a graph style.

```APIDOC
## visualtorch.graph.graph_view

### Description
Generates an architecture visualization for a given linear PyTorch model in a graph style.

### Parameters
#### Path Parameters
- **model** (torch.nn.Module) - Required - A PyTorch model that will be visualized.
- **input_shape** (tuple) - Required - The shape of the input tensor.

#### Query Parameters
- **to_file** (str | None) - Optional - Path to the file to write the created image to. If the image does not exist yet, it will be created, else overwritten. Image type is inferred from the file ending. Providing None will disable writing.
- **color_map** (dict[Any, Any] | None) - Optional - Dict defining fill and outline for each layer by class type. Will fallback to default values for not specified classes.
- **node_size** (int) - Optional - Size in pixels each node will have. Defaults to 50.
- **background_fill** (str | tuple[int, ...]) - Optional - Color for the image background. Can be str or (R,G,B,A). Defaults to 'white'.
- **padding** (int) - Optional - Distance in pixels before the first and after the last layer. Defaults to 10.
- **layer_spacing** (int) - Optional - Spacing in pixels between two layers. Defaults to 250.
- **node_spacing** (int) - Optional - Spacing in pixels between nodes. Defaults to 10.
- **connector_fill** (str | tuple[int, ...]) - Optional - Color for the connectors. Can be str or (R,G,B,A). Defaults to 'gray'.
- **connector_width** (int) - Optional - Line-width of the connectors in pixels. Defaults to 1.
- **ellipsize_after** (int) - Optional - Maximum number of neurons per layer to draw. If a layer is exceeding this, the remaining neurons will be drawn as ellipses. Defaults to 10.
- **show_neurons** (bool) - Optional - If True a node for each neuron in supported layers is created (constrained by ellipsize_after), else each layer is represented by a node. Defaults to True.
- **opacity** (int) - Optional - Transparency of the color (0 ~ 255). Defaults to 255.

### Returns
Generated architecture image.

### Return type
Image.Image
```

--------------------------------

### visualtorch.layered.layered_view

Source: https://github.com/willyfh/visualtorch/blob/main/docs/source/markdown/api_references/layered.md

Generates a layered architecture visualization for a given PyTorch model.

```APIDOC
## visualtorch.layered.layered_view

### Description
Generate a layered architecture visualization for a given torch model.

### Parameters
#### Parameters
- **model** (*torch.nn.Module*) – A torch model that will be visualized.
- **input_shape** (*tuple*) – The shape of the input tensor (default: (1, 3, 224, 224)).
- **to_file** (*str* *,* *optional*) – Path to the file to write the created image. Overwrite if exist. Image type is inferred from the file extension. Providing None will disable writing.
- **min_z** (*int* *,* *optional*) – Minimum size in pixels that a layer will have along the z-axis.
- **min_xy** (*int* *,* *optional*) – Minimum size in pixels that a layer will have along the x and y axes.
- **max_z** (*int* *,* *optional*) – Maximum size in pixels that a layer will have along the z-axis.
- **max_xy** (*int* *,* *optional*) – Maximum size in pixels that a layer will have along the x and y axes.
- **scale_z** (*float* *,* *optional*) – Scalar multiplier for the size of each layer along the z-axis.
- **scale_xy** (*float* *,* *optional*) – Scalar multiplier for the size of each layer along the x and y axes.
- **type_ignore** (*list* *,* *optional*) – List of layer types in the torch model to ignore during drawing.
- **index_ignore** (*list* *,* *optional*) – List of layer indexes in the torch model to ignore during drawing.
- **color_map** (*dict* *,* *optional*) – Dictionary defining fill and outline colors for each layer by class type. Will fallback to default values for unspecified classes.
- **one_dim_orientation** (*str* *,* *optional*) – Axis on which one-dim layers should be drawn. E.g., ‘x’, ‘y’, or ‘z’.
- **background_fill** (*str* *or* *tuple* *,* *optional*) – Background color for the image. A string or a tuple (R, G, B, A).
- **draw_volume** (*bool* *,* *optional*) – Flag to switch between 3D volumetric view and 2D box view.
- **padding** (*int* *,* *optional*) – Distance in pixels before the first and after the last layer.
- **spacing** (*int* *,* *optional*) – Spacing in pixels between two layers.
- **draw_funnel** (*bool* *,* *optional*) – If True, a funnel will be drawn between consecutive layers.
- **shade_step** (*int* *,* *optional*) – Deviation in lightness for drawing shades (only in volumetric view).
- **legend** (*bool* *,* *optional*) – Add a legend of the layers to the image.
- **font** (*PIL.ImageFont* *,* *optional*) – Font that will be used for the legend. If None, default font will be used.
- **font_color** (*str* *or* *tuple* *,* *optional*) – Color for the font if used. Can be a string or a tuple (R, G, B, A).
- **opacity** (*int*) – Transparency of the color (0 ~ 255).

### Returns
An Image object representing the generated architecture visualization.

### Return type
PIL.Image
```

--------------------------------

### Graph Style Visualization of a Custom Model

Source: https://github.com/willyfh/visualtorch/blob/main/paper/paper.md

Generates a graph-style visualization for a custom PyTorch nn.Module. This visualization is helpful for understanding the flow of data through custom-defined layers. Matplotlib is needed to display the image.

```python
import matplotlib.pyplot as plt
import torch
import visualtorch
from torch import nn

class SimpleDense(nn.Module):
    def __init__(self) -> None:
        super().__init__()
        self.h0 = nn.Linear(4, 8)
        self.h1 = nn.Linear(8, 8)
        self.h2 = nn.Linear(8, 4)
        self.out = nn.Linear(4, 2)

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        x = self.h0(x)
        x = self.h1(x)
        x = self.h2(x)
        return self.out(x)

model = SimpleDense()

input_shape = (1, 4)

img = visualtorch.graph_view(model, input_shape)

plt.axis("off")
plt.tight_layout()
plt.imshow(img)
plt.show()
```
Tokens:
Raw