1. 下载与启动

1. 用 VyZ.World 账户在本网站登录后下载 zip 文件。软件不需要申请授权或激活。
2. 解压之前先解除下载标记：右键 zip 文件 > 属性 > 勾选 解除锁定 > 确定。否则每次启动 Windows 都会要求确认。
3. 解压到任意有写权限的文件夹（路径中可以有空格和中文），双击 PortableVolumeViewer.exe 即可运行。
4. 本软件没有代码签名。如果出现 “Windows 已保护你的电脑”，点 更多信息 > 仍要运行。

系统要求：Windows 10 或 11，64 位；不需要安装 Python 或其他软件。可用内存建议不少于所打开体数据大小的 2 倍。有显卡时三维视图使用显卡渲染；没有可用显卡时会自动改用软件渲染。

没有自己的数据时，可以选择 文件 > 示例数据（或“打开”菜单中的 示例数据），程序会生成一个合成的多孔材料体数据供试用。

2. 界面总览

• 顶部工具栏：打开（旁边的小箭头展开菜单：文件夹、网盘、网页链接、原始数据、示例数据、最近打开）、网盘、保存标注、截图（小箭头展开更多截图方式）、撤销、重做、布局（最大化当前视图 / 恢复 2×2）、复位（所有视图适应窗口）；右侧依次是语言（中文 / EN）、触控模式、全屏、面板、设置、帮助。
• 左侧工具栏：浏览工具（定位、平移、窗宽窗位）、各种标注工具、选择 / 编辑、橡皮擦、标注颜色和线宽。窗口太矮放不下时，用滚轮或手指上下滑动即可。
• 四个视图：左上体渲染（三维）、右上 XY、左下 YZ、右下 XZ。每个视图有彩色标签和标题栏，标题栏上有 适应窗口、截图、最大化 按钮；二维视图下方有切片滑块和 − / + 按钮。当前视图有蓝色边框。
• 右侧面板：显示（亮度 / 对比度、伪彩色、叠加显示）、三维（渲染选项）、标注（标注列表与导出）、信息（数据属性、体素尺寸、十字线位置）。用 面板 按钮（F9）显示或隐藏。
• 状态栏：提示信息、指针处的体素数值，以及当前使用的三维渲染方式。

最大化视图

任何一个视图都可以放大到整个布局：点它的 最大化 按钮、在视图内双击、双击它的标题栏、用手指快速点按两次，或按 Ctrl+1（三维）、Ctrl+2（XY）、Ctrl+3（YZ）、Ctrl+4（XZ）。再操作一次或按 F10 即恢复 2×2 布局。在二维视图内双击最大化适用于定位、平移、窗宽窗位和选择工具；使用绘图工具时，双击属于绘图本身（例如结束多边形）。

3. 打开数据

也可以把文件或文件夹直接拖到窗口中，从 最近打开 中选择，或在命令行中带路径启动：PortableVolumeViewer.exe D:\data\stack。

体素尺寸。测量结果以及 YZ / XZ 视图的真实比例都取决于体素尺寸。请在 信息 页检查，必要时修改 X、Y、Z 和单位后按 应用。图像文件夹只能从文件中读出 X 和 Y 方向的尺寸，Z 暂按与 X 相同处理，此时会显示黄色提示。

超大数据。如果体数据所需内存超过可用内存，程序会询问是否以降低的分辨率载入（每个方向每 2 个体素取一个，内存为 1/8）。也可以在 设置 > 常规 > 载入 中固定这样载入。三维视图总是使用降采样后的副本（见 三维视图），切面视图则以载入的原始分辨率显示。

4. 切面视图（XY、YZ、XZ）

XY 显示某个 Z 位置的切面，YZ 显示某个 X 位置的切面（行方向为 Z），XZ 显示某个 Y 位置的切面（行方向为 Z）。第 1 层在最上方。各视图按真实物理比例显示。彩色线条表示另外两个切面的位置：红色 = YZ 切面，绿色 = XZ 切面，蓝色 = XY 切面。

