Convert Functions

class pyonfx.convert.ColorModel(*values)[source]
class pyonfx.convert.Convert[source]

This class is a collection of static methods that will help the user to convert everything needed to the ASS format.

static time(ass_ms: int) → str[source]
static time(ass_ms: str) → int

Converts between milliseconds and ASS timestamp.

You can probably ignore that function, you will not make use of it for KFX or typesetting generation.

Parameters:

ass_ms (int or str) – If int, than milliseconds are expected, else ASS timestamp as str is expected.

Returns:

If milliseconds -> ASS timestamp, else if ASS timestamp -> milliseconds, else ValueError will be raised.

static alpha_ass_to_dec(alpha_ass: str) → int[source]

Converts from ASS alpha string to corresponding decimal value.

Parameters:

alpha_ass (str) – A string in the format ‘&HXX&’.

Returns:

A decimal in [0, 255] representing alpha_ass converted.

Examples

print(Convert.alpha_ass_to_dec("&HFF&"))

>>> 255
static alpha_dec_to_ass(alpha_dec: int | float) → str[source]

Converts from decimal value to corresponding ASS alpha string.

Parameters:

alpha_dec (int or float) – Decimal in [0, 255] representing an alpha value.

Returns:

A string in the format ‘&HXX&’ representing alpha_dec converted.

Examples

print(Convert.alpha_dec_to_ass(255))
print(Convert.alpha_dec_to_ass(255.0))

>>> "&HFF&"
>>> "&HFF&"
static color(c: str | tuple[int | float, int | float, int | float] | tuple[int | float, int | float, int | float, int | float], input_format: ColorModel, output_format: ColorModel, round_output: bool = True) → str | tuple[int, int, int] | tuple[int, int, int, int] | tuple[float, float, float] | tuple[float, float, float, float][source]

Converts a provided color from a color model to another.

Parameters:

  • c (str or tuple of int or tuple of float) – A color in the format input_format.

  • input_format (ColorModel) – The color format of c.

  • output_format (ColorModel) – The color format for the output.

  • round_output (bool) – A boolean to determine whether the output should be rounded or not.

Returns:

A color in the format output_format.

Examples

print(Convert.color("&H0000FF&", ColorModel.ASS, ColorModel.RGB))

>>> (255, 0, 0)
static color_ass_to_rgb(color_ass: str, as_str: bool = False) → str | tuple[int, int, int][source]

Converts from ASS color string to corresponding RGB color.

Parameters:

  • color_ass (str) – A string in the format ‘&HBBGGRR&’.

  • as_str (bool) – A boolean to determine the output type format.

Returns:

The output represents color_ass converted. If as_str = False, the output is a tuple of integers in range [0, 255]. Else, the output is a string in the format ‘#RRGGBB’.

Examples

print(Convert.color_ass_to_rgb("&HABCDEF&"))
print(Convert.color_ass_to_rgb("&HABCDEF&", as_str=True))

>>> (239, 205, 171)
>>> "#EFCDAB"
static color_ass_to_hsv(color_ass: str, round_output: bool = True) → tuple[int, int, int] | tuple[float, float, float][source]

Converts from ASS color string to corresponding HSV color.

Parameters:

  • color_ass (str) – A string in the format ‘&HBBGGRR&’.

  • round_output (bool) – A boolean to determine whether the output should be rounded or not.

Returns:

The output represents color_ass converted. If round_output = True, the output is a tuple of integers in range ( [0, 360), [0, 100], [0, 100] ). Else, the output is a tuple of floats in range ( [0, 360), [0, 100], [0, 100] ).

Examples

print(Convert.color_ass_to_hsv("&HABCDEF&"))
print(Convert.color_ass_to_hsv("&HABCDEF&", round_output=False))

>>> (30, 28, 94)
>>> (30.000000000000014, 28.451882845188294, 93.72549019607843)
static color_rgb_to_ass(color_rgb: str | tuple[int | float, int | float, int | float]) → str[source]

Converts from RGB color to corresponding ASS color.

