PyOpticalTable

https://jamesdpickering.com/pyopticaltable/
Admin
PyOpticalTable is a Python library built on matplotlib that makes it easy to create precise,...
Tokens:24,610
Snippets:115
Trust Score:5.2
Update:5 hours ago
Show doc for...
Tokens:
Raw
### Initialize a LaserBeam and beampath list

Source: https://jamesdpickering.com/pyopticaltable/

Creates a green LaserBeam object and an empty list 'beampath' that will hold optical elements in the order the beam hits them.

```python
beam = pyopt.LaserBeam(colour='green')
beampath = []
```

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

### Create an OpticalTable

Source: https://jamesdpickering.com/pyopticaltable/

Creates a 20x10 table in axis coordinates with size_factor=10, resulting in a 200mm by 100mm figure. show_edge draws the table border, show_grid draws a 1-unit grid (20x10). The origin is at the center.

```python
table = pyopt.OpticalTable(20, 10, size_factor=10, show_edge=True, show_grid=True)
```

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

### Add mirrors to beampath

Source: https://jamesdpickering.com/pyopticaltable/

Creates four mirrors with size 0.5 at specified positions and angles, appending each to the beampath list. The beam reflects off them in order.

```python
mirrorsize = 0.5
mirror1 = table.mirror(0,0,mirrorsize,45)
beampath.append(mirror1)

mirror2 = table.mirror(0,3,mirrorsize,45)
beampath.append(mirror2)

mirror3 = table.mirror(5,3,mirrorsize,-45)
beampath.append(mirror3)

mirror4 = table.mirror(5,0,mirrorsize,-45)
beampath.append(mirror4)
```

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

### OpticalTable constructor

Source: https://jamesdpickering.com/pyopticaltable/

Initializes an OpticalTable instance, which serves as the main drawing canvas for optical elements. The table dimensions and appearance are configured via parameters.

```APIDOC
## OpticalTable(length, width, size_factor=10.0, edgecolour='k', grid_spacing=1.0, gridcolour='gray', show_edge=True, show_grid=False, show_labels=False)

### Description
Initializes an OpticalTable instance, which serves as the main drawing canvas for optical elements. The table dimensions and appearance are configured via parameters.

### Parameters
- **length** (int) - Required - Length (x dimension) of the table, in internal figure coordinates.
- **width** (int) - Required - Width (y dimension) of the table, in internal figure coordinates.
- **size_factor** (float, optional) - The length and width are each multiplied by the size factor to give the dimensions of the final figure in millimetres. The default is 10.
- **edgecolour** (string, optional) - Colour of the border of the table, any matplotlib supported colour works. The default is 'k' (black).
- **grid_spacing** (float, optional) - Spacing of lines shown on the table grid, in internal figure coordinates. Must be chosen such that there is an integer number of lines over the length. The default is 1.
- **gridcolour** (string, optional) - Colour of the grid on the table, any matplotlib supported colour works. The default is 'gray'.
- **show_edge** (bool, optional) - If true then the edge of the table is shown. The default is True.
- **show_grid** (bool, optional) - If true then a grid is shown over the table. The default is False.
- **show_labels** (bool, optional) - If true then coordinate labels are added to the grid. The default is False.

```

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

### Place a box source (laser)

Source: https://jamesdpickering.com/pyopticaltable/

Adds a box labelled 'Laser' centered at (-5,0), 4 wide and 2 high. output_side='right' makes the beam originate from the right side. The box is an OpticalElement object.

```python
laser = table.box_source(-5,0, 4, 2, 0, colour='k', output_side='right',label='Laser', textcolour='green', labelpad=0)
```

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

### mirror(x, y, size, angle, colour='k', label=None, label_pos='bottom', labelpad=0.25, textcolour='k', fontsize=8)

Source: https://jamesdpickering.com/pyopticaltable/

