# Changelog #31 - UV List Maps (TASK-014-11)

**Date:** 2025-11-27
**Version:** 1.9.10
**Phase:** Phase 7 - Introspection & Listing APIs
**Task:** TASK-014-11

---

## 📋 Summary

Implemented `uv_list_maps` tool - the first tool in a new UV Tools domain for texture coordinate mapping operations. This tool provides comprehensive UV map introspection for mesh objects, enabling AI agents to plan UV workflows and verify texture coordinate setups.

---

## ✨ Features Added

### Domain Layer
- **`server/domain/tools/uv.py`** (NEW)
  - Created `IUVTool` interface
  - Defined `list_maps()` abstract method

### Application Layer
- **`server/application/tool_handlers/uv_handler.py`** (NEW)
  - Implemented `UVToolHandler` class
  - RPC handler for `uv.list_maps` endpoint
  - Validates mesh type and object existence

### Blender Addon Handler
- **`blender_addon/application/handlers/uv.py`** (NEW)
  - Implemented `UVHandler` class with `list_maps()` method
  - Accesses `obj.data.uv_layers` for UV map data
  - Reads active flags: `uv_layer.active`, `uv_layer.active_render`
  - Counts UV coordinates via `len(uv_layer.data)`
  - Validates mesh type before processing

### MCP Adapter
- **`server/adapters/mcp/server.py`**
  - Added `@mcp.tool() uv_list_maps()`
  - Tagged: `[UV][SAFE][READ-ONLY]`
  - Formatted output with active flags and optional counts

### Dependency Injection
- **`server/infrastructure/di.py`**
  - Added `get_uv_handler()` provider function
  - Imports `IUVTool` and `UVToolHandler`

### Registration
- **`blender_addon/__init__.py`**
  - Imported `UVHandler`
  - Instantiated `uv_handler` in composition root
  - Registered RPC endpoint: `uv.list_maps`

---

## 📊 Return Data Structure

```json
{
  "object_name": "Cube",
  "uv_map_count": 1,
  "uv_maps": [
    {
      "name": "UVMap",
      "is_active": true,
      "is_active_render": true,
      "uv_loop_count": 24
    }
  ]
}
```

---

## 🧪 Testing

### Test File
- **`tests/test_uv_tools.py`** (NEW)
  - `test_uv_list_maps_basic()` - Basic UV map listing
  - `test_uv_list_maps_with_island_counts()` - With optional island counts
  - `test_uv_list_maps_invalid_object()` - Invalid object name handling
  - `test_uv_list_maps_non_mesh_object()` - Non-mesh object validation

All tests include Blender availability checks and skip gracefully when Blender is not running.

---

## 📚 Documentation Updates

### New Architecture Documentation
- **`_docs/UV_TOOLS_ARCHITECTURE.md`** (NEW)
  - Documented tool #1: `uv_list_maps`
  - Architecture layers and patterns
  - Future enhancements (island counting, overlap detection, density analysis)
  - Related tools and use cases

### Tools Summary
- **`_docs/AVAILABLE_TOOLS_SUMMARY.md`**
  - Added UV Tools section with `uv_list_maps`

### Task Tracking
- **`_docs/_TASKS/TASK-014-11_UV_List_Maps.md`**
  - Marked as ✅ Done
  - Added completion date: 2025-11-27

---

## 🔧 Use Cases

1. **UV Setup Verification**: Check which UV maps exist on an object
2. **Active Map Identification**: Determine which UV map is active for editing/rendering
3. **Texture Workflow Planning**: Ensure objects have proper UV maps before material assignment
4. **Multi-UV Management**: Inspect objects with multiple UV maps (e.g., lightmap + texture map)
5. **Quality Control**: Verify UV maps exist before export

---

## 💡 Key Implementation Details

- **Mesh-only validation**: Tool checks `obj.type == 'MESH'` before accessing UV data
- **Object Mode operation**: No mode switching required, improving performance
- **Active flag tracking**: Reports both edit-active and render-active UV maps
- **UV loop counting**: Counts total UV coordinates via `len(uv_layer.data)`
- **Island counting placeholder**: Marked as future enhancement (requires bmesh analysis)

---

## 🎯 Future Enhancements

- **UV Island Counting**: Implement proper island detection using bmesh.ops
- **UV Overlap Detection**: Identify overlapping UV coordinates for optimization
- **UV Density Analysis**: Calculate texel density per face for texture resolution planning
- **UV Distortion Metrics**: Measure stretching and compression
- **Active Map Setting**: Tool to programmatically change active UV map

---

## 🧩 Related Tools

- `scene_inspect_object` - Includes basic UV map count in object inspection
- `material_list_by_object` - Shows material slots (textures use UV maps for coordinates)

---

**Status:** ✅ Complete
**Next:** TASK-014-12 (Mesh List Groups)
