technical_documentation.tex

\documentclass[11pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{geometry}
\usepackage{tikz}
\usepackage{float}
\usepackage{hyperref}
\usepackage{listings}
\usepackage{xcolor}
\usepackage{algorithm}
\usepackage{algpseudocode}
\usepackage{textgreek}

\geometry{margin=1in}

\title{\textbf{UVfromView: Technical Documentation}\\
\large Automatic UV Projection for Blender Hard-Surface Models}
\author{Bartosz Titkin}
\date{Version 1.0.0 --- January 2026}

\begin{document}

\maketitle

\begin{abstract}
This document provides comprehensive technical documentation for the UVfromView Blender addon. We present the mathematical foundations, algorithmic implementation, and projection methodologies used for automatic UV mapping aligned to global axes. The addon implements multi-axis projection systems ranging from 6-axis cubic to 32-axis truncated icosahedral distributions, ensuring consistent texel density and UV continuity for tileable textures.
\end{abstract}

\tableofcontents
\newpage

\section{Introduction}

\subsection{Purpose}
UVfromView is a Blender addon designed to automate UV mapping for hard-surface 3D models. Unlike traditional UV unwrapping methods that require manual face selection and projection, this addon:

\begin{itemize}
    \item Automatically clusters faces based on normal directions
    \item Projects UV coordinates aligned to global orthographic axes
    \item Maintains consistent texel density across all UV islands
    \item Preserves UV continuity for seamless tileable textures
\end{itemize}

\subsection{Use Cases}
\begin{itemize}
    \item Hard-surface modeling (architecture, mechanical parts)
    \item Trim sheet workflows (modular texture atlases)
    \item Tileable texture application
    \item Game asset UV preparation
\end{itemize}

\section{Mathematical Foundations}

\subsection{Coordinate Systems}

Let $\mathbb{R}^3$ denote the 3D world space with standard orthonormal basis vectors:
\begin{equation}
    \mathbf{e}_x = \begin{pmatrix} 1 \\ 0 \\ 0 \end{pmatrix}, \quad
    \mathbf{e}_y = \begin{pmatrix} 0 \\ 1 \\ 0 \end{pmatrix}, \quad
    \mathbf{e}_z = \begin{pmatrix} 0 \\ 0 \\ 1 \end{pmatrix}
\end{equation}

UV space is defined as $\mathbb{R}^2$ with coordinates $(u, v)$.

\subsection{Face Normal Calculation}

For a triangular face with vertices $\mathbf{v}_1, \mathbf{v}_2, \mathbf{v}_3 \in \mathbb{R}^3$, the face normal $\mathbf{n}$ is:

\begin{equation}
    \mathbf{n} = \frac{(\mathbf{v}_2 - \mathbf{v}_1) \times (\mathbf{v}_3 - \mathbf{v}_1)}{\|(\mathbf{v}_2 - \mathbf{v}_1) \times (\mathbf{v}_3 - \mathbf{v}_1)\|}
\end{equation}

where $\times$ denotes the cross product and $\|\cdot\|$ is the Euclidean norm.

\subsection{Projection Matrix Construction}

For a given projection direction defined by normal $\mathbf{n}$, we construct an orthogonal projection matrix $P \in \mathbb{R}^{3 \times 3}$ that maps 3D vertices to 2D UV coordinates.

\subsubsection{Tangent and Bitangent Determination}

The projection plane is defined by two orthogonal vectors: tangent $\mathbf{t}$ and bitangent $\mathbf{b}$. These are determined based on the dominant axis of $\mathbf{n} = (n_x, n_y, n_z)$:

\begin{equation}
    (\mathbf{t}_0, \mathbf{b}_0) = 
    \begin{cases}
        (\mathbf{e}_x, \mathbf{e}_y) & \text{if } |n_z| > \max(|n_x|, |n_y|) \quad \text{(Z-dominant)} \\
        (\mathbf{e}_x, \mathbf{e}_z) & \text{if } |n_y| > |n_x| \quad \text{(Y-dominant)} \\
        (\mathbf{e}_y, \mathbf{e}_z) & \text{otherwise} \quad \text{(X-dominant)}
    \end{cases}
\end{equation}

These initial vectors are then orthogonalized using the Gram-Schmidt process:

\begin{align}
    \mathbf{t} &= \frac{\mathbf{t}_0 - (\mathbf{t}_0 \cdot \mathbf{n})\mathbf{n}}{\|\mathbf{t}_0 - (\mathbf{t}_0 \cdot \mathbf{n})\mathbf{n}\|} \\
    \mathbf{b} &= \frac{\mathbf{b}_0 - (\mathbf{b}_0 \cdot \mathbf{n})\mathbf{n} - (\mathbf{b}_0 \cdot \mathbf{t})\mathbf{t}}{\|\mathbf{b}_0 - (\mathbf{b}_0 \cdot \mathbf{n})\mathbf{n} - (\mathbf{b}_0 \cdot \mathbf{t})\mathbf{t}\|}
\end{align}

\subsubsection{Projection Matrix}

The final projection matrix is:

\begin{equation}
    P = \begin{pmatrix}
        t_x & t_y & t_z \\
        b_x & b_y & b_z \\
        n_x & n_y & n_z
    \end{pmatrix}^T
\end{equation}

For a 3D vertex $\mathbf{v} = (x, y, z)^T$, the UV coordinates are:

\begin{equation}
    \begin{pmatrix} u \\ v \end{pmatrix} = 
    \begin{pmatrix}
        \mathbf{t} \cdot \mathbf{v} \\
        \mathbf{b} \cdot \mathbf{v}
    \end{pmatrix}
\end{equation}

\section{Projection Mode Geometries}

\subsection{6-Axis Cubic Projection}

The simplest mode uses 6 cardinal directions corresponding to cube face normals:

\begin{equation}
    \mathcal{A}_6 = \{\pm\mathbf{e}_x, \pm\mathbf{e}_y, \pm\mathbf{e}_z\}
\end{equation}

Each face is mapped to its nearest cardinal axis via dot product maximization:

\begin{equation}
    \mathbf{a}^* = \arg\max_{\mathbf{a} \in \mathcal{A}_6} (\mathbf{n} \cdot \mathbf{a})
\end{equation}

\subsection{12-Axis Dodecahedral Projection}

Utilizes the 12 vertices of a regular dodecahedron, based on the golden ratio $\varphi = \frac{1 + \sqrt{5}}{2} \approx 1.618$:

\begin{equation}
    \mathcal{A}_{12} = \left\{
        \frac{1}{\|\mathbf{v}\|}\mathbf{v} \;\middle|\; \mathbf{v} \in \mathcal{V}_{\text{dodec}}
    \right\}
\end{equation}

where $\mathcal{V}_{\text{dodec}}$ consists of all permutations and sign combinations of:

\begin{align}
    &(\pm\varphi, \pm1, 0) \\
    &(\pm1, 0, \pm\varphi) \\
    &(0, \pm\varphi, \pm1)
\end{align}

\subsection{32-Axis Truncated Icosahedral Projection}

The most sophisticated mode uses 32 face normals of a truncated icosahedron (soccer ball):

\subsubsection{12 Pentagonal Faces (Icosahedron Vertices)}

\begin{equation}
    \mathcal{P}_{12} = \left\{
        \frac{1}{\|\mathbf{v}\|}\mathbf{v} \;\middle|\; \mathbf{v} \in \mathcal{V}_{\text{ico}}
    \right\}
\end{equation}

where $\mathcal{V}_{\text{ico}}$ consists of all permutations and sign combinations of:

\begin{align}
    &(0, \pm1, \pm\varphi) \\
    &(\pm1, \pm\varphi, 0) \\
    &(\pm\varphi, 0, \pm1)
\end{align}

\subsubsection{20 Hexagonal Faces (Dodecahedron Vertices)}

Define $\psi = 1/\varphi \approx 0.618$ (reciprocal golden ratio). Then:

\begin{equation}
    \mathcal{H}_{20} = \left\{
        \frac{1}{\|\mathbf{v}\|}\mathbf{v} \;\middle|\; \mathbf{v} \in \mathcal{V}_{\text{hex}}
    \right\}
\end{equation}

where $\mathcal{V}_{\text{hex}}$ includes:

\begin{align}
    &(\pm1, \pm1, \pm1) \quad \text{(8 vertices)} \\
    &(0, \pm\varphi, \pm\psi) \quad \text{(permutations, 12 vertices)}
\end{align}

The complete truncated icosahedron axis set is:

\begin{equation}
    \mathcal{A}_{32} = \mathcal{P}_{12} \cup \mathcal{H}_{20}
\end{equation}

\section{Texel Density Normalization}

\subsection{Definition}

Texel density (TD) measures texture resolution per unit world-space area:

\begin{equation}
    \text{TD} = \frac{\text{pixels}}{\text{meter}} = \frac{\sqrt{A_{UV} \cdot S^2}}{A_{3D}}
\end{equation}

where:
\begin{itemize}
    \item $A_{UV}$ = UV island area (in UV space)
    \item $A_{3D}$ = 3D surface area (in world units)
    \item $S$ = texture resolution (pixels)
\end{itemize}

\subsection{UV Area Calculation}

For a face with $n$ vertices and UV coordinates $\mathbf{uv}_i = (u_i, v_i)$, triangulate and sum:

\begin{equation}
    A_{UV} = \sum_{i=1}^{n-2} \frac{1}{2} \left| (\mathbf{uv}_{i+1} - \mathbf{uv}_1) \times (\mathbf{uv}_{i+2} - \mathbf{uv}_1) \right|
\end{equation}

\subsection{3D Surface Area}

\begin{equation}
    A_{3D} = \sum_{\text{faces}} \frac{1}{2} \|(\mathbf{v}_2 - \mathbf{v}_1) \times (\mathbf{v}_3 - \mathbf{v}_1)\|
\end{equation}

\subsection{Scaling Factor}

To achieve target texel density $\text{TD}_{\text{target}}$:

\begin{equation}
    \alpha = \frac{\text{TD}_{\text{target}}}{\text{TD}_{\text{current}}}
\end{equation}

All UV coordinates are scaled:

\begin{equation}
    \mathbf{uv}_i' = \mathbf{c} + \alpha(\mathbf{uv}_i - \mathbf{c})
\end{equation}

where $\mathbf{c}$ is the island centroid:

\begin{equation}
    \mathbf{c} = \frac{1}{N} \sum_{i=1}^{N} \mathbf{uv}_i
\end{equation}

\section{Face Clustering Algorithm}

\subsection{Angle-Based Clustering}

Faces are grouped if their normal vectors differ by less than threshold $\theta_{\max}$:

\begin{equation}
    \mathbf{n}_i \sim \mathbf{n}_j \iff \arccos(\mathbf{n}_i \cdot \mathbf{n}_j) < \theta_{\max}
\end{equation}

This defines an equivalence relation. Clusters are the equivalence classes under this relation.

\subsection{Fixed-Axis Clustering}

For modes with predefined axes $\mathcal{A}$, assign each face to its nearest axis:

\begin{equation}
    C_k = \left\{ f \;\middle|\; \mathbf{a}_k = \arg\max_{\mathbf{a} \in \mathcal{A}} (\mathbf{n}_f \cdot \mathbf{a}) \right\}
\end{equation}

\section{Grid Layout Algorithm}

\subsection{Island Bounding Box}

For each UV island, compute:

\begin{align}
    u_{\min} &= \min_i u_i, \quad u_{\max} = \max_i u_i \\
    v_{\min} &= \min_i v_i, \quad v_{\max} = \max_i v_i \\
    w &= u_{\max} - u_{\min} \\
    h &= v_{\max} - v_{\min}
\end{align}

\subsection{Row Packing}

Islands are sorted by height (descending) and packed row-by-row:

\begin{algorithm}
\caption{Grid Layout Packing}
\begin{algorithmic}[1]
\State $x \gets 0, \; y \gets 0, \; h_{\text{row}} \gets 0$
\For{each island $I$ (sorted by height)}
    \If{$x > 0$ \textbf{and} $x + w_I > W_{\max}$}
        \State $x \gets 0$
        \State $y \gets y + h_{\text{row}} + p$
        \State $h_{\text{row}} \gets 0$
    \EndIf
    \State Translate island to $(x - u_{\min}, y - v_{\min})$
    \State $x \gets x + w_I + p$
    \State $h_{\text{row}} \gets \max(h_{\text{row}}, h_I)$
\EndFor
\end{algorithmic}
\end{algorithm}

where $W_{\max}$ is maximum row width and $p$ is padding.

\section{Narrow Face Auto-Rotation}

\subsection{Aspect Ratio Detection}

For each face, compute bounding box in projection space:

\begin{equation}
    r = \frac{\max(w, h)}{\min(w, h)}
\end{equation}

If $r > r_{\text{threshold}}$ (default 2.5), the face is classified as narrow.

\subsection{Rotation Transformation}

Apply 90° rotation if aspect ratio $h/w > r_{\text{threshold}}$:

\begin{equation}
    \begin{pmatrix} u' \\ v' \end{pmatrix} = 
    \begin{pmatrix} 0 & -1 \\ 1 & 0 \end{pmatrix}
    \begin{pmatrix} u \\ v \end{pmatrix} =
    \begin{pmatrix} -v \\ u \end{pmatrix}
\end{equation}

This aligns texture lines with the longest edge dimension.

\section{Implementation Details}

\subsection{Complexity Analysis}

Let $F$ be the number of faces and $C$ be the number of clusters.

\begin{itemize}
    \item Face clustering: $O(F \log F)$ (sorting-based)
    \item Projection per face: $O(1)$
    \item Texel density calculation: $O(F)$ per cluster
    \item Grid layout: $O(C \log C)$ (sorting islands)
\end{itemize}

Total complexity: $O(F \log F + CF)$

\subsection{Numerical Stability}

All vector normalizations include epsilon checks:

\begin{equation}
    \hat{\mathbf{v}} = 
    \begin{cases}
        \frac{\mathbf{v}}{\|\mathbf{v}\|} & \text{if } \|\mathbf{v}\| > \epsilon \\
        \mathbf{0} & \text{otherwise}
    \end{cases}
\end{equation}

where $\epsilon = 10^{-6}$ prevents division by zero.

\section{Usage Examples}

\subsection{Typical Workflow}

\begin{enumerate}
    \item Import/create hard-surface model
    \item Select object in Edit Mode
    \item Set projection mode (32-Axis recommended)
    \item Set target texel density (1024--2048 px/m)
    \item Run Auto UV Map operator
    \item Apply tileable texture
\end{enumerate}

\subsection{Parameter Recommendations}

\begin{table}[H]
\centering
\begin{tabular}{|l|l|l|}
\hline
\textbf{Model Type} & \textbf{Projection Mode} & \textbf{Texel Density} \\
\hline
Boxy architecture & 6-Axis (Cube) & 512--1024 \\
Complex hard-surface & 32-Axis (Truncated Icosahedron) & 1024--2048 \\
Organic hard-surface & Angle Based (10--15$^\circ$) & 2048--4096 \\
Game assets & 12-Axis (Dodecahedron) & 1024 \\
\hline
\end{tabular}
\caption{Recommended settings by use case}
\end{table}

\section{Limitations and Future Work}

\subsection{Current Limitations}

\begin{itemize}
    \item Designed for hard-surface models; not suitable for organic meshes
    \item No automatic seam reduction across cluster boundaries
    \item Grid layout may introduce discontinuities for tileable textures
\end{itemize}

\subsection{Future Improvements}

\begin{itemize}
    \item Adaptive axis selection based on model topology
    \item Seam-aware clustering with edge relaxation
    \item Integration with procedural texture systems
    \item GPU acceleration for large meshes
\end{itemize}

\section{References}

\begin{enumerate}
    \item Coxeter, H.S.M. (1973). \textit{Regular Polytopes}. Dover Publications.
    \item Lévy, B., et al. (2002). "Least Squares Conformal Maps for Automatic Texture Atlas Generation." \textit{ACM Transactions on Graphics}.
    \item Sheffer, A., Praun, E., Rose, K. (2006). "Mesh Parameterization Methods and Their Applications." \textit{Foundations and Trends in Computer Graphics and Vision}.
\end{enumerate}

\appendix

\section{Polyhedron Vertex Tables}

\subsection{Dodecahedron Vertices \texorpdfstring{($\varphi = 1.618...$)}{(phi = 1.618...)}}

All permutations and signs of:
\begin{itemize}
    \item $(\varphi, 1, 0)$
    \item $(1, 0, \varphi)$
    \item $(0, \varphi, 1)$
\end{itemize}

Total: 12 vertices

\subsection{Icosahedron Vertices}

All permutations and signs of:
\begin{itemize}
    \item $(0, 1, \varphi)$
    \item $(1, \varphi, 0)$
    \item $(\varphi, 0, 1)$
\end{itemize}

Total: 12 vertices

\subsection{Truncated Icosahedron}

\textbf{Pentagonal faces (12):} Icosahedron vertices (normalized)

\textbf{Hexagonal faces (20):} 
\begin{itemize}
    \item 8 vertices: $(\pm 1, \pm 1, \pm 1)$ (normalized)
    \item 12 vertices: permutations of $(0, \varphi, 1/\varphi)$ (normalized)
\end{itemize}

\section{Source Code Availability}

The complete implementation is available at:
\begin{center}
\url{https://github.com/btitkin/UVfromView.git}
\end{center}

Licensed under MIT License. Copyright \copyright{} 2026 Bartosz Titkin.

\end{document}