### Install with Dev Dependencies using uv

Source: https://github.com/jrkerns/pylinac/blob/master/AGENTS.md

Use this command to install the project with development dependencies. Ensure you are in the project's root directory.

```bash
uv pip install -e ".[developer]"
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/developer.md

Build the documentation and start a local web server to view it. Changes to documentation files will auto-reload.

```bash
uv run nox -s serve_docs
```

--------------------------------

### Install Python Versions with uv

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/developer.md

Use uv to install specific Python versions for testing or development. Ensure uv is installed globally.

```bash
# install Python 3.11
uv python install 3.11

# or install older versions of Python
uv python install 3.10
```

--------------------------------

### Run Field Analysis Demo

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/field_analysis.md

Import the main class and run the demo method to see an example of field analysis output.

```text
Field Analysis Results
----------------------
File: E:\OneDrive - F...demo_files\flatsym_demo.dcm
Protocol: VARIAN
Centering method: Beam center
Normalization method: Beam center
Interpolation: Linear
Edge detection method: Inflection Derivative

Penumbra width (20/80):
Left: 2.7mm
Right: 3.0mm
Top: 3.9mm
Bottom: 2.8mm

Field Size:
Horizontal: 140.9mm
Vertical: 200.3mm

CAX to edge distances:
CAX -> Top edge: 99.8mm
CAX -> Bottom edge: 100.5mm
CAX -> Left edge: 60.4mm
CAX -> Right edge: 80.5mm

Top slope: -0.006%/mm
Bottom slope: 0.044%/mm
Left slope: 0.013%/mm
Right slope: 0.014%/mm

Protocol data:
--------------
Vertical symmetry: -2.631%
Horizontal symmetry: -3.006%

Vertical flatness: 1.700%
Horizontal flatness: 1.857%
```

--------------------------------

### Install pylinac using pip

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/installation.md

Use this command to install the pylinac library if you already have Python set up.

```bash
$ pip install pylinac
```

--------------------------------

### Starshot Demo Output Example

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/general_tips.md

Example of the console output when running the Starshot demo, showing analysis results like minimum circle diameter and center coordinates.

```text
Result: PASS

The minimum circle that touches all the star lines has a diameter of 0.434 mm.

The center of the minimum circle is at 1270.1, 1437.1
```

--------------------------------

### Sync Dependencies with uv

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/developer.md

After cloning the repository, use uv sync to install all necessary development dependencies within your virtual environment.

```bash
# in your cloned directory of pylinac
uv sync
```

--------------------------------

### Run Starshot Demo

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/general_tips.md

Instantiate the Starshot class and run its demonstration method to see an example analysis. This will print information to the console and display an analyzed image.

```python
starshot = Starshot()
starshot.run_demo()
```

--------------------------------

### Run Picket Fence Demo

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/picketfence.md

Execute the Picket Fence demo to see analysis results printed to the console and a figure pop up. No setup is required beyond importing the class.

```python
from pylinac import PicketFence

PicketFence.run_demo()
```

--------------------------------

### CloudFileMixin Example

Source: https://github.com/jrkerns/pylinac/blob/master/tests_basic/AGENTS.md

Demonstrates how to use the CloudFileMixin to automatically download and resolve local paths for files stored in a cloud repository. Set `dir_path` and `file_name`, then call `get_filename()`.

```python
class MyTest(CloudFileMixin, TestCase):
    dir_path = ["Starshot"]
    file_name = "Starshot-1.tif"
```

--------------------------------

### Start Pylinac GUI

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/changelog.md

Run the Pylinac GUI application. This can be done programmatically or via the command line.

```python
import pylinac

pylinac.gui()
```

```bash
pylinac gui
```

--------------------------------

### Load CatPhan504 from demo images

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/cbct.md

Initialize a CatPhan504 object using the demo images provided with the pylinac library. Useful for testing and examples.

```python
mycbct = CatPhan504.from_demo_images()
```

--------------------------------

### Global Disk Locator Example

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/topics/image_metrics.md

Use GlobalDiskLocator to search the entire image for disks or BBs, useful when their location is unknown or variable. Requires specifying radius and tolerance.

```python
from pylinac.core.image import XIM
from pylinac.metrics.image import GlobalDiskLocator

