README_zh_cn.md

Language :

Box-X

Hack Python and Vision

Box-X 是一个旨在提高 Python 代码开发和调试效率的工具库，尤其是在 科学计算 和 计算机视觉 领域.

简介 | 安装 | 示例 | 教程 | 致谢

_{Code with ❤︎ by DIYer22 and contributors}

---

一. 简介

Box-X 的目标是提高 Python 代码的开发和调试效率.

特别是在 科学计算 和 计算机视觉 领域有着良好的支持.

因此，工具库的所有功能 会根据该功能是否通用 而被分为了两个部分:

• 通用功能: 这些功能（工具）可以在任何 Python 开发中发挥作用

• 科学计算和计算机视觉功能: 这些功能（工具）主要用于科学计算和计算机视觉领域

boxx 兼容 Python 2/3 及 Linux | macOS | Windows 操作系统, 支持 纯 Python、IPython、Spyder、Jupyer Notebook 等 Python 运行环境

P.S. 如果对计算机视觉感兴趣，这里有一个详尽的关于 boxx 的介绍：

开发, 调试计算机视觉代码有哪些技巧？

二. 安装

pip install boxx

三. 示例

示例也被分为了两个部分

左侧为 通用功能，右侧为 科学计算和计算机视觉功能。

💡 Note:

• 点击图片可以查看大图，如果是 GIF，GIF还会从头开始播放
• 下面的内容是为桌面浏览器排版的内容，如通过手机浏览器查看，推荐访问=> 静态的 Tutorial

通用功能 ▶ p/x 是更方便 print(x) 的方式 p/x 在执行 print(x) 后会返回 x 💡 Note: p/x 能够方便的打印表达式中的值. ▶ g.name = x 和 g.name/x 可以把函数内的变量传送到 Python interactive console 中 💡 Note: gg 的意思是 to Global and log， 和 g 的用法一样, 但 gg 会在传输的同时打印变量. 需要注意， 如果之前在终端中存在一样的变量名称，则变量的值会被新值覆盖. ▶ g() 一次性传输函数内的所有变量到 Python interactive console 中 💡 Note: g() 在 Debug 时非常有用. import boxx.g 是 g() 的便携版本，避免了 from boxx import g;g()(import boxx.gg 同理) ▶ with p, with g, with gg 分别是 p, g, gg 的多变量版本，只需把变量放入 with 结构中即可 使得对应操作只作用于感兴趣的几个变量 💡 Note: with p, with g, with gg 只作用于在 with 结构中进行赋值操作的变量. 如果变量名在 with 前存在于 locals() 中, 同时 id(变量) 没有变化 , with 结构可能无法检测到该变量.

科学计算和计算机视觉功能 本部分通过用例来介绍几个在 科学计算 和 计算机视觉 领域内的一些实用工具 . 几乎所有的工具(函数) 都支持 numpy, torch.tensor, mxnet.ndarray, PIL.Image 等类似多维数组的数据类型 💡 Note: 若通过 ssh 在远程服务器上执行代码， 建议在 ssh 加上 -X 参数，使可视化的 plt 图表能传输到本地显示，即 ssh -X user@host。 ▶ 用 loga 来可视化多维数组 loga 是 "log array" 的缩写, loga 能展示多维数组的许多属性. 💡 Note: loga 支持 numpy, torch.tensor, mxnet.ndarray, PIL.Image .etc ▶ 用 show 来方便地可视化图像，哪怕图像隐藏于复杂的结构中 show 能够从复杂结构中找出所有类型的图像 并可视化他们。它甚至支持从 torch 的 Dataloader 中展示一个 batch 的图像 💡 Note: 如果有函数作为 show 的参数(比如 torgb)，则会对所有 numpy 执行此函数后再可视化。 ▶ 使用 tree 来可视化复杂结构 如同 shell 中的 tree 命令， boxx.tree 可以直观地展示复杂结构. 💡 Note: tree 支持的数据有 list, tuple, dict, numpy, torch.tensor/Dataset/DataLoader, mxnet.ndarray, PIL.Image.etc

▶ boxx 调试工具矩阵 变量个数 \ 操作 print transport print & transport 单变量 p/x g.name/x gg.name/x 多变量 with p: with g: with gg: locals() p() g() gg() locals()_2 import boxx.p import boxx.g import boxx.gg 💡 Note: transport 操作是指 把函数内的变量传送到 Python interactive console 中 locals() 指作 用于函数或 module 内的所有变量 locals()_2: 当 boxx 未导入时， import boxx.{操作} 能等价于 from boxx import {操作};{操作}() ▶ 使用 what 来了解任何对象 💡 Note: what(x) 通过打印 x 自己及x 的 文档, 父类继承关系, 内部结构 及 所有属性 来全面了解 x. 是 help(x) 的补充. ▶ timeit 是一个方便的计时工具 💡 Note: timeit 会对在 with 结构下的代码块进行计时，并用蓝色来打印出运行的时间. ▶ mapmp 是多进程版本的 map mapmp 是 "MAP for Multi Process"的缩写, 和 map 有着一样的用法，但会用多进程加速. 💡 Note: mapmp 的 pool 参数来控制进程数目，默认为 CPU 线程数目. 在多进程程序中, 打印进度往往非常麻烦. mapmp 的 printfreq 参数能解决这个问题. 如同 map 一样，mapmp 支持将多个参数输入函数，如mapmp(add, list_1, list_2) 在 Python 中，多进程代码最好在 __name__ == '__main__' 环境中运行. 如果加速 numpy 程序，请注意 在 MKL 版本的 numpy 中，多进程会更慢, 可以运行 boxx.testNumpyMultiprocessing() 来测试当前环境对多进程 numpy 的友好程度 ▶ 用 heatmap 来展示代码的运行时间热力图 💡 Note: heatmap 也支持字符串形式的 Python 代码. ▶ performance 可以统计函数调用并通过火焰图可视化代码性能 💡 Note: performance 也支持字符串形式的 Python 代码.

---

四. 教程

boxx 的教程是一个 Jupyter Notebook 文件，可以边看边运行.

有三种方式来查看/运行此教程

方式一：可执行的在线 Notebook:

Notebook 文件被运行在 Binder 上。Binder 提供了可执行、可交互的在线 Notebook 环境.
也就是说，无需下载和运行任何代码，只需浏览器打开链接，就可以在线执行 Notebook 教程中的代码块。

• => 可直接执行的在线教程

方式二：下载并在本地打开教程:

git clone https://github.com/DIYer22/boxx
cd boxx/
python setup.py install
jupyter notebook

在 Jupyter Notebook 中打开 ./tutorial_for_boxx.ipynb 即可.

方式三：静态的 Notebook:

只能看 不能交互的 Notebook.

• => 静态的 Tutorial

五. 致谢

• 特别感谢徐晓栋、吴国栋、范浩强和熊鹏飞对 boxx 提出的建议
• I develop boxx in Spyder IDE, Spyder is a awesome Scientific Python Development Environment with Powerful Qt-IPython
• performance is supported by SnakeViz
• heatmap is supported by csurfer/pyheat