API Reference

This section complements the narrative component pages with a compact reference to the public package surface and the runtime/helper modules that users most often inspect while extending pyRTC.

Public Package Surface

Public package exports for pyRTC.

pyRTC provides the building blocks needed to assemble an adaptive-optics real- time controller in Python. The package root re-exports the main component base classes, orchestration helpers, shared-memory transport primitives, and logging utilities so users can build systems from a compact public API surface.

class pyRTC.ImageSHM(name, shape, dtype, gpuDevice=None, consumer=True)

Named shared-memory array with metadata and optional GPU mirror state.

ImageSHM is the transport primitive used throughout pyRTC. Each stream has a CPU shared-memory block, a small metadata block containing shape, dtype, and timing information, and optionally a GPU-backed tensor mirror in hard-RTC deployments where CUDA sharing is supported.

Producers create the stream and update it with NumPy arrays. Consumers reconstruct the stream by name and read either safe copies or direct views, depending on their performance and synchronization needs.

METADATA_SIZE = 10

checkNew()

close()

createGPUMemSHM()

hold(timeout=None, RELEASE_GIL=True)

initGPUMemFromSHM()

markSeen()

read(SAFE=True, GPU=False, RELEASE_GIL=True)

read_noblock(SAFE=True, GPU=False)

read_timeout(timeout, SAFE=True, GPU=False, RELEASE_GIL=True)

updateMetadata(FULL_UPDATE=False)

write(arr)

class pyRTC.Listener(hardware, port)

Server-side control socket for a launched hardware object.

Listener is the child-process counterpart to hardwareLauncher. It binds a localhost socket, accepts the RTC-side connection, and services a narrow JSON RPC surface for property access, method calls, and clean shutdown.

listen()

read()

write(message)

class pyRTC.Loop(conf)

Real-time controller that closes the adaptive optics loop.

Loop reads the current residual signal from the slopes pipeline, combines that signal with the calibrated control model, and writes the next correction vector to the wavefront-corrector stream. It also owns the operator-facing calibration state used to load or build interaction and control matrices and to tune classical integrator settings.

In day-to-day use, this is the component that embodies the chosen control law for the system.

Config

numDroppedModesint, optional

Number of modes to drop. Default is 0.

gainfloat, optional

Gain for the integrator. Default is 0.1.

leakyGainfloat, optional

Leaky integrator gain. Default is 0.0.

hardwareDelayfloat, optional

Delay for the hardware. Default is 0.0.

pokeAmpfloat, optional

Amplitude for poking. Default is 0.01.

numItersIMint, optional

Number of iterations for interaction matrix computation. Default is 100.

delayint, optional

Delay for corrections. Default is 0.

IMMethodstr, optional

Method for interaction matrix computation. Default is “push-pull”.

IMFilestr, optional

File to save the interaction matrix. Default is “”.

pGainfloat, optional

Proportional gain for PID integrator. Default is 0.1.

iGainfloat, optional

Integral gain for PID integrator. Default is 0.0.

dGainfloat, optional

Derivative gain for PID integrator. Default is 0.0.

controlLimitslist, optional

Control limits for PID integrator. Default is [-inf, inf].

integralLimitslist, optional

Integral limits for PID integrator. Default is [-inf, inf].

absoluteLimitslist, optional

Absolute limits for corrections. Default is [-inf, inf].

derivativeFilterfloat, optional

Filter for the derivative term. Default is 0.1.

Attributes

confdict

Loop configuration.

namestr

Name of the loop.

signalDTypetype

Data type of the wavefront sensor signal.

signalSizeint

Size of the wavefront sensor signal.

signalShmImageSHM

Shared memory object for the wavefront sensor signal.

nullSignalnumpy.ndarray

Null signal.

signal2DDTypetype

Data type of the 2D wavefront sensor signal.

signal2DSizeint

Size of the 2D wavefront sensor signal.

signal2D_widthint

Width of the 2D wavefront sensor signal.

signal2D_heightint

Height of the 2D wavefront sensor signal.

wfcDTypetype