img = XIM("my_image.xim")
bbs = img.compute(
    metrics=GlobalDiskLocator(
        radius_mm=3.5,
        radius_tolerance_mm=1.5,
        min_number=10,
    )
)
img.plot()
```

--------------------------------

### Get BB Shift Instructions for Winston-Lutz

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/changelog.md

Retrieve instructions for shifting the BB to the determined iso for iterative Winston-Lutz testing. Load demo images to initialize.

```python
import pylinac

wl = pylinac.WinstonLutz.from_demo_images()
print(wl.bb_shift_instructions())
# output: RIGHT 0.29mm; DOWN 0.04mm; OUT 0.41mm
# shift BB and run it again...
```

--------------------------------

### Disk ROI Metric Example (Physical Units)

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/topics/image_metrics.md

Use the `from_physical` class method of DiskROIMetric to define a circular ROI using physical units (mm). This enables sampling based on physical radius and center coordinates.

```python
roi: DiskROI = img.compute(
    metrics=DiskROIMetric.from_physical(
        radius_mm=10,
        center_mm=(70, 80),
    )
)
```

--------------------------------

### Load Planar Image from Demo Data

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/planar_imaging.md

Load a sample planar image provided with pylinac using the from_demo_image() class method. Useful for testing and examples.

```python
leeds = LeedsTOR.from_demo_image()
```

--------------------------------

### Global Sized Field Locator Example (Physical Units)

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/topics/image_metrics.md

Use the `from_physical` class method of GlobalSizedFieldLocator to find fields using physical units (mm). This is an alternative to pixel-based location when physical dimensions are known.

```python
img = DicomImage("my_image.dcm")
img.compute(
    metrics=GlobalSizedFieldLocator.from_physical(
        field_width_mm=30, field_height_mm=30, field_tolerance_mm=4, max_number=2
    )
)
```

--------------------------------

### Activate Anaconda Environment

Source: https://github.com/jrkerns/pylinac/wiki/Advice-on-running-pylinac-with-Anaconda

Activate the newly created 'py34' environment to start using it. This command prepares the environment for subsequent installations and commands.

```bash
activate py34
```

--------------------------------

### Get Low-Contrast ROI Contrast

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/planar_imaging.md

Retrieve the contrast value of a specific low-contrast ROI from an analyzed Leeds TOR phantom. ROI indexing starts at 1.

```python
leeds = LeedsTOR(...)
leeds.analyze(...)
print(leeds.low_contrast_rois[1].contrast)  # get the 2nd ROI contrast value
```

--------------------------------

### Install pylinac using Conda

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/changelog.md

Add the jrkerns channel to your conda configuration and then install or upgrade pylinac using the conda install command.

```bash
$ conda config --add channels jrkerns
```

```bash
$ conda install pylinac
```

--------------------------------

### Check Pylinac Installation

Source: https://github.com/jrkerns/pylinac/wiki/Advice-on-running-pylinac-with-Anaconda

Verify that pylinac has been successfully installed in the current conda environment. This command lists all installed packages in the active environment.

```bash
conda list
```

--------------------------------

### Basic Profile Analysis with FWXMProfile

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/topics/profiles.md

Demonstrates how to instantiate and use the FWXMProfile class to find the field center, edges, and width, and to plot the profile. Use the `...Physical` variants for physical data sources.

```python
from pylinac.core.profile import FWXMProfile

