Materials Module

Material presets and shader functions for terrain visualization.

This module provides color presets, material configurations, and shader functions for creating professional-looking terrain renders with roads, water, and other features.

Color Presets

The module defines several color preset dictionaries:

ROAD_COLORS - Polished stone/mineral appearance for roads:

obsidian: Near-black volcanic glass
azurite: Deep blue mineral
azurite-light: Richer azurite
malachite: Deep green copper mineral
hematite: Dark iron red-gray

BASE_MATERIALS - Materials for mesh bases and backgrounds:

clay: Matte gray clay (default)
obsidian: Dark volcanic glass
chrome: Metallic chrome
plastic: Glossy white plastic
gold: Metallic gold
ivory: Off-white with warm tone

ALL_COLORS - Unified dictionary combining all presets.

Color Helper Functions

src.terrain.materials.get_all_colors_choices()[source]

Return list of all valid color preset names for argparse choices.

Get list of all available color preset names.

Return type:: list[str]

src.terrain.materials.get_all_colors_help()[source]

Generate help text listing all available color presets (unified).

Get formatted help text listing all color presets.

Return type:: str

src.terrain.materials.get_terrain_materials_choices()[source]

Return list of valid terrain material preset names for argparse choices.

Return type:: list[str]

src.terrain.materials.get_terrain_materials_help()[source]

Generate help text listing all available terrain material presets.

Return type:: str

src.terrain.materials.get_road_colors_choices()[source]

Return list of all valid color preset names for argparse choices.

Return type:: list[str]

src.terrain.materials.get_road_colors_help()[source]

Generate help text listing all available color presets.

Return type:: str

src.terrain.materials.get_base_materials_choices()[source]

Return list of all valid color preset names for argparse choices.

Return type:: list[str]

src.terrain.materials.get_base_materials_help()[source]

Generate help text listing all available color presets.

Return type:: str

Color Lookup Functions

src.terrain.materials.get_color(color)[source]

Resolve a color preset name to RGB color tuple.

Accepts either a preset color name (case-insensitive) or an RGB tuple. Color names map to predefined RGB values from ALL_COLORS (combined road colors and base materials).

For terrain material presets (like “satin”, “matte”) that don’t have associated colors, returns clay gray (0.5, 0.48, 0.45) as a neutral default.

Parameters:: color (str | Tuple[float, float, float]) – Either a preset name from ALL_COLORS or an RGB tuple (0-1 range). Available presets: {get_all_colors_help()}
Returns:: RGB tuple (0-1 range) representing the color.
Raises:: ValueError – If color is a string but not in ALL_COLORS or TERRAIN_MATERIALS.
Return type:: Tuple[float, float, float]

Examples

>>> get_color("clay")
(0.5, 0.48, 0.45)

>>> get_color("azurite")  # Road color preset
(0.04, 0.09, 0.16)

>>> get_color("GOLD")  # Case-insensitive
(1.0, 0.766, 0.336)

>>> get_color("satin")  # Terrain material - returns clay gray
(0.5, 0.48, 0.45)

>>> get_color((0.6, 0.55, 0.5))  # Custom RGB
(0.6, 0.55, 0.5)

Convert color preset name or RGB tuple to normalized RGB.

Example:

# Using preset name
rgb = get_color("azurite")  # Returns (0.04, 0.09, 0.16)

# Using RGB tuple
rgb = get_color((0.5, 0.5, 0.5))  # Returns (0.5, 0.5, 0.5)

src.terrain.materials.get_base_material_color(material)[source]

Resolve a color preset name to RGB. Alias for get_color().

Get color for base material presets.

Parameters:: material (str | Tuple[float, float, float])
Return type:: Tuple[float, float, float]

src.terrain.materials.get_terrain_material_params(material)[source]

Get terrain material parameters by preset name.

Parameters:: material (str) – Preset name (case-insensitive). One of: - “matte”: Pure diffuse, no specular (3D print preview) - “eggshell”: Very subtle sheen (print-quality renders) - “satin”: Soft highlights (general-purpose, default) - “ceramic”: Glossy museum model look - “lacquered”: Very glossy varnished wood look - “clearcoat”: Glossy clear layer over matte color - “velvet”: Soft fabric-like with edge highlights
Returns:: Dict of Principled BSDF parameters.
Raises:: ValueError – If material name is not recognized.
Return type:: Dict