Data type of the wavefront corrector.

numModesint

Number of modes in the wavefront corrector.

wfcShmImageSHM

Shared memory object for the wavefront corrector.

numDroppedModesint

Number of dropped modes.

numActiveModesint

Number of active modes.

flatnumpy.ndarray

Flat correction vector.

IMnumpy.ndarray

Interaction matrix.

CMnumpy.ndarray

Control matrix.

gainfloat

Gain for the integrator.

leakyGainfloat

Leaky integrator gain.

perturbAmpfloat

Perturbation amplitude.

hardwareDelayfloat

Delay for the hardware.

pokeAmpfloat

Amplitude for poking.

numItersIMint

Number of iterations for interaction matrix computation.

delayint

Delay for corrections.

IMMethodstr

Method for interaction matrix computation.

IMFilestr

File to save the interaction matrix.

pGainfloat

Proportional gain for PID integrator.

iGainfloat

Integral gain for PID integrator.

dGainfloat

Derivative gain for PID integrator.

controlLimitslist

Control limits for PID integrator.

integralLimitslist

Integral limits for PID integrator.

absoluteLimitslist

Absolute limits for corrections.

derivativeFilterfloat

Filter for the derivative term.

integralnumpy.ndarray

Integral term for PID integrator.

previousWfErrornumpy.ndarray

Previous wavefront error.

previousDerivativenumpy.ndarray

Previous derivative term.

controlOutputnumpy.ndarray

Control output.

computeCM()

Compute the control matrix from the interaction matrix.

computeIM()

Compute the interaction matrix using the specified method. Method specified using IMMethod, default is push-pull.

docrimeIM()

Compute the interaction matrix using the DOCRIME method.

flatten()

Send the flat correction to the wavefront corrector.

leakyIntegrator()

Leaky integrator.

loadIM(filename='')

Load the interaction matrix from a file.

Parameters

filenamestr, optional

File to load the interaction matrix from. If not specified, uses the configured IMFile.

pidIntegrator(slopes=None, correction=None)

PID integrator.

Parameters

slopesnumpy.ndarray, optional

Current slopes vector. If not provided, reads from shared memory.

correctionnumpy.ndarray, optional

Current correction vector. If not provided, reads from shared memory.

pidIntegratorPOL()

PID integrator using the pseudo-open loop slopes.

plotIM(row=None)

pushPullIM()

Compute the interaction matrix using the push-pull method.

saveIM(filename='')

Save the interaction matrix to a file.

Parameters

filenamestr, optional

File to save the interaction matrix to. If not specified, uses the configured IMFile.

sendToWfc(correction, slopes=None)

setGain(gain)

Set the integrator gain. Only needed for certain integrators.

Parameters

gainfloat

Gain to set.

setPeturbAmp(amp)

Set the perturbation amplitude.

Parameters

ampfloat

Amplitude to set.

solveDocrime()

standardIntegrator()

Standard integrator.

standardIntegratorPOL()

Standard integrator using the pseudo open loop slopes.

updateCorrectionPOL(correction=array([], dtype=float32), slopes=array([], dtype=float32))

Update the correction using pseudo open loop slopes.

Parameters

correctionnumpy.ndarray

Current correction vector.

slopesnumpy.ndarray

Current slopes vector.

Returns

numpy.ndarray

Updated correction vector.

class pyRTC.Modulator(conf)

Common lifecycle and positioning interface for modulator devices.

Concrete subclasses are expected to bind this abstract interface to a real hardware controller or simulator. The base class handles configuration and logging while subclasses implement the actual move/restart behavior.

New code should use set_position(); goTo() is retained as a compatibility alias for older call sites.

goTo(position)

abstractmethod restart()

Restart the modulator waveform or hardware state.

abstractmethod set_position(position)

Move the modulator to a requested position.

start()

Start the registered real-time functions.

stop()

Stops the registered real-time functions.

class pyRTC.Optimizer(conf)

Abstract Optuna-backed optimization driver.

