{"id":13688973,"url":"https://github.com/xwying/torchshow","last_synced_at":"2025-10-08T17:12:56.332Z","repository":{"id":37650666,"uuid":"320686801","full_name":"xwying/torchshow","owner":"xwying","description":"Visualize PyTorch tensors with a single line of code.","archived":false,"fork":false,"pushed_at":"2025-03-20T05:53:35.000Z","size":7993,"stargazers_count":666,"open_issues_count":3,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-28T19:23:06.449Z","etag":null,"topics":["image-tensor","notebook","pytorch","tensor","visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xwying.png","metadata":{"files":{"readme":"README.md","changelog":"changelogs.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-11T21:22:38.000Z","updated_at":"2025-05-25T08:12:08.000Z","dependencies_parsed_at":"2023-12-17T20:38:51.354Z","dependency_job_id":"b4404c50-6991-425d-ab04-d2d7f72a00d8","html_url":"https://github.com/xwying/torchshow","commit_stats":{"total_commits":82,"total_committers":3,"mean_commits":"27.333333333333332","dds":0.1585365853658537,"last_synced_commit":"3008c23ebac2811f07c314119b14ba1725b215f7"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/xwying/torchshow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwying%2Ftorchshow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwying%2Ftorchshow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwying%2Ftorchshow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwying%2Ftorchshow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xwying","download_url":"https://codeload.github.com/xwying/torchshow/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwying%2Ftorchshow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278981518,"owners_count":26079640,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-tensor","notebook","pytorch","tensor","visualization"],"created_at":"2024-08-02T15:01:29.363Z","updated_at":"2025-10-08T17:12:56.326Z","avatar_url":"https://github.com/xwying.png","language":"Python","funding_links":[],"categories":["Python","Deep Learning Framework"],"sub_categories":["High-Level DL APIs"],"readme":"\u003cdiv align=\"center\"\u003e\n\n![TorchShow Logo](https://raw.githubusercontent.com/xwying/torchshow/master/imgs/torchshow.png)\n\n[![PyPI version](https://badge.fury.io/py/torchshow.svg)](https://badge.fury.io/py/torchshow)\n[![Downloads](https://static.pepy.tech/personalized-badge/torchshow?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=brightgreen\u0026left_text=Downloads)](https://pepy.tech/project/torchshow)\n![License](https://img.shields.io/github/license/xwying/torchshow?color=brightgreen)\n\n\u003c/div\u003e\n\n----\n\nTorchshow visualizes your data in one line of code. It is designed to help debugging Computer Vision project.\n\nTorchshow automatically infers the type of a tensor such as RGB images, grayscale images, binary masks, categorical masks (automatically apply color palette), etc. and perform necessary unnormalization if needed. \n\n**Supported Type:**\n\n- [x] RGB Images\n- [x] Grayscale Images\n- [x] Binary Mask\n- [x] Categorical Mask (Integer Labels)\n- [x] Multiple Images\n- [x] Videos\n- [x] Multiple Videos\n- [x] Optical Flows (powered by [flow_vis](https://github.com/tomrunia/OpticalFlow_Visualization))\n\n\n\n## What's New in v0.5.2\n- Fixed the version comparison bugs in `set_window_title` function ([#24](https://github.com/xwying/torchshow/issues/24)).\n- Support more data dtype for pytorch tensors.\n\nSee the complete [changelogs](changelogs.md).\n\n\n## Installation\nInstall from [PyPI](https://pypi.org/project/torchshow/):\n\n```bash\npip install torchshow\n```\n\nAlternatively, you can install directly from this repo to test the latest features.\n\n```bash\npip install git+https://github.com/xwying/torchshow.git@master\n```\n\n\n## Basic Usage\n\nThe usage of TorchShow is extremely simple. Simply import the package and visualize your data in one line:\n\n```python\nimport torchshow as ts\nts.show(tensor)\n```\n\nIf you work on a headless server without display. You can use `ts.save(tensor)` command (since version 0.3.2).\n\n```python\nimport torchshow as ts\nts.save(tensor) # Figure will be saved under ./_torchshow/***.png\nts.save(tensor, './vis/test.jpg') # You can specify the save path.\n```\n\n## API References\n\nPlease check [this page](./API.md) for detailed API references.\n\n\n## Examples\n\n### Table of Contents\n- [Visualizing Image Tensor](#1-visualizing-image-tensor)\n- [Visualizing Mask Tensors](#2-visualizing-mask-tensors)\n- [Visualizing Batch of Tensors](#3-visualizing-batch-of-tensors)\n- [Visualizing Channels in Feature Maps](#4-visualizing-feature-maps)\n- [Visualizing Multiple Tensors with Custom Layout.](#5-visualizing-multiple-tensors-with-custom-layout)\n- [Examine the pixel with rich information.](#6-examine-the-pixel-with-richer-information)\n- [Visualizing Tensors as Video Clip](#7-visualizing-tensors-as-video-clip)\n- [Display Video Animation in Jupyter Notebook](#8-display-video-animation-in-jupyter-notebook)\n- [Visualizing Optical Flows](#9-visualizing-optical-flows)\n- [Change Channel Order (RGB/BGR)](#10-change-channel-order-rgbbgr)\n- [Change Unnormalization Presets](#11-change-unnormalization-presets)\n- [Overlay Visualizations](#12-overlay-visualizations)\n\n### 1. Visualizing Image Tensor\nVisualizing an image-like tensor is not difficult but could be very cumbersome. You usually need to convert the tensor to numpy array with proper shapes. In many cases images were normalized during dataloader, which means that you have to unnormalize it so it can be displayed correctly.\n\nIf you need to frequently verify what your tensors look like, TorchShow is a very helpful tool. \n\nUsing Matplotlib             |  Using TorchShow\n:-------------------------:|:-------------------------:\n![](./imgs/RGB_image_plt.gif)  |  ![](./imgs/RGB_image_ts.gif)\n|The image tensor has been normalized so Matplotlib cannot display it correctly. | TorchShow does the conversion automatically.|\n\n### 2. Visualizing Mask Tensors\nFor projects related to Semantic Segmentation or Instance Segmentation, we often need to visualize mask tensors -- either ground truth annotations or model's prediction. This can be easily done using TorchShow.\n\nUsing Matplotlib             |  Using TorchShow\n:-------------------------:|:-------------------------:\n![](./imgs/cat_mask_plt.gif)  |  ![](./imgs/cat_mask_ts.gif)\n| Different instances have same colors. Some categories are missing. | TorchShow automatically apply color palletes during visualization.|\n\n### 3. Visualizing Batch of Tensors\nWhen the tensor is a batch of images, TorchShow will automatically create grid layout to visualize them. It is also possible to manually control the number of rows and columns.\n\n![](./imgs/batch_imgs.gif)\n\n### 4. Visualizing Feature Maps\nIf the input tensor has more than 3 channels, TorchShow will visualize each of the channel similar to batch visualization. This is useful to visualize a feature map.\n\n![](./imgs/featuremap.gif)\n\n### 5. Visualizing Multiple Tensors with Custom Layout.\nTorchShow has more flexibility to visualize multiple tensor using a custom layout.\n\nTo control the layout, put the tensors in list of list as an 2D array. The following example will create a 2 x 3 grid layout.\n\n```\nts.show([[tensor1, tensor2, tensor3],\n         [tensor4, tensor5, tensor6]])\n```\n\nIt is worth mentioning that there is no need to fill up all the places in the grid. The following example visualizes 5 tensors in a 2 x 3 grid layout.\n\n```\nts.show([[tensor1, tensor2],\n         [tensor3, tensor4, tensor5]])\n```\n\n![](./imgs/custom_layout.gif)\n\n\n### 6. Examine the pixel with richer information.\nSince `v0.4.1`, TorchShow allows you to get richer information from a pixel you are interested by simply hovering your mouse over that pixel. This is very helpful for some types of tensors such as Categorical Mask and Optical Flows. \n\nCurrently, Torchshow displays the following information: \n\n- `Mode`: Visualization Mode.\n- `Shape`: Shape of the tensor.\n- `X`, `Y`: The pixel location of the mouse cursor.\n- `Raw`: The raw tensor value at (X, Y).\n- `Disp`: The display value at (X, Y).\n\n![](./imgs/rich_info.gif)\n\n**Note: if the information is not showing on the status bar, try to resize the window and make it wider.**\n\nThis feature can be turned off by `ts.show_rich_info(False)`.\n\n\n### 7. Visualizing Tensors as Video Clip\nTensors can be visualized as video clips, which very helpful if the tensor is a sequence of frames. This can be done using `show_video` function.\n\n```python\nts.show_video(video_tensor)\n```\n\n![](./imgs/video.gif)\n\nIt is also possible to visualize multiple videos in a custom grid layout.\n\n![](./imgs/video_grid.gif)\n\n### 8. Display Video Animation in Jupyter Notebook\nTorchShow visualizes video clips as an `matplotlib.func_animation` object and may not display in a notebook by default. The following example shows a simple trick to display it.\n\n```python\nimport torchshow as ts\nfrom IPython.display import HTML\n\nani = ts.show_video(video_tensor)\nHTML(ani.to_jshtml())\n```\n\n### 9. Visualizing Optical Flows\nTorchShow support visualizing optical flow (powered by [flow_vis](https://github.com/tomrunia/OpticalFlow_Visualization)). Below is a demostration using a VSCode debugger remotely attached to a SSH server (with X-server configured). Running in a Jupyter Notebook is also supported.\n\n![](./imgs/flow_ts.gif)\n\n### 10. Change Channel Order (RGB/BGR)\nBy default tensorflow visualize image tensor in the RGB mode, you can switch the setting to BGR in case you are using opencv to load the image.\n```python\nts.set_color_mode('bgr')\n```\n\n### 11. Change Unnormalization Presets\nThe image tensor may have been preprocessed with a normalization function. If not specified, torchshow will automatically rescale it to 0-1. \n\n\nTo change the preset to imagenet normalization. Use the following code.\n```python\nts.show(tensor, unnormalize='imagenet')\n```\n\nTo use a customize mean and std value, use the following command. \n```python\nts.set_image_mean([0., 0., 0.])\nts.set_image_std([1., 1., 1.])\n```\nNote that once this is set, torchshow will use this value for the following visualization. This is useful because usually only a single normalization preset will be used for the entire project.\n\n\n### 12. Overlay Visualizations\nIn Computer Vision project there are many times we will be dealing with different representations of the scene, including but not limited to RGB image, depth image, infrared image, semantic mask, instance mask, etc. Sometimes it will be very helpful to overlay these different data for visualization. Since `v0.5.0`, TorchShow provides a very useful API `ts.overlay()` for this purpose.\n\nIn the below example we have an RGB image and its corresponding semantic mask. Let's first check what they look like using TorchShow.\n\n```python\nimport torchshow as ts\nts.show([\"example_rgb.jpg\", \"example_category_mask.png\"])\n```\n\n![](./imgs/overlay_1.png)\n\nNow I would like to overlay the mask on top of the RGB image to gain more insights, with TorchShow this can be easily done with one line of code.\n\n```python\nimport torchshow as ts\nts.overlay([\"example_rgb.jpg\", \"example_category_mask.png\"], alpha=[1, 0.6])\n```\n\n![](./imgs/overlay_2.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxwying%2Ftorchshow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxwying%2Ftorchshow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxwying%2Ftorchshow/lists"}