Examples

>>> params = get_terrain_material_params("satin")
>>> params["roughness"]
0.7

Get material parameters (color, roughness, metallic) for terrain materials.

Material Application Functions

src.terrain.materials.apply_colormap_material(material, terrain_material=None)[source]

Create a physically-based material for terrain visualization using vertex colors.

Uses pure Principled BSDF for proper lighting response - no emission. Terrain responds realistically to sun direction and casts proper shadows.

Parameters:

material (Material) – Blender material to configure
terrain_material (str | None) – Optional preset name for material appearance. One of: - “matte”: Pure diffuse, no specular (3D print preview) - “eggshell”: Very subtle sheen (print-quality renders) - “satin”: Soft highlights (general-purpose, recommended) - “ceramic”: Glossy museum model look - “lacquered”: Very glossy varnished wood look - “clearcoat”: Glossy clear layer over matte color - “velvet”: Soft fabric-like with edge highlights If None, uses DEFAULT_TERRAIN_MATERIAL (“satin”).

Return type:

None

Apply vertex color material to terrain mesh.

src.terrain.materials.apply_water_shader(material, water_color=(0.0, 0.153, 0.298), terrain_material=None)[source]

Apply water shader to material, coloring water areas based on vertex alpha channel. Uses alpha channel to mix between water color and elevation colors. Water pixels (alpha=1.0) render as water color; land pixels (alpha=0.0) show elevation colors.

Parameters:

material (Material) – Blender material to configure
water_color (Tuple[float, float, float]) – RGB tuple for water (default: University of Michigan blue #00274C)
terrain_material (str | None) – Optional preset name for land material appearance. See apply_colormap_material() for available presets. If None, uses DEFAULT_TERRAIN_MATERIAL.

Return type:

None

Apply water shader with custom color and glossiness.

src.terrain.materials.apply_terrain_with_obsidian_roads(material, terrain_style=None, road_color='obsidian', terrain_material=None)[source]

Create a material with glossy roads and terrain colors/test material.

Reads from two vertex color layers: - “TerrainColors”: The actual terrain colors (used for non-road areas) - “RoadMask”: R channel marks road pixels (R > 0.5 = road)

Roads render with glossy dielectric properties (like polished stone). Non-road areas use either vertex colors or a test material.

Parameters:

material (Material) – Blender material to configure
terrain_style (str | None) – Optional test material for terrain (“chrome”, “clay”, etc.) If None, uses vertex colors with terrain_material preset.
road_color (str | Tuple[float, float, float]) – Road color - either a preset name from ROAD_COLORS (“obsidian”, “azurite”, “azurite-light”, “malachite”, “hematite”) or an RGB tuple (0-1 range). Default: “obsidian” (near-black).
terrain_material (str | None) – Optional preset name for terrain material appearance when using vertex colors (terrain_style=None). One of: “matte”, “eggshell”, “satin”, “ceramic”, “lacquered”, “clearcoat”, “velvet”. Default: DEFAULT_TERRAIN_MATERIAL.

Return type:

None

Apply vertex colors to terrain with glossy road material. Used in Combined Render: Full-Featured Example for road rendering.

Example:

apply_terrain_with_obsidian_roads(
    terrain_mesh,
    road_color="azurite",
    road_roughness=0.05
)

src.terrain.materials.apply_glassy_road_material(material)[source]

Deprecated: Use apply_terrain_with_obsidian_roads() instead.

Apply glossy glass-like material to road surfaces.

Parameters:: material (Material)
Return type:: None

src.terrain.materials.apply_test_material(material, style)[source]

Apply a test material to the entire terrain mesh.

Test materials ignore vertex colors and apply a uniform material style for testing lighting, shadows, and mesh geometry.

Parameters:

material (Material) – Blender material to configure
style (str) – Material style name - any color from ALL_COLORS ({get_all_colors_help()}) or “terrain” for normal vertex colors.

Raises:

ValueError – If style is not recognized

Return type:

None

Apply test materials for development (obsidian, chrome, clay, plastic, gold, ivory).

Example:

apply_test_material(material, style="obsidian")
apply_test_material(material, style="chrome")