• 移动十字线（定位工具，N）：在视图中点按或拖动，另外两个视图随即切换到该位置。
• 换层：在视图上滚动鼠标滚轮，使用视图下方的滑块和 − / + 按钮，按方向键（Page Up / Page Down 一次 10 层），或三指上下滑动。
• 缩放：按住鼠标滚轮（中键）拖动——向上拖放大、向下拖缩小，以按下的位置为中心；或 Ctrl + 滚轮；或按 + / − 键；或双指捏合。Home 键或 适应窗口 按钮让切面适应视图大小。
• 平移：按住鼠标右键拖动，或使用平移工具（H），或双指拖动。
• 亮度 / 对比度：在 显示 页拖动直方图上的两个手柄（或它们之间的区域），输入下限 / 上限，或按 自动（取数值的 0.5 %～99.8 %）、全范围。使用窗宽窗位工具（W）时，在任一二维视图中左右拖动调对比度、上下拖动调亮度。
• 伪彩色：灰度、热度、骨骼、Viridis、Magma、彩虹、冷暖、绿色、红色、青色；反色 把颜色表反转。
• 叠加显示：十字线、比例尺、切面与像素信息、标注、测量值、放大时平滑显示，以及同时显示前后若干层（± N）的标注。

每个视图左上角显示层号及其实际位置，右上角显示缩放比例，左下角显示指针处的体素坐标与数值，右下角是比例尺。

5. 三维视图

• 旋转：按住左键或单指拖动。平移：按住右键、Shift + 左键或双指拖动。缩放：按住滚轮（中键）拖动、滚动滚轮、Ctrl + 左键拖动或双指捏合。滚转：双指旋转。复位：标题栏上的 适应窗口 按钮、Home 或 R 键。
• 方式（三维页）：体渲染（合成）、最大 / 最小 / 平均密度投影、等值面（可设定等值）。
• 颜色表和数值范围：默认与二维视图相同；取消 与二维视图相同 后可用直方图单独设定。
• 不透明度曲线（柔和、线性、阈值、峰形、反向）与 不透明度 控制物质的透明程度；光照 / 阴影 增强立体感。
• 质量：采样（快速 / 普通 / 精细）和 分辨率（每轴 256～1024 体素，或原始分辨率）。三维视图使用降采样副本以保证流畅；显卡性能强时可以选更高的分辨率。
• 显示：体数据、切面图像（在三维中显示当前三个切面）、切面位置框（彩色边框）、外框、坐标轴、标注。
• 裁剪：X / Y / Z 范围滑块切去部分体数据；取消裁剪 恢复。
• 相机：沿 +X、−X、+Y、−Y、+Z、−Z 方向观察，复位，或自动旋转。

渲染方式。程序启动时会自动检测显卡。在没有可用显卡驱动的电脑上（虚拟机、部分远程桌面），自动改用自带的软件 OpenGL（较慢，状态栏显示“软件 OpenGL”）；如果仍不可用，则显示简单的最大密度投影。可以在 设置 > 三维渲染 中指定方式（重新启动后生效）。

6. 标注与测量

标注画在二维视图中，每个标注属于某个视图的某一层。长度、面积和角度按体素尺寸换算成实际单位（µm、mm 等）。标注也会显示在三维视图中。

• 选择 / 编辑（S）：点按标注将其选中；拖动它可移动，拖动白色手柄可修改某个点；双击文字标注可修改文字。按 Delete 删除选中的标注。
• 橡皮擦（X）：点按或拖过标注即删除。
• 颜色和线宽（左侧工具栏底部）用于新画的标注，也会应用到当前选中的标注。
• 撤销 / 重做：Ctrl+Z / Ctrl+Y 或工具栏按钮。按 Esc 取消正在画的标注。
• 标注页：列出所有标注及其测量值，选中某项即跳到所在的层。按钮：定位到、文字…、颜色、删除、全部清除、载入…、保存…（JSON）和 CSV…（所有测量值及体素坐标的表格，可用 Excel 打开）。
• 自动保存：标注在操作过程中自动保存，下次打开同一数据时自动恢复。保存（Ctrl+S）写出一个 JSON 文件，便于与数据一起保存或分享；若保存在数据旁边并命名为 <名称>.annotations.json，下次打开数据时也会自动载入。

7. 截图