Optimizer is meant to be subclassed by hardware- or algorithm-specific optimizers in pyRTC.hardware. The base class owns the Optuna study, default CMA-ES sampler choice, and the helper methods used to run a full study or advance one trial at a time.

Subclasses are responsible for defining the objective function and for applying candidate parameters to the system under test.

Attributes

namestr

Name of the optimizer component.

studyoptuna.Study

The Optuna study object, initialized with a CMA-ES sampler.

numStepsint

Number of steps/trials to perform during optimization.

Methods

objective():

Defines the objective function for the optimization.

optimize():

Performs the optimization process.

applyOptimum():

Applies the optimum values obtained from the optimization process.

applyTrial(trial):

Applies a given trial.

applyNext():

Requests and applies the next trial from the study.

applyNext()

Requests and applies the next trial from the study.

This method obtains the next trial from the study and applies it using the applyTrial method.

applyOptimum()

Applies the optimum values obtained from the optimization process.

This method should be implemented to apply the optimal parameters found during the optimization to the system or component.

applyTrial(trial)

Applies a given trial.

Parameters:

trial – The trial object containing the parameters to be applied.

objective()

Defines the objective function for the optimization.

This method should be overridden by subclasses to provide the specific objective function for the optimization task.

Returns:

The objective value to be optimized.

optimize()

Performs the optimization process.

This method runs the optimization process using the defined objective function and the number of steps specified in the configuration.

resetStudy()

class pyRTC.ScienceCamera(conf)

Base class for cameras that produce science images and image-quality metrics.

ScienceCamera centralizes the parts of imaging that are shared across real and synthetic science-camera backends: SHM publication, dark/model PSF handling, long-exposure accumulation, and simple Strehl/tip-tilt telemetry. Subclasses are expected to implement the device-facing acquisition logic and then call the parent methods so the standard pyRTC products stay updated.

Config

namestr

Name of the camera.

widthint

Width of the image. Required.

heightint

Height of the image. Required.

darkCountint

Number of dark frames to average. Required.

integrationint

Integration length. Required.

darkFilestr, optional

File to save the dark frames. Default is “”.

modelFilestr, optional

File to save the model PSF. Default is “”.

Attributes

namestr

Name of the camera.

imageShapetuple

Shape of the image.

imageRawDTypetype

Data type of the raw image.

imageDTypetype

Data type of the image.

psfLongDtypetype

Data type of the long exposure PSF.

psfShortImageSHM

Shared memory object for the short exposure PSF.

psfLongImageSHM

Shared memory object for the long exposure PSF.

strehlShmImageSHM

Shared memory object for the Strehl ratio.

tipTiltShmImageSHM

Shared memory object for the tip-tilt.

datanumpy.ndarray

Data array for the image.

darknumpy.ndarray

Dark frame.

darkCountint

Number of dark frames to average.

darkFilestr

File to save the dark frames.

modelnumpy.ndarray

Model PSF.

modelFilestr

File to save the model PSF.

strehl_ratiofloat

Strehl ratio.

peak_distfloat

Peak distance.

integrationLengthint

Integration length.

roiWidthint

Width of the region of interest.

roiHeightint

Height of the region of interest.

roiLeftint

Left coordinate of the region of interest.

roiTopint

Top coordinate of the region of interest.

exposureint

Exposure time.

binningint

Binning factor.

gainint

Gain setting.

bitDepthint

Bit depth setting.

computeStrehl(median_filter_size=1, gaussian_sigma=0)

Compute the rough Strehl ratio and tip tilt offset. These values are reference to the modelPSF. If your model PSF is taken empirically, then the Strehl ratio is not absolute, and should only be used as a relative measurement for focal plane feedback.

Parameters

median_filter_sizeint, optional

Size of the median filter to apply. Default is 1.

gaussian_sigmafloat, optional

Sigma for the Gaussian filter. Default is 0.

Returns

float

Strehl ratio.

expose()

Perform a single exposure.

integrate()

Perform multiple exposures and integrate the results. Number of frames set by integrationLength.

loadDark(filename='')

Load the dark frame from a file.

Parameters

filenamestr, optional

