# metalness

**Repository Path**: nodets/metalness

## Basic Information

- **Project Name**: metalness
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-22
- **Last Updated**: 2025-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# metalness

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


## 核心特点

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


## 安装

```bash
npm install metalness
# 或
yarn add metalness
```


## 快速开始

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

```typescript
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
// }
```

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

```typescript
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磨砂黄金旧件（室外强光环境）
```typescript
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 工业件
```typescript
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'` | 环境湿度，潮湿环境增强氧化质感 |

**示例**：黄铜重度氧化磨砂件（潮湿环境）
```typescript
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'` | 使用场景，活动部件更粗糙 |

**示例**：钢轻微锈蚀机加工活动部件
```typescript
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系黑色阳极氧化铝（海洋环境）
```typescript
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` 结构：
```typescript
{
  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