HDFCOMPASS(1)

📦
version 0.7~b15 · 3 versions
, in ubuntu resolute, ubuntu stonking

🦋 HDFCOMPASS(1) 🦋

the HDF Compass manual, part 1 of 2 ✨

✨ NAME ✨

hdfcompass - HDF Compass Documentation 💖

Okay bestie, this doc is all about the HDF Compass app 🧚 It's basically the official info dump, and it's giving everything you need to know.

✨ IN BRIEF ✨

So HDF Compass is an experimental viewer program for HDF5 and related formats 📂 It's built to complement the bigger, more complex apps like HDFView, not replace them. The vibe is clean, minimal design 🤍 with maximum extensibility through a plugin system for new formats. Literally so customizable 💅

HDF Compass is written in Python, but it ships as a native application on Windows, OS X, and Linux 🖥️ It gets packaged up with PyInstaller and Py2App so you don't have to set up Python yourself. Lowkey so convenient 🌸

✨ CONTENTS ✨

Requirements

TBD 🫠 Still cooking, bestie.

License

Application License

Copyright Notice and License Terms for HDF Compass - Viewer for HDF5 and other file formats 📜

HDF Compass Copyright 2014-2016 by The HDF Group. 🎀

All rights reserved. 🔒

Okay so the redistribution rules are very simple to vibe with 🦋 Redistribution and use in source and binary forms, with or without modification, are permitted for any purpose (including commercial purposes) provided that these conditions are met:

  1. Source code redistributions have to keep the above copyright notice, this list of conditions, and the following disclaimer 💜
  2. Binary redistributions have to reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or materials provided with the distribution 📦
  3. On top of that, redistributions of modified forms of the source or binary code must carry prominent notices stating that the original code was changed and the date of the change 🗓️
  4. All publications or advertising materials that mention features or use of this software are asked, but not required, to acknowledge that it was developed by The HDF Group and credit the contributors 🙌
  5. You can't use the name of The HDF Group, or the name of any Contributor, to endorse or promote products derived from this software without specific prior written permission from The HDF Group or the Contributor, respectively 🚫
DISCLAIMER: THIS SOFTWARE IS PROVIDED BY THE HDF GROUP AND THE CONTRIBUTORS "AS IS" WITH NO WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED. In no event shall The HDF Group or the Contributors be liable for any damages suffered by the users arising out of the use of this software, even if advised of the possibility of such damage. 💀

Translation: it comes "AS IS" with zero warranty, and nobody's on the hook for damages from using it, even if they were warned that could happen 🫶

Copyright and license terms for the following software can be found in the adjacent subdirectory Additional_Legal/ 📁 This info was pulled from sources provided by each software package provider at the location listed under "Original source:", and it was current as of 19 December 2014 🌈

HDF Compass uses selected icons from the following icon sets 🎨

Pre-built HDF Compass binaries include the following software 📦 None of this software is present in whole or in part in the HDF Compass source code, so no drama there ✨

  • Python interpreter
    • Provided by: Python Software Foundation
    • Copyright and license information: additional_legal/Python_Copyright_and_License.txt
    • Original source: <https://docs.python.org/3/license.html>
    • License type: BSD-style license
  • wxPython GUI layer
    • Provided by: Julian Smart, Vadim Zeitlin, Stefan Csomor, Robert Roebling, and other members of the wxWidgets team
    • Copyright and license information: additional_legal/wxWidgets_Copyrights_and_Licenses.txt
    • Original source: <http://docs.wxwidgets.org/3.0/page_copyright.html>
    • License type: GNU LGPL version 2 license with exception
  • PyInstaller runtime support code (Windows & Linux only)
  • HDF5 for Python (h5py)
    • Provided by: Andrew Collette and contributors
    • Copyright and license information: additional_legal/h5py_Copyrights_and_Licenses.txt
    • Original source: <http://docs.h5py.org/en/latest/licenses.html>
    • License type: BSD-style license
  • HydrOffice BAG (hyo2.bag)
  • NumPy
    • Provided by: NumPy Developers
    • Copyright and license information: additional_legal/NumPy_Copyright_and_License.txt
    • Original source: <http://www.numpy.org/license.html>
    • License type: BSD-style license
  • matplotlib
    • Provided by: Matplotlib Development Team
    • Copyright and license information: additional_legal/matplotlib_Copyright_and_License.txt
    • Original source: <http://matplotlib.org/users/license.html>
    • License type: BSD-style license
  • PyDAP
    • Provided by: Roberto De Almeida
    • Copyright and license information: additional_legal/PyDAP_Copyright_and_License.txt
    • Original source: <http://www.pydap.org/license.html>
    • License type: BSD-style license
  • ADIOS
    • Provided by: ADIOS Developers (ORNL), and contributors
    • Copyright and license information: additional_legal/ADIOS_Copyrights_and_Licenses.txt
    • Original source: <https://www.olcf.ornl.gov/center-projects/adios/>
    • License type: BSD-style license