File to load the dark frame from. If not specified, uses the configured darkFile.

loadModelPSF(filename='')

Load the model PSF from a file.

Parameters

filenamestr, optional

File to load the model PSF from. If not specified, uses the configured modelFile.

plot()

Plot the current short exposure PSF.

read(block=True)

Read the current short exposure PSF.

Returns

numpy.ndarray

Current short exposure PSF.

readLong()

Read the current long exposure PSF.

Returns

numpy.ndarray

Current long exposure PSF.

saveDark(filename='')

Save the dark frame to a file.

Parameters

filenamestr, optional

File to save the dark frame to. If not specified, uses the configured darkFile.

saveModelPSF(filename='')

Save the model PSF to a file.

Parameters

filenamestr, optional

File to save the model PSF to. If not specified, uses the configured modelFile.

setBinning(binning)

Set the binning factor.

Parameters

binningint

Binning factor to set.

setBitDepth(bitDepth)

Set the bit depth.

Parameters

bitDepthint

Bit depth to set.

setDark(dark)

Set the dark frame.

Parameters

darknumpy.ndarray

Dark frame to set.

setExposure(exposure)

Set the exposure time.

Parameters

exposureint

Exposure time to set.

setGain(gain)

Set the gain.

Parameters

gainint

Gain to set.

setGamma(gamma)

Set the gamma.

Parameters

gammafloat

Gamma to set.

setIntegrationLength(integrationLength)

Set the integration length.

Parameters

integrationLengthint

Integration length to set.

setModelPSF(model)

Set the model PSF.

Parameters

modelnumpy.ndarray

Model PSF to set.

setRoi(roi)

Set the region of interest (ROI).

Parameters

roituple

Tuple containing (width, height, left, top) of the ROI.

takeDark()

Take dark frames and average them to create a dark frame. Number of exposures to average set by darkCount parameter.

takeModelPSF()

Capture the current long exposure PSF as the model PSF.

class pyRTC.SlopesProcess(conf)

A class to handle real-time slope computation for wavefront sensors.

Config

typestr

Type of the WFS (“PYWFS” or “SHWFS”).

signalTypestr

Type of signal (“slopes”).

imageNoisefloat, optional

Image noise. Default is 0.0.

centralObscurationRatiofloat, optional

Central obscuration ratio. Default is 0.0.

flatNormfloat, optional

Normalization factor for the flat. Required for “PYWFS” with “slopes” signalType.

pupilslist of str, optional

List of pupil locations in “x,y” format. Required for “PYWFS”.

pupilsRadiusint, optional

Radius of the pupils. Required for “PYWFS”.

contrastfloat, optional

Contrast for “SHWFS”. Default is 0.

subApSpacingfloat, optional

Sub-aperture spacing for “SHWFS”.

subApOffsetXfloat, optional

Sub-aperture offset in X direction for “SHWFS”.

subApOffsetYfloat, optional

Sub-aperture offset in Y direction for “SHWFS”.

refSlopeCountint, optional

Number of reference slopes for averaging. Default is 1000.

validSubApsFilestr, optional

File containing valid sub-aperture mask. Default is “”.

refSlopesFilestr, optional

File containing reference slopes. Default is “”.

Attributes

confWFSdict

Wavefront sensor configuration.

namestr

Name of the process.

imageShapetuple

Shape of the WFS image.

confdict

Slopes configuration.

wfsMetanumpy.ndarray

Metadata of the WFS image.

imageDTypetype

Data type of the WFS image.

wfsShmImageSHM

Shared memory object for the WFS image.

signalDTypetype

Data type of the signal.

imageNoisefloat

Image noise.

centralObscurationRatiofloat

Central obscuration ratio.

wfsTypestr

Type of the WFS.

signalTypestr

Type of signal.

validSubApsnumpy.ndarray or None

Valid sub-aperture mask.

shwfsContrastfloat

Contrast for “SHWFS”.

subApSpacingfloat

Sub-aperture spacing for “SHWFS”.

numRegionsint

Number of regions for “SHWFS”.

