Struct PhotometricCalculations 

pub struct PhotometricCalculations;

Photometric calculations on Eulumdat data.

Implementations

impl PhotometricCalculations

pub fn downward_flux(ldt: &Eulumdat, arc: f64) -> f64

Calculate the downward flux fraction up to a given arc angle.

Integrates the luminous intensity distribution from 0° to the specified arc angle to determine the percentage of light directed downward.

Arguments

• ldt - The Eulumdat data
• arc - The maximum angle from vertical (0° = straight down, 90° = horizontal)

Returns

The downward flux fraction as a percentage (0-100).

pub fn total_output(ldt: &Eulumdat) -> f64

Calculate total luminous output.

Integrates the luminous intensity over the entire sphere.

pub fn calculated_luminous_flux(ldt: &Eulumdat) -> f64

Calculate the luminous flux from the stored intensity distribution.

This uses the conversion factor to convert from cd/klm to actual lumens.

pub fn calculate_direct_ratios(ldt: &Eulumdat, shr: &str) -> [f64; 10]

Calculate direct ratios (utilization factors) for standard room indices.

Room indices k: 0.60, 0.80, 1.00, 1.25, 1.50, 2.00, 2.50, 3.00, 4.00, 5.00

Arguments

• ldt - The Eulumdat data
• shr - Spacing to Height Ratio (typically “1.00”, “1.25”, or “1.50”)

Returns

Array of 10 direct ratio values for the standard room indices.

pub fn beam_angle(ldt: &Eulumdat) -> f64

Calculate beam angle (full angle where intensity drops to 50% of maximum).

Uses the IES definition: angle between directions where intensity is 50% of the maximum intensity (FWHM - Full Width at Half Maximum).

Important: Per CIE S 017:2020 (17-27-077), beam angle is defined as a full angle, not a half angle. This function returns the full angle (2× the half-angle from nadir).

Reference: https://cie.co.at/eilvterm/17-27-077

pub fn field_angle(ldt: &Eulumdat) -> f64

Calculate field angle (full angle where intensity drops to 10% of maximum).

Uses the IES definition: angle between directions where intensity is 10% of the maximum intensity.

Important: Per CIE S 017:2020, field angle is defined as a full angle, not a half angle. This function returns the full angle (2× the half-angle from nadir).

pub fn beam_angle_cie(ldt: &Eulumdat) -> f64

Calculate beam angle using CIE definition (center-beam intensity).

Uses the CIE/NEMA definition: angle between directions where intensity is 50% of the center-beam intensity (intensity at 0° gamma).

Important: Per CIE S 017:2020 (17-27-077), beam angle is defined as a full angle, not a half angle. This function returns the full angle.

This can differ significantly from the IES (max-based) definition for luminaires with “batwing” distributions where center-beam intensity is less than maximum intensity.

pub fn field_angle_cie(ldt: &Eulumdat) -> f64

Calculate field angle using CIE definition (center-beam intensity).

Uses the CIE/NEMA definition: angle between directions where intensity is 10% of the center-beam intensity.

Important: Per CIE S 017:2020, field angle is defined as a full angle, not a half angle. This function returns the full angle.

pub fn half_beam_angle(ldt: &Eulumdat) -> f64

Calculate half beam angle (angle from nadir to 50% intensity).

This returns the half angle from nadir (0°) to where intensity drops to 50% of maximum. For the full beam angle per CIE definition, use beam_angle().

This is useful for cone diagrams and coverage calculations where the half-angle is needed.

pub fn half_field_angle(ldt: &Eulumdat) -> f64

Calculate half field angle (angle from nadir to 10% intensity).

This returns the half angle from nadir (0°) to where intensity drops to 10% of maximum. For the full field angle per CIE definition, use field_angle().

pub fn beam_field_analysis(ldt: &Eulumdat) -> BeamFieldAnalysis

Get detailed beam/field angle analysis comparing IES and CIE definitions.

Returns a BeamFieldAnalysis struct containing:

• Beam and field angles using both IES (max) and CIE (center-beam) definitions
• Maximum intensity and center-beam intensity values
• Whether the distribution has a “batwing” pattern (center < max)

This is useful for understanding luminaires like the examples in the Wikipedia “Beam angle” article where the two definitions give different results.

pub fn upward_beam_angle(ldt: &Eulumdat) -> f64

Calculate beam angle for upward light (peak near 180°).