• 截图（工具栏，F12）：按屏幕上的排列保存所有可见视图为图片文件。
• 截图按钮旁的小箭头、文件 > 截图 菜单或各视图标题栏上的相机按钮：当前视图（Shift+F12）、三维视图、原始分辨率的切面（当前切面连同标注和比例尺，每个体素对应一个像素）、复制所有视图到剪贴板（Ctrl+Shift+C）、打开截图文件夹。
• 图片默认保存在 图片\PortableVolumeViewer，文件名包含数据名称和时间。文件夹、格式（PNG、JPG、TIFF、BMP）和尺寸（1×、2×、3×）在 设置 > 常规 中设定。

8. 触摸屏操作

触控模式（工具栏的 触控 按钮）会放大所有按钮、滑块、手柄和列表行，便于手指操作。有触摸屏的电脑会自动开启，也可以随时切换。所有功能都能通过点按完成，不需要右键或键盘。手写笔的用法与鼠标相同。

9. 网盘与网页链接

点工具栏上的 网盘（Ctrl+Shift+D）。下载的文件保存在缓存中，再次打开同一文件时直接使用。

Google Drive

• 分享链接（无需登录）：把共享为“知道链接的任何人”的文件或文件夹链接粘贴到 分享链接 页，按 打开。文件会下载后直接打开；文件夹会先列出内容——可以打开其中某个文件，或按 把此文件夹作为体数据打开 下载其中的图像作为图像堆。
• 浏览自己的 Google Drive（可选）：需要自己的 Google OAuth 客户端。在 Google Cloud 控制台创建项目、启用 Google Drive API、配置 OAuth 同意屏幕（把自己加为测试用户）、创建类型为 桌面应用 的 OAuth 客户端 ID，然后把客户端 ID 和密钥填入 设置 > 网盘。之后在 Google Drive 页按 登录：浏览器会打开登录页面，完成后程序自动继续。访问权限为只读。

百度网盘

• 在百度网盘开放平台（pan.baidu.com/union）免费创建一个应用（类型：软件），把它的 AppKey 和 SecretKey 填入 设置 > 网盘。
• 在百度网盘页按 登录：程序显示一个验证码并在浏览器中打开百度的页面，在那里输入验证码（或用百度网盘 App 扫描二维码）。之后即可浏览 我的网盘，打开其中的文件或文件夹。
• 分享链接：百度不允许第三方程序直接打开分享链接。把分享文字（链接和提取码）粘贴到分享链接页并按 打开，程序会说明这一点并可在浏览器中打开该链接（自动带上提取码）。请在那里把文件保存到自己的网盘，然后从 我的网盘 打开。

其他链接

任何直接下载链接（http 或 https）都可以粘贴到分享链接页，或用 打开 > 打开网页链接…。Dropbox 和 GitHub 的文件链接会自动转换为直接下载链接。

10. 设置与数据存放位置

• 设置 > 常规：语言（或跟随 Windows）、触控模式（自动 / 开 / 关）、以降低的分辨率载入、截图文件夹、格式和尺寸。
• 设置 > 三维渲染：自动、显卡、软件 OpenGL 或仅 CPU。
• 设置 > 网盘：Google API 密钥和 OAuth 客户端、百度 AppKey 和 SecretKey、下载缓存（大小、打开、清空）。
• 语言：工具栏上的 中文 / EN 按钮（Ctrl+L）立即切换整个界面，包括标准对话框。

设置、缓存、自动保存的标注、网盘登录凭据（按当前 Windows 用户加密）和日志保存在 %LOCALAPPDATA%\PortableVolumeViewer。如果希望全部放在程序旁边（完全便携，例如放在 U 盘中），在 PortableVolumeViewer.exe 旁新建一个名为 UserData 的文件夹即可。删除软件时直接删除解压出的文件夹（如需同时删除设置，再删除 %LOCALAPPDATA%\PortableVolumeViewer）。

11. 键盘与鼠标速查

12. 常见问题

三维视图一直是黑色，或显示“正在启动三维视图…”

启动时检测显卡需要几秒钟。如果一直是黑色，请在 设置 > 三维渲染 中选择 软件 OpenGL，然后重新启动。