offsetXfloat

Sub-aperture offset in X direction for “SHWFS”.

offsetYfloat

Sub-aperture offset in Y direction for “SHWFS”.

refSlopeCountint

Number of reference slopes for averaging.

signal2DSizeint

Size of the 2D signal.

signal2DShapetuple

Shape of the 2D signal.

validSubApsFilestr

File containing valid sub-aperture mask.

signalSizeint

Size of the signal.

signalShapetuple

Shape of the signal.

signalImageSHM

Shared memory object for the signal.

signal2DImageSHM

Shared memory object for the 2D signal.

refSlopesFilestr

File containing reference slopes.

refSlopesnumpy.ndarray

Reference slopes.

gpuDevicestr

Default device if using GPU

flatNormfloat

Normalization factor for the flat.

pupilLocslist of tuple

List of pupil locations.

pupilRadiusint

Radius of the pupils.

pupilMasknumpy.ndarray

Mask of the pupils.

p1masknumpy.ndarray

Mask for pupil 1.

p2masknumpy.ndarray

Mask for pupil 2.

p3masknumpy.ndarray

Mask for pupil 3.

p4masknumpy.ndarray

Mask for pupil 4.

computeImageNoise()

Compute the image noise. Useful to set a good SNR cutoff for SHWFS

computePupilsMask()

Compute the mask for the pupils. Assumes circular aperture with obstruction ratio set by the centralObscurationRatio parameter.

computeSignal()

Compute the signal from the WFS image.

computeSignal2D(signal, validSubAps=None)

Compute the 2D signal from the valid sub-aperture mask.

Parameters

signalnumpy.ndarray

Signal to process.

validSubApsnumpy.ndarray, optional

Valid sub-aperture mask. If not provided, uses the current valid sub-aperture mask.

Returns

numpy.ndarray

2D signal.

loadRefSlopes(filename='')

Load the reference slopes from a file.

Parameters

filenamestr, optional

File to load the reference slopes from. If not specified, uses the configured refSlopesFile.

loadValidSubAps(filename='')

Load the valid sub-aperture mask from a file.

Parameters

filenamestr, optional

File to load the valid sub-aperture mask from. If not specified, uses the configured validSubApsFile.

plotPupils()

Plot the pupil mask to see if its right.

read(block=True, SAFE=True, GPU=False)

Read the current signal.

Returns

numpy.ndarray

Current signal.

readImage(SAFE=True, GPU=False, block=True)

Read the current WFS image.

Returns

numpy.ndarray

Current WFS image.

saveRefSlopes(filename='')

Save the reference slopes to a file.

Parameters

filenamestr, optional

File to save the reference slopes to. If not specified, uses the configured refSlopesFile.

saveValidSubAps(filename='')

Save the valid sub-aperture mask to a file.

Parameters

filenamestr, optional

File to save the valid sub-aperture mask to. If not specified, uses the configured validSubApsFile.

setPupils(pupilLocs, pupilRadius)

Set the pupils’ locations and radius. First computes a Pupil Mask, then generates slope mask and sets up SHMS of the correct sizes.

Parameters

pupilLocslist of tuple

List of pupil locations.

pupilRadiusint

Radius of the pupils.

setRefSlopes(refSlopes)

Set the reference slopes.

Parameters

refSlopesnumpy.ndarray

Reference slopes.

setValidSubAps(validSubAps)

Set the valid sub-aperture mask. Converts to boolean if not already

Parameters

validSubApsnumpy.ndarray

Valid sub-aperture mask.

takeRefSlopes()

Take reference slopes by averaging multiple slope measurements. Number of measurements set by refSlopeCount variable.

class pyRTC.Telemetry(conf)

Persist a bounded capture from an existing pyRTC stream.

Telemetry attaches to named shared-memory streams that are already being produced elsewhere in the running RTC, writes a configurable number of frames to disk, and keeps enough bookkeeping to reconstruct known captures with the correct dtype and dimensions later.

Typical uses include saving wavefront sensor frames, residual signals, or command vectors during tuning and diagnostics.