Draws a mirror on the optical table. A mirror is an angled line; laser beams bounce off the middle of the mirror at (x,y). Returns an OpticalElement instance.

```APIDOC
## mirror(x, y, size, angle, colour='k', label=None, label_pos='bottom', labelpad=0.25, textcolour='k', fontsize=8)

### Description
Draw a mirror on the optical table. A mirror is simply an angled line. Laser beams will bounce off the middle of the mirror, at the point (x,y).

### Parameters
- **x** (float) - Required - x-coordinate of the centre of the optic.
- **y** (float) - Required - y-coordinate of the centre of the optic.
- **size** (float) - Required - Size of the optic.
- **angle** (float) - Required - Rotation of the optic anticlockwise from the positive x-axis, in degrees.
- **colour** (string, optional) - Colour of the optic, any matplotlib supported colour works. The default is 'k'.
- **label** (string, optional) - Text to put in the label for the optic. The default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the optic ('top', 'bottom', 'left', 'right'). The default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the optic. The default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. The default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. The default is fontparams['fontsize'].

### Returns
- **OpticalElement** - Instance of the OpticalElement class for this optic.
```

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

### Import PyOpticalTable

Source: https://jamesdpickering.com/pyopticaltable/

Loads the pyopticaltable package. Requires pyopticaltable.py in the working directory or on the Python path.

```python
import pyopticaltable as pyopt
```

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

### generic_circle(x, y, size, colour='k', fill=False, fillcolour='k', label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

Source: https://jamesdpickering.com/pyopticaltable/

Draws a circle on the optical table centered at (x,y). The radius is determined by the size parameter. Returns an OpticalElement instance.

```APIDOC
## generic_circle(x, y, size, colour='k', fill=False, fillcolour='k', label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

### Description
Draw a circle on the optical table centered at (x,y). The radius of the circle is determined by the size parameter.

### Parameters
- **x** (float) - Required - x-coordinate of the centre of the circle.
- **y** (float) - Required - y-coordinate of the centre of the circle.
- **size** (float) - Required - Radius of the circle.
- **colour** (string, optional) - Colour of the edge of the circle. The default is 'k'.
- **fill** (bool, optional) - If True then the circle is filled with fillcolour. The default is False.
- **fillcolour** (string, optional) - Colour to fill the circle with. The default is 'k'.
- **label** (string, optional) - Text to put in the label for the box. The default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the box ('top', 'bottom', 'left', 'right'). The default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the box. The default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. The default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. The default is fontparams['fontsize'].

### Returns
- **OpticalElement** - Instance of the OpticalElement class for this optic.
```

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

### OpticalElement constructor

Source: https://jamesdpickering.com/pyopticaltable/

Initializes an OpticalElement instance, which contains information specific to an optical element. It is created whenever an optical element is added to the table.

```APIDOC
## OpticalElement(x, y, mode, angle=None, element_type=None)

### Description
Initializes an OpticalElement instance, which contains information specific to an optical element. It is created whenever an optical element is added to the table.

### Parameters
- **x** (float) - Required - x coordinate of the optical element.
- **y** (float) - Required - y coordinate of the optical element.
- **mode** (string) - Required - mode of the optic - transmissive "t", or reflective "r" (UNUSED).
- **angle** (float, optional) - rotation angle of the optic relative to the x axis.
- **element_type** (optional) - Type of the optical element.

```

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

### LaserBeam constructor

Source: https://jamesdpickering.com/pyopticaltable/

Initializes a LaserBeam instance with the given colour, linewidth, and linestyle. The beam is not drawn until the draw method is called.