profile = FWXMProfile(..., fwxm_height=50)
print(profile.center_idx)  # print the center of the field position
print(profile.field_edge_idx(side="left"))  # print the left field edge position
print(profile.field_width_px)  # print the field width in pixels
profile.plot()  # plot the profile
```

--------------------------------

### Build HTML Documentation with uv and nox

Source: https://github.com/jrkerns/pylinac/blob/master/AGENTS.md

Build the project's HTML documentation using uv and nox. This command generates static HTML files for the documentation.

```bash
uv run nox -s build_docs
```

--------------------------------

### Winston-Lutz Analysis Output Example

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/winston_lutz.md

Example of the console output from a Winston-Lutz analysis, including distances, shifts, and isocenter diameters.

```text
Winston-Lutz Analysis
=================================
Number of images: 17
Maximum 2D CAX->BB distance: 1.23mm
Median 2D CAX->BB distance: 0.69mm
Shift to iso: facing gantry, move BB: RIGHT 0.36mm; OUT 0.36mm; DOWN 0.20mm
Gantry 3D isocenter diameter: 1.05mm (9/17 images considered)
Maximum Gantry RMS deviation (mm): 1.03mm
Maximum EPID RMS deviation (mm): 1.31mm
Gantry+Collimator 3D isocenter diameter: 1.11mm (13/17 images considered)
Collimator 2D isocenter diameter: 1.09mm (7/17 images considered)
Maximum Collimator RMS deviation (mm): 0.79
Couch 2D isocenter diameter: 2.32mm (7/17 images considered)
Maximum Couch RMS deviation (mm): 1.23
```

--------------------------------

### Build PDF Documentation with uv and nox

Source: https://github.com/jrkerns/pylinac/blob/master/AGENTS.md

Build the project's documentation in PDF format using uv and nox. This command is used for generating printable documentation.

```bash
uv run nox -s build_docs_pdf
```

--------------------------------

### Install Pylinac in Conda Environment

Source: https://github.com/jrkerns/pylinac/wiki/Advice-on-running-pylinac-with-Anaconda

Install pylinac using pip within the activated Python 3.4 environment. Ensure the environment is active before running this command.

```bash
pip install pylinac
```

--------------------------------

### Import GEHeliosCTDaily Class

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/helios.md

Import the necessary class to start using the Helios analysis.

```python
from pylinac import GEHeliosCTDaily
```

--------------------------------

### Instantiate PicketFence with Image Keyword Args

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/changelog.md

Pass image keyword arguments during instantiation for images lacking basic DICOM tags like DPI or SID. This is useful for images that require manual metadata.

```python
from pylinac import PicketFence

path = ...  # very sad image that has no DICOM tags for DPI or SID
pf = PicketFence(path, image_kwargs={"dpi": 184, "sid": 1500})
pf.analyze()
...
```

--------------------------------

### Export Results to JSON

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/topics/exporting_results.md

Use the `results_data(to_json=True)` method to get a JSON string of the analysis data. This string can then be saved to a file.

```python
from pylinac import Starshot

star = Starshot.from_zip("myzip.zip")
star.analyze()
json_str = star.results_data(
    to_json=True
)  # dumps to a string that can be loaded by any JSON reader
with open("my_starshot.json", "w") as f:
    f.write(json_str)
```

--------------------------------

### Instantiate Catphan with List of Paths

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/changelog.md

The Catphan module can now accept a list of image paths during instantiation, allowing for analysis of multiple images at once.

```python
Catphan504([path1, path2, path3, ...])
```

--------------------------------

### Load Demo Image

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/field_analysis.md

Load a pre-existing demo image for testing or demonstration purposes.

```python
my_img = FieldAnalysis.from_demo_image()
```

--------------------------------

### Get BB Shift Instructions

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/winston_lutz.md

Retrieve instructions for shifting the BB based on the analysis results. This can be done with or without providing couch coordinates.

```python
print(wl.bb_shift_instructions())
# LEFT: 0.1mm, DOWN: 0.22mm, ...
print(wl.bb_shift_instructions(couch_vrt=0.41, couch_lng=96.23, couch_lat=0.12))
# New couch coordinates (mm): VRT: 0.32; LNG: 96.11; LAT: 0.11
```

--------------------------------

### Create Custom Simulator

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/image_generator.md

Inherit from Simulator and define pixel_size and shape to create a custom simulator.

```python
from pylinac.core.image_generator.simulators import Simulator