read(filename='', dtype=None)

save(shmName, numFrames, uniqueStr='')

class pyRTC.WavefrontCorrector(conf)

Base class for deformable mirrors and other wavefront-correction devices.

WavefrontCorrector is responsible for the control-plane machinery around command generation: SHM output, flat shapes, mode-to-command transforms, floating actuator handling, and delayed command buffers. Subclasses are left to implement the device-specific transport in sendToHardware.

Config

namestr

Name of the wavefront corrector.

numActuatorsint

Number of actuators. Required.

numModesint

Number of modes. Required.

affinitystr

Affinity setting.

m2cFilestr

Path to the mode-to-command file.

floatingInfluenceRadiusint, optional

Radius for floating influence. Default is 1.

frameDelayint, optional

Frame delay. Default is 0.

saveFilestr, optional

File to save the shape. Default is “wfcShape.npy”.

Attributes

namestr

Name of the wavefront corrector.

numActuatorsint

Number of actuators.

numModesint

Number of modes.

affinitystr

Affinity setting.

m2cFilestr

Path to the mode-to-command file.

correctionVectorImageSHM

Correction vector.

correctionVector2DImageSHM or None

2D correction vector for display.

flatnumpy.ndarray

Initial flat shape.

flatModalnumpy.ndarray

Flat shape in modal basis.

currentShapenumpy.ndarray

Current shape.

actuatorStatusnumpy.ndarray

Status of each actuator.

index_mapnumpy.ndarray or None

Index map for actuators.

floatingInfluenceRadiusint

Radius for floating influence.

floatMatrixnumpy.ndarray

Floating actuator matrix.

frameDelayint

Frame delay.

saveFilestr

File to save the shape.

layoutnumpy.ndarray or None

Layout of the actuators.

M2Cnumpy.ndarray

Mode-to-command matrix.

f_M2Cnumpy.ndarray

Floating mode-to-command matrix.

C2Mnumpy.ndarray

Command-to-mode matrix.

currentCorrectionnumpy.ndarray

Current correction vector.

shapeBuffernumpy.ndarray

Buffer for shapes with frame delay.

correctionVector2D_templatenumpy.ndarray

Template for the 2D correction vector.

deactivateActuators(actuators)

Deactivate specified actuators. Actuators are assumed to be floating

Parameters

actuatorslist of int

List of actuator indices to deactivate.

flatten()

Flatten the wavefront corrector.

loadFlat(filename='')

Loads the Flat from a file.

Parameters

filenamestr, optional

Filename to load the dark frame from. If not specified, uses the dark file path from the configuration.

plot(addFlat=False)

Plot the current correction.

Parameters

removeFlatbool, optional

If True, removes the flat shape from the current correction before plotting. Default is False.

push(mode, amp)

Push a specific mode with a given amplitude.

Parameters

modeint

Mode index to push.

ampfloat

Amplitude to push the mode with.

reactivateActuators(actuators)

Reactivate specified actuators.

Parameters

actuatorslist of int

List of actuator indices to reactivate.

read(block=False)

Read the current correction vector.

Returns

numpy.ndarray

Current correction vector.

readM2C(filename='')

Read the mode-to-command matrix from a file.

Parameters

filenamestr, optional

File to read the mode-to-command matrix from. If not specified, uses the configured m2cFile.

saveShape(filename='')

Save the current shape to a file.

Parameters

filenamestr, optional

File to save the shape to. If not specified, uses the configured saveFile.

sendToHardware()

Send the current correction to the hardware. Nominally, this function is overwritten by the child hardware class and registered to the real-time loop from the config.

setDelay(delay)

Sets an artificial frame delay. Used for testing, nominally the delay should always be zero.

Parameters

delayint

Frame delay to set.

setFlat(flat)

Set the flat shape.

Parameters

flatnumpy.ndarray

Flat shape to set.

setLayout(layout)

Set the layout of the actuators.

Parameters

layoutnumpy.ndarray or None

Layout of the actuators. Is converted to boolean if not already.

setM2C(M2C)

