{"id":19388371,"url":"https://github.com/mk-fg/infinite-image-scroller","last_synced_at":"2025-04-23T23:31:38.033Z","repository":{"id":40002821,"uuid":"73020306","full_name":"mk-fg/infinite-image-scroller","owner":"mk-fg","description":"Python/GTK desktop app to scroll images across the window carousel-style","archived":false,"fork":false,"pushed_at":"2025-03-25T14:31:02.000Z","size":116,"stargazers_count":16,"open_issues_count":0,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-02T22:23:21.269Z","etag":null,"topics":["carousel","desktop","gtk","image-processing","image-viewer","kiosk","python","scroll"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mk-fg.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-06T21:31:16.000Z","updated_at":"2025-03-29T18:44:11.000Z","dependencies_parsed_at":"2024-11-10T10:12:37.185Z","dependency_job_id":"e2967598-88ac-45bf-ba28-8907768568c7","html_url":"https://github.com/mk-fg/infinite-image-scroller","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Finfinite-image-scroller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Finfinite-image-scroller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Finfinite-image-scroller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Finfinite-image-scroller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mk-fg","download_url":"https://codeload.github.com/mk-fg/infinite-image-scroller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250532054,"owners_count":21446107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["carousel","desktop","gtk","image-processing","image-viewer","kiosk","python","scroll"],"created_at":"2024-11-10T10:12:33.024Z","updated_at":"2025-04-23T23:31:37.770Z","avatar_url":"https://github.com/mk-fg.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"=======================\nInfinite Image Scroller\n=======================\n-----------------------------------------------------------\n Python GTK3 desktop app to scroll images across the window\n-----------------------------------------------------------\n\nScript loops through all specified image files/dirs, resizes each to window\nwidth/height (preserving aspect ratio) and scrolls them one after another,\ni.e. concatenated into one endless \"image feed\", but loading images only as\nthey're close to be scrolled into view.\n\nSimilar widget/behavior is usually called \"image carousel\" in web development.\n\n``--auto-scroll`` option allows slideshow-like behavior, but otherwise one can\nscroll through these manually.\n\nNeeds Python-3.x, GTK3_ and PyGObject_ to run.\nThese tend to come pre-installed on desktop linuxes.\n\nThere's also optional pixbuf_proc.c module which would need gcc and gtk headers\nto build, and allows to load/scale images efficiently and asynchronously in\nbackground threads without stuttering, as well as image brightness adjustment.\n\nAimed to be rather simple and straightforward, not a full-fledged image viewer.\n\nSee below for info on general usage and specific features.\n\n.. _GTK3: https://www.gtk.org/\n.. _PyGObject: https://pygobject.readthedocs.io/\n\n.. contents::\n  :backlinks: none\n\nURLs for this project repository:\n\n- https://github.com/mk-fg/infinite-image-scroller\n- https://codeberg.org/mk-fg/infinite-image-scroller\n- https://fraggod.net/code/git/infinite-image-scroller\n\n\nUsage\n-----\n\nSome simple usage examples::\n\n  % ./infinite-image-scroller.py image1.jpg image2.jpg image3.jpg\n  % ./infinite-image-scroller.py --loop --shuffle path/to/my-image-dir\n  % ./infinite-image-scroller.py -s0 -dr -a 5:0.01 --pause-on-image 5 /mnt/my-images/\n\nCan also read a list or an endless feed of paths (files/dirs) from a\nnewline-separated list-file or stdin::\n\n  % find -name '*.jpg' | shuf | ./infinite-image-scroller.py -f -\n  % ./infinite-image-scroller.py -f carousel.list --auto-scroll 10:0.1\n\n``-a/--auto-scroll`` option takes ``px[:seconds]`` parameter for scrolling\n\"step\" and how often it is repeated (default is 1 second, if omitted), i.e.\n``-a 10:0.1`` means \"scroll by 10px every 0.1 seconds\".\n\nMore fancy display options - scrolling transparent 800px\nsticky/undecorated/unfocusable/bottom-layer sidebar (like conky_)\non the right::\n\n  % ./infinite-image-scroller.py --pos=800xS-0 --spacing=10 --opacity=0.7 \\\n      --wm-hints='stick keep_below skip_taskbar skip_pager -accept_focus -decorated' \\\n      --wm-type-hints=utility --queue=8:0.8 --auto-scroll=10:0.2 -- /mnt/images/\n\nOr borderless window on whole second monitor::\n\n  % ./infinite-image-scroller.py -p M2 -x=-decorated -a 10:0.05 /mnt/images/\n\n(transparency options should only work with compositing WMs though)\n\nSee ``./infinite-image-scroller.py --help`` for full list of available options.\n\n.. _conky: https://en.wikipedia.org/wiki/Conky_(software)\n\n\nAppearance\n----------\n\n`GTK3 CSS`_ (e.g. ``~/.config/gtk-3.0/gtk.css``) can be used to style app window\nsomewhat and also to define new key bindings there.\n\nFull hierarchy of gtk3 widgets used (without \"Gtk\" prefixes)::\n\n  Window #infinite-image-scroller\n    ScrolledWindow\n      VBox\n        Image\n        Image\n        ...\n\n(to see tree of these for running app, find all style nodes, tweak stuff on the\nfly and such, use GtkInspector_)\n\nDefault css just makes backgrounds in all of these transparent, which doesn't affect\nopacity of the images, which can be controlled with ``-o/--opacity`` option instead.\n\nFor example, to have half-transparent dark-greenish background in the window\n(should only be poking-out with ``--spacing`` or non-solid ``--opacity`` settings)::\n\n  #infinite-image-scroller { background: rgba(16,28,16,0.5); }\n\nThere isn't much to tweak inside this window in general - just images.\n\nSee ``--wm-hints``, ``--wm-type-hints``, ``--icon-name`` and similar options for\nstuff related to WM-side decorations like title bar, borders, icon, etc.\n\n.. _GTK3 CSS: https://developer.gnome.org/gtk3/stable/theming.html\n.. _GtkInspector: https://wiki.gnome.org/Projects/GTK%2B/Inspector\n\n\nConfiguration File(s)\n---------------------\n\nScript will load any \"infinite-image-scroller.ini\" configuration file(s) from\nany of the $XDG_CONFIG_DIRS, $XDG_CONFIG_HOME, ``~/.config`` directories,\nor any files specified with ``-c/--conf`` option directly, in that order.\n\nAll sections and parameters in these are optional.\nValues in later files will override earlier ones.\n\nSpecial \"-\" (dash) value can be used to disable looking up configs in any\nof the default dirs above, and only use specified one(s) and cli options.\n\nRun script with ``--conf-dump`` option to print resulting configuration\n(after loading all existing/specified files), or ``--conf-dump-defaults``\nto see default configuration.\n\nCommand-line parameters always override config files.\n\n\nKey bindings\n------------\n\nDefault keybindings are:\n\n- Arrow keys, Page Up/Down, WSAD - scroll.\n- Esc, q, ctrl+q, ctrl+w - quit.\n- p, space - pause.\n- n, m - slow down, speed up.\n\nSome key/mouse bindings can be added/changed via GTK3 CSS,\nsame as per \"Appearance\" section above - look there for details.\n\nExample - add Vi keybindings for scrolling in this window\n(append this to e.g. ``~/.config/gtk-3.0/gtk.css``)::\n\n  @binding-set image-scroller-keys {\n    bind \"k\" { \"scroll-child\" (step-up, 0) };\n    bind \"j\" { \"scroll-child\" (step-down, 0) };\n    bind \"h\" { \"scroll-child\" (step-left, 1) };\n    bind \"l\" { \"scroll-child\" (step-right, 1) };\n  }\n\n  #infinite-image-scroller scrolledwindow {\n    -gtk-key-bindings: image-scroller-keys;\n  }\n\nOther non-window keys can be changed via ini configuration file,\nin ``[keys]`` section.\n\nMouse clicks print image paths to stdout by default.\nFormat of those lines can be set via \"click-print-format\" ini option,\nor empty value there will disable this output.\n\n\nImage processing\n----------------\n\nWhen using ``-b/--brightness`` and ``-B/--brightness-adapt`` options to apply\npixel-level processing to images, small helper pixbuf_proc.so C-API module\nimplementing that has to be compiled::\n\n  gcc -O2 -fpic --shared `python3-config --includes` \\\n    `pkg-config --libs --cflags gtk+-3.0` pixbuf_proc.c -o pixbuf_proc.so\n\nCan be left in the same dir as the main script or PYTHONPATH anywhere.\n\nNot using PIL/pillow module because simple R/G/B multiplication it uses for this\nstuff was very slow/suboptimal, and python GIL prevents using background threads\nfor such processing.\n\n\nPerformance\n-----------\n\nWhen scrolling large-enough images, synchronous loading (esp. from\nnon-local filesystem) and resizing (for high-res pics in particular)\ncan cause stuttering, blocking GUI operation while it happens.\n\nBundled pixbuf_proc.so helper module tries to address that as well,\nby loading/scaling images in a separate background non-GIL-locked threads,\nand will be auto-imported if it's available.\n\nSee `Image processing`_ section above for how to build it.\n\n\nPotential TODOs\n---------------\n\n- Click-and-drag scrolling.\n\n- Some popup menu (e.g. on right-click) for options maybe.\n\n- Load stuff when manually scrolling in either direction, not just one.\n\n- 2d grid layout mode.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Finfinite-image-scroller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmk-fg%2Finfinite-image-scroller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Finfinite-image-scroller/lists"}