metalness

金属材质参数生成工具库，专注于通过多层级参数配置，快速生成符合物理特性的金属材质参数，适配Three.js等3D引擎。

核心特点

• 多层级参数控制：从基础属性到环境适配，支持精细化配置（如纯度、氧化程度、表面工艺等）
• 物理特性匹配：参数基于真实金属物理特性校准（如黄金金属度≈0.99，氧化铜金属度≈0.65）
• 场景化配置：参数选项贴近实际使用场景（如"潮湿环境"、"室外强光"、"工业磨损"）
• 零依赖：纯TypeScript实现，返回通用材质格式（支持Three.js等主流3D引擎）

安装

npm install metalness
# 或
yarn add metalness

快速开始

基础使用（获取默认材质）

import { get } from 'metalness';

// 获取默认黄金材质参数（24k抛光，室内环境）
const goldMaterial = get('gold');
console.log(goldMaterial);
// {
//   color: [1.0, 0.78, 0.35],
//   metalness: 0.99,
//   roughness: 0.05,
//   reflectivity: 0.97,
//   envMapIntensity: 1.5
// }

自定义配置（以铜材质为例）

import { copper } from 'metalness';
import * as THREE from 'three';

// 配置：黄铜材质 + 中度氧化 + 磨砂表面 + 潮湿环境
const brassParams = copper({
  type: 'brass',
  oxidation: 'medium',
  finish: 'matte',
  environment: 'humid'
});

// 转换为Three.js材质
const material = new THREE.MeshStandardMaterial({
  color: new THREE.Color(...brassParams.color),
  metalness: brassParams.metalness,
  roughness: brassParams.roughness,
  envMapIntensity: brassParams.envMapIntensity
});

支持的金属类型

| 金属类型 | 核心配置维度 | 典型场景 | |----------|--------------|----------| | gold | 纯度、表面工艺、磨损程度、环境光 | 珠宝、高端装饰 | | silver | 合金类型、 tarnish程度、使用场景 | 器皿、首饰、工业部件 | | copper | 铜类型、氧化等级、表面工艺、环境湿度 | 管道、复古装饰、乐器 | | iron | 合金类型、锈蚀等级、表面处理、使用场景 | 工业零件、工具、结构件 | | aluminum | 铝型号、表面处理、阳极氧化色、环境 | 工业型材、设备外壳、海洋工程 |

详细参数配置

1. 黄金（gold）

| 层级参数 | 可选值 | 说明 | |----------|--------|------| | purity | '24k'（默认）、'18k'、'14k' | 纯度越高，色泽越亮，金属度越高 | | finish | 'polished'（默认）、'matte'、'brushed'、'gilded'、'engraved' | 表面工艺，影响粗糙度 | | wear | 'new'（默认）、'slight'、'heavy' | 磨损程度，叠加修正粗糙度 | | environment | 'medium'（默认）、'low'、'high'、'extreme' | 环境光强度，影响反射强度 |

示例：18k磨砂黄金旧件（室外强光环境）

gold({
  purity: '18k',
  finish: 'matte',
  wear: 'heavy',
  environment: 'high'
});

2. 白银（silver）

| 层级参数 | 可选值 | 说明 | |----------|--------|------| | alloy | 'pure'（默认）、'sterling'、'plated' | 合金类型，纯银金属度最高 | | finish | 'polished'（默认）、'matte'、'brushed'、'plated'、'oxidized-light' | 表面工艺 | | tarnish | 'none'（默认）、'light'、'heavy' | tarnish（氧化发黑）程度，影响颜色和金属性 | | scenario | 'decorative'（默认）、'industrial'、'jewelry'、'structural' | 使用场景，影响反射强度 |

示例：镀银拉丝重度 tarnish 工业件

silver({
  alloy: 'plated',
  finish: 'brushed',
  tarnish: 'heavy',
  scenario: 'industrial'
});

3. 铜（copper）

| 层级参数 | 可选值 | 说明 | |----------|--------|------| | type | 'pure'（默认）、'brass'（黄铜）、'bronze'（青铜） | 铜类型，影响基础色泽 | | oxidation | 'none'、'light'（默认）、'medium'、'heavy' | 氧化等级，氧化越重越接近铜绿色 | | finish | 'polished'（默认）、'matte'、'brushed' | 表面工艺，影响粗糙度 | | environment | 'dry'（默认）、'humid' | 环境湿度，潮湿环境增强氧化质感 |

示例：黄铜重度氧化磨砂件（潮湿环境）

copper({
  type: 'brass',
  oxidation: 'heavy',
  finish: 'matte',
  environment: 'humid'
});

4. 铁（iron）

| 层级参数 | 可选值 | 说明 | |----------|--------|------| | alloy | 'steel'（默认）、'pure'、'cast-iron' | 合金类型，钢的金属性最高 | | rust | 'pristine'、'slight'（默认）、'moderate'、'severe' | 锈蚀等级，锈蚀越重颜色越偏铁锈红 | | finish | 'machined'（默认）、'as-cast'、'painted' | 表面处理，影响基础粗糙度 | | usage | 'static'（默认）、'moving'、'exposed' | 使用场景，活动部件更粗糙 |

示例：钢轻微锈蚀机加工活动部件

iron({
  alloy: 'steel',
  rust: 'slight',
  finish: 'machined',
  usage: 'moving'
});

5. 铝（aluminum）

| 层级参数 | 可选值 | 说明 | |----------|--------|------| | grade | '1000'、'3000'、'6000'（默认） | 铝型号，影响基础色泽 | | treatment | 'mill'（默认）、'polished'、'anodized'、'powder-coated' | 表面处理，阳极氧化支持颜色定制 | | anodizeColor | 'clear'（默认）、'black'、'gold'、'blue' | 阳极氧化色（仅treatment='anodized'时生效） | | environment | 'indoor'（默认）、'outdoor'、'marine' | 使用环境，海洋环境更易腐蚀 |

示例：3000系黑色阳极氧化铝（海洋环境）

aluminum({
  grade: '3000',
  treatment: 'anodized',
  anodizeColor: 'black',
  environment: 'marine'
});

API 文档

1. 金属材质函数

| 函数 | 说明 | 返回值 | |------|------|--------| | gold(options?) | 生成黄金材质参数 | MaterialParams | | silver(options?) | 生成白银材质参数 | MaterialParams | | copper(options?) | 生成铜材质参数 | MaterialParams | | iron(options?) | 生成铁材质参数 | MaterialParams | | aluminum(options?) | 生成铝材质参数 | MaterialParams |

MaterialParams 结构：

{
  color: [number, number, number]; // RGB数组，值范围0-1
  metalness: number; // 金属度，值范围0-1
  roughness: number; // 粗糙度，值范围0-1
  reflectivity: number; // 反射率，值范围0-1
  envMapIntensity: number; // 环境贴图强度
}

2. 工具函数

| 函数 | 说明 | 返回值 | |------|------|--------| | get(type) | 获取指定金属的默认材质参数 | MaterialParams | | getMetadata() | 获取所有金属的层级参数说明 | 元数据对象 |

许可证

MIT License © 2023