Set the mode-to-command matrix. This is the basis for correction.

Parameters

M2Cnumpy.ndarray or None

Mode-to-command matrix to set. Axes are [numActuators, numModes]

write(correction)

Write a new correction.

Parameters

correctionnumpy.ndarray

Correction vector to write.

class pyRTC.WavefrontSensor(conf)

Base class for cameras that feed the wavefront-sensing pipeline.

The class owns the common control-plane behavior for wavefront-sensor image sources: configuration, dark subtraction, optional downsampling and rotation, and publication of both raw and processed frames. Concrete sensor adapters in pyRTC.hardware are responsible for talking to vendor SDKs and filling self.data before delegating back to the base implementation.

Config

namestr

The name of the wavefront sensor. Default “wavefrontSensor”

widthint

The width of the wavefront sensor image. Required.

heightint

The width of the wavefront sensor image. Required.

darkCountint

Number of dark frames to average. Default 1000.

darkFilestr

Path to the dark frame file. Default, empty string.

Attributes

imageShapetuple

The shape of the image (width, height).

imageRawDTypedata-type

The data type for raw image.

imageDTypedata-type

The data type for processed image.

imageRawImageSHM

Shared memory object for raw image.

imageImageSHM

Shared memory object for processed image.

datandarray

Array to store raw image data.

darkndarray

Array to store dark frame data.

affinityint

The affinity configuration.

roiWidthint

Width of the region of interest.

roiHeightint

Height of the region of interest.

roiLeftint

Left coordinate of the region of interest.

roiTopint

Top coordinate of the region of interest.

exposurefloat

Exposure time.

binningint

Binning factor.

gainfloat

Gain setting.

bitDepthint

Bit depth of the image.

Methods

setRoi(roi)

Sets the region of interest.

setExposure(exposure)

Sets the exposure time.

setBinning(binning)

Sets the binning factor.

setGain(gain)

Sets the gain.

setBitDepth(bitDepth)

Sets the bit depth.

expose()

Writes the current image data to shared memory.

read()

Reads the processed image data from shared memory.

takeDark()

Captures and sets the dark frame.

setDark(dark)

Sets the dark frame.

saveDark(filename=’’)

Saves the dark frame to a file.

loadDark(filename=’’)

Loads the dark frame from a file.

plot()

Plots the current image data.

rotateImage(angle_deg)

Rotates the current image data by the specified angle in degrees.

expose()

Writes the current image data to shared memory. Both raw, and dark subtracted.

Parameters

Return type:

None

loadDark(filename='')

Loads the dark frame from a file.

Parameters

filenamestr, optional

Filename to load the dark frame from. If not specified, uses the dark file path from the configuration.

plot()

Plots the current image data.

Return type:

None

read(block=True)

Reads the dark subtracted image data from shared memory.

Returns

ndarray

Processed image data.

Return type:

None

rotateImage(angle_deg)

Rotates the current image data by the specified angle.

This method uses a high-performance numba JIT-compiled bilinear interpolation rotation algorithm that is significantly faster than scipy or opencv implementations while maintaining good image quality.

Parameters

angle_degfloat

Rotation angle in degrees. Positive values rotate counter-clockwise.

Returns

ndarray

Rotated image data with the same shape and dtype as the original.

Examples

>>> wfs = WavefrontSensor(config)
>>> rotated_img = wfs.rotateImage(45.0)  # Rotate 45 degrees counter-clockwise
>>> rotated_img = wfs.rotateImage(-90.0) # Rotate 90 degrees clockwise

Parameters:

angle_deg (float)

Return type:

ndarray

saveDark(filename='')

Saves the dark frame to a file.

Parameters

filenamestr, optional

Filename to save the dark frame to. If not specified, uses the dark file path from the configuration.

setBinning(binning)

Sets the binning factor for the sensor.

Parameters

binningint

Binning factor.

Parameters:

binning (int)

Return type:

None

setBitDepth(bitDepth)

Sets the bit depth for the sensor.

Parameters

bitDepthint

