fitsmd5(1)

💖 fitsmd5 — bestie edition 💖

okay so you found fitsmd5(1), the General Commands Manual girlie who computes and updates the DATAMD5 keyword/value. she's lowkey iconic and we're gonna get you two acquainted 🫶

✨ NAME ✨

fitsmd5 — Compute/update the DATAMD5 keyword/value

🌸 SYNOPSIS 🌸

fitsmd5 [-u] [-s] [-a] <FITS files...>

🎀 DESCRIPTION 🎀

so basically, fitsmd5 computes the MD5 signature of all the data sections in a FITS file and prints the results on stdout. and if you want, she can also update the main FITS header by changing the value of the DATAMD5 key. she's flexible like that 💅

this command is literally made to give a unique ID to a FITS file. the algorithm just browses through every data section in the input file and hands those data blocks over to an MD5 hash function. what comes out is a 128-bit signature that can be used to uniquely identify the file. slay ✨

now listen, because this part matters, bestie — this approach is meant to give you a tool to tag FITS files with unique IDs. it is not meant to be used as a checksum for file integrity (the CKSUM key is the solution for that one, iykyk), although it could be used in that spirit. the main point is that only data sections are taken into account, which leaves you the possibility of changing the headers without affecting the data signature. cute, right?

MD5 hashing is cryptographically strong, which means the probability of two different FITS files getting the same ID is almost zero. so it should be good enough to assign a unique ID to several tens of thousands of frames. but — and this is the part where we keep it real — since there's still a tiny but non-zero possibility that two different files will get an identical key, this approach is not recommended to tag very large numbers of files (typically: millions of them 😭). if you do have a large database of FITS files, using a timestamp is usually a better approach. no cap.

the MD5 signature is a good solution to tag a list of FITS files which might have originated from various sources that the database maintainer has no control over. typically, calibration databases holding calibration frames for a given instrument receive data from different actors who might not be in sync with unique file naming conventions. this command makes sure it is always possible to assign a unique ID to each frame. main character energy, honestly 👑

notice that if the input FITS file has no data section, the returned MD5 key will be non-zero (it is exactly d41d8cd98f00b204e9800998ecf8427e). this signature also offers the interesting property that if two files have exactly the same pixels (bit-wise comparisons) they will get the same ID — which is useful e.g. for regression tests. obsessed 🦋

if you want to produce files containing the DATAMD5 key in their main headers, you should use the qfits library, which always inserts this key. if you're working with other FITS-processing software, you should allocate an empty DATAMD5 placeholder and apply this command with the -u option to update the value. got it? good 🫶

notice that this command can also compute the MD5 sum of a complete file, not just its data sections (see the -a option). in this mode, the command is completely identical to the GNU md5sum command, which is used to compute checksums on files. input files in that case need not be FITS, though they still need to be regular files. yes bestie, regular files only, we don't play like that 🙈

💅 OPTIONS 💅

• -u — try to update the DATAMD5 keyword in the main header if present.
• -s — silent mode: run without printing any message. 🤫
• -a — compute the MD5 sum on all bits in the file. in this mode, the command behaves like the GNU md5sum command, to be used e.g. as a checksum. this option excludes all others. ⚠️ like, all of them, so don't try to be cute and stack it.

🍓 FILES 🍓

input files to fitsmd5 shall comply with the FITS format, except when used with the -a option. (see? told you -a was the rebel 🌈)

and that's the whole vibe check, bestie — this page came from the General Commands Manual, dated 01 Aug 2001, and it's all yours now. go tag some frames, you absolute legend 💖✨🎀🦋