====== UV Coordinates ======

=== Configuring UV Mapping Parameters with JSON ===

The UV coordinates generated by this software are suitable only for **seamless textures**. If you intend to use the generated geometry with baked textures, it is recommended to export the geometry as a watertight solid in the **''.OBJ''** format and unwrap it manually. You can do this using the **''--no-uvs''** command. The **''.OBJ''** format produces a mesh with a closed volume that can be more easily unwrapped in software such as Blender. The **''uv''** object can be specified **globally** or inside the **''frame":[....]''** array or inside **''innerPanel''** object.

[]
*Figure: UV settings block in JSON used globally*
<code json>
"uv": {
	"patchSize": 150,
	"uvOrigin": "ORIGIN",
	"uOffset": 0,
	"vOffset": 0
},
</code>

The section provided here is an example of a JSON object representing the UV mapping parameters. The **''uv''** key contains an object that holds the UV mapping properties.

The properties inside this object (e.g., **''patchSize''**, **''uvorigin''**, **''uOffset''**, **''vOffset''**, **''rotation''**) are key-value pairs that define the configuration for UV mapping.
All of them override the global values are optional.

[ array]]
*Figure: UV settings block inside inside the **''frame":[....]''** array*
<code json>
"frame": [
	{
		"board": "1",
		"position": {
			"x": 0,
			"y": 0
		},
		"profile": "board",
		"uv": {
			"patchSize": 150,
			"uvorigin": "ORIGIN",
			"uOffset": 0,
			"vOffset": 0
			"rotation": 90
		}
	},
	{
		"board": "2",
		"position": {
			"x": 609.6,
			"y": 0
		},
		"profile": "board",
		"uv": {
			"rotation": 0
		}
	}, ......rest of boards..............
]
</code>



=== UV Mapping ("uvOrigin") ===

The following parameters control how UV coordinates are generated for seamless texture mapping in 3D models. These options are provided in the JSON configuration and are interpreted in millimeters (**mm**).

  * **''uvOrigin''** (string):

Defines the starting point (origin) of the UV coordinate system when unwrapping the surface of a 3D object. This affects where textures begin when mapped onto geometry.

  * **''CENTER''**: (Default) The UV origin is centered on the surface (i.e., at the middle of the x-z plane), as in the legacy Model Solid 1.0 implementation.
  * **''ORIGIN''**: The UV origin is aligned with the (0, 0) coordinate of the local object space, typically the lower-left corner.

If the **''uvOrigin''** field is missing or invalid, **''CENTER''** is used as the fallback behavior.


^ **Figure 21: UV Origin Comparison** ^
| {{:ig:gfx:modelprocessor:center_origin_uv.png?nolink&600|}} |
^ Caption ^
| Isometric view of a 3×3 checker tile.  Left: UV origin at the tile center.  Right: UV origin at the lower-left corner. |


=== UV tile scale ("patchSize") ===

Determines the scale (tiling size) of the UV texture patches. This controls how large a texture appears when applied to a surface.

  * **''patchSize''** (float, in mm):

  * Default: **150** mm
  * Values that are too small or too large may be flagged as potentially meaningless depending on context.

^ **Figure 22: Patch Size View** ^
| {{:ig:gfx:modelprocessor:patchsize_150_300.png?nolink&600|}} |
^ Caption ^
| Patch size view of two shapes on a square with a side length of 450 mm. \\ Left: UV is the patch size value of 150 mm. \\ Right: UV is the patch size value of 300 mm. |


=== Offsetting texture ("uOffset") and ("vOffset") ===

  * **''uOffset''**, **''vOffset''** (float, in mm):

Optional UV offset values along the U (horizontal) and V (vertical) axes, respectively. These are applied *after* the UV origin is assigned, if no default value will be used. Offsets are useful when deliberate shifts in texture placement are needed (e.g., aligning a wood grain or pattern).

^ **Figure 23: UV Offset Comparison** ^
| {{:ig:gfx:modelprocessor:uv_no_offset.png?nolink&400|}} | {{:ig:gfx:modelprocessor:offseted_uv.png?nolink&400|}} |
^ Caption: Left: No offset. Right: Offset **uOffset** and **vOffset** with 10 mm. ||

These settings are especially important for ensuring consistent, seamless texturing across parts of a 3D model, particularly in parametric or modular design workflows.

=== UV Mapping Method ("uvType") ===

Specifies how the UV mapping is applied to the panel.

  * **Type:** string
  * **Enum:** **CUBIC**, **AUTO**
  * **Default:** **CUBIC**

  * **CUBIC** — Applies a cubic projection to the panel, useful for simple box-like geometry.
  * **AUTO** — Automatically calculates UVs based on the geometry, suitable for irregular or complex shapes.

**Note:** This setting overrides the global UV projection behavior for the panel it is applied to.

[]
*Figure: Comparison of **''uvType''** methods.
//Left:// **CUBIC** — single projection along X/Y/Z axes.
//Right:// **AUTO** — multiple UV islands separated by seams.*

<code json>
"uv": {
	"patchSize": 150,
	"uvorigin": "ORIGIN",
	"uOffset": 0,
	"vOffset": 0,
	"uvType": "CUBIC"
},

"frame": [
	{
		"board": "1",
		"position": { "x": 0, "y": 0 },
		"profile": "board",
		"uv": {
			"patchSize": 150,
			"uvorigin": "ORIGIN",
			"uOffset": 0,
			"vOffset": 0,
			"rotation": 90,    // 90° clockwise
			"uvType": "AUTO"   // Automatic mapping for irregular shapes
		}
	},
	{
		"board": "2",
		"position": { "x": 609.6, "y": 0 },
		"profile": "board",
		"uv": {
			"rotation": -45,   // 45° counter-clockwise
			"uvType": "CUBIC"  // Cubic projection
		}
	}
]
</code>

=== UV Rotation ("rotation") ===

The **''rotation''** parameter is applied only within a **''frame''** array, where it overrides the global UV rotation (which defaults to 0.0°). It is specified per board and must be given in degrees—negative values are accepted.

  * Only valid inside the **''frame''** array for individual boards.
  * Overrides the global UV rotation value of 0.0°.
  * Expressed in degrees; e.g., **"rotation": 90** for a 90° clockwise turn, or **"rotation": -45** for a 45° counter-clockwise turn.

==== Usage Example ====

<code json>
"uv": {
	"patchSize": 150,
	"uvorigin": "ORIGIN",
	"uOffset": 0,
	"vOffset": 0
},

"frame": [
	{
		"board": "1",
		"position": { "x": 0, "y": 0 },
		"profile": "board",
		"uv": {
			"patchSize": 150,
			"uvorigin": "ORIGIN",
			"uOffset": 0,
			"vOffset": 0,
			"rotation": 90    // 90° clockwise
		}
	},
	{
		"board": "2",
		"position": { "x": 609.6, "y": 0 },
		"profile": "board",
		"uv": {
			"rotation": -45    // 45° counter-clockwise
		}
	}
]
</code>

**Note:** It is useful when you want to adjust the wood grain along the length of a board.