Bit depth. pyRTC convention is this is the number of bits in the ADC, e.g., 8, 16, 12, 10.

Parameters:

bitDepth (int)

Return type:

None

setDark(dark)

Sets the dark frame.

Parameters

darkndarray

Dark frame data.

Return type:

None

setExposure(exposure)

Sets the exposure time for the sensor.

Parameters

exposurefloat

Exposure time in whatever unit your camera uses.

Parameters:

exposure (float)

Return type:

None

setGain(gain)

Sets the gain for the sensor.

Parameters

gainfloat

Gain value.

Parameters:

gain (float)

Return type:

None

setRoi(roi)

Sets the region of interest (ROI) for the sensor.

Parameters

roituple

A tuple containing (width, height, left, top) of the ROI.

takeDark()

Captures and sets the dark frame.

Return type:

None

Parameters:

conf (dict)

pyRTC.add_logging_cli_args(parser)

Parameters:

parser (ArgumentParser)

Return type:

ArgumentParser

pyRTC.configure_logging(*, app_name='pyrtc', component_name=None, level=None, log_dir=None, log_file=None, color=None, console=None, export_env=True)

Parameters:

• app_name (str)

• export_env (bool)

Return type:

Logger

pyRTC.configure_logging_from_args(args, *, app_name='pyrtc', component_name=None)

Parameters:

app_name (str)

Return type:

Logger

pyRTC.get_logger(name=None)

Parameters:

name (str | None)

Return type:

Logger

pyRTC.gpu_torch_available()

Return type:

bool

class pyRTC.hardwareLauncher(hardwareFile, configFile, port, timeout=None)

Launch and supervise a hardware-side child process.

The launcher is the client-side helper for pyRTC’s hard-RTC deployment model. It starts a Python subprocess, waits for the child to expose a socket listener, and then sends simple JSON messages to get or set properties, invoke helper methods, or request shutdown.

Logging-related environment variables are propagated so parent and child processes share the same operator-facing logging policy.

getProperty(property)

launch()

read()

run(function, *args, timeout=None)

setProperty(property, value)

shutdown()

write(message)

writeAndRead(message)

pyRTC.initExistingShm(shmName, gpuDevice=None)

pyRTC.launchComponent(component, confKey, start=True)

pyRTC.normalize_gpu_device(gpuDevice, context='')

Parameters:

context (str)

class pyRTC.pyRTCComponent(conf)

Common threaded component base used throughout pyRTC.

The base class standardizes the repeated mechanics shared by the wavefront sensor, slopes processor, loop controller, telemetry recorder, and many hardware-facing helpers. Components list runtime methods under the configuration key functions and the base class starts one worker thread per listed method.

Those worker functions are assumed to matter for their side effects rather than their return values. They usually produce, consume, or transform shared- memory streams inside the running RTC.

For examples:

psf:

functions: - expose - integrate

Config Parameters

affinityint

Base CPU affinity for the component. Additional worker functions are assigned subsequent cores when possible.

functionslist

Bound method names to run in worker threads.

gpuDevicestr, optional

Requested GPU device identifier. When PyTorch is unavailable this is normalized back to CPU mode.

Attributes

alivebool

Indicates whether the component is alive.

runningbool

Indicates whether the component is currently running.

The class intentionally does not define component-specific data flow. It is only responsible for the shared runtime lifecycle.

start()

Start the registered real-time functions.

stop()

Stops the registered real-time functions.

pyRTC.setFromConfig(conf, name, default)

Return a config value or a typed default.

When a default is provided, this helper asserts that any override found in the configuration matches the default’s type. That makes many YAML mistakes fail early during component startup instead of surfacing later.

Module Index

Pipeline	Shared-memory transport and hard-RTC process helpers for pyRTC.
utils	General utility helpers shared across pyRTC.

SyntheticSystems

Synthetic hardware components for onboarding and test flows.

Notes

Optional vendor-backed hardware adapters are not listed here because some of them depend on site-specific SDKs that may not be installed on the docs host. Those adapters are still documented in source and in the hardware example modules under pyRTC.hardware.