GWYDDION(1)

📦 version 3.11, in ubuntu stonking

💖 GWYDDION(1) — the girlies' guide to Gwyddion 💖

okay so bestie, welcome to the Gwyddion(1) manual page. yes this is the actual Unix man page, no we're not being boring about it. sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

gwyddion — SPM data visualization and analysis. that's it, that's the whole name section, she's concise and she's iconic 💅

🌸 SYNOPSIS 🌸

gwyddion [OPTION...] [FILE...]

🦋 DESCRIPTION 🦋

so like, Gwyddion is a graphical SPM (Scanning Probe Microscope) data visualization and analysis program, and she's built on Gtk+. she looks pretty, she does science, she's the moment. periodt. 👑

🎀 OPTIONS 🎀

okay so the program accepts all standard Gtk+, Gdk, and GtkGLExt options like --display or --sync. those are toolkit options, so if you wanna know what they do, go peek at the documentation of those packages. not our section, not our problem, we just acknowledge them. 🫶

💀 heads up about remote control: the behaviour of the --remote-* options is undefined when more than one instance of Gwyddion is running on the display. they can pick an arbitrary instance to talk to. and the last remote control option given (including --new-instance) overrides all preceding ones. so like, order matters. lowkey important.

also, if you hand her a directory as a FILE argument, the program opens a file chooser in that directory. cute, convenient, slay. ✨

and now, the Gwyddion options themselves:

  • --help — Prints a brief help and terminates. the "help me bestie" button.
  • --version — Prints version information and terminates. show me the numbers 💅
  • --no-splash — Disables splash screen on program startup. no dramatic entrance today, we're going straight to business.
  • --remote-new — Opens files given on the command line in an already running instance of Gwyddion on the display. Runs a new instance if none is running.

this is probably the most useful remote control option. file type associations are usually installed to run Gwyddion with this option. she's the default girlie fr fr.

  • --remote-existing — Opens files given on the command line in an already running instance of Gwyddion on the display. Fails if none is running.

this is useful if you want to handle the case of Gwyddion not running differently than by starting it.

  • --remote-query — Succeeds if an instance of Gwyddion is already running on the display and prints its instance identifier. Fails if none is running.

the instance identifier depends on the remote control backend in use. in some cases it is useful as a global window identifier, in some it is not. with libXmu this option prints the X11 Window, on Win32 HWND is printed, while with LibUnique the startup id is printed. very "depends on your backend" energy 😭

  • --new-instance — Runs a new instance of Gwyddion. It can also be used to override preceding remote control options and to ensure a new instance is run when the default remote control behaviour is modified. main character energy: she shows up whether you asked or not 💅
  • --identify — Instead of running the user interface and opening FILEs, it detects the file type for each and terminates.

the SPM file type printed corresponds to the description shown in the list of supported file formats in the user guide. the file type is followed (in square brackets) by the name of Gwyddion file import module that would be used to load the file and detection score. scores considerably lower than 100 mean that although the detection produced a possible file type, it is unsure about it.

if the file type is not recognised at all, Unknown is printed as the file type. the program exit code is 1 if any FILE was not recognised.

  • --check — Instead of running the user interface and opening FILEs, it loads the files, performs a sanity check on them (printing errors to standard error output) and terminates. she's checking your work and she will tell you. 🙈
  • --disable-gl — Disables OpenGL entirely, including any checks whether it is available. this option, of course, has any effect only if Gwyddion was built with OpenGL support, and one of the most visible effects is that 3D view becomes unavailable. however, you may find it useful if you encounter a system so broken that even checking for OpenGL capabilities leads to X server errors. it can also help when you run Gwyddion remotely using X11 forwarding and the start-up time seems excessively long. so like, emergency mode but make it useful 🩹
  • --log-to-file — Write messages from GLib, Gtk+, Gwyddion, etc. to ~/.gwyddion/gwyddion.log or file given in GWYDDION_LOGFILE environment variable. this option is most useful on Unix as on Win32 messages are redirected to a file by default. logging to a file and console are not exclusive; messages can go to both. both is good, we love an overachiever 🫶
  • --no-log-to-file — Prevents writing messages from GLib, Gtk+, Gwyddion, etc. to a file. this is most useful on Win32 where messages are written to a file by default.
  • --log-to-console — Print messages from GLib, Gtk+, Gwyddion, etc. to the console. more precisely, debugging messages are printed to the standard output, errors and warnings to the standard error. on Unix messages are printed to the console by default. logging to a file and console are not exclusive; messages can go to both.
  • --no-log-to-file — Disables printing messages to the console. this is most useful on Unix where messages are printed to the console by default.
