Skip to content

Latest commit

 

History

History
169 lines (153 loc) · 7.92 KB

README.md

File metadata and controls

169 lines (153 loc) · 7.92 KB
Raw

qubesimgconvertertt & qvm-get-image-tt notes

Library and Utility for custom effects of Qubes OS VM icons. Provided effects are overlay, thin-border, thick-border, marker as well as the standard tint which use the label color for their effects. Special filters of untouched, invert, mirror, flip are also available. Screenshots of Tweak Tools effects are at the bottom of this page. Real-life use cases are documented and explained in qubesappmenustt and window-icon-updater-tt sub-directories.

Internals & Features

The qubesimgconvertertt library is derived from the original qubesimgconverter library and Image class. Effects are written as individual methods.

The qvm-get-image-tt is a utility which could be used as a drop-in replacement for qvm-get-tinted-image. It is based on qubes-app-linux-img-converter utilities with additional --filter & --mirror options which allows user to select the desired filter. An extra --ANSI function is provided to quickly check the results directly within the terminal. A special --alphacomposite option is available which allows composition of one image on another. By default, qvm-get-image-tt checks for an special ttfilter VM feature and uses it to determine the current Tweak Tool filter effect per VM. If the ttfilter key is not present or is invalid, the default tint effect will be applied. To change the Tweak Tool filter effect of any VM:

qvm-features VMNAME ttfilter <tint|overlay|thin-border|thick-border|untouched|invert|mirror|flip|marker>

Installation & Removal

To install the library & tool at your ~/.local/lib & ~/bin directories, run this command in the current directory:

make install

The policy file to allow VM1 to read images from VM2. Both VMs could be disposable and do not need network connection. It is better to use an XFCE or GNOME based template to have some Images in VM2 and an image viewer application in VM2

admin.vm.List		*	VM1 VM1	 allow target=dom0
admin.vm.List		*	VM1 VM2	 allow target=dom0
admin.vm.List		*	VM1 @adminvm	 allow target=dom0
qubes.GetImageRGBA	*	VM1 VM2	 allow target=VM2

To remove them from your system, run this command in the current directory:

make remove

Limitations, Issues & ToDo

These are the current known limitation with the tool & library:

  • Performance of the effects could be evaluated via the provided benchmark.py:
vendor_id	 :  GenuineIntel
model name	 :  Intel(R) Core(TM) i5-4300U CPU @ 1.90GHz
cpu MHz		 :  2494.222
cpu cores	 :  2
Performing benchmarks on a 32x32 image for 10000 times...
Untouched Image (no effect):  0.001457245998608414
The original tint effect:     1.1380185189991607
Alpha Compositor:             2.7502541360008763
Overlay Effect:               0.9338325909993728
Border Effects:               3.3812881099947845
Invert Effect:                0.3477331649992266
Mirror Effect:                0.33721530900220387
Rotate Effect:                0.2404281990020536
Marker Effect:                7.658134213001176
Diagonal Effect:              6.850988145000883
Image resize (scale):         40.1643057639958
Image canvas resize (pad):    0.5904967830065289
  • Performance of the border effects is nearly 3 times slower than tint. This is because of the Anti-Aliased Alpha Compositor implementation. Considering the superior quality, it is well worth it as 1 pixel borders are barely distinguishable. Individual implementation of thick-border with integer based calculation would improve its speed. It is already darn fast on my 10 year old i5-4300U test machine.
  • Original unit tests are performed on a 2x2 image. Mostly done from security perspective. Not suitable for most of the Tweak Tool effects. Individual unit tests are developed to represent effects via ANSI output.
  • Currently tested only on Qubes OS 4.2.1
  • Theoretically it should be possible to install the library and utility within any Qube if the dependency (python3-qubesimgconverter) is installed in its template. And if the necessary policies to allow it to retrieve Image from destination VM(s) is granted. This is yet to be tested and documented.
  • It should be noted that the current systray effects are not implemented via the qubesimgconverter library but are rather written in C language and a part of qubes-gui-daemon repository. Further study of its mechanism is needed. Github Issue #2846 provides better context.

Credits

Screenshots & Demo

The untouched 32x32 pixel Icon of Ristretto. ANSI color representation of output is printed to the terminal via --ANSI option.

qvm-get-image-tt personal 0x0000FF /usr/share/icons/hicolor/32x32/apps/org.xfce.ristretto.png --ANSI pattern --filter untouched

The default Tint effect. Original work by Wojciech Porczyk et. al.

qvm-get-image-tt personal 0x0000FF /usr/share/icons/hicolor/32x32/apps/org.xfce.ristretto.png --ANSI pattern --filter tint

Overlaying image on the provided color using images Alpha channel.

qvm-get-image-tt personal 0x0000FF /usr/share/icons/hicolor/32x32/apps/org.xfce.ristretto.png --ANSI pattern --filter overlay

Thin and Thick borders. Bordering supports percentage of image instead of fixed pixel count. This allows consistent results on HiDPI displays. The anti-aliased 1.536 pixel width thin-border for 32x32 icons is much more distinguishable and comfortable than the fixed 1 pixel width.

qvm-get-image-tt personal 0x0000FF /usr/share/icons/hicolor/32x32/apps/org.xfce.ristretto.png --ANSI pattern --filter thin-border


qvm-get-image-tt personal 0x0000FF /usr/share/icons/hicolor/32x32/apps/org.xfce.ristretto.png --ANSI pattern --filter thick-border

I primarily use the marker effect for TemplateVMs. It makes the xfce-terminal icons belonging to templates easily identifiable.

qvm-get-image-tt personal 0x0000FF /usr/share/icons/hicolor/32x32/apps/org.xfce.ristretto.png --ANSI pattern --filter marker

Special invert effect is very useful for untrusted VM. As it implies a paranoid effect.

qvm-get-image-tt personal 0x0000FF /usr/share/icons/hicolor/32x32/apps/org.xfce.ristretto.png --ANSI pattern --filter invert

Mirrored or flipped icons are not that much usable as in practice, our brains do not register them well as distinguishable effects.

qvm-get-image-tt personal 0x0000FF /usr/share/icons/hicolor/32x32/apps/org.xfce.ristretto.png --ANSI pattern --filter untouched --mirror horizontal

Alpha Compositing 16x16 pixel Firefox icon on Chrome icon. This effect could be useful for compositing qube icon on application icons. It is necessary to consult professional UI/UX experts for better feedback.

qvm-get-image-tt personal 0x0000FF /usr/share/icons/hicolor/16x16/apps/firefox.png --ANSI pattern --filter untouched --alphacomposite /usr/share/icons/hicolor/32x32/apps/google-chrome.png

Mixed effects are feasible. Here is a mirrored Wilber (GIMP’s macot), tinted with Magenta, finally composited on Qubes OS icon.

qvm-get-image-tt personal 0xFF00FF /usr/share/icons/hicolor/16x16/apps/gimp.png --mirror horizontal --filter tint --alphacomposite /usr/share/icons/hicolor/32x32/apps/qubes-logo-icon.png --ANSI pattern