Package: vpype-perspective
vpype-perspectivevpype-perspectiveis avpypeplug-in to bring your 2D artwork in 3D space and render it in perspective. This project both aims to be a usable tool enabling new creative possibilities, and educational material demonstrating advanced uses ofvpypeand 3D computer graphics math basics.InstallationNote:vpype-perspectiverequiresvpype1.10 or later.If you haven't already, installvpypeby following theinstallation instructions.You can ensure thatvpypeis up-to-date with the following command:$pipxupgradevpypeThen, addvpype-perspectiveto yourvpypeinstallation:$pipxinjectvpypegit+https://github.com/abey79/vpype-perspectiveCheck that your install is successful:$vpype--version
$vpypeperspective--help[...]DocumentationNote: the figures below have been created usingvpype-perspective. The.vpyand corresponding.svgfiles are located in theexamples/figuresdirectory of the present repo.Basic 3D layoutAs starting point, theperspectivecommand builds a 3D stack of layer. Each layer is a planar "quad" (flat, rectangular 3D surface) whose dimensions match the current page size (or, if it is undefined, the computed bounds of the geometries). The quads are aligned to the X and Y axes, and stacked along the Z axis. The Z position of each layer quad is determined by the corresponding layer ID, such that layer 1 lies atz = 0and consecutive layer IDs are spaced bydelta_z(which defaults to 1cm). The z position of layer N is thusz = (layer_ID - 1) * delta_z. Thedelta_zvalue can be overridden by using thepspread DELTAZcommand before any othervpype-perspectivecommand.Theperspectivecommand uses a world coordinate system where the X axis points right (when facing a layer quad), the Y axis points up, and the Z axis is perpendicular to the layer quads and points in the direction of the layers with higher IDs. The origin of the world coordinate system thus lies in the middle of layer 1's quad. This is represented in red in the figures above.Note that the X and Y axes of the world coordinate system do not matchvpype's native coordinate system. In the world coordinate system, (0, 0) is in the middle of the layer and the Y axis pointed upward, while invpype's coordinate system, (0, 0) is on the top-left corner of the layer and the Y axis is pointing downward.By default, the camera faces the front-most layer quad (highest layer ID/z value) and its aiming point is in the middle of the rectangular cuboid defined by the front-most layer and layer 1 (the default aiming point world coordinates are thus(0, 0, (N-1) * delta_z / 2))if N is the layer ID of the front-most layer). An alternative camera aiming point can be set using the--aiming-point PX PY PZoption.The camera focal distance is chosen based on the desired horizontal field-of-view (which can be set using--fov). It is choose such that, will all default settings, the front-most layer is unchanged by theperspectivecommand, and the other layers are increasingly scaled down the further they are. This can be demonstrated by the following command:$ vpype \
    pagesize 10x10cm \
    repeat 5 \
        rect -l %_i+1% 0 0 10cm 10cm \
        text -l %_i+1% -p 0.1cm 0.2cm -s 12 "layer %_i+1%" \
    end \
    perspective --hfov 60 \
    showUsing larger field-of-view yields stronger perspective distortion effects.Camera controlThe position and orientation of the camera can easily be altered using the--aiming-point,--pan,--tilt, and--moveoptions of theperspectivecommand.The--panoption orbits the camera right (for positive angles) or left (for negative angles) around the origin, while keeping pointed at it.Likewise, the--tiltoption orbits the camera up (for positive angles) and down (for negative angles) around the origin, again keeping pointed at it.Finally, the--moveoption translate the camera in the provided X, Y, and Z direction.The camera translation is applied in the camera coordinate system,afterthe pan and tilt angles are applied (in this order). The order in which the options are passed to theperspectivecommanddoes notaffect the order in which they are applied. The following figure illustrate this order:Note how, in the right-most example, the camera moved "over" the geometries. The camera was moved by 5cm in the Y ("up") direction *in the camera coordinate system". Since the camera pointing slightly downward due to the--tiltoption, moving "up" in the camera coordinate system implies some forward horizontal displacement in the world coordinate system.Modifying layersEach layer can be individually manipulated in the 3D space using thepspread,protate,pscale, andptranslatecommands. These commands operate by setting or modifying customproperties. Theperspectivecommand then recognises these properties and apply the corresponding transforms to the geometry during the rendering process. Theproplistcommand can be used to make this apparent:$ vpype rect 0 0 10cm 15cm protate y 25 proplist --layer 1
listing 1 properties for layer 1
  prsp_transform: (ndarray) [[ 0.90630779  0.          0.42261826  0.        ]
 [ 0.          1.          0.          0.        ]
 [-0.42261826  0.          0.90630779  0.        ]
 [ 0.          0.          0.          1.        ]]Thepspreadcommand overrides the defaultdelta_zvalue and thus influences the positions of all layers but layer 1.Important:pspreadmustbe usedbeforeany othervpype-perspectivecommand because they rely on the layer's position in space.Theprotatecommand rotates the layer quad around the X, Y, or Z axis (in world coordinate). By default (--origin layer), the rotation is applied around the layer quad's center. Using--origin world, the rotation is applied around the world origin instead.Theptranslatecommand translates the layer quad along the X, Y, and Z axis (in world coordinates). By default, the coordinates are considered offsets to be applied on the quad's current position. When using the--absoluteoption, the coordinates are instead considered as absolute values and the layer quad is translated such as its center lies on them.On the right side of the figure above, all three translated layer quads are superposed, with their center lying on the [3cm, 0, 0] world coordinates.Thepscalecommand scales the layer quad by a factors along the X, Y, and & axis (in world coordinates). By default (--origin layer), the scaling is applied around the layer quad's center. Using--origin world, the scaling is applied around the world coordinate origin instead.The commands may be chained to achieve complex transform of the layer quad.Finally, thepresetcommand resets the transform currently applied.Development setupHere is how to clone the project for development:$gitclonehttps://github.com/abey79/vpype-perspective.git
$cdvpype-perspectiveCreate a virtual environment:$python3-mvenvvenv
$sourcevenv/bin/activate
$pipinstall--upgradepipInstallvpype-perspectiveand its dependencies (includingvpype):$pipinstall-e.
$pipinstall-rdev-dependencies.txtLicenseSee theLICENSEfile for details.