class AS5000(Simulator):
    pixel_size = 0.12
    shape = (5000, 5000)


# use like any other simulator
```

--------------------------------

### CatPhan Instantiation with Classifier

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/changelog.md

Shows how to enable the classifier during CatPhan object instantiation, moving the 'use_classifier' parameter from the analyze method.

```default
from pylinac import CatPhan504
cat504 = CatPhan504('my/folder', use_classifier=True)
cat504.analyze()  # no classifier argument
```

--------------------------------

### Get VMAT Results as Dictionary

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/vmat_docs.md

Retrieve the results of a VMAT analysis, such as DRGS, in a dictionary format for easy access to specific test types.

```python
data_dict = my_drgs.results_data(as_dict=True)
data_dict["test_type"]
```

--------------------------------

### Initialize and Analyze Las Vegas Phantom

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/changelog.md

Example of how to use the Las Vegas phantom class for analysis. Ensure the DICOM file is correctly specified.

```python
from pylinac import LasVegas

lv = LasVegas("myfile.dcm")
lv.analyze()
lv.publish_pdf()
...
```

--------------------------------

### Initialize PlanGenerator

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/plan_generator.md

Initialize the PlanGenerator from an existing RT Plan file. Requires the file path and plan details.

```python
from pylinac.plan_generator.dicom import PlanGenerator

path = r"path/to/my/rtplan.dcm"
pg = PlanGenerator.from_rt_plan_file(path, plan_label="MyQA", plan_name="QA")
```

--------------------------------

### Loosen ROI Finding Conditions

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/planar_imaging.md

Customize ROI detection by overriding default conditions. This example loosens the size constraint for Leeds TOR phantoms.

```python
from pylinac.planar_imaging import is_right_size, is_centered, LeedsTOR

def is_right_size_loose(region, instance, rtol=0.3):  # rtol default is 0.1
    return is_right_size(region, instance, rtol)


# set the new condition for whatever
LeedsTOR.detection_conditions = [is_right_size_loose, is_centered]
# proceed as normal
myleeds = LeedsTOR(...)
```

--------------------------------

### Load Winston-Lutz Images from Directory

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/winston_lutz.md

Initialize the WinstonLutz object by providing the path to a directory containing the test images.

```python
my_directory = "path/to/wl_images"
wl = WinstonLutz(my_directory)
```

--------------------------------

### Planar Phantom Analysis Examples

Source: https://github.com/jrkerns/pylinac/blob/master/README.rst

Analyze images from various planar phantoms for quality assurance. Supports automatic phantom localization and contrast determination.

```python
from pylinac import LeedsTOR, StandardImagingQC3, LasVegas, DoselabMC2kV, DoselabMC2MV

leeds = LeedsTOR("my_leeds.dcm")
leeds.analyze()
leeds.plot_analyzed_image()
leeds.publish_pdf()

qc3 = StandardImagingQC3("my_qc3.dcm")
qc3.analyze()
qc3.plot_analyzed_image()
qc3.publish_pdf("qc3.pdf")

lv = LasVegas("my_lv.dcm")
lv.analyze()
lv.plot_analyzed_image()
lv.publish_pdf("lv.pdf", open_file=True)  # open the PDF after publishing

...
```

--------------------------------

### Subclass ImagePhantomBase for Custom Phantom

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/planar_imaging.md

Start by creating a new class that inherits from pylinac's ImagePhantomBase. This provides a foundation for custom phantom analysis.

```python
from pylinac.planar_imaging import ImagePhantomBase


class CustomPhantom(ImagePhantomBase):
    pass
```

--------------------------------

### Multi-Axis Winston-Lutz Analysis

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/winston_lutz.md

Perform a multi-axis Winston-Lutz analysis with offset BB for visualization. This setup accounts for varying gantry, collimator, and couch values.

```python
from pylinac.core.geometry import Point
from pylinac.core.image import Image
from pylinac.core.utilities import results_to_yaml
from pylinac.winston_lutz import WinstonLutz