提示“这个体数据需要……内存”

选择以降低的分辨率载入，关闭其他程序，或在 设置 > 常规 > 载入 中选择每 2 个体素取一个。

YZ / XZ 视图看起来被压扁或拉长

Z 方向的体素尺寸可能不对。请在 信息 页更正后按 应用。

文件夹中的图像顺序不对

文件按名称自然排序（2 在 10 之前）。请重新命名，使编号与切片顺序一致。

Google Drive 提示文件未公开或已达到下载上限

请文件所有者把共享设置为“知道链接的任何人”，稍后再试，或用自己的 Google 账户登录后下载。

日志在哪里？

%LOCALAPPDATA%\PortableVolumeViewer\logs\pvv.log（便携模式下在 UserData\logs）。反馈问题时请附上日志，发送到 info@vyz.world。

1. Download and start

1. Sign in on this site with your VyZ.World account and download the zip file. No license or activation is needed.
2. Before unzipping, unblock the file: right-click the zip > Properties > tick Unblock > OK. Otherwise Windows asks for confirmation every time the program starts.
3. Unzip it into any folder you can write to (paths with spaces or Chinese characters are fine) and double-click PortableVolumeViewer.exe.
4. The program is not code-signed. If Windows shows "Windows protected your PC", click More info > Run anyway.

Requirements: Windows 10 or 11, 64-bit. Python or other software is not needed. As a rule of thumb, have free memory of at least twice the size of the volume you open. A graphics card is used for the 3D view when available; without one the program falls back to software rendering automatically.

To try the program without your own data, choose File > Sample data (or the Sample data entry in the Open menu): a synthetic porous material is created.

2. The window

• Toolbar (top): Open (the arrow opens the menu with folder, cloud, web link, raw data, sample data and recent files), Cloud, Save annotations, Screenshot (the arrow opens more screenshot choices), Undo, Redo, Layout (maximize the active view / back to 2 x 2), Reset (fit all views), and on the right: language (中文 / EN), Touch mode, Full screen, Panel, Settings, Help.
• Tool column (left): the navigation tools (Navigate, Pan, Window/level), the annotation tools, Select / edit, Eraser, the annotation colour and line width. When the window is too short for all buttons, scroll the column with the wheel or a finger.
• Four views: 3D volume rendering (top left), XY (top right), YZ (bottom left), XZ (bottom right). Each has a coloured tag, a header with Fit, Screenshot and Maximize buttons, and the 2D views have a slice slider with - / + buttons. The active view has a blue frame.
• Side panel (right): Display (brightness/contrast, colour map, overlays), 3D (rendering options), Annotations (list, export) and Info (data properties, voxel size, cursor position). Hide or show it with Panel (F9).
• Status bar: messages, the value under the pointer, and the 3D renderer in use.

Maximizing a view

Any view can fill the whole layout: click its Maximize button, double-click inside it, double-click its header, double-tap it with a finger, or press Ctrl+1 (3D), Ctrl+2 (XY), Ctrl+3 (YZ), Ctrl+4 (XZ). Do the same again, or press F10, to return to the 2 x 2 layout. Double-clicking inside a 2D view maximizes it with the Navigate, Pan, Window/level and Select tools (with a drawing tool active, a double-click belongs to the drawing, e.g. it finishes a polygon).

3. Opening data

You can also drag and drop a file or folder onto the window, open one of the Recent items, or start the program with a path: PortableVolumeViewer.exe D:\data\stack.

Voxel size. Measurements and the true proportions of the YZ / XZ views depend on the voxel size. Check it on the Info page and correct X, Y, Z and the unit if needed, then press Apply. For an image folder only X and Y can be read from the files; Z is then assumed equal to X and a yellow note says so.

Very large data. If a volume needs more memory than is free, the program offers to load it at reduced resolution (every 2nd voxel along each axis = 1/8 of the memory). You can also choose this permanently under Settings > General > Loading. The 3D view always uses a reduced copy (see the 3D view); the slice views show the loaded data at full resolution.

4. The slice views (XY, YZ, XZ)

