jkearney126 / kubi Goto Github PK

kubi is a fast and flexible cubemap generator based on libvips

pip install git+https://github.com/indus/kubi.git

• numpy
• pyvips (bindings for libvips)

kubi can convert equirectangular images into a variety of common layouts. All image formats supported by vips (JPEG, PNG, TIFF, WEBP, HEIF, ...) can be used for input and output. With the DZ format of libvips it is even possible to create tiled images of the cubefaces.
When used with a glob pattern for multiple input files, kubi generates an index file once and reuses it while processing all matched images. This can lead to a significant speedup.

• all options

kubi -h

• basic usage

kubi [-s <size>] [-l {row,column,crossL,crossR,crossH}] srcfile [dstfile]

none	row	column

crossL	crossR	crossH

• tiled cubemaps

kubi -s 2048 -co tile_size=512 -co depth=onetile -co overlap=0 -co layout=google -co suffix=.jpg[Q=75] -n l r u d f b srcfile dstfile.dz

With some fiddling the file and folder structure could be made compatiple to 360° image viewers.
The above would work with Marzipano:

Marzipano.ImageUrlSource.fromString("<some_path>/dstfile_{f}/{z}/{y}/{x}.jpg");

system: CPU: i7-6700 CPU @ 3.40GHz, 4 cores; MEM: 64GB; OS: Win 10

input: equirectangular image with 4096x2048px
output: cubemap with a cross layout

input: equirectangular image with 4096x2048px
output: cubemap as seperate tiles

If only a few cubemaps are needed, performance is probably of minor concern. But with kubi it should also be possible to process thousands of animation frames in a reasonable time:

input: multiple equirectangular images with 4096x2048px
output: multiple cubemaps with a cross layout and a face size of 2048px

In addition to regular cubemaps, two optimized mappings can be generated:

• Equi-Angular Cubemap (EAC)
  C.Brown (2017): Bringing pixels front and center in VR video
• Optimized Tangens Cubemap (OTC)
  M.Zucker & Y.Higashi (2018): Cube-to-sphere Projections for Procedural Texturing and Beyond (Ch. 3.2 & Ch. 5)

Both transforms are univariate and therefore very easy to implement. They both significantly reduce the distortion of the cubemap and thus optimize the pixel yield. However, support in other tools and libraries is rather scarce.

error	ltr: regular cubemap, EAC, OTC
area
distance

To ensure the correct representation of a transformed cubemap, the reverse transformation must be performed at some point. The following example shows this for the OTC transformation in a fragment shader.

//FRAGMENT SHADER for OTC

vec3 n = vNormal.xyz; // or vPosition

n /= max(max(abs(n.x),abs(n.y)),abs(n.z));
n = atan(n * tan(0.8687));

gl_FragColor = textureCube(otcSampler, n);