For uplights where maximum intensity is in the upper hemisphere (gamma > 90°), this calculates the beam angle centered on the upward peak.

Returns the full angle where intensity is above 50% of maximum.

pub fn upward_field_angle(ldt: &Eulumdat) -> f64

Calculate field angle for upward light (peak near 180°).

Returns the full angle where intensity is above 10% of maximum.

pub fn downward_beam_angle(ldt: &Eulumdat) -> f64

Calculate beam angle for downward light (peak near 0°).

For downlights where maximum intensity is in the lower hemisphere (gamma < 90°), this calculates the beam angle centered on the downward peak.

Returns the full angle where intensity is above 50% of maximum.

pub fn downward_field_angle(ldt: &Eulumdat) -> f64

Calculate field angle for downward light (peak near 0°).

Returns the full angle where intensity is above 10% of maximum.

pub fn comprehensive_beam_analysis(ldt: &Eulumdat) -> ComprehensiveBeamAnalysis

Get comprehensive beam angle analysis including both downward and upward components.

For luminaires with significant flux in both hemispheres (e.g., direct-indirect), this provides separate beam angles for each direction.

pub fn ugr_crosssection(ldt: &Eulumdat) -> Vec<(f64, f64)>

Calculate UGR (Unified Glare Rating) cross-section data.

Returns intensity values at standard viewing angles for UGR calculation.

pub fn cie_flux_codes(ldt: &Eulumdat) -> CieFluxCodes

Calculate CIE Flux Codes.

Returns a tuple of 5 values (N1, N2, N3, N4, N5) representing the percentage of lamp flux in different angular zones:

• N1: % in lower hemisphere (0-90°)
• N2: % in 0-60° zone
• N3: % in 0-40° zone
• N4: % in upper hemisphere (90-180°)
• N5: % in 90-120° zone (near-horizontal uplight)

The flux code is typically written as: N1 N2 N3 N4 N5 Example: “92 68 42 8 3” means 92% downward, 68% within 60°, etc.

pub fn luminaire_efficacy(ldt: &Eulumdat) -> f64

Calculate luminaire efficacy in lm/W.

This differs from lamp efficacy by accounting for the Light Output Ratio (LOR). Luminaire efficacy = (lamp flux × LOR) / system watts

Returns

Luminaire efficacy in lumens per watt (lm/W)

pub fn luminaire_efficiency(ldt: &Eulumdat) -> f64

Calculate luminaire efficiency (same as LOR but calculated from intensities).

Compares calculated luminous flux to rated lamp flux.

Returns

Efficiency as a percentage (0-100)

pub fn spacing_criterion(ldt: &Eulumdat, c_plane: f64) -> f64

Calculate the spacing criterion (S/H ratio) for uniform illumination.

The spacing criterion indicates the maximum ratio of luminaire spacing to mounting height that will provide reasonably uniform illumination.

Arguments

• ldt - The Eulumdat data
• c_plane - The C-plane to analyze (typically 0 or 90)

Returns

The spacing to height ratio (typically 1.0 to 2.0)

pub fn spacing_criteria(ldt: &Eulumdat) -> (f64, f64)

Calculate spacing criteria for both principal planes.

Returns

(S/H parallel, S/H perpendicular) - spacing ratios for C0 and C90 planes

pub fn spacing_criterion_ies( ldt: &Eulumdat, c_plane: f64, uniformity_threshold: f64, ) -> f64

IES-style spacing criterion based on work plane illuminance uniformity.

This method finds the maximum S/H ratio where illuminance uniformity (Emin/Emax) remains above the threshold (default 0.7) on the work plane.

The IES method accounts for:

• Inverse square law (1/d²)
• Cosine law for horizontal illuminance (cos³θ)
• Contribution from adjacent luminaires

Arguments

• ldt - The Eulumdat data
• c_plane - The C-plane to analyze (0 for 0-180, 90 for 90-270)
• uniformity_threshold - Minimum Emin/Emax ratio (typically 0.7)

Returns

The spacing to height ratio (typically 1.0 to 1.5)

pub fn spacing_criteria_ies(ldt: &Eulumdat) -> (f64, f64, f64)

Calculate IES-style spacing criteria for both principal planes.

Uses illuminance-based uniformity calculation per IES methodology.

Returns

(SC 0-180, SC 90-270, SC diagonal)

pub fn zonal_lumens_10deg(ldt: &Eulumdat) -> [f64; 18]