XY shows a slice at a given Z, YZ a slice at a given X (rows = Z), XZ a slice at a given Y (rows = Z). Slice 1 is at the top. The views are drawn in their true physical proportions. The coloured lines are the other two planes: red = YZ plane, green = XZ plane, blue = XY plane.

• Move the cross-hairs (Navigate tool, N): click or drag in a view. The other two views jump to that position.
• Change slice: mouse wheel over the view, the slider and the - / + buttons below it, the arrow keys (Page Up / Page Down = 10 slices), or a three-finger swipe up / down.
• Zoom: hold the wheel button (middle button) and drag up to zoom in or down to zoom out around the point where you pressed; or Ctrl + wheel; or the + / - keys; or pinch with two fingers. Home or the Fit button fits the slice to the view.
• Pan: drag with the right mouse button, use the Pan tool (H), or drag with two fingers.
• Brightness / contrast: on the Display page drag the two handles of the histogram (or the band between them), type Min / Max, or press Auto (0.5 % - 99.8 % of the values) or Full range. With the Window/level tool (W) drag left/right for contrast and up/down for brightness in any 2D view.
• Colour map: grey, hot, bone, viridis, magma, rainbow, cool-warm, green, red, cyan; Invert reverses it.
• Overlays: cross-hairs, scale bar, slice and pixel information, annotations, measurements, smooth display when magnified, and showing annotations of neighbouring slices (± N).

The top-left corner of each view shows the slice number and its physical position, the top-right corner the zoom, the bottom-left corner the voxel coordinates and value under the pointer, the bottom-right corner the scale bar.

5. The 3D view

• Rotate: drag with the left button or one finger. Pan: drag with the right button, Shift + left button, or two fingers. Zoom: drag with the wheel button held, turn the wheel, Ctrl + left drag, or pinch. Roll: twist two fingers. Reset: the Fit button in the header, Home or R.
• Mode (3D page): volume (composite), maximum / minimum / average intensity projection, iso-surface (choose the iso value).
• Colour map and value range: by default the same as the 2D views; untick Same as the 2D views to set a separate range with the histogram.
• Opacity curve (soft, linear, threshold, peak, inverse) and Opacity control how transparent the material is. Lighting / shading adds depth.
• Quality: Sampling (fast / normal / high) and Resolution (256 - 1024 voxels per axis, or full). The 3D view uses a reduced copy of the volume so that it stays fluid; choose a higher resolution on a strong graphics card.
• Show: volume, slices (the three current slices drawn in 3D), slice planes (coloured frames), bounding box, axes, annotations.
• Crop: the X / Y / Z range sliders cut the volume; Reset crop undoes it.
• Camera: look along +X, -X, +Y, -Y, +Z, -Z, reset, or let it rotate continuously.

Renderer. At start-up the program tests the graphics card. On computers without a usable graphics driver (virtual machines, some remote desktops) it uses its own software OpenGL automatically (slower, the status bar says "software OpenGL"); if even that is impossible it shows a simple maximum-intensity projection. Settings > 3D rendering can force a choice (takes effect after a restart).

6. Annotations and measurements

Annotations are drawn in the 2D views; each belongs to one slice of one view. Lengths, areas and angles use the voxel size, so they are in physical units (µm, mm...). Annotations also appear in the 3D view.

• Select / edit (S): click an annotation to select it; drag it to move it, drag a white handle to change a point; double-click a text to edit it. Delete removes the selected annotation.
• Eraser (X): click or drag over annotations to delete them.
• Colour and line width (bottom of the tool column) apply to new annotations and to the selected one.
• Undo / Redo: Ctrl+Z / Ctrl+Y or the toolbar buttons. Esc cancels a drawing in progress.
• Annotations page: the list of all annotations with their measurements. Selecting an item jumps to its slice. Buttons: Go to, Text..., colour, Delete, Clear all, Load..., Save... (JSON) and CSV... (a table of all measurements with voxel coordinates, readable by Excel).
• Automatic saving: annotations are saved automatically while you work and come back the next time you open the same data. Save (Ctrl+S) writes a JSON file you can keep with your data or share; if it is saved next to the data as <name>.annotations.json, it is loaded automatically too.

7. Screenshots

