Skip to content

v.transform

Performs an affine transformation (shift, scale and rotate) on vector map.

v.transform [-twxyab] input=name [layer=string] output=name [xshift=float] [yshift=float] [zshift=float] [xscale=float] [yscale=float] [zscale=float] [zrotation=float] [columns=name [,name,...]] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

v.transform input=name output=name

grass.script.run_command("v.transform", input, layer="-1", output, xshift=0.0, yshift=0.0, zshift=0.0, xscale=1.0, yscale=1.0, zscale=1.0, zrotation=0.0, columns=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("v.transform", input="name", output="name")

Parameters

input=name [required]
    Name of input vector map
    Or data source for direct OGR access
layer=string
    Layer number or name ('-1' for all layers)
    A single vector map can be connected to multiple database tables. This number determines which table to use. When used with direct OGR access this is the layer name.
    Default: -1
output=name [required]
    Name for output vector map
xshift=float
    Shifting value for x coordinates
    Default: 0.0
yshift=float
    Shifting value for y coordinates
    Default: 0.0
zshift=float
    Shifting value for z coordinates
    Default: 0.0
xscale=float
    Scaling factor for x coordinates
    Default: 1.0
yscale=float
    Scaling factor for y coordinates
    Default: 1.0
zscale=float
    Scaling factor for z coordinates
    Default: 1.0
zrotation=float
    Rotation around z axis in degrees (counter-clockwise)
    Default: 0.0
columns=name [,name,...]
    Name of attribute column(s) used as transformation parameters
    Format: parameter:column, e.g. xshift:xs,yshift:ys,zrot:zr
-t
    Shift all z values to bottom=0
-w
    Swap coordinates x, y and then apply other parameters
-x
    Swap coordinates x, z and then apply other parameters
-y
    Swap coordinates y, z and then apply other parameters
-a
    Swap coordinates after the other transformations
-b
    Do not build topology
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str, required
    Name of input vector map
    Or data source for direct OGR access
    Used as: input, vector, name
layer : str, optional
    Layer number or name ('-1' for all layers)
    A single vector map can be connected to multiple database tables. This number determines which table to use. When used with direct OGR access this is the layer name.
    Used as: input, layer
    Default: -1
output : str, required
    Name for output vector map
    Used as: output, vector, name
xshift : float, optional
    Shifting value for x coordinates
    Default: 0.0
yshift : float, optional
    Shifting value for y coordinates
    Default: 0.0
zshift : float, optional
    Shifting value for z coordinates
    Default: 0.0
xscale : float, optional
    Scaling factor for x coordinates
    Default: 1.0
yscale : float, optional
    Scaling factor for y coordinates
    Default: 1.0
zscale : float, optional
    Scaling factor for z coordinates
    Default: 1.0
zrotation : float, optional
    Rotation around z axis in degrees (counter-clockwise)
    Default: 0.0
columns : str | list[str], optional
    Name of attribute column(s) used as transformation parameters
    Format: parameter:column, e.g. xshift:xs,yshift:ys,zrot:zr
    Used as: input, dbcolumn, name
flags : str, optional
    Allowed values: t, w, x, y, a, b
    t
        Shift all z values to bottom=0
    w
        Swap coordinates x, y and then apply other parameters
    x
        Swap coordinates x, z and then apply other parameters
    y
        Swap coordinates y, z and then apply other parameters
    a
        Swap coordinates after the other transformations
    b
        Do not build topology
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

v.transform performs an affine transformation (translate and rotate) of a vector map. An affine transform includes one or several linear transformations (scaling, rotation) and translation (shifting). Several linear transformations can be combined in a single operation. The command can be used to georeference unreferenced vector maps or to modify existing geocoded maps.

NOTES

Coordinate transformation based on Ground Control Points (GCPs) is done by v.rectify and not supported by v.transform.

Transformation parameters (i.e. xshift, yshift, etc.) can be fetched from attribute table connected to the vector map. In this case vector objects can be transformed with different parameters based on their category number. If the parameter cannot be fetched from the table, default value is used instead.

Note that the transformation matrix can be printed by m.transform.

EXAMPLE

DXF/DWG drawings

Most DXF/DWG drawings are done within XY coordinate space. To transform them to a national grid, we can use v.transform together with v.rectify and a first-order transformation.

v.transform -t in=watertowerXY out=watertower_z zscale=0.04 zshift=1320
v.rectify in=watertower_z out=watertowerUTM points=wt.points order=1

Extrude 2D vector points to 3D based on attribute column values

Spearfish example with manual table editing for vertical shift:

# work on own map copy:
g.copy vect=archsites@PERMANENT,myarchsites
# add new 'zs' column to later store height of each site:
v.db.addcolumn myarchsites col="zs double precision"
v.db.update myarchsites layer=1 column=zs value="cat * 1000"

# perform z transformation:
v.transform -t input=archsites output=myarchsites3d column="zshift:zs" table="archsites_t"
# drop table containing transformation parameters:
echo "drop table archsites_t" | db.execute

The resulting map is a 3D vector map.

Extrude 2D vector points to 3D with automated elevation extraction

Spearfish example with automated elevation extraction for vertical shift:

# work on own map copy:
g.copy vect=archsites@PERMANENT,myarchsites
# add new 'zs' column to later store height of each site:
v.db.addcolumn myarchsites col="zs double precision"

# set region to elevation map and fetch individual heights:
g.region raster=elevation.10m -p
v.what.rast myarchsites rast=elevation.10m col=zs
# verify:
v.db.select myarchsites

# perform transformation to 3D
v.transform -t myarchsites output=myarchsites3d column="zshift:zs" layer=1
# drop table containing transformation parameters
v.db.dropcolumn myarchsites3d col=zs

The resulting map is a 3D vector map.

SEE ALSO

m.transform, i.rectify, v.rectify, r.region

AUTHORS

Radim Blazek, ITC-irst, Trento, Italy,
Column support added by Martin Landa, FBK-irst (formerly ITC-irst), Trento, Italy (2007/09)

SOURCE CODE

Available at: v.transform source code (history)
Latest change: Saturday Feb 15 00:20:39 2025 in commit ea58114