Package: ueberzug-bak
NOTE: This is a fork of the originalueberzugproject. I did not write this code.ÜberzugÜberzug is a command line util
which allows to draw images on terminals by using child windows.Advantages to w3mimgdisplay:no race conditions as a new window is created to display imagesexpose events will be processed,so images will be redrawn on switch workspacestmux support (excluding multi pane windows)terminals without the WINDOWID environment variable are supportedchars are used as position - and size unitno memory leak (/ unlimited cache)OverviewDependenciesInstallationCommunicationCommand formatsActionsAddRemoveLibrariesBash(deprecated)PythonPython UrwidExamplesDependenciesLibraries used in the c extension:pythonX11XextXResThere are also other direct dependencies,but they will be installed by pip.Installation$ pip install ueberzug-bakNote: You can improve the performance of image manipulation functions
by usingpillow-simdinstead of pillow.CommunicationThe communication is realised via stdin.A command is a request to execute a specific action with the passed arguments.(Therefore a command has to contain a key value pair "action": action_name)Commands are separated with a line break.Command formatsjson: Command as json objectsimple:Key-value pairs seperated by a tab,pairs are also seperated by a tab:warning: ONLY FOR TESTING!Simple was never intended for the usage in production!It doesn't support paths containing tabs or line breakswhich makes it error prone.bash: dump of an associative array (declare -p variable_name)ActionsAddName: addDescription:Adds an image to the screen.If there's already an image with the same identifierit will be replaced.KeyTypeDescriptionOptionalidentifierStringa freely choosen identifier of the imageNoxIntegerx positionNoyIntegery positionNopathStringpath to the imageNowidthIntegerdesired width; original width will be used if not setYesheightIntegerdesired height; original width will be used if not setYesmax_widthIntegerDeprecated: replaced by scalers (this behavior is implemented by the default scaler contain)image will be resized (while keeping it's aspect ratio) if it's width is bigger than max widthYesmax_heightIntegerDeprecated: replaced by scalers (this behavior is implemented by the default scaler contain)image will be resized (while keeping it's aspect ratio) if it's height is bigger than max heightYesdrawBooleanredraw window after adding the image, default TrueYessynchronously_drawBooleanredraw window immediatelyYesscalerStringname of the image scaler(algorithm which resizes the image to fit into the placement)Yesscaling_position_xFloatthe centered position, if possibleSpecified as factor of the image size,so it should be an element of [0, 1].Yesscaling_position_yFloatanalogous to scaling_position_xYesImageScalers:NameDescriptioncropCrops out an area of the size of the placement size.distortDistorts the image to the placement size.fit_containResizes the image that either the width matches the maximum width or the height matches the maximum height while keeping the image ratio.containResizes the image to a size <= the placement size while keeping the image ratio.forced_coverResizes the image to cover the entire area which should be filledwhile keeping the image ratio.If the image is smaller than the desired sizeit will be stretched to reach the desired size.If the ratio of the area differsfrom the image ratio the edges will be cut off.coverThe same as forced_cover but images won't be stretchedif they are smaller than the area which should be filled.RemoveName: removeDescription:Removes an image from the screen.KeyTypeDescriptionOptionalidentifierStringa previously used identifierNodrawBooleanredraw window after removing the image, default TrueYesLibrariesJust a reminder: This is a GPLv3 licensed project, so if you use any of these libraries you also need to license it with a GPLv3 compatible license.BashThe library is deprecated.Dump associative arrays if you want to use ueberzug with bash.First of all the library doesn't follow the posix standard,so you can't use it in any other shell than bash.Executingueberzug librarywill print the path to the library to stdout.Functions:ImageLayerstarts the ueberzug process and uses bashs associative arrays to transfer commands.Also there will be a function namedImageLayer::{action_name}declared for each action.Each of this function takes the key values pairs of the respective action as arguments.Every argument of these functions has to be an associative key value pair.ImageLayer::{action_name} [{key0}]="{value0}" [{key1}]="{value1}" ...Executing such a function builds the desired command string according to the passed arguments and prints it to stdout.PythonFirst of all everything which isn't mentioned here isn't safe to use andwon't necessarily shipped with new coming versions.The library is included in ueberzug's package.importueberzug.lib.v0asueberzugClasses:Visibility:An enum which contains the visibility states of a placement.VISIBLEINVISIBLEPlacement:A placement to put images on.Every key value pair of the add action is an attribute (except identifier).Changing one of it will lead to building and transmitting an add commandif the placement is visible.The identifier key value pair is implemented as a property and not changeable.Constructor:NameTypeOptionalDescriptioncanvasCanvasNothe canvas where images should be drawn onidentifierStringNoa unique string used to address this placementvisibilityVisibilityYesthe initial visibility state(if it's VISIBLE every attribute without a default value needs to be set)**kwargsdictYeskey value pairs of the add actionProperties:NameTypeSetterDescriptionidentifierStringNothe identifier of this placementcanvasCanvasNothe canvas this placement belongs tovisibilityVisibilityYesthe visibility state of this placement- setting it to VISIBLE leads to the transmission of an add command- setting it to INVISIBLE leads to the transmission of a remove commandWarning:The transmission of a command can lead to an IOError.(A transmission happens on assign a new value to an attribute of a visible Placement.The transmission is delayed till leaving a with-statement if lazy_drawing is used.)ScalerOption:Enum which contains the useable scaler names.Canvas:Should either be used with a with-statement or with a decorated function.(Starts and stops the ueberzug process)Constructor:NameTypedefaultDescriptiondebugboolFalsesuppresses printing stderr if it's falseMethods:NameReturnsDescriptioncreate_placementPlacementprevents the use of the same identifier multiple times,takes the same arguments as the Placement constructor (excluding canvas parameter)__call__FunctionDecorator which returns a function which calls the decorated function with the keyword parameter canvas=this_canvas_object.Of course other arguments are also passed through.request_transmission-Transmits queued commands if automatic_transmission is enabled or force=True is passed as keyword argument.Properties / Attributes:NameTypeSetterDescriptionlazy_drawingcontext manager factoryNoprevents the transmission of commands till the with-statement was leftwith canvas.lazy_drawing: passsynchronous_lazy_drawingcontext manager factoryNoDoes the same as lazy_drawing. Additionally forces the redrawing of the windows to happen immediately.automatic_transmissionboolYesTransmit commands instantly on changing a placement. If it's disabled commands won't be transmitted till a lazy_drawing or synchronous_lazy_drawing with-statement was left or request_transmission(force=True) was called. Default: TrueExamplesCommand formats:Json command format:{"action": "add", "x": 0, "y": 0, "path": "/some/path/some_image.jpg"}Simple command format:action add x   0   y   0   path    /some/path/some_image.jpgBash command format:declare -A command=([path]="/some/path/some_image.jpg" [action]="add" [x]="0" [y]="0" )Bash:# process substitution example:ueberzuglayer--parserbash0<<(declare-Apadd_command=([action]="add"[identifier]="example0"[x]="0"[y]="0"[path]="/some/path/some_image0.jpg")declare-Apadd_command=([action]="add"[identifier]="example1"[x]="10"[y]="0"[path]="/some/path/some_image1.jpg")sleep5declare-Apremove_command=([action]="remove"[identifier]="example0")sleep5)# group commands example:{declare-Apadd_command=([action]="add"[identifier]="example0"[x]="0"[y]="0"[path]="/some/path/some_image0.jpg")declare-Apadd_command=([action]="add"[identifier]="example1"[x]="10"[y]="0"[path]="/some/path/some_image1.jpg")readdeclare-Apremove_command=([action]="remove"[identifier]="example0")read}|ueberzuglayer--parserbashPython library:curses (based onhttps://docs.python.org/3/howto/curses.html#user-input):importcursesimporttimefromcurses.textpadimportTextbox,rectangleimportueberzug.lib.v0asueberzug@ueberzug.Canvas()defmain(stdscr,canvas):demo=canvas.create_placement('demo',x=10,y=0)stdscr.addstr(0,0,"Enter IM message: (hit Ctrl-G to send)")editwin=curses.newwin(5,30,3,1)rectangle(stdscr,2,0,2+5+1,2+30+1)stdscr.refresh()box=Textbox(editwin)# Let the user edit until Ctrl-G is struck.box.edit()# Get resulting contentsmessage=box.gather()demo.path=''.join(message.split())demo.visibility=ueberzug.Visibility.VISIBLEtime.sleep(2)if__name__=='__main__':curses.wrapper(main)general example:importueberzug.lib.v0asueberzugimporttimeif__name__=='__main__':withueberzug.Canvas()asc:paths=['/some/path/some_image.png','/some/path/another_image.png']demo=c.create_placement('demo',x=0,y=0,scaler=ueberzug.ScalerOption.COVER.value)demo.path=paths[0]demo.visibility=ueberzug.Visibility.VISIBLEforiinrange(30):withc.lazy_drawing:demo.x=i*3demo.y=i*3demo.path=paths[i%2]time.sleep(1/30)time.sleep(2)Scripts:fzf with image preview:https://github.com/seebye/ueberzug/blob/master/examples/fzfimg.shMastodon viewer:https://github.com/seebye/ueberzug/blob/master/examples/mastodon.shFzfMpdUserInterface:https://github.com/seebye/fmui