Template:Cubemap viewer/doc

This is a documentation subpage for Template:Cubemap viewer.
It may contain usage information, categories and other content that is not part of the original template page.

Usage

This template uses Template:Calculator.

This template uses TemplateStyles:

Template:Cubemap viewer/styles.css

Creates a 360-degree image viewer out of a cubemap image file.

This is similar to Template:PanoViewer except it's on-wiki and uses cubemap instead of equirectangular projection.

Syntax

If you have a single cubemap file containing all the faces (e.g. file:Eesti Lennundusmuuseum. Hävitaja F-4C Phantom II kabiin (cubemap).jpg ) use the montage parameter. If you have spearate files that all follow the correct naming convention (See below), then use the faces= parameter.

[ ]

Cockpit of a McDonnell Douglas F-4 Phantom II.

Simple example [Shown at the right]:

{{Cubemap viewer
|montage=Eesti Lennundusmuuseum. Hävitaja F-4C Phantom II kabiin (cubemap).jpg
|panoviewer=Eesti Lennundusmuuseum. Hävitaja F-4C Phantom II kabiin.jpg
|viewbox height=350
|viewbox width=400
|pitch=-5
|yaw=90
|hfov=94
|caption=Cockpit of a McDonnell Douglas F-4 Phantom II.
}}

Common options (See template data for all options)

{{Cubemap viewer
|faces=Franklin Park photosphere, May 2019
|hfov=45 <!-- Horizontal field of view in degrees -->
|pitch=25 <!-- pitch (up/down) in degrees -->
|yaw=114 <!-- yaw (left/right) in degrees -->
|textcontrols=1 <!-- show text controls -->
|zoomcontrols=1 <!-- show zoom controls -->
|arrowcontrols=1 <!-- Show arrow controls -->
|caption=Your caption here
|align=left
|viewbox width=200
|viewbox height=200
|resolution=600 <!-- Resolution to use for rendering images. -->
|pannoviewer= <!-- Image in equirectangular format to make a link to pannoviewer -->
}}

If you need to use it without the image frame wrapper, you can use {{Cubemap viewer/core}}.

Examples

Using multiple files all following the correct naming convention prefixed with Franklin Park photosphere, May 2019

[ ]

Franklin Park, May 2019

File:Olympic Village Cafeteria CubeMap 360.png

Pitch: 25°

Yaw: 114°

Field of view: 80°

File:Skybox example.png

Pitch: -10°

Yaw: -10°

Field of view: 80°

An additional caption here. Note that the different control types are options

File:Panorama cube map.png You can specify viewbox width and viewbox height

Pitch: 8°

Yaw: 40°

Field of view: 80°

File:Basílica de San Patricio 360 panoramic view.jpg Example adjusting viewpoint

In this example we adjust the viewpoint to make the floor design be central. We also set overlap=0 to ensure all the strong lines line up

