Reference:UV Mapping

All textures in POV-Ray are defined in 3 dimensions. Even planar image mapping is done this way. However, it is sometimes more desirable to have the texture defined for the surface of the object. This is especially true for bicubic_patch objects and mesh objects, that can be stretched and compressed. When the object is stretched or compressed, it would be nice for the texture to be glued to the object's surface and follow the object's deformations.

When uv_mapping is used, then that object's texture will be mapped to it using surface coordinates (u and v) instead of spatial coordinates (x, y, and z). This is done by taking a slice of the object's regular 3D texture from the XY plane (Z=0) and wrapping it around the surface of the object, following the object's surface coordinates.

Note: Some textures should be rotated to fit the slice in the XY plane.

Syntax:

texture {
  uv_mapping pigment{PIGMENT_BODY} | pigment{uv_mapping PIGMENT_BODY}
  uv_mapping normal {NORMAL_BODY } | normal {uv_mapping NORMAL_BODY }
  uv_mapping texture{TEXTURE_BODY} | texture{uv_mapping TEXTURE_BODY)
  }

Supported Objects

New for version 3.8 the cone, cylinder and lemon were added to the growing list of objects that support UV mapping:

Note: A Change in version 3.8 improves ovus mapping as noted below. Backward compatibility can be obtained by simply using a spherical warp instead.

• bicubic_patch: UV coordinates are based on the patch's parametric coordinates. They stretch with the control points. The default range is (0..1) and can be changed.
• box: the image is wrapped around the box, as shown below.
• cone, cylinder: mapping is the same as the lemon object listed below, however, keep in mind that a true cone is not a cylinder.
• lathe, sor: modified spherical mapping... the u coordinate (0..1) wraps around the y axis, while the v coordinate is linked to the object's control points (also ranging 0..1). Surface of Revolution also has special disc mapping on the end caps if the object is not open.
• lemon: wrapped around the object axis (u coordinate) from the base point to the cap point in these (v coordinate) proportions: [0 to 0.25] base (center to radius) [0.25 to 0.75] spindle and [0.75 to 1.0] cap (radius to center).
• mesh, mesh2: UV coordinates are defined for each vertex and interpolated between.
• ovus: uses a slightly bulging conical mapping scheme that has rounded end caps with the same proportions as the aforementioned lemon.
• parametric: in this case the map is not taken from a fixed set of coordinates but the map is taken from the area defined by the boundaries of the uv-space, in which the parametric surface has to be calculated.
• sphere: traditional spherical mapping.
• torus: the map is taken from the area <0,0><1,1> where the u-coordinate is wrapped around the major radius and the the v-coordinate is wrapped around the minor radius.

Note: Recent additions revealed torus mapping to be reversed with respect to the u-coordinate. For backward compatibility reasons it remains the same in this release, however this may change in the future.

UV Boxmap

Additional UV Examples

UV Vectors

With the keyword uv_vectors, the UV coordinates of the corners can be controlled for bicubic patches and standard triangle mesh.

For bicubic patches the UV coordinates can be specified for each of the four corners of the patch. This goes right before the control points.
The syntax is:

  uv_vectors <corner1>,<corner2>,<corner3>, <corner4>
with default
  uv_vectors <0,0>,<1,0>,<1,1>,<0,1>

For standard triangle meshes (not mesh2) you can specify the UV coordinates for each of the three vertices uv_vectors <uv1>,<uv2>,<uv3> inside each mesh triangle. This goes right after the coordinates (or coordinates & normals with smooth triangles) and right before the texture.
Example:

mesh {
  triangle {
    <0,0,0>, <0.5,0,0>, <0.5,0.5,0>
    uv_vectors <0,0>, <1,0>, <1,1>
    }
  triangle {
    <0,0,0>, <0.5,0.5,0>, <0,0.5,0>
    uv_vectors <0,0>, <1,1>, <0,1>
    }
  texture {
    uv_mapping
    pigment {
      image_map {
      sys "SomeImage"
      map_type 0
      interpolate 0
      }
    }
  }
}