{"id":13648729,"url":"https://github.com/aldanor/hdf5-rust","last_synced_at":"2025-04-11T19:14:24.421Z","repository":{"id":32976196,"uuid":"36598545","full_name":"aldanor/hdf5-rust","owner":"aldanor","description":"HDF5 for Rust","archived":false,"fork":false,"pushed_at":"2024-08-08T08:55:58.000Z","size":1771,"stargazers_count":317,"open_issues_count":54,"forks_count":95,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-11T19:14:15.335Z","etag":null,"topics":["hdf5","rust"],"latest_commit_sha":null,"homepage":"https://docs.rs/hdf5","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aldanor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","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":"2015-05-31T10:40:35.000Z","updated_at":"2025-04-09T07:18:48.000Z","dependencies_parsed_at":"2023-11-17T01:09:43.617Z","dependency_job_id":"745d5ba5-1893-4535-b816-4cf8daeec950","html_url":"https://github.com/aldanor/hdf5-rust","commit_stats":{"total_commits":1373,"total_committers":22,"mean_commits":62.40909090909091,"dds":0.1937363437727604,"last_synced_commit":"2e44e9033cb06551fea9769a816eca4895b6267a"},"previous_names":["aldanor/hdf5-rs"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldanor%2Fhdf5-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldanor%2Fhdf5-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldanor%2Fhdf5-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldanor%2Fhdf5-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aldanor","download_url":"https://codeload.github.com/aldanor/hdf5-rust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248465345,"owners_count":21108244,"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":["hdf5","rust"],"created_at":"2024-08-02T01:04:29.300Z","updated_at":"2025-04-11T19:14:24.394Z","avatar_url":"https://github.com/aldanor.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# hdf5-rust\n\nHDF5 for Rust.\n\n[![Build](https://github.com/aldanor/hdf5-rust/workflows/CI/badge.svg)](https://github.com/aldanor/hdf5-rust/actions?query=branch%3Amaster)\n[![Latest Version](https://img.shields.io/crates/v/hdf5.svg)](https://crates.io/crates/hdf5)\n[![Documentation](https://docs.rs/hdf5/badge.svg)](https://docs.rs/hdf5)\n[![Changelog](https://img.shields.io/github/v/release/aldanor/hdf5-rust)](https://github.com/aldanor/hdf5-rust/blob/master/CHANGELOG.md)\n![hdf5: rustc 1.51+](https://img.shields.io/badge/hdf5-rustc_1.51+-lightblue.svg)\n[![Total Lines](https://tokei.rs/b1/github/aldanor/hdf5-rust)](https://github.com/aldanor/hdf5-rust)\n[![Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nThe `hdf5` crate (previously known as `hdf5-rs`) provides thread-safe Rust bindings and \nhigh-level wrappers for the HDF5 library API. Some of the features include:\n\n- Thread-safety with non-threadsafe libhdf5 builds guaranteed via reentrant mutexes.\n- Native representation of most HDF5 types, including variable-length strings and arrays.\n- Derive-macro for automatic mapping of user structs and enums to HDF5 types.\n- Multi-dimensional array reading/writing interface via `ndarray`.\n\nDirect low-level bindings are also available and are provided in the `hdf5-sys` crate.\n\nRequires HDF5 library of version 1.8.4 or later.\n\n## Example\n\n```rust\n#[cfg(feature = \"blosc\")]\nuse hdf5::filters::blosc_set_nthreads;\nuse hdf5::{File, H5Type, Result};\nuse ndarray::{arr2, s};\n\n#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5\n#[repr(u8)]\npub enum Color {\n    R = 1,\n    G = 2,\n    B = 3,\n}\n\n#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5\n#[repr(C)]\npub struct Pixel {\n    xy: (i64, i64),\n    color: Color,\n}\n\nimpl Pixel {\n    pub fn new(x: i64, y: i64, color: Color) -\u003e Self {\n        Self { xy: (x, y), color }\n    }\n}\n\nfn write_hdf5() -\u003e Result\u003c()\u003e {\n    use Color::*;\n    let file = File::create(\"pixels.h5\")?; // open for writing\n    let group = file.create_group(\"dir\")?; // create a group\n    #[cfg(feature = \"blosc\")]\n    blosc_set_nthreads(2); // set number of blosc threads\n    let builder = group.new_dataset_builder();\n    #[cfg(feature = \"blosc\")]\n    let builder = builder.blosc_zstd(9, true); // zstd + shuffle\n    let ds = builder\n        .with_data(\u0026arr2(\u0026[\n            // write a 2-D array of data\n            [Pixel::new(1, 2, R), Pixel::new(2, 3, B)],\n            [Pixel::new(3, 4, G), Pixel::new(4, 5, R)],\n            [Pixel::new(5, 6, B), Pixel::new(6, 7, G)],\n        ]))\n        // finalize and write the dataset\n        .create(\"pixels\")?;\n    // create an attr with fixed shape but don't write the data\n    let attr = ds.new_attr::\u003cColor\u003e().shape([3]).create(\"colors\")?;\n    // write the attr data\n    attr.write(\u0026[R, G, B])?;\n    Ok(())\n}\n\nfn read_hdf5() -\u003e Result\u003c()\u003e {\n    use Color::*;\n    let file = File::open(\"pixels.h5\")?; // open for reading\n    let ds = file.dataset(\"dir/pixels\")?; // open the dataset\n    assert_eq!(\n        // read a slice of the 2-D dataset and verify it\n        ds.read_slice::\u003cPixel, _, _\u003e(s![1.., ..])?,\n        arr2(\u0026[\n            [Pixel::new(3, 4, G), Pixel::new(4, 5, R)],\n            [Pixel::new(5, 6, B), Pixel::new(6, 7, G)],\n        ])\n    );\n    let attr = ds.attr(\"colors\")?; // open the attribute\n    assert_eq!(attr.read_1d::\u003cColor\u003e()?.as_slice().unwrap(), \u0026[R, G, B]);\n    Ok(())\n}\n\nfn main() -\u003e Result\u003c()\u003e {\n    write_hdf5()?;\n    read_hdf5()?;\n    Ok(())\n}\n```\n\n## Compatibility\n\n### Platforms\n\n`hdf5` crate is known to run on these platforms: Linux, macOS, Windows (tested on:\nUbuntu 16.04, 18.04, and 20.04; Windows Server 2019 with both MSVC and GNU \ntoolchains; macOS Catalina).\n\n### Rust\n\n`hdf5` crate is tested continuously for all three official release channels, and\nrequires a reasonably recent Rust compiler (e.g. of version 1.51 or newer).\n\n### HDF5\n\nRequired HDF5 version is 1.8.4 or newer. The library doesn't have to be built with\nthreadsafe option enabled in order to make the user code threadsafe.\n\nVarious HDF5 installation options are supported and tested: via package managers\nlike homebrew and apt; system-wide installations on Windows; conda installations \nfrom both the official channels and conda-forge. On Linux and macOS, both OpenMPI \nand MPICH parallel builds are supported and tested. \n\nThe HDF5 C library can also be built from source and linked in statically by \nenabling `hdf5-sys/static` feature (CMake required).\n\n## Building\n\n### HDF5 version\n\nBuild scripts for both `hdf5-sys` and `hdf5` crates check the actual version of the\nHDF5 library that they are being linked against, and some functionality may be conditionally\nenabled or disabled at compile time. While this allows supporting multiple versions of HDF5\nin a single codebase, this is something the library user should be aware of in case they\nchoose to use the low level FFI bindings.\n\n### Environment variables\n\nIf `HDF5_DIR` is set, the build script will look there (and nowhere else) for HDF5\nheaders and binaries (i.e., it will look for headers under `$HDF5_DIR/include`).\n\nIf `HDF5_VERSION` is set, the build script will check that the library version matches\nthe specified version string; in some cases it may also be used by the build script to\nhelp locating the library (e.g. when both 1.8 and 1.10 are installed via Homebrew on macOS).\n\n### conda\n\nIt is possible to link against `hdf5` conda package; a few notes and tips:\n\n- Point `HDF5_DIR` to conda environment root.\n- The build script knows about conda environment layout specifics and will adjust\n  paths accordingly (e.g. `Library` subfolder in Windows environments).\n- On Windows, environment's `bin` folder must be in `PATH` (or the environment can\n  be activated prior to running cargo).\n- On Linux / macOS, it is recommended to set rpath, e.g. by setting\n  `RUSTFLAGS=\"-C link-args=-Wl,-rpath,$HDF5_DIR/lib\"`.\n- For old versions of HDF5 conda packages on macOS, it may also be necessary to set\n  `DYLD_FALLBACK_LIBRARY_PATH=\"$HDF5_DIR/lib\"`.\n\n### Linux\n\nThe build script will attempt to use pkg-config first, which will likely work out without\nfurther tweaking for the more recent versions of HDF5. The build script will then also look \nin some standard locations where HDF5 can be found after being apt-installed on Ubuntu.\n\n### macOS\n\nOn macOS, the build script will attempt to locate HDF5 via Homebrew if it's available.\nIf both 1.8 and 1.10 are installed and available, the default (1.10) will be used \nunless `HDF5_VERSION` is set.\n\n### Windows\n\n`hdf5` crate fully supports MSVC toolchain, which allows using the\n[official releases](https://www.hdfgroup.org/downloads/index.html) of\nHDF5 and is generally the recommended way to go. That being said, previous experiments have \nshown that all tests pass on the `gnu` target as well, one just needs to be careful with \nbuilding the HDF5 binary itself and configuring the build environment.\n\nFew things to note when building on Windows:\n\n- `hdf5.dll` should be available in the search path at build time and runtime (both `gnu` and `msvc`).\n  This normally requires adding the `bin` folder of HDF5 installation to `PATH`. If using an official\n  HDF5 release (`msvc` only), this will typically be done automatically by the installer.\n- `msvc`: installed Visual Studio version should match the HDF5 binary (2013 or 2015). Note that it\n  is not necessary to run `vcvars` scripts; Rust build system will take care of that.\n- When building for either target, make sure that there are no conflicts in the search path (e.g.,\n  some binaries from MinGW toolchain may shadow MSVS executables or vice versa).\n- The recommended platform for `gnu` target is [TDM distribution](http://tdm-gcc.tdragon.net/) of\n  MinGW-GCC as it contains bintools for both 32-bit and 64-bit.\n- The recommended setup for `msvc` target is VS2015 x64 since that matches CI build configuration,\n  however VS2013 and x86 should work equally well.\n\n## License\n\n`hdf5` crate is primarily distributed under the terms of both the MIT license and the\nApache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and\n[LICENSE-MIT](LICENSE-MIT) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faldanor%2Fhdf5-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faldanor%2Fhdf5-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faldanor%2Fhdf5-rust/lists"}