```APIDOC
## LaserBeam(colour, width=1, style='-', divergent=False, divergence_angle=None)

### Description
Initializes a LaserBeam instance with the given colour, linewidth, and linestyle. The beam is not drawn until the draw method is called.

### Parameters
- **colour** (string) - Required - Colour of the laser beam, any matplotlib defined colour is fine.
- **width** (float, optional) - Linewidth of the drawn laser beam (as defined in matplotlib). The default is 1.
- **style** (string, optional) - Linestyle of the drawn laser beam, see matplotlib docs for more details. The default is '-' (unbroken line).
- **divergent** (bool, optional) - NOT IMPLEMENTED.
- **divergence_angle** (float, optional) - NOT IMPLEMENTED.

```

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

### OpticalElement Class Constructor

Source: https://jamesdpickering.com/pyopticaltable/

Creates an instance of the OpticalElement class for a transmissive plate optic. Parameters control colour, thickness, fill, label, and drawing order.

```APIDOC
## OpticalElement Class Constructor

### Description
Creates an instance of the OpticalElement class for a transmissive plate optic.

### Parameters
- **colour** (string, optional) - Colour of the optic, any matplotlib supported colour works. Default is 'k'.
- **offset_factor** (float, optional) - How thick the transmissive plate is. Default is 0.05.
- **fill** (bool, optional) - If true then the plate is filled with a colour. Default is False.
- **fillcolour** (string, optional) - Colour to fill the plate with. Default is 'k'.
- **label** (string, optional) - Text to put in the label for the optic. Default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the optic ('top', 'bottom', 'left', 'right'). Default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the optic. Default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. Default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. Default is fontparams['fontsize'].
- **zorder** (int, optional) - Zorder for the transmissive plate (controls drawing order). Default is 2.

### Returns
- **OpticalElement** - Instance of the OpticalElement class for this optic.
```

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

### TransmissivePlate Constructor

Source: https://jamesdpickering.com/pyopticaltable/index.html

Creates a transmissive plate optic with configurable colour, thickness, fill, label, and positioning options.

```APIDOC
## TransmissivePlate Constructor

### Description
Creates a transmissive plate optic with configurable colour, thickness, fill, label, and positioning options.

### Method
Constructor

### Parameters
- **colour** (string, optional) - Colour of the optic, any matplotlib supported colour works. Default is 'k'.
- **offset_factor** (float, optional) - How thick the transmissive plate is. Default is 0.05.
- **fill** (bool, optional) - If true then the plate is filled with a colour. Default is False.
- **fillcolour** (string, optional) - Colour to fill the plate with. Default is 'k'.
- **label** (string, optional) - Text to put in the label for the optic. Default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the optic ('top', 'bottom', 'left', 'right'). Default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the optic. Default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. Default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. Default is fontparams['fontsize'].
- **zorder** (int, optional) - Zorder for the transmissive plate (controls drawing order). Default is 2.

### Returns
- **OpticalElement** - Instance of the OpticalElement class for this optic.
```

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

### box_source(x, y, size_x, size_y, angle, output_side, colour='k', label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

Source: https://jamesdpickering.com/pyopticaltable/

Draws a box on the table that a laser beam can come from. The box is centered on (x, y), and the beam comes from the midpoint of one of the four sides, determined by the output_side parameter.

```APIDOC
## box_source(x, y, size_x, size_y, angle, output_side, colour='k', label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

### Description
Draw a box on the table that a laser beam can come from. Box is centered on (x, y), and the beam will come from the midpoint of one of the four sides, determined by the string passed via output_side. Allowed sides are 'top', 'bottom', 'left', 'right'.

### Parameters
- **x** (float) - Required - x-coordinate of the centre of the box.
- **y** (float) - Required - y-coordinate of the centre of the box.
- **size_x** (float) - Required - Size of the box in the x direction.
- **size_y** (float) - Required - Size of the box in the y direction.
- **angle** (float) - Required - Rotation of the box anticlockwise from the positive x-axis, in degrees.
- **output_side** (string) - Required - Which side of the box the beam will come from, allowed values 'top', 'bottom', 'left', 'right'.
- **colour** (string, optional) - Colour of the box edge, any matplotlib supported colour works. The default is 'k'.
- **label** (string, optional) - Text to put in the label for the box. The default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the box ('top', 'bottom', 'left', 'right'). The default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the box. The default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. The default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. The default is fontparams['fontsize'].

### Raises
- **ValueError** - Raised if an invalid output side is entered.

### Returns
- **OpticalElement** - Instance of the OpticalElement class for this optic.
```

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