Parameters:

color_rgb (str or tuple of int or tuple of float) – Either a string in the format ‘#RRGGBB’ or a tuple of three integers (or floats) in the range [0, 255].

Returns:

A string in the format ‘&HBBGGRR&’ representing color_rgb converted.

Examples

print(Convert.color_rgb_to_ass("#ABCDEF"))

>>> "&HEFCDAB&"
static color_rgb_to_hsv(color_rgb: str | tuple[int | float, int | float, int | float], round_output: bool = True) → tuple[int, int, int] | tuple[float, float, float][source]

Converts from RGB color to corresponding HSV color.

Parameters:

  • color_rgb (str or tuple of int or tuple of float) – Either a string in the format ‘#RRGGBB’ or a tuple of three integers (or floats) in the range [0, 255].

  • round_output (bool) – A boolean to determine whether the output should be rounded or not.

Returns:

The output represents color_rgb converted. If round_output = True, the output is a tuple of integers in range ( [0, 360), [0, 100], [0, 100] ). Else, the output is a tuple of floats in range ( [0, 360), [0, 100], [0, 100] ).

Examples

print(Convert.color_rgb_to_hsv("#ABCDEF"))
print(Convert.color_rgb_to_hsv("#ABCDEF"), round_output=False)

>>> (210, 28, 94)
>>> (210.0, 28.451882845188294, 93.72549019607843)
static color_hsv_to_ass(color_hsv: tuple[int | float, int | float, int | float]) → str[source]

Converts from HSV color string to corresponding ASS color.

Parameters:

color_hsv (tuple of int/float) – A tuple of three integers (or floats) in the range ( [0, 360), [0, 100], [0, 100] ).

Returns:

A string in the format ‘&HBBGGRR&’ representing color_hsv converted.

Examples

print(Convert.color_hsv_to_ass((100, 100, 100)))

>>> "&H00FF55&"
static color_hsv_to_rgb(color_hsv: tuple[int | float, int | float, int | float], as_str: bool = False, round_output: bool = True) → str | tuple[int, int, int] | tuple[float, float, float][source]

Converts from HSV color string to corresponding RGB color.

Parameters:

  • color_hsv (tuple of int/float) – A tuple of three integers (or floats) in the range ( [0, 360), [0, 100], [0, 100] ).

  • as_str (bool) – A boolean to determine the output type format.

  • round_output (bool) – A boolean to determine whether the output should be rounded or not.

Returns:

The output represents color_hsv converted. If as_str = False, the output is a tuple ( also, if round_output = True, the output is a tuple of integers in range ( [0, 360), [0, 100], [0, 100] ), else a tuple of float in range ( [0, 360), [0, 100], [0, 100] ) ). Else, the output is a string in the format ‘#RRGGBB’.

Examples

print(Convert.color_hsv_to_rgb((100, 100, 100)))
print(Convert.color_hsv_to_rgb((100, 100, 100), as_str=True))
print(Convert.color_hsv_to_rgb((100, 100, 100), round_output=False))

>>> (85, 255, 0)
>>> "#55FF00"
>>> (84.99999999999999, 255.0, 0.0)
static text_to_shape(obj: Line | Word | Syllable | Char, fscx: float | None = None, fscy: float | None = None) → Shape[source]

Converts text with given style information to an ASS shape.

Tips: You can easily create impressive deforming effects.

Parameters:

  • obj (Line, Word, Syllable or Char) – An object of class Line, Word, Syllable or Char.

  • fscx (float, optional) – The scale_x value for the shape.

  • fscy (float, optional) – The scale_y value for the shape.

Returns:

A Shape object, representing the text with the style format values of the object.

Examples

line = Line.copy(lines[1])
line.text = "{\\an7\\pos(%.3f,%.3f)\\p1}%s" % (line.left, line.top, Convert.text_to_shape(line))
io.write_line(line)
static text_to_clip(obj: Line | Word | Syllable | Char, an: int = 5, fscx: float | None = None, fscy: float | None = None) → Shape[source]