Calculate luminous flux in standard angular zones.

Returns flux percentages in 10° zones from 0° to 180°.

Returns

Array of 18 values representing % flux in each 10° zone

pub fn zonal_lumens_30deg(ldt: &Eulumdat) -> ZonalLumens30

Calculate luminous flux in standard 30° zones.

Returns

ZonalLumens30 struct with flux in each 30° zone

pub fn k_factor( ldt: &Eulumdat, room_index: f64, reflectances: (f64, f64, f64), ) -> f64

Calculate the K-factor (utilance) for a room.

K = (E_avg × A) / Φ_lamp

Where:

• E_avg = average illuminance on work plane
• A = room area
• Φ_lamp = total lamp flux

Arguments

• ldt - The Eulumdat data
• room_index - Room index k = (L×W) / (H_m × (L+W))
• reflectances - (ceiling, wall, floor) reflectances as decimals

Returns

K-factor (utilance) as a decimal (0-1)

pub fn ugr(ldt: &Eulumdat, params: &UgrParams) -> f64

Calculate UGR (Unified Glare Rating) for a specific room configuration.

UGR = 8 × log₁₀((0.25/Lb) × Σ(L²×ω/p²))

Where:

• Lb = background luminance
• L = luminaire luminance in direction of observer
• ω = solid angle of luminaire
• p = position index

Arguments

• ldt - The Eulumdat data
• params - UGR calculation parameters

Returns

UGR value (typically 10-30, lower is better)

pub fn cu_table(ldt: &Eulumdat) -> CuTable

Calculate Coefficient of Utilization table using Zonal Cavity Method.

Returns a table of CU values (as percentages, 0-100+) for standard room cavity ratios (RCR 0-10) and reflectance combinations.

Based on IES LM-57 and IES Handbook calculation methods.

pub fn ugr_table(ldt: &Eulumdat) -> UgrTable

Calculate Unified Glare Rating table.

Returns UGR values for standard room dimensions and reflectance combinations. Based on CIE 117:1995 and CIE 190:2010 methods.

pub fn candela_tabulation(ldt: &Eulumdat) -> CandelaTabulation

Generate candela tabulation data for reports.

Returns absolute candela values at each angle, suitable for inclusion in photometric reports (similar to Photometric Toolbox format).

impl PhotometricCalculations

pub fn beam_angle_for_plane(ldt: &Eulumdat, c_plane: f64) -> f64

Calculate beam angle (50% intensity) for a specific C-plane.

Returns the full angle per CIE S 017:2020 definition.

pub fn field_angle_for_plane(ldt: &Eulumdat, c_plane: f64) -> f64

Calculate field angle (10% intensity) for a specific C-plane.

Returns the full angle per CIE S 017:2020 definition.

pub fn half_beam_angle_for_plane(ldt: &Eulumdat, c_plane: f64) -> f64

Calculate half beam angle for a specific C-plane.

Returns the half angle from nadir to 50% intensity point.

pub fn half_field_angle_for_plane(ldt: &Eulumdat, c_plane: f64) -> f64

Calculate half field angle for a specific C-plane.

Returns the half angle from nadir to 10% intensity point.

pub fn luminaire_luminance(ldt: &Eulumdat, viewing_angle: f64) -> f64

Calculate luminaire luminance at a given viewing angle (cd/m²).

L = I / A_projected Where A_projected is the luminous area projected in viewing direction.

pub fn cut_off_angle(ldt: &Eulumdat) -> f64

Calculate cut-off angle (where intensity drops below 2.5% of maximum).

pub fn ugr_table_values(ldt: &Eulumdat) -> Option<UgrTableValues>

Calculate UGR table values for standard room configuration.

Standard configuration: 4H×8H room, reflectances 0.70/0.50/0.20

pub fn photometric_code(ldt: &Eulumdat) -> String

Generate photometric classification code.

Format: D/I where:

• D = Distribution type (1=direct, 2=semi-direct, 3=general diffuse, 4=semi-indirect, 5=indirect)
• I = Intensity class based on max intensity

impl PhotometricCalculations

pub fn nema_classification(ldt: &Eulumdat) -> NemaClassification

Classify a luminaire according to NEMA floodlight beam types.

Scans the horizontal plane (V=0) and vertical plane (H=0) in Type B coordinates at 0.5° steps, finding where intensity drops below 10% of the peak intensity.