ngl this license section is a lot, but every single credit matters 💖 Stay tuned for part 2! 🧚

  • Store.__contains__(key) — (Abstract) okay so this one checks if the key is in the store 👀 It gives back True if it's there and False if it isn't 💖
  • static Store.canhandle(url) — (Abstract) this is the vibe check for a class. It returns True if the class can make sense of url, and False otherwise 🔥 The GUI uses it to decide which Store implementation to grab when opening a file. For example, the HDF5 plugin uses h5py.is_hdf5(filename) 🦋
  • Store.__init__(url) — (Abstract) makes a brand new store instance from the data at url ✨ URLs are written in the scheme://locator style. Like, an HDF5 file might live at file:///path/to/file.hdf5 🌸
  • Store.close(): — (Abstract) cuts off access to the data store 🙈
  • Store.get_parent(key) — (Abstract) returns the object that contains key, or None if there's no such object 🧚
  • Store.url — (Abstract) the URL that was used to open the store 🔗
  • Store.displayname — (Abstract) a short name for the store, like basename(filepath) 💅
  • Store.root — (Abstract) a Node instance that marks the starting point in the file 👑 For hierarchical formats, that's the root container. For scalar formats (FITS, for example), it could be something like an Array or Image instance 🌈
  • Store.file_extensions — for plugins that support local file access, this is a dictionary mapping file kinds to lists of extensions in "glob" format, e.g. {'HDF5 File': ['.h5', '.hdf5']} 💜 It's used to fill the filter in the file-open dialog, among other things ✨

🦋 Nodes 🦋

A "node" is any object that lives in the data store 🌸 The Node class is the base class for the more interesting abstract classes, like containers and arrays. It defines a lot of the interface 💖

  • class Node — base class for all objects that live in a data store 💅 You generally shouldn't inherit from Node directly. Go for one of the more useful Node subclasses in this file instead. Direct Node subclasses can't do anything interesting in the GUI, they just show up in the browser 🙈
  • Node.icons — a class attribute holding a dict for icon support 🎀 The keys should be integers giving the icon size, and the values should be a callable that returns a byte string with PNG image data. Example: icons = {16: get_png_16, 32: get_png_32} 🖼️ Icons are a pain to handle, so default icons are provided by compass_model, and this attribute is optional 🫶
  • Node.classkind — (Abstract) a short string (2 or 3 words) describing what the class represents 🍓 It shows up in places like the "Open As" context menu. Examples: "HDF5 Image" or "Swath" ✨
  • static Node.canhandle(store, key) — (Abstract) figures out whether this class can usefully represent the object 🔍 Keep in mind that keys aren't technically required to be strings 🧐
  • Node.__init__(store, key): — (Abstract) creates a new instance representing the object that key points to in store 🧚
  • Node.key — (Abstract) a unique key that identifies this object in the store 🔑 Keys can be any hashable object, though strings are the most common 💜
  • Node.store — (Abstract) the data store that the object belongs to 🏠
  • Node.displayname — (Abstract) a short name for display purposes, around 16 chars or so. Anything longer gets ellipsized 💅
  • Node.description — (Abstract) a descriptive string, which can be multi-line 📝

🌷 Containers 🌷

  • class Container(Node) — represents an object that holds other objects, like an HDF5 group or a filesystem directory 📁 Implementations get displayed in the browser view 👀
  • Container.__len__() — (Abstract) gets the number of objects directly attached to the container 🔢
  • Container.__getitem__(index) — (Abstract) retrieves the node at index. Heads up, this returns a Node instance, not a key 🫶

🌈 Arrays 🌈

  • class Array(Node) — represents a multidimensional array, with an interface inspired by Numpy arrays 🍓 Implementations get displayed in a spreadsheet-style viewer with controls for subsetting and plotting 📊
  • Array.shape — the shape of the array, as a Python tuple 📐
  • Array.dtype — a NumPy data type object representing the type of the array 🧮
  • Array.__getitem__(indices) — retrieves data from the array using the standard array-slicing syntax: data = array[idx1, idx2, idx3] ✂️ indices are the slicing arguments. Only integer indexes and slice objects (representing ranges) are supported 💖

🫧 Key-Value lists 🫧

  • class KeyValue(Node) — represents an object that holds a sequence of key: value attributes 💅 Keys must be strings. Values can be Python or NumPy objects 🔥 Implementations get displayed using a list-like control 📜
  • KeyValue.keys — (Abstract) a list containing all of the (string) keys in the object 🗝️
  • KeyValue.__getitem__(name) — (Abstract) retrieves the value associated with the string name 💜

🖼️ Images 🖼️

  • class Image(Node) — represents an image 🎨 The current interface only supports true-color RGB images with the origin at upper left. It could easily be extended to more complex formats, including RGBA or palette-based images 🌈 Implementations get displayed in an image viewer 👀
  • Image.width — image width in pixels 📏
  • Image.height — image height in pixels 📏
  • Image.data — the image data. Right now it's RGB, pixel-interlaced 🌸

🧚 Top-level functions 🧚

One public function is defined in compass_model:

  • push(storeclass) — registers a new Store subclass with HDFCompass 💖 When a URL is being opened, the class gets queried (via storeclass.canhandle) to see if it can make sense of the URL 🔍

💅 How to release [developer] 💅

🎀 Versioning 🎀

The following files need updating for each new release:

  • HDFCompass.1file.spec
  • HDFCompass.1folder.spec
  • setup.cfg
  • setup.py
  • spec.json
  • docs/conf.py
  • hdf_compass/utils/__init__.py

🧁 PyInstaller 🧁

For the HDFCompass.1file.spec file, you need to verify that the following parameters are passed to the EXE() function:

  • console=False — this avoids a console window opening at run-time for standard I/O 🙈
  • debug=False — this avoids the boot-loader issuing progress messages while it initializes and starts the bundled app 🤫

🛠️ How to freeze [developer] 🛠️

TBD

  • Index <>
  • Module Index <>
  • Search Page <>

✨ Author ✨

The HDF Group

2017, The HDF Group

Okay bestie, that's the whole page! 🌈 Version 0.7 from Jan 21, 2026 is the one we're talking about here, so you're all caught up 💖 Go forth and freeze, release, and slay responsibly 💅✨🦋

📦 where this page comes from