Converts text with given style information to an ASS shape, applying some translation/scaling to it since it is not possible to position a shape with pos() once it is in a clip.

This is an high level function since it does some additional operations, check text_to_shape for further infromations.

Tips: You can easily create text masks even for growing/shrinking text without too much effort.

Parameters:

  • obj (Line, Word, Syllable or Char) – An object of class Line, Word, Syllable or Char.

  • an (integer, optional) – The alignment wanted for the shape.

  • fscx (float, optional) – The scale_x value for the shape.

  • fscy (float, optional) – The scale_y value for the shape.

Returns:

A Shape object, representing the text with the style format values of the object.

Examples

line = Line.copy(lines[1])
line.text = "{\\an5\\pos(%.3f,%.3f)\\clip(%s)}%s" % (line.center, line.middle, Convert.text_to_clip(line), line.text)
io.write_line(line)
static text_to_pixels(obj: Line | Word | Syllable | Char, supersampling: int = 8) → PixelCollection[source]
Converts text with given style information to a PixelCollection.
A pixel data is a dictionary containing ‘x’ (horizontal position), ‘y’ (vertical position) and ‘alpha’ (alpha/transparency).

It is highly suggested to create a dedicated style for pixels, because you will write less tags for line in your pixels, which means less size for your .ass file.

The style suggested (named “p” in the example) is:
- an=7 (very important!);
- bord=0;
- shad=0;
- For Font informations leave whatever the default is;

Tips: It allows easy creation of text decaying or light effects.

Parameters:

  • obj (Line, Word, Syllable or Char) – An object of class Line, Word, Syllable or Char.

  • supersampling (int) – Value used for supersampling. Higher value means smoother and more precise anti-aliasing (and more computational time for generation).

Returns:

A list of dictionaries representing each individual pixel of the input text styled.

Examples

l.style = "p"
p_sh = Shape.polygon(4, 1)
for pixel in Convert.text_to_pixels(l):
    x, y = math.floor(l.left) + pixel.x, math.floor(l.top) + pixel.y
    alpha = "\alpha" + Convert.alpha_dec_to_ass(pixel.alpha) if pixel.alpha != 0 else ""

    l.text = "{\p1\pos(%d,%d)%s}%s" % (x, y, alpha, p_sh)
    io.write_line(l)
static shape_to_pixels(shape: Shape, supersampling: int = 8, output_rgba: bool = False) → PixelCollection[source]

Converts a Shape object to a PixelCollection.

It is highly suggested to use a dedicated style for pixels, because you will write less tags for line in your pixels, which means less size for your .ass file.

PyonFX provides io.insert_pixel_style() to take care of this for you, so be sure to call it before using this function.

Tips: As for text, even shapes can decay!

Parameters:

  • shape (Shape) – An object of class Shape.

  • supersampling (int) – Supersampling factor (≥ 1). Higher values mean smoother anti-aliasing but slower generation.

  • output_rgba (bool) – If True, output RGBA values instead of ASS color and alpha.

Returns:

A PixelCollection containing Pixel objects, representing each individual pixel of the input shape. Each pixel contains ‘x’ (horizontal position), ‘y’ (vertical position) and ‘alpha’ (alpha/transparency).

static image_to_pixels(image_path: str, width: int | None = None, height: int | None = None, skip_transparent: bool = True, output_rgba: bool = False) → PixelCollection[source]

Converts an image to a PixelCollection.

Parameters:

  • image_path (str) – A file path to an image (either absolute or relative to the script).

  • width (int, optional) – Target width for rescaling. If None, original width is used.

  • height (int, optional) – Target height for rescaling. If None, original height is used. If only one dimension is specified, aspect ratio is maintained.

  • skip_transparent (bool) – If True, skip fully transparent pixels (i.e. alpha == 255).

  • output_rgba (bool) – If True, output RGBA values instead of ASS color and alpha.

Returns:

A PixelCollection containing Pixel objects, each containing x, y, color, alpha values.