### concave_mirror(x, y, size, angle, colour='k', lens_factor=1, label=None, label_pos='bottom', labelpad=0.25, textcolour='k', fontsize=8)

Source: https://jamesdpickering.com/pyopticaltable/index.html

Draws a concave mirror on the optical table. The beam will pass through the point (x,y), which is the centre of the flat face of the mirror. Returns an OpticalElement instance.

```APIDOC
## concave_mirror(x, y, size, angle, colour='k', lens_factor=1, label=None, label_pos='bottom', labelpad=0.25, textcolour='k', fontsize=8)

### Description
Draws a concave mirror on the optical table. The beam will pass through the point (x,y), which is the centre of the flat face of the mirror.

### Method
Function call

### Endpoint
concave_mirror(x, y, size, angle, colour='k', lens_factor=1, label=None, label_pos='bottom', labelpad=0.25, textcolour='k', fontsize=8)

### Parameters
- **x** (float) - Required - x-coordinate of the centre of the flat face of the mirror.
- **y** (float) - Required - y-coordinate of the centre of the flat face of the mirror.
- **size** (float) - Required - Size of the optic.
- **angle** (float) - Required - Rotation of the optic anticlockwise from the positive x-axis, in degrees.
- **colour** (string, optional) - Colour of the optic, any matplotlib supported colour works. The default is 'k'.
- **lens_factor** (float, optional) - Controls how curved the mirror is (how "lens-y" it looks). The default is 1.
- **label** (string, optional) - Text to put in the label for the optic. The default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the optic ('top', 'bottom', 'left', 'right'). The default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the optic. The default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. The default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. The default is fontparams['fontsize'].

### Returns
Instance of the OpticalElement class for this optic.

### Return Type
OpticalElement
```

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

### box(x, y, size_x, size_y, angle, colour='k', standalone=False, label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

Source: https://jamesdpickering.com/pyopticaltable/

Creates a rectangular box of arbitrary size and rotation angle. If standalone=True, the box is drawn on the table; otherwise, the corner coordinates are returned.

```APIDOC
## box(x, y, size_x, size_y, angle, colour='k', standalone=False, label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

### Description
Create a rectangular box of arbitrary size and rotation angle. The box can be drawn on the table (if standalone=True), otherwise the corner coordinates of the box are returned from the function to use in other functions.

### Parameters
- **x** (float) - Required - x-coordinate of the centre of the box.
- **y** (float) - Required - y-coordinate of the centre of the box.
- **size_x** (float) - Required - Size of the box in the x direction.
- **size_y** (float) - Required - Size of the box in the y direction.
- **angle** (float) - Required - Rotation angle of the box.
- **colour** (string, optional) - Colour of the box, any matplotlib supported colour works. The default is 'k'.
- **standalone** (bool, optional) - If True, the box is drawn on the table. The default is False.
- **label** (string, optional) - Text to put in the label for the box. The default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the box ('top', 'bottom', 'left', 'right'). The default is "top".
- **labelpad** (float, optional) - Additional padding to add between the label and the box. The default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. The default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. The default is fontparams['fontsize'].

### Returns
- **corner coordinates** - The corner coordinates of the box, used in other functions.
```

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

### Add lenses and beam dump to the optical table

Source: https://jamesdpickering.com/pyopticaltable/

Adds a convex lens, a concave lens, and a beam dump to the optical table, appending each to the 'beampath' list. The lenses are positioned to act like a telescope, and the beam dump catches the beam at the end. These lines should be added before drawing the beam.