• Screenshot (toolbar, F12): all visible views as they are arranged on screen, saved as a picture file.
• The arrow beside it, the File > Screenshot menu or the camera button in each view header: Active view (Shift+F12), 3D view, Slice at full resolution (the current slice with its annotations and scale bar, one image pixel per voxel), Copy all views to the clipboard (Ctrl+Shift+C), Open the screenshot folder.
• Pictures go to Pictures\PortableVolumeViewer with the data name and the time in the file name. Folder, format (PNG, JPG, TIFF, BMP) and size (1x, 2x, 3x) are set under Settings > General.

8. Touch screens

Touch mode (toolbar button Touch) enlarges every button, slider, handle and list row for fingers. It is switched on automatically on a computer with a touch screen and can be changed at any time. Every function is reachable with taps; no right-click or keyboard is needed. A pen works like a mouse.

9. Cloud drives and web links

Choose Cloud in the toolbar (Ctrl+Shift+D). Downloads are kept in the cache and reused when you open the same file again.

Google Drive

• Share links (no sign-in): paste the link of a file or folder that is shared with Anyone with the link on the Share link page and press Open. A file is downloaded and opened; a folder is listed - open one of its files, or press Open this folder as a volume to download its images as a stack.
• Your own Drive (optional): needs your own Google OAuth client. In the Google Cloud console create a project, enable the Google Drive API, set up the OAuth consent screen (add yourself as a test user), create an OAuth client ID of type Desktop app, and enter the client ID and secret under Settings > Cloud. Then press Sign in on the Google Drive page; your browser opens for the sign-in and the program continues by itself. Access is read-only.

Baidu Netdisk (百度网盘)

• Create a free app on the Baidu Netdisk open platform (pan.baidu.com/union, type: software) and enter its AppKey and SecretKey under Settings > Cloud.
• Press Sign in on the Baidu Netdisk page: a code is shown, your browser opens the Baidu page where you enter it (or scan the QR code with the Baidu Netdisk app). Then browse My netdisk and open a file or folder.
• Share links: Baidu does not allow other programs to open share links. Paste the shared text (link and extraction code) on the Share link page and press Open: the program explains this and offers to open the link in your browser (with the extraction code filled in). Save the files to your own netdisk there, then open them from My netdisk.

Other links

Any direct download link (http or https) can be pasted on the Share link page or with Open > Open web link.... Dropbox and GitHub file links are converted to direct downloads automatically.

10. Settings and where data is kept

• Settings > General: language (or like Windows), touch mode (automatic / on / off), loading at reduced resolution, screenshot folder, format and size.
• Settings > 3D rendering: automatic, graphics card, software OpenGL or CPU only.
• Settings > Cloud: Google API key and OAuth client, Baidu AppKey and SecretKey, the download cache (size, open, clear).
• Language: the 中文 / EN button (Ctrl+L) switches the whole interface immediately, including the standard dialogs.

Settings, the cache, automatically saved annotations, sign-in tokens (encrypted for your Windows account) and logs are kept in %LOCALAPPDATA%\PortableVolumeViewer. To keep everything beside the program instead (fully portable, e.g. on a USB stick), create a folder named UserData next to PortableVolumeViewer.exe. To remove the program, delete its folder (and %LOCALAPPDATA%\PortableVolumeViewer if you want to remove the settings too).

11. Keyboard and mouse reference

12. Troubleshooting

The 3D view stays black or says "Starting the 3D view..."

The graphics test takes a few seconds at start-up. If it remains black, choose Settings > 3D rendering > Software OpenGL and restart.

"The volume needs ... of memory"

Accept loading at reduced resolution, close other programs, or set Settings > General > Loading to every 2nd voxel.

The YZ / XZ views look squashed or stretched

The Z voxel size is probably wrong. Correct it on the Info page and press Apply.

Images of a folder are in the wrong order

Files are sorted naturally by name (2 before 10). Rename them so that the numbers reflect the slice order.

Google Drive says the file is not public or the download limit is reached

Ask the owner to share it with "Anyone with the link", try again later, or sign in with your own Google account.

Where is the log?

%LOCALAPPDATA%\PortableVolumeViewer\logs\pvv.log (or UserData\logs in portable mode). Please attach it when you report a problem to info@vyz.world.