# Create dummy images
images = []
for _ in range(8):
    img = Image.from_array(np.zeros((100, 100)))
    img.pixel_spacing = (1, 1)
    img.center_of_mass = Point(50, 50)
    img.field_size = 10
    img.dvh = None
    images.append(img)

# Offset the BB in the first image
images[0].catheter_center = Point(48, 50)

# Create Winston-Lutz object
wl = WinstonLutz()

# Add images
for img in images:
    wl.add_image(img)

# Analyze
wl.analyze()

# Print results
print(wl.results())
```

--------------------------------

### Analyze with RMS Contrast Method

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/changelog.md

Demonstrates how to use the new Root-mean-square (RMS) contrast method during image analysis. Ensure the Contrast class is imported.

```python
leeds.analyze(..., contrast_method=Contrast.RMS)
```

--------------------------------

### Analyze Picket Fence Demo and Publish PDF

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/picketfence.md

Load the demo data, perform the analysis, and generate a PDF report. This is useful for saving and sharing the analysis results.

```python
pf = PicketFence.from_demo()
pf.analyze()
pf.publish_pdf(filename="PF Oct-2018.pdf")
```

--------------------------------

### FFF Beam Analysis Results Example

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/field_analysis.md

When analyzing FFF beams, specific metrics like 'Top' position and field slopes are calculated and displayed in the results.

```text
'Top' vertical distance from CAX: 1.3mm
'Top' horizontal distance from CAX: 0.6mm
'Top' vertical distance from beam center: 1.7mm
'Top' horizontal distance from beam center: 0.3mm
```

--------------------------------

### Upload Wheel to PyPI with nox

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/developer.md

Upload the built wheel package to PyPI using the nox upload_wheel session. Requires appropriate credentials.

```bash
uv run nox -s upload_wheel
```

--------------------------------

### Import PicketFence Class

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/picketfence.md

Import the PicketFence class from the pylinac library to begin.

```python
from pylinac import PicketFence
```

--------------------------------

### Compute Profile Metrics with FWXMProfile

Source: https://context7.com/jrkerns/pylinac/llms.txt

Use FWXMProfile to compute metrics like penumbra, flatness, and symmetry from 1D image profiles. Requires importing specific metric classes and initializing FWXMProfile with image data and dpmm.

```python
from pylinac import image
from pylinac.core.profile import FWXMProfile
from pylinac.metrics.profile import (
    PenumbraLeftMetric,
    PenumbraRightMetric,
    FlatnessDifferenceMetric,
    SymmetryAreaMetric,
)

img = image.load("path/to/field.dcm")
row = img.shape[0] // 2
prof = FWXMProfile(img.array[row, :], dpmm=img.dpmm)

results = prof.compute(
    metrics=[
        PenumbraLeftMetric(upper=80, lower=20),
        PenumbraRightMetric(upper=80, lower=20),
        FlatnessDifferenceMetric(),
        SymmetryAreaMetric(),
    ]
)

for name, value in results.items():
    print(f"{name}: {value:.3f}")
# e.g.:
# PenumbraLeft: 3.2
# PenumbraRight: 3.4
# FlatnessDifference: 1.7
# SymmetryArea: -0.3
```

--------------------------------

### FFF Beam Slope Analysis Results Example

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/field_analysis.md

The results for FFF beams include the slopes of each side of the field, calculated between field edges and the slope exclusion ratio.

```text
Top slope: 0.292%/mm
Bottom slope: -0.291%/mm
Left slope: 0.295%/mm
Right slope: -0.296%/mm
```

--------------------------------

### Load Trajectory Log from Demo Data

Source: https://github.com/jrkerns/pylinac/blob/master/docs/source/general_tips.md

Instantiate TrajectoryLog using the `from_demo` class method to load a sample dataset for experimentation when no actual data is available.

```python
tlog = TrajectoryLog.from_demo()
```