```python
L1 = table.convex_lens(6, 0, mirrorsize, 90)
beampath.append(L1)

L2 = table.concave_lens(7, 0, mirrorsize, 270)
beampath.append(L2)

dump = table.beam_dump(8, 0, 0.1, 0, fillcolour='k')
beampath.append(dump)
```

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

### point_source

Source: https://jamesdpickering.com/pyopticaltable/

Creates a point source for a laser beam at a given (x, y) coordinate. The source is not visible on the table but serves as a place where a beam can emanate from or pass through.

```APIDOC
## point_source(x, y, label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

### Description
Create a source for a laser beam at (x,y). The source is not visible on the table, but just serves as a place where a beam can emanate from/pass through.

### Method
point_source

### Parameters
- **x** (float) - Required - x-coordinate of the point.
- **y** (float) - Required - y-coordinate of the point.
- **label** (string, optional) - Text to put in the label for the box. The default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the box ('top', 'bottom', 'left', 'right'). The default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the box. The default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. The default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. The default is fontparams['fontsize'].

### Returns
Instance of the OpticalElement class for this optic.

### Return Type
OpticalElement
```

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

### concave_mirror(x, y, size, angle, colour='k', lens_factor=1, label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

Source: https://jamesdpickering.com/pyopticaltable/

Draws a concave mirror on the optical table. The beam will hit the mirror at the point (x, y).

```APIDOC
## concave_mirror(x, y, size, angle, colour='k', lens_factor=1, label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

### Description
Draw a concave mirror on the optical table. The beam will hit the mirror at the point (x, y).

### Parameters
- **x** (float) - Required - x-coordinate of the centre of the optic.
- **y** (float) - Required - y-coordinate of the centre of the optic.
- **size** (float) - Required - Size of the optic.
- **angle** (float) - Required - Rotation of the optic anticlockwise from the positive x-axis, in degrees.
- **colour** (string, optional) - Colour of the optic, any matplotlib supported colour works. The default is 'k'.
- **lens_factor** (float, optional) - Controls how curved the mirror is. The default is 1.
- **label** (string, optional) - Text to put in the label for the optic. The default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the optic ('top', 'bottom', 'left', 'right'). The default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the optic. The default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. The default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. The default is fontparams['fontsize'].

### Returns
- **OpticalElement** - Instance of the OpticalElement class for this optic.
```

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

### beam_dump(x, y, size, angle, colour='k', fillcolour='k', label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

Source: https://jamesdpickering.com/pyopticaltable/

Draws a beam dump on the table, a filled block where a beam can terminate. The zorder=10 ensures it is drawn on top of the beam.

```APIDOC
## beam_dump(x, y, size, angle, colour='k', fillcolour='k', label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

### Description
Draw a beam dump on the table. A beam dump is simply a filled in block where a beam can terminate. The zorder=10 ensures that the beam dump is always drawn on top of the beam, such that it looks like the beam is effectively blocked.

### Parameters
- **x** (float) - Required - x-coordinate of the centre of the optic.
- **y** (float) - Required - y-coordinate of the centre of the optic.
- **size** (float) - Required - Size of the optic.
- **angle** (float) - Required - Rotation of the optic anticlockwise from the positive x-axis, in degrees.
- **colour** (string, optional) - Colour of the optic, any matplotlib supported colour works. The default is 'k'.
- **fillcolour** (string, optional) - Colour to fill the block with. The default is 'k'.
- **label** (string, optional) - Text to put in the label for the box. The default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the box ('top', 'bottom', 'left', 'right'). The default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the box. The default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. The default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. The default is fontparams['fontsize'].

### Returns
- **OpticalElement** - Instance of the OpticalElement class for this optic.
```

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

### Tools.get_label_coords(x, y, size, labelpad)

Source: https://jamesdpickering.com/pyopticaltable/

Returns the coordinates where the label for an optic should be. Calculates them based on the position and size of the optic. User defined labelpad can also be used to further move the label.

