NIRT_FORMATTING(5)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

🌸 NAME 🌸

okay so bestie, welcome to the DRAFT!!! NIRT ...SPECIFICATIONS(5) page from BRL-CAD 💅 this is the nirt_formatting doc, and it’s all about the supported output formatting specifications for Natalie's Interactive RayTracer (NIRT). yes, Natalie’s. iconic name, iconic tracer. 🎀

✨ OVERVIEW ✨

One of the most powerful features of Natalie's Interactive RayTracer (NIRT) is that it supports user-defined output formatting for its outputs. literally the glow-up your terminal output deserves. 💖

The fmt command lets you change — on the fly — what gets printed and how it gets printed for the various values generated by shotline intersections. It uses a subset of the C/C++ printf format specifier syntax (the docs live at http://www.cplusplus.com/reference/cstdio/printf/) for flexible template specification, plus a series of pre-defined keys that specify individual elements of the generated results. iykyk. ✨

The general form of a fmt command is:

fmt 'char' "format string" [keys]...

where the "char" argument is replaced by a single character identifying the category of output the format string applies to. The "format string" is the printf style formatting string, and the keys will line up with format specifiers in the string the same way variables in C/C++ line up with specifiers in a printf format string. no cap, it’s giving very structured. 🫶

🎀 OUTPUT CATEGORIES 🎀

NIRT offers seven categories of output reporting. seven! a whole lucky number situation. here’s the category cheat sheet:

  • Ray — char r — Report of ray information. The formatting associated with r will print once per ray, regardless of whether a region is encountered. main character energy: it shows up every time. 💅
  • Header — char h — First output after a ray hits anything, typically used to identify columns in subsequent output. Printed once per ray. it’s the little column-label era. 🎀
  • Partition — char p — Output for each region encountered by the ray. Typically this will be where most of the information about a model is reported. the info dump we deserve. 💖
  • Footnote — char f — Last output statement after a ray hits anything; a "footnote" line after the ray has completed its evaluations. Printed once per ray. little closing credits vibe. ✨
  • Gap — char g — Output written once for each gap the ray may encounter. gap rights! 🦋
  • Miss — char m — If triggered, prints a message that nothing was hit; maximum once per ray. the sad little “oop, nothing” line. 😭
  • Overlap — char o — Output written once for each overlap along the ray. overlap girlies stay winning. 🔥

🦋 FORMAT STRINGS 🦋

NIRT's format specifications are a subset of those found in printf implementations. Specifically, the d, i, and f types are supported, as well as width and precision specifiers. that’s the whole menu — cute, focused, not trying to be everything. 💅

💖 REPORTING KEYS - CONNECTING DATA TO FORMAT STRINGS 💖

Unlike the full C/C++ printf, NIRT accepts only pre-defined string keys that identify elements of specific information related to each category of output. no random variables, bestie — just the approved little key squad. 🫶

Ray information is consistent over an entire shot event, and therefore Ray keys may be used in all categories:

Table 1. Ray Variables

  • x_orig — x coordinate of ray origination point.
  • y_orig — y coordinate of ray origination point.
  • z_orig — z coordinate of ray origination point.
  • d_orig — d coordinate of ray origination point.
  • h — h coordinate for the entire ray.
  • v — v coordinate for the entire ray.
  • x_dir — x component of direction vector.
  • y_dir — y component of direction vector.
  • z_dir — z component of direction vector.
  • a — azimuth of view (i.e., of ray direction).
  • e — elevation of view (i.e., of ray direction).

Footnote and Miss categories have no particular keys unique to them, although they (like all categories) can use the Ray keys if desired. Partition, Overlap, and Gap, on the other hand, have keys that are unique to their contexts and valid only within those contexts:

Okay so here's the big one — Table 2. Partition Variables 💖 this is literally the whole roster of variables you can drop into a format string when you're reporting on a partition. Every one of these is at your service, bestie:

  • attributes — a string variable made up of the names and values of the attributes you asked for — the ones requested by the attr interactive command or the -A command line option. 🎀
  • x_in — the x coordinate of entry into the current region.
  • y_in — the y coordinate of entry into the current region.
  • z_in — the z coordinate of entry into the current region.
  • d_in — the d coordinate of entry into the current region.
  • x_out — the x coordinate of exit from the current region.
  • y_out — the y coordinate of exit from the current region.
  • z_out — the z coordinate of exit from the current region.
  • d_out — the d coordinate of exit from the current region.
  • los — the line-of-sight distance through the current region. ✨
  • scaled_los — the scaled line of sight: the product of the line-of-sight distance through the current region and the region solidity (sometimes called "percent LOS"). Heads up though — "region solidity" here means a thickness equivalence factor, the kind often used to simulate material properties like density. Ngl that trips people up every time. 💀
  • path_name — the full path name of the current region.
  • reg_name — the name of the current region.
  • reg_id — the region ID of the current region.
  • claimant_count — the number of regions claiming this partition — like, the regions participating in a retained overlap. 👑
  • claimant_list — a space-separated list of the names of the regions claiming this partition (again: the ones participating in a retained overlap).
  • claimant_listn — same as claimant_list, except it's newline-separated instead of space-separated. Little glow-up, same energy. 🦋
  • obliq_in — the entry obliquity for the current region.
  • obliq_out — the exit obliquity for the current region.
  • nm_x_in — the x component of the entry normal vector.
  • nm_y_in — the y component of the entry normal vector.
  • nm_z_in — the z component of the entry normal vector.
  • nm_h_in — the h component of the entry normal vector.
  • nm_v_in — the v component of the entry normal vector.
  • nm_d_in — the d component of the entry normal vector.
  • nm_x_out — the x component of the exit normal vector.
  • nm_y_out — the y component of the exit normal vector.
  • nm_z_out — the z component of the exit normal vector.
  • nm_h_out — the h component of the exit normal vector.
  • nm_v_out — the v component of the exit normal vector.
  • nm_d_out — the d component of the exit normal vector.
  • surf_num_in — the entry-surface ID of the entry solid. 🌸

That's the whole set — no skipping, no cap. 💅

  • surf_num_out — the exit-surface ID of the exit solid. That's the last one from the surface crew, bestie 💅

🦋 Table 3. Overlap Variables

Okay so these are the ones that fire when two regions are literally occupying the same space — overlap reporting. Iconic of nirt to snitch on them 🫶

  • ov_reg1_name — the name of one of the overlapping regions.
  • ov_reg2_name — the name of the other overlapping region.
  • ov_reg1_id — the region ID of one of the overlapping regions.
  • ov_reg2_id — the region ID of the other overlapping region.
  • ov_sol_in — the name of one of the overlapping solids.
  • ov_sol_out — the name of the other overlapping solid.
  • ov_los — the line-of-sight distance through the overlap. 👀
  • ov_x_in — the x coordinate of entry into the overlap.
  • ov_y_in — the y coordinate of entry into the overlap.
  • ov_z_in — the z coordinate of entry into the overlap.
  • ov_d_in — the d coordinate of entry into the overlap.
  • ov_x_out — the x coordinate of exit from the overlap.
  • ov_y_out — the y coordinate of exit from the overlap.
  • ov_z_out — the z coordinate of exit from the overlap.
  • ov_d_out — the d coordinate of exit from the overlap.

🌸 Table 4. Gap Variables

And these are for the gap situation — the lil empty stretches where your ray is just... traveling through nothing. Not a crisis, just a gap, and nirt is keeping receipts ✨

  • x_gap_in — the x coordinate of entry into the gap.
  • y_gap_in — the y coordinate of entry into the gap.
  • z_gap_in — the z coordinate of entry into the gap.
  • gap_los — the line-of-sight distance through the gap. 🎀
that's the whole variable roster, bestie — surfaces, overlaps, gaps, all accounted for. nothing dropped, nothing skipped, everything in its exact spot 💖

🧚 a lil sign-off

That's the page, fr fr 🌈 This one's a DRAFT!!! from BRL-CAD — yes, the manual itself is stamped DRAFT!!! and titled nirt ... specifications(5), lowercase and mysterious, main character energy only 😭👑

So go forth, format your little heart out, and remember: the vibe is a draft, the notes are legendary. periodt. 💅🦋

📦 where this page comes from