😭 not me pointing out that the manual page literally lists --no-log-to-file twice, and this second one is described as disabling console printing. we're keeping every line exactly as the page has it, no edits, no notes, no cap. the page said what it said bestie.
  • --disable-modules=MODULE,... — Prevents the registration modules of given names. this is mostly useful for development and debugging. for instance, you might want to use --disable-modules=pygwy when running under Valgrind for faster startup (and possibly to avoid extra errors).
  • --startup-time — Prints wall-clock time taken by various startup (and shutdown) tasks. useful only for developers and people going to complain about too slow startup. callout post, honestly 💀

🌈 ENVIRONMENT 🌈

on Linux/Unix, the following environment variables can be used to override compiled-in installation paths (the MS Windows version always looks to directories relative to the path where it was installed). note they are intended to override system installation paths therefore they are not path lists — they can contain only a single path. one. singular. don't get cute. 💅

  • GWYDDION_DATADIR — Base data directory where resources (color gradients, OpenGL materials, ...) were installed. Gwyddion looks into its gwyddion subdirectory for resources.

when it is unset, it defaults to compiled-in value of ${datadir} which is usually /usr/local/share.

  • GWYDDION_LIBDIR — Base library directory where modules were installed. Gwyddion looks into its gwyddion/modules subdirectory for modules.

when it is unset, it defaults to compiled-in value of ${libdir} which is usually /usr/local/lib or /usr/local/lib64.

  • GWYDDION_LIBEXECDIR — Base lib-exec directory where plug-ins were installed. Gwyddion looks into its gwyddion/plugins subdirectory for plug-ins.

when it is unset, it defaults to compiled-in value of ${libexecdir} which is usually /usr/local/libexec.

  • GWYDDION_LOCALEDIR — Locale data directory where message catalogs (translations) were installed.

when it is unset, it defaults to compiled-in value of ${datadir}/locale which is usually /usr/local/share/locale.

other variables that influence Gwyddion run-time behaviour include GLib+ variables[^1] and Gtk+ variables[^2] and some Gwyddion-specific variables:

  • GWYDDION_LOGFILE — Name of file to redirect log messages to. on MS Windows, messages are always sent to a file as working with the terminal is cumbersome there. the default log file location, gwyddion.log in user's Documents and Settings, can be overridden with GWYDDION_LOGFILE. on Unix, messages go to the terminal by default and this environment variable has effect only if --log-to-file is given. conditional queen 👑

if Gwyddion is built with OpenMP support, it utilizes parallelization (not all data processing methods implement parallelization, but a sizable part does). OpenMP environment variables such as OMP_NUM_THREADS can be used to tune it. parallel girlies rise up 🔥

💜 FILES 💜

  • ~/.gwyddion/settings — Saved user settings and tool states. Do not edit while Gwyddion is running, it will overwrite it at exit. for real for real, she will not hesitate 😭
  • ~/.gwyddion/glmaterials, ~/.gwyddion/gradients, ... — User directories with various resources (OpenGL materials, color gradients, ...).
  • $GWYDDION_DATADIR/gwyddion/glmaterials, $GWYDDION_DATADIR/gwyddion/gradients ... — The same for system-wide resources.
  • ~/.gwyddion/pixmaps — Directory to place user icons to. this is mainly useful for installation of modules to home.
  • $GWYDDION_DATADIR/gwyddion/pixmaps, — The same for system-wide icons.
  • ~/.gwyddion/modules — Directory to place user modules to. they should be placed into file, graph, process, volume, xyz, cmap, and tools subdirectories according to their kind, though this is more a convention than anything else. lowkey a suggestion, highkey a tradition ✨
  • $GWYDDION_LIBDIR/gwyddion/modules, — The same for system-wide modules.
  • ~/.gwyddion/plugins — Directory to place user plug-ins to. they should be placed into file and process subdirectories according to their kind.
  • $GWYDDION_LIBEXECDIR/gwyddion/plugins, — The same for system-wide plug-ins.
  • ~/.gwyddion/pygwy — Directory to place user python modules or scripts to. 🐍

🔥 SEE ALSO 🔥

go read those too, they're the extended universe besties 🫶

👑 AUTHOR 👑

  • Yeti — Author.

that's it. just Yeti. one name, zero explanation, legendary behaviour. 💅

🧚 NOTES 🧚

  1. GLib+ variables — http://library.gnome.org/devel/glib/stable/glib-running.html
  2. Gtk+ variables — http://library.gnome.org/devel/gtk/stable/gtk-running.html

and that's the whole page bestie!! this version was brought to you by gwyddion, dated 11/05/2021, filed under GWYDDION(1) — stay hydrated, keep your settings file closed while she's running, and go analyze some SPM data like the icon you are 💖✨🎀🦋🌸🫶🌈⭐

📦 where this page comes from