```APIDOC
## Tools.get_label_coords(x, y, size, labelpad)

### Description
Returns the coordinates where the label for an optic should be. Calculates them based on the position and size of the optic. User defined labelpad can also be used to further move the label.

### Parameters
- **label_pos** (string) - String determining label position relative to the optic. Allowable values are 'top', 'bottom', 'left', 'right'.
- **x** (float) - x-coordinate of the optical element being labelled.
- **y** (float) - y-coordinate of the optical element being labelled.
- **size** (float) - size of optical element being labelled.
- **labelpad** (float) - additional space to put between optic and label.

### Returns
- **label_x** (float) - x-coordinate of label position.
- **label_y** (TYPE) - y-coordinate of label position.
```

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

### Tools.mm_to_inch()

Source: https://jamesdpickering.com/pyopticaltable/

Convert millimetre to inches.

```APIDOC
## Tools.mm_to_inch()

### Description
Convert millimetre to inches.
```

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

### LaserBeam.draw(table, optics)

Source: https://jamesdpickering.com/pyopticaltable/

Draws a laser beam on the specified optical table, passing through the given list of optical elements in order. The beam parameters are set during initialization.

```APIDOC
## LaserBeam.draw(table, optics)

### Description
Draws a laser beam on the specified optical table, passing through the given list of optical elements in order. The beam parameters are set during initialization.

### Method
Draw

### Parameters
- **table** (OpticalTable) - Required - The instance of OpticalTable the beam is drawn on.
- **optics** (list) - Required - List of OpticalElement instances.

### Returns
None

```

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

### Tools.inch_to_mm()

Source: https://jamesdpickering.com/pyopticaltable/

Convert inches to millimetre.

```APIDOC
## Tools.inch_to_mm()

### Description
Convert inches to millimetre.
```

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

### Draw the beam on the optical table

Source: https://jamesdpickering.com/pyopticaltable/

Draws the beam on the OpticalTable object 'table' following the path defined by the 'beampath' list. The beam is drawn in green and automatically re-routes if the positions of the mirrors are changed.

```python
beam.draw(table, beampath)
```

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

### convex_lens(x, y, size, angle, colour='k', lens_factor=2, label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

Source: https://jamesdpickering.com/pyopticaltable/

Draws a convex lens on the optical table. The beam passes through the centre of the flat face of the lens at (x, y). Returns an OpticalElement instance.

```APIDOC
## convex_lens(x, y, size, angle, colour='k', lens_factor=2, label=None, label_pos='top', labelpad=0.25, textcolour='k', fontsize=8)

### Description
Draw a convex lens on the optical table. The beam will pass through the point (x,y), which is the centre of the flat face of the lens.

### Parameters
- **x** (float) - Required - x-coordinate of the centre of the flat face of the lens.
- **y** (float) - Required - y-coordinate of the centre of the flat face of the lens.
- **size** (float) - Required - Size of the optic.
- **angle** (float) - Required - Rotation of the optic anticlockwise from the positive x-axis, in degrees.
- **colour** (string, optional) - Colour of the optic, any matplotlib supported colour works. The default is 'k'.
- **lens_factor** (float, optional) - Controls how curved the lens is (how "lens-y" it looks). The default is 2.
- **label** (string, optional) - Text to put in the label for the optic. The default is None (no label).
- **label_pos** (string, optional) - Position of the label relative to the optic ('top', 'bottom', 'left', 'right'). The default is "bottom".
- **labelpad** (float, optional) - Additional padding to add between the label and the optic. The default is 0.25.
- **textcolour** (string, optional) - Colour of the label text. The default is 'k' (black).
- **fontsize** (float, optional) - Font size for the label text. The default is fontparams['fontsize'].

### Returns
- **OpticalElement** - Instance of the OpticalElement class for this optic.
```
Tokens:
Raw