F3D 颜色映射（Color Maps）完全指南：从图片色表到自定义标量着色

F3D 颜色映射Color Maps完全指南从图片色表到自定义标量着色【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d导读颜色映射Color Map是 F3D 中把数据标量scalar value映射为视觉颜色的核心机制广泛应用于科学可视化场景例如按温度、应力、高程等物理量对模型表面着色。本文以官方文档 doc/user/10-COLOR_MAPS.md 为主体完整讲解 F3D 的两种色表指定方式通过--colormap-file加载图片色表文件以及通过--colormap直接传入自定义色标值并结合仓库源码与配置深入解释文件查找顺序、支持的图片格式、色标解析规则与底层数据流。读完本文你将能够为 F3D 配置任意自定义色表并理解其从文件到渲染管线的完整实现原理。1. 概览F3D 中色表的两种指定方式F3D 提供两条互补的路径来设定科学可视化着色所用的色表方式CLI 选项适用场景图片色表文件--colormap-file使用预设色表或自行制作一张 RGB 渐变图片内联色标值--colormap快速在命令行/配置文件/脚本中手写一组标量-颜色对两种方式最终都会转换为同一份内部数据结构——f3d::colormap_t即一段形如val,r,g,b重复序列的数值向量见 library/public/types.h 中对colormap_t的定义Describe a colormap, which is a vector of repeated: val,r,g,b。这意味着无论你通过哪种方式配置渲染引擎拿到的都是同一种规范化表示。在 library/options.json 中colormap选项的类型被声明为colormap其默认值为0.0, 0.0, 0.0, 0.0, 0.4, 0.9, 0.0, 0.0, 0.8, 0.9, 0.9, 0.0, 1.0, 1.0, 1.0, 1.0它对应 4 组val,r,g,b黑色 → 红色 → 黄色 → 白色也就是官方文档中提到的默认hot预设。该默认值最终在 library/src/window_impl.cxx 中通过renderer-SetColormap(...)与renderer-SetColormapDiscretization(...)被应用到 VTK 渲染器上。2. 使用图片文件作为色表--colormap-file2.1 基本用法--colormap-file接受一个路径其取值可以是指向图片文件的绝对路径相对路径仅文件名如hot.png仅文件主干名filestem如hot不带扩展名。当给定的不是绝对路径时F3D 会按固定顺序在多个目录中查找该文件命中第一个存在的文件即停止。2.2 各平台查找目录顺序平台查找目录按顺序Linux${XDG_CONFIG_HOME}/f3d/colormaps、~/.config/f3d/colormaps、/etc/f3d/colormaps、/usr/share/f3d/colormaps、[安装目录]/share/f3d/colormapsWindows%APPDATA%\f3d\colormaps、[安装目录]\share\f3d\configs\colormapsmacOS${XDG_CONFIG_HOME}/f3d/colormaps、~/.config/f3d/colormaps、/usr/local/etc/f3d/colormaps、f3d.app/Contents/Resources/configs/colormaps用户自定义色表应放在用户配置目录Linux/macOS 为~/.config/f3d/colormapsWindows 为%APPDATA%\f3d\colormaps该目录始终排在查找顺序的最前面因此可以覆盖系统级预设。上述查找逻辑在 application/F3DColorMapTools.cxx 的F3DColorMapTools::Find函数中有完整的源码实现它首先尝试将输入作为路径直接判断是否为常规文件若不是绝对路径则依次遍历GetUserConfigFileDirectory()/colormaps、/etc/f3d/colormapsLinux/FreeBSD、/usr/share/f3d/colormapsLinux/FreeBSD、/usr/local/etc/f3d/colormapsmacOS以及GetBinaryResourceDirectory()/colormaps。当输入是文件主干名即fs::path(str).stem() str时还会对f3d::image::getSupportedFormats()返回的每种支持扩展名逐一尝试拼接查找。2.3 官方内置色表仓库在 resources/colormaps 目录下随附了 9 个开箱即用的色表文件均为 256×1 像素的 PNG对应的名称filestem与视觉渐变如下名称渐变示意256×1cividiscubehelixgist_earthhotinfernomagmaplasmaseismicviridis使用示例文件名与主干名等价# 使用主干名推荐跨平台可移植 f3d model.vtp --colormap-filehot # 或使用带扩展名的文件名 f3d model.vtp --colormap-filehot.png # 或使用绝对/相对路径 f3d model.vtp --colormap-file/path/to/my_cmap.png f3d model.vtp --colormap-file./cmaps/my_cmap.png当传入的是主干名时F3D 会依次尝试所有受支持的图片扩展名因此--colormap-filehot与--colormap-filehot.png效果完全一致。这些色表的原始许可证信息记录在 resources/colormaps/licenses.md 中。2.4 创建自定义色表图片官方文档明确你可以通过创建一张任意受支持格式的简单 RGB 图片来制作自己的色表分辨率为任意值——但如果图片高度超过 1 行只有第一行会被采用。制作完成后将图片复制到用户配置目录Linux/macOS~/.config/f3d/colormapsWindows%APPDATA%\f3d\colormaps随后即可通过--colormap-file你的色表名直接引用。这一“只取第一行”的行为在源码中有严格对应application/F3DColorMapTools.cxx 中当img.getHeight() ! 1时会输出警告The specified color map height is not equal to 1, only the first row is taken into account然后仅对第 0 行逐像素取样每个像素的归一化颜色值会被转换为(x, r, g, b)形式的四元组其中x i / (w - 1)为水平归一化坐标见 Read1DMap 实现最终拼装成f3d::colormap_tF3DColorMapTools.h 中的Read函数。也就是说色表图片的横向宽度决定了色标的采样密度纵向高度不影响结果。2.5 支持的图片格式可被--colormap-file用作色表的图片格式与项目支持的图片格式一致完整列表如下.png.pnm、.pgm、.ppm.tif、.tiff.bmp.slc.hdr.pic.jpeg、.jpg.MR.CT.mhd、.mha.tga.exr需启用F3D_MODULE_EXR编译选项.webp需启用F3D_MODULE_WEBP编译选项注意.exr与.webp属于可选模块仅在构建 F3D 时开启对应 CMake 选项后才可用其余格式随默认构建即可使用。该格式列表由f3d::image::getSupportedFormats()动态提供见 Find 函数。3. 手动指定自定义色标值--colormap3.1 语法与示例当不指定色表文件时也可以直接使用--colormap选项手动设置色标值其解析规则由 doc/user/08-PARSING.md 定义支持两种书写格式val, red, green, blue, ... val, color, ...其中color可以是 F3D 支持的任何颜色格式RGB 三元组、#RRGGBB、rgb()、hsl()、hsv()、hwb()、cmyk()或颜色名称详见 颜色解析规则 与 命名颜色列表。官方文档给出的最典型示例是默认hot预设的手动等价写法--colormap0.0,rgb(0,0,0),0.4,rgb(230,0,0),0.8,rgb(230,230,0),1.0,rgb(255,255,255)该写法由4 组“递增的标量值 对应颜色”组成标量值颜色0.0黑色rgb(0,0,0)0.4红色rgb(230,0,0)0.8黄色rgb(230,230,0)1.0白色rgb(255,255,255)标量值限定在 01 区间且必须递增介于两个关键点之间的数值会进行插值从而形成平滑渐变。这与 library/options.json 中colormap的默认值0.0,0.0,0.0,0.0, 0.4,0.9,0.0,0.0, 0.8,0.9,0.9,0.0, 1.0,1.0,1.0,1.0即每组为val,r,g,b在语义上完全一致。3.2 命令行中的括号注意事项当在命令行中直接使用带括号的颜色格式如rgb(...)、hsl(...)时括号会被 shell 解释因此需要将整个选项用引号包裹# 正确整体加引号 f3d model.vtp --colormap0.0,rgb(0,0,0),1.0,rgb(255,255,255) # 错误括号可能被 shell 截断 f3d model.vtp --colormap0.0,rgb(0,0,0),1.0,rgb(255,255,255)该注意事项在 doc/user/08-PARSING.md 中有同样说明原文When using parenthesis in a command line arg, you may need to quote the entire option, eg: --background-colorrgb(84, 84, 84)。3.3 解析器与内部表示从源码实现看--colormap与--colormap-file殊途同归前者由 library/src/options.cxx 中的F3D_DECL_TYPE(colormap_t)宏展开的字符串解析器处理后者则由F3DColorMapTools::Read将图片像素转换出的std::vectordouble直接构造为f3d::colormap_tF3DColorMapTools.h。两者最终都会进入f3d::colormap_tval,r,g,b重复序列并在 library/src/window_impl.cxx 中交给 VTK 渲染器完成实际着色。由此可以推断手动色标值的插值密度完全由你提供的“标量-颜色”对数量决定——关键点越多渐变越细腻而图片色表的采样密度则由图片宽度决定。4. 配套选项让色表发挥作用的上下文colormap属于“模型着色model/scivis”选项组在 library/options.json 中与下列选项同组共同构成完整的标量着色管线选项类型默认值说明colormapcolormap见上文默认值hot标量到颜色的映射表opacity_mapdouble_vector0.0, 0.0, 1.0, 1.0标量到透明度的映射val,opacity序列rangedouble_vector空标量映射范围未设置时自动从数据计算discretizationint1domain 11024步长 5将色表离散化为固定级数array_namestring空参与着色的数据数组名componentint-1参与着色的数组分量-1 表示使用默认cellsboolfalse使用单元数据cell data而非点数据enableboolfalse启用/禁用标量着色其中colormap、opacity_map与range的配合是核心用法range决定标量映射区间--rangemin,maxopacity_map则让色表同时驱动透明度例如按高度渐隐。discretization的取值在渲染端通过SetColormapDiscretization生效window_impl.cxx可用于生成等值带效果。一个综合示例# 启用标量着色、使用 viridis 色表、限定映射范围并叠加透明度 f3d model.vtp --scalars --colormap-fileviridis --range0,100 --opacity-map0.0,1.0,1.0,0.2上述选项中scalars为启用标量着色的开关对应model.scivis.enable其余选项名均可直接用于 CLI、配置文件 或 libf3d 选项字符串 API。5. 实践建议与注意事项小结优先使用 filestem 引用色表--colormap-filehot比--colormap-file/usr/share/f3d/colormaps/hot.png更具可移植性跨平台一致。用户色表放在用户配置目录~/.config/f3d/colormapsLinux/macOS或%APPDATA%\f3d\colormapsWindows这样既能被自动发现又不会被系统更新覆盖。自制色表只认第一行制作图片时请保持高度为 1 行或多行但确保第一行即目标渐变横向分辨率决定采样密度。命令行中给带括号的颜色加引号--colormap0.0,rgb(0,0,0),1.0,rgb(255,255,255)。标量值必须递增且在 01 之间--colormap的每个关键点标量按升序排列中间值自动插值。格式可选性使用.exr/.webp色表前确认构建时已开启F3D_MODULE_EXR/F3D_MODULE_WEBP。6. 深入阅读色表文件查找与读取实现application/F3DColorMapTools.cxx、application/F3DColorMapTools.h色标类型定义f3d::colormap_tlibrary/public/types.h选项定义与默认值library/options.json渲染端应用SetColormap/SetColormapDiscretizationlibrary/src/window_impl.cxx颜色解析格式doc/user/08-PARSING.md命名颜色doc/user/09-NAMED_COLORS.md相关功能--opacity-map透明度映射、--range标量范围、--discretization色表离散化【免费下载链接】f3dFast and minimalist 3D viewer.项目地址: https://gitcode.com/GitHub_Trending/f3/f3d创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考