Metadata-Version: 2.1
Name: photompy
Version: 0.1.6
Summary: A library for reading, writing, and viewing photometric files.
Home-page: https://github.com/jvbelenky/photompy
Author: J. Vivian Belenky
Author-email: j.vivian.belenky@outlook.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: matplotlib

PhotomPy: Photometric Python
===========================
A library for reading, writing, and viewing photometric files.

<!-- Installation -->
## Installation

Install with pip:

	pip install photompy

Alternatively, clone the repo and build locally:

	git clone https://github.com/jvbelenky/photompy.git
    cd photompy
    python setup.py sdist
    pip install .


<!-- USAGE EXAMPLES -->
## Usage

### Modern API (Recommended)

The recommended way to work with IES files is through the `IESFile` class:

```python
from photompy import IESFile

# Read an IES file
ies = IESFile.read("lamp.ies")

# Access photometry data
print(ies.photometry.thetas)  # vertical angles
print(ies.photometry.phis)    # horizontal angles
print(ies.photometry.values)  # candela values

# Calculate total optical power
power = ies.photometry.total_optical_power()

# Get intensity at specific angles
intensity = ies.photometry.get_intensity(theta=45, phi=0)

# Plot the photometry
fig, ax = ies.plot(plot_type="polar")
fig, ax = ies.plot(plot_type="cartesian", elev=45, azim=30)

# Scale values
ies.scale_to_max(5000)           # Scale to max candela value
ies.scale_to_total(1000)         # Scale to total power
ies.scale_to_center(2500)        # Scale to center intensity
ies.scale(2.0)                   # Scale by factor

# Write to file
ies.write("output.ies")                    # Write original angles
ies.write("output.ies", which="full")      # Write expanded angles
ies.write("output.ies", which="interp")    # Write interpolated angles

# Access header information
print(ies.header.units)           # FEET or METERS
print(ies.header.width)           # luminous width
print(ies.header.length)          # luminous length
print(ies.header.input_watts)     # input watts
```

### Legacy API (Deprecated)

The following functions are still available but deprecated. They will emit deprecation warnings:

```python
from photompy import read_ies_data, write_ies_data, total_optical_power, plot_ies

# These still work but will warn
lampdict = read_ies_data(filename)
power = total_optical_power(filename)
fig, ax = plot_ies(filename)
```

See `docs/migration.md` for a complete guide on migrating from the legacy API.

### Working with Photometry Directly

For advanced use cases, you can work with the `Photometry` class directly:

```python
from photompy import IESFile

ies = IESFile.read("lamp.ies")
phot = ies.photometry

# Get expanded (mirrored) photometry
expanded = phot.expanded()

# Get interpolated photometry
interpolated = phot.interpolated(num_thetas=361, num_phis=721)
```

### Simple calculations

```python
from photompy import total_optical_power, lamp_area

power = total_optical_power(filename)
luminous_area = lamp_area(filename, units="meters")
```

### Writing files

To scale and write IES files:

```python
from photompy import scale_lamp_to_max, scale_lamp_to_total

# Scale to specific maximum value
scale_lamp_to_max(5000, "input.ies", "output.ies")

# Scale to specific total optical power
scale_lamp_to_total(1000, "input.ies", "output.ies")
```

<!-- ROADMAP -->
## Roadmap

- [x] PhotometricData and AngleData objects (IESFile and Photometry classes)
- [ ] Generate .ies files from an angular distribution table
- [x] Type A and B photometry support
- [ ] Dialux file (.ldt) support
- [ ] More extensive write support


<!-- LICENSE -->
## License

Distributed under the MIT License. See `LICENSE.txt` for more information.

<!-- CONTACT -->
## Contact

Vivian Belenky - jvb@osluv.org