{{Cubemap viewer
|faces=Basílica de San Patricio 360 panoramic view
|caption=[[St. Patrick's Basilica, Montreal]].
|yaw=185
|pitch=-3
|hfov=70
|viewbox height=420
|viewbox width=300
|horizontal adjust=-11
|arrowcontrols=
|overlap=0
|background=#9b764a
|align=none
}}

[ ]

St. Patrick's Basilica, Montreal.

File:Women's Cross Country 5KM Relay CubeMap 360.png

This one has no controls but you can still navigate via click

File:Earth cube map.png [Inside out]

Pitch: -10°

Yaw: -10°

Field of view: 80°

Template data

Render a 360 panorama in cubemap format as a 3D view

Template parameters
This template prefers block formatting of parameters.
Parameter		Description	Type	Status
faces	`faces`	Prefix to use for image files. Do not include namespace or extension. Will append (front).jpg, (back).jpg and so on to get the various faces of the cubemap. Will also assume that adding just .jpg gets the file in equirectangular format (if the file exists). Example Franklin Park photosphere, May 2019	Unknown	required
montage	`montage` `img`	Cubemap image, no file namespace. Use this if you have an entire cubemap in a single file. If using individual file, use the faces parameter instead. Example Skybox example.png	File	optional
face up	`face up`	Image file to use as the top/up (+Y) face. Overrides faces & montage parameter	File	optional
face back	`face back`	Image file to use as the back (-X) face. Overrides faces & montage parameter	File	optional
face down	`face down`	Image file to use as the down (-Y) face. Overrides faces & montage parameter	Unknown	optional
face left	`face left`	Image file to use as the left (+Z) face. Overrides faces & montage parameter	File	optional
face front	`face front`	Image file to use as the front (+X) face. Overrides faces & montage parameter	File	optional
face right	`face right`	Image file to use as the right (-Z) face. Overrides faces & montage parameter	File	optional
caption	`caption`	Caption to include under image	Content	suggested
align	`align`	Where to put the image in the page Suggested values `left` `right` `center` `none` Default right	String	suggested
yaw	`yaw`	Initial value for yaw (left<->right) in degrees. Default -10 Example 45	Number	suggested
pitch	`pitch`	Initial value for pitch (Up/down direction) in degrees. Note: If using non-default value, be sure to test in chrome on mobile frontend. Default -10	Number	suggested
horizontal field of view	`hfov`	Horizontal field of view (in degrees). This controls how zoomed in the image is. Note: be sure to test in chrome on mobile before using a custom value. Default 80 Example 100	Number	suggested
arrowcontrols	`arrowcontrols`	Include left, right, up, down arrow controls Default true	Boolean	optional
zoomcontrols	`zoomcontrols`	Add +/- to control zoom level Default true	Boolean	optional
playcontrols	`playcontrols`	Show a play button that triggers one full revolution of the yaw coordinate Default true	Boolean	optional
textcontrols	`textcontrols`	Include text box controls in the caption Example true	Boolean	optional
panoviewer	`panoviewer`	Equirectangular version of the parnorama in order to make a link to PanoViewer on toolforge. If not specified will use faces parameter Example Nebel Schienen Panorama.jpg	File	optional
viewbox width	`viewbox width`	Width of image box to show Default 300 Example 300	Number	suggested
viewbox height	`viewbox height`	Height of image box to show Default 225	Number	suggested
minimum horizontal field of view	`minhfov`	The max amount you can zoom in Default 1 Example 10	Number	optional
maximum horizontal field of view	`maxhfov`	The most you can zoom in. If too high the image becomes very distorted. Default 150 Example 110	Number	optional
resolution	`resolution`	Resolution of image to render the faces. Must not be more than 4 times the max width of the source image when using montage. Generally twice the value of viewbox width is a good value. Default 600	Number	suggested
background	`background`	Background colour which might show through when images are initially loading or if there are small seams between the images Default #7D7F7C Example white	String	optional
overlap	`overlap`	How much to overlap the images. Generally 2 is a good value. If you see seams between the images try increasing. If the faces don't line up try decreasing. Default 2 Example 0	Number	optional
viewbox style	`viewbox style`	Additional CSS to add just to the view box. In some cases adding filter: blur(0.5px) may be easier on the eyes if the picture has lots of high frequency data.	String	optional
horizontal adjust	`horizontal adjust`	Adjust user perspective this many pixels to the left Default 0 Example -10	Number	optional
vertical adjust	`vertical adjust`	Adjust vertical perspective by this many pixels Default 0 Example -10	Number	optional
rotate	`rotate`	Rotate the viewpoint by this many degrees Example 1.1	Number	optional

Converting images to cubic form

If you have a panorama file in equirectangular projection, you can convert it cubemap format using https://jaxry.github.io/panorama-to-cubemap/ (Very large files may crash the browser). It is recommended to use lanczos for the interopolation, jpeg as the output format, and set the cube rotation so the most interesting part of the image is in the third column of the middle row. An alternative converter is https://gitlab.wikimedia.org/repos/commtech/pano-projector which works better for large files.

If using pano-projector, the following script might be helpful:

Shell script for using pano-projector to extract faces

pano-projector face --face left --mem-limit 3000 --quality  93 --copy-icc "$1" "${1%.jpg}_(left).jpg"
pano-projector face --face right --mem-limit 3000 --quality  93 --copy-icc "$1" "${1%.jpg}_(right).jpg"
pano-projector face --face back --mem-limit 3000 --quality  93 --copy-icc "$1" "${1%.jpg}_(back).jpg"
pano-projector face --face front --mem-limit 3000 --quality  93 --copy-icc "$1" "${1%.jpg}_(front).jpg"
pano-projector face --face top --mem-limit 3000 --quality  93 --copy-icc "$1" "tmp_up.jpg"
jpegtran -perfect -rotate 270 tmp_up.jpg > "${1%.jpg}_(up).jpg"
pano-projector face --face bottom --mem-limit 3000 --quality  93 --copy-icc "$1" "tmp_down.jpg"
jpegtran -perfect -rotate 90 tmp_down.jpg > "${1%.jpg}_(down).jpg"

exiftool -tagsFromFile "$1" -XMP-GPano:ALL= "${1%.jpg}_(left).jpg" "${1%.jpg}_(right).jpg" "${1%.jpg}_(back).jpg" "${1%.jpg}_(front).jpg" "${1%.jpg}_(up).jpg" "${1%.jpg}_(down).jpg"

When uploading files, it is recommended to follow the naming convention based on File:Skybox_example.png. Namely: Use File:Filename.jpg for the original equirectangular version, FILE:Filename (up).jpg for the 2nd column of the first row (The "py" or "+Y" face), FILE:Filename (back).jpg for the 1st column 2nd row (The "nx" or "-X" face), File:Filename (left).jpg for the 2nd column first row ("pz" or "+Z" face), File:Filename (front).jpg for the 3rd column 2nd row ("px" or "+X" face), File:Filename (right).jpg for the 4th column 2nd row ("nz" or "-Z" face), and File:Filename (down).jpg for the 2nd column 3rd row (ny or "-Y" face). If you follow this naming convention, the template will find all the files if you use the parameter |faces=Filename

Its probably best to upload them as separate files, as that allows the different views to be reused as normal photos. Alternatively they can create a montage of all the faces to project the entire panorama into a cubemap format (e.g. Like File:Eesti Lennundusmuuseum. Hävitaja F-4C Phantom II kabiin (cubemap).jpg ). If you want to do that with ImageMagick's montage program. First create a pure white file of the size of one of the faces: convert -size 4249x4249 xc:white white.jpg then run the command: montage white.jpg py.jpg white.jpg white.jpg nx.jpg pz.jpg px.jpg nz.jpg white.jpg ny.jpg white.jpg white.jpg -mode Concatenate -tile 4x3 -quality 91 out.jpg

Usage

Syntax

Examples

Template data

Converting images to cubic form

See also