Loudspeaker Layout¶
The ear.core.layout module contains data structures which represent
loudspeaker layouts. Rather than being constructed directly, these should be
created by calling ear.core.bs2051.get_layout(), and modified to match
real-world layouts using the functionality described in Real-world Layouts.
- class ear.core.layout.Layout(name, channels, screen=PolarScreen(aspectRatio=1.78, centrePosition=PolarPosition(azimuth=0.0, elevation=0.0, distance=1.0), widthAzimuth=58.0))¶
Representation of a loudspeaker layout, with a name and a list of channels.
- screen¶
screen information to use for screen-related content
- Type
Optional[Union[CartesianScreen, PolarScreen]]
- property channels_by_name¶
dict from channel name to Channel.
- check_positions(callback=<function _print_warning>)¶
Call callback with error messages for any channel positions that are out of range.
- check_upmix_matrix(upmix, callback=<function _print_warning>)¶
Call callback with error messages for any errors in an upmix matrix.
each input channel should be routed to 1 output channel
each output channel should be routed from 0 or 1 input channels
- property is_lfe¶
Bool array corresponding to channels that selects LFE channels.
- property nominal_positions¶
Nominal channel positions as an (n, 3) numpy array.
- property norm_positions¶
Normalised channel positions as an (n, 3) numpy array.
- property positions¶
Channel positions as an (n, 3) numpy array.
- with_real_layout(real_layout)¶
Incorporate information from a real layout.
Note: see with_speakers for information on speaker mapping
- Parameters
real_layout (RealLayout) – real layout information to incorporate
- Returns
A new Layout object with updated speaker positions and screen information.
An upmix matrix to map the loudspeakers to the correct channels and apply gains.
- with_speakers(speakers)¶
Remap speaker positions to those in speakers, and produce an upmix matrix to map from the channels in the layout to the channels in the speaker list.
- Parameters
- Returns
A new Layout object with the same channels but with positions matching those in speakers.
An upmix matrix m, such that m.dot(x) will map values corresponding to the channels in self.channels to the channel numbers in speakers. This matrix may be missing entries or have duplicate entries depending on the contents of speakers; use check_upmix_matrix.
- class ear.core.layout.Channel(name, polar_position, polar_nominal_position=NOTHING, az_range=NOTHING, el_range=NOTHING, is_lfe=False)¶
Representation of a channel, with a name, real and nominal positions, allowed azimuth and elevation ranges, and an lfe flag.
- polar_position¶
real speaker location
- Type
PolarPosition, or arguments for PolarPosition
- polar_nominal_position¶
nominal speaker location, defaults to polar_position
- Type
PolarPosition, or arguments for PolarPosition
- az_range¶
azimuth range in degrees; allowed range is interpreted as starting at az_range[0], moving anticlockwise to az_range[1]; defaults to the azimuth of polar_nominal_position.
- Type
2-tuple of floats
- el_range¶
elevation range in degrees; allowed range is interpreted as starting at el_range[0], moving up to el_range[1]; defaults to the elevation of polar_nominal_position.
- Type
2-tuple of floats
- check_position(callback=<function _print_warning>)¶
Call callback with an error message if the position is outside the azimuth and elevation ranges.
BS.2051 Layouts¶
Real-world Layouts¶
The following functionality is used to allow a user to specify the real
position of loudspeakers in a listening room (independent of the layouts that
can be created with them), which can be used to modify layout.Layout
objects using Layout.with_real_layout():
- class ear.core.layout.RealLayout(speakers=None, screen=PolarScreen(aspectRatio=1.78, centrePosition=PolarPosition(azimuth=0.0, elevation=0.0, distance=1.0), widthAzimuth=58.0))¶
Representation of a complete listening environment, onto which a standard layout will be mapped.
- screen¶
screen information to use for screen-related content
- Type
Optional[Union[CartesianScreen, PolarScreen]]
- class ear.core.layout.Speaker(channel, names, polar_position=None, gain_linear=1.0)¶
Representation of a real-world loudspeaker; an array of these represents the data required to use the renderer in a given listening room.
- polar_position¶
real loudspeaker position, if known
- Type
Optional[PolarPosition]
- ear.core.layout.load_real_layout(fileobj)¶
Load a real layout from a yaml file.
The format is either a list of objects representing speakers, or an object with optional keys
speakers(which contains a list of objects representing speakers) andscreen(which contains an object representing the screen).Objects representing speakers may have the following keys:
- channel
0-based channel number, required
- names
list (or a single string) of BS.2051 channel names that this speaker should handle, i.e. like
"M+000"or["U+180", "UH+180"]- position
optional associative array containing the real loudspeaker position, with keys:
- az
anti-clockwise azimuth in degrees
- el
elevation in degrees
- r
radius in metres
- gain_linear
optional linear gain to be applied to this channel
A polar screen may be represented with the following keys:
- type
"polar", required- aspectRatio
aspect ratio of the screen
- centrePosition
object representing the centre position of the screen:
- az
anti-clockwise azimuth in degrees
- el
elevation in degrees
- r
radius in metres
- widthAzimuth
width of the screen in degrees
A Cartesian screen may be represented with the following keys:
- type
"cart", required- aspectRatio
aspect ratio of the screen
- centrePosition
object representing the centre position of the screen containing X, Y and Z coordinates
- widthX
width of the screen along the Cartesian X axis
If the screen is omitted, the default screen is used; if the screen is specified but null, then screen-related processing will not be applied.
- Parameters
fileobj – a file-like object to read yaml from
- Returns
real layout information
- Return type
See Speakers File Format for more details and examples.