diff --git a/py5/__init__.py b/py5/__init__.py index 1669d0e..b0c15d6 100644 --- a/py5/__init__.py +++ b/py5/__init__.py @@ -47,7 +47,7 @@ py5_tools.add_jars(str(base_path / 'jars')) # if the cwd has a jars subdirectory, add that next py5_tools.add_jars(Path('jars')) - # if the PY5_CLASSPATH environment variable exists, add those jars + # if the PY5_JARS environment variable exists, add those jars if (py5_classpath := os.environ.get('PY5_JARS')): py5_tools.add_jars(Path(py5_classpath)) @@ -88,7 +88,7 @@ pass -__version__ = '0.8.1a1' +__version__ = '0.8.2a1' _PY5_USE_IMPORTED_MODE = py5_tools.get_imported_mode() py5_tools._lock_imported_mode() @@ -672,52 +672,52 @@ def apply_matrix(n00: float, n01: float, n02: float, ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -769,52 +769,52 @@ def apply_matrix( ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -849,52 +849,52 @@ def apply_matrix(source: npt.NDArray[np.floating], /) -> None: ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -928,52 +928,52 @@ def apply_matrix(*args): ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -10907,6 +10907,9 @@ def push() -> None: ``push_matrix()``, ``pop_matrix()``, ``push_style()``, and ``pop_style()``. The difference is that ``push()`` and ``pop()`` control both the transformations (rotate, scale, translate) and the drawing styles at the same time. + + This method can be used as a context manager to ensure that ``pop()`` always + gets called, as shown in the last example. """ return _py5sketch.push() @@ -10926,6 +10929,9 @@ def push_matrix() -> None: ``push_matrix()`` and ``pop_matrix()`` are used in conjuction with the other transformation functions and may be embedded to control the scope of the transformations. + + This method can be used as a context manager to ensure that ``pop_matrix()`` + always gets called, as shown in the last example. """ return _py5sketch.push_matrix() @@ -10953,6 +10959,9 @@ def push_style() -> None: ``ellipse_mode()``, ``shape_mode()``, ``color_mode()``, ``text_align()``, ``text_font()``, ``text_mode()``, ``text_size()``, ``text_leading()``, ``emissive()``, ``specular()``, ``shininess()``, and ``ambient()``. + + This method can be used as a context manager to ensure that ``pop_style()`` + always gets called, as shown in the last example. """ return _py5sketch.push_style() @@ -12890,6 +12899,14 @@ def size(width: int, height: int, /) -> None: * ``SVG``: The ``SVG`` renderer draws 2D graphics directly to an SVG file. This is great for importing into other vector programs or using for digital fabrication. + + When using the ``PDF`` and ``SVG`` renderers with the ``size()`` method, you + must use the ``path`` parameter to specify the file to write the output to. No + window will open while the Sketch is running. You must also call + ``exit_sketch()`` to exit the Sketch and write the completed output to the file. + Without this call, the Sketch will not exit and the output file will be empty. + If you would like to draw 3D objects to a PDF or SVG file, use the ``P3D`` + renderer and the strategy described in ``begin_raw()``. """ pass @@ -12982,6 +12999,14 @@ def size(width: int, height: int, renderer: str, /) -> None: * ``SVG``: The ``SVG`` renderer draws 2D graphics directly to an SVG file. This is great for importing into other vector programs or using for digital fabrication. + + When using the ``PDF`` and ``SVG`` renderers with the ``size()`` method, you + must use the ``path`` parameter to specify the file to write the output to. No + window will open while the Sketch is running. You must also call + ``exit_sketch()`` to exit the Sketch and write the completed output to the file. + Without this call, the Sketch will not exit and the output file will be empty. + If you would like to draw 3D objects to a PDF or SVG file, use the ``P3D`` + renderer and the strategy described in ``begin_raw()``. """ pass @@ -13074,6 +13099,14 @@ def size(width: int, height: int, renderer: str, path: str, /) -> None: * ``SVG``: The ``SVG`` renderer draws 2D graphics directly to an SVG file. This is great for importing into other vector programs or using for digital fabrication. + + When using the ``PDF`` and ``SVG`` renderers with the ``size()`` method, you + must use the ``path`` parameter to specify the file to write the output to. No + window will open while the Sketch is running. You must also call + ``exit_sketch()`` to exit the Sketch and write the completed output to the file. + Without this call, the Sketch will not exit and the output file will be empty. + If you would like to draw 3D objects to a PDF or SVG file, use the ``P3D`` + renderer and the strategy described in ``begin_raw()``. """ pass @@ -13165,6 +13198,14 @@ def size(*args): * ``SVG``: The ``SVG`` renderer draws 2D graphics directly to an SVG file. This is great for importing into other vector programs or using for digital fabrication. + + When using the ``PDF`` and ``SVG`` renderers with the ``size()`` method, you + must use the ``path`` parameter to specify the file to write the output to. No + window will open while the Sketch is running. You must also call + ``exit_sketch()`` to exit the Sketch and write the completed output to the file. + Without this call, the Sketch will not exit and the output file will be empty. + If you would like to draw 3D objects to a PDF or SVG file, use the ``P3D`` + renderer and the strategy described in ``begin_raw()``. """ return _py5sketch.size(*args) @@ -17404,80 +17445,6 @@ def year() -> int: """ return Sketch.year() -############################################################################## -# module functions from print_tools.py -############################################################################## - - -def set_println_stream(println_stream: Any) -> None: - """Customize where the output of ``println()`` goes. - - Parameters - ---------- - - println_stream: Any - println stream object to be used by println method - - Notes - ----- - - Customize where the output of ``println()`` goes. - - When running a Sketch asynchronously through Jupyter Notebook, any ``print`` - statements using Python's builtin function will always appear in the output of - the currently active cell. This will rarely be desirable, as the active cell - will keep changing as the user executes code elsewhere in the notebook. The - ``println()`` method was created to provide users with print functionality in a - Sketch without having to cope with output moving from one cell to the next. Use - ``set_println_stream`` to change how the output is handled. The - ``println_stream`` object must provide ``init()`` and ``print()`` methods, as - shown in the example. The example demonstrates how to configure py5 to output - text to an IPython Widget. - """ - return _py5sketch.set_println_stream(println_stream) - - -def println( - *args, - sep: str = ' ', - end: str = '\n', - stderr: bool = False) -> None: - """Print text or other values to the screen. - - Parameters - ---------- - - args - values to be printed - - end: str = '\\n' - string appended after the last value, defaults to newline character - - sep: str = ' ' - string inserted between values, defaults to a space - - stderr: bool = False - use stderr instead of stdout - - Notes - ----- - - Print text or other values to the screen. For a Sketch running outside of a - Jupyter Notebook, this method will behave the same as the Python's builtin - ``print`` method. For Sketches running in a Jupyter Notebook, this will place - text in the output of the cell that made the ``run_sketch()`` call. - - When running a Sketch asynchronously through Jupyter Notebook, any ``print`` - statements using Python's builtin function will always appear in the output of - the currently active cell. This will rarely be desirable, as the active cell - will keep changing as the user executes code elsewhere in the notebook. This - method was created to provide users with print functionality in a Sketch without - having to cope with output moving from one cell to the next. - - Use ``set_println_stream()`` to customize the behavior of ``println()``. - """ - return _py5sketch.println(*args, sep=sep, end=end, stderr=stderr) - ############################################################################## # module functions from data.py ############################################################################## @@ -17567,1238 +17534,905 @@ def parse_json(serialized_json: Any, **kwargs: dict[str, Any]) -> Any: return Sketch.parse_json(serialized_json, **kwargs) ############################################################################## -# module functions from pixels.py +# module functions from math.py ############################################################################## -def load_np_pixels() -> None: - """Loads the pixel data of the current display window into the ``np_pixels[]`` - array. +def hex_color(color: int) -> str: + """Convert a color value to a hex color string. + + Parameters + ---------- + + color: int + any color value Notes ----- - Loads the pixel data of the current display window into the ``np_pixels[]`` - array. This method must always be called before reading from or writing to - ``np_pixels[]``. Subsequent changes to the display window will not be reflected - in ``np_pixels[]`` until ``load_np_pixels()`` is called again. - - The ``load_np_pixels()`` method is similar to ``load_pixels()`` in that - ``load_np_pixels()`` must be called before reading from or writing to - ``np_pixels[]`` just as ``load_pixels()`` must be called before reading from or - writing to ``pixels[]``. + Convert a color value to a hex color string. Processing and py5 store color + values in 32 bit integers that are inconvenient for a human to parse. To + interpret these values, one can use methods like ``red()``, ``green()``, and + ``blue()`` to extract color channel values from the 32 bit integers. This method + provides an alternative approach, converting the 32 bit integer into a string + such as ``'#0F3FF0FF'``. The hex string has 8 hexadecimal values following a + ``#`` character. The first two values represent the red value, the next two + green, the next two blue, and the last two alpha. This is consistent with CSS 8 + digit hex colors. - Note that ``load_np_pixels()`` will as a side effect call ``load_pixels()``, so - if your code needs to read ``np_pixels[]`` and ``pixels[]`` simultaneously, - there is no need for a separate call to ``load_pixels()``. However, be aware - that modifying both ``np_pixels[]`` and ``pixels[]`` simultaneously will likely - result in the updates to ``pixels[]`` being discarded. + Conveniently, the hex color string returned by this method can also be used as + parameter for other methods that accept color values. Observe how this is done + in the example code. """ - return _py5sketch.load_np_pixels() + return Sketch.hex_color(color) -def update_np_pixels() -> None: - """Updates the display window with the data in the ``np_pixels[]`` array. +def sin(angle: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """Calculates the sine of an angle. + + Parameters + ---------- + + angle: Union[float, npt.ArrayLike] + angle in radians Notes ----- - Updates the display window with the data in the ``np_pixels[]`` array. Use in - conjunction with ``load_np_pixels()``. If you're only reading pixels from the - array, there's no need to call ``update_np_pixels()`` — updating is only - necessary to apply changes. + Calculates the sine of an angle. This function expects the values of the angle + parameter to be provided in radians (values from ``0`` to ``TWO_PI``). Values + are returned in the range -1 to 1. - The ``update_np_pixels()`` method is similar to ``update_pixels()`` in that - ``update_np_pixels()`` must be called after modifying ``np_pixels[]`` just as - ``update_pixels()`` must be called after modifying ``pixels[]``. + This function makes a call to the numpy ``sin()`` function. """ - return _py5sketch.update_np_pixels() - - -np_pixels: npt.NDArray[np.uint8] = None + return Sketch.sin(angle) -def set_np_pixels(array: npt.NDArray[np.uint8], bands: str = 'ARGB') -> None: - """Set the entire contents of ``np_pixels[]`` to the contents of another properly - sized and typed numpy array. +def cos(angle: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """Calculates the cosine of an angle. Parameters ---------- - array: npt.NDArray[np.uint8] - properly sized numpy array to be copied to np_pixels[] - - bands: str = 'ARGB' - color channels in the array's third dimension + angle: Union[float, npt.ArrayLike] + angle in radians Notes ----- - Set the entire contents of ``np_pixels[]`` to the contents of another properly - sized and typed numpy array. The size of ``array``'s first and second dimensions - must match the height and width of the Sketch window, respectively. The array's - ``dtype`` must be ``np.uint8``. - - The ``bands`` parameter is used to interpret the ``array``'s color channel - dimension (the array's third dimension). It can be one of ``'L'`` (single- - channel grayscale), ``'ARGB'``, ``'RGB'``, or ``'RGBA'``. If there is no alpha - channel, ``array`` is assumed to have no transparency, but recall that the - display window's pixels can never be transparent so any transparency in - ``array`` will have no effect. If the ``bands`` parameter is ``'L'``, - ``array``'s third dimension is optional. - - This method makes its own calls to ``load_np_pixels()`` and - ``update_np_pixels()`` so there is no need to call either explicitly. + Calculates the cosine of an angle. This function expects the values of the angle + parameter to be provided in radians (values from ``0`` to ``TWO_PI``). Values + are returned in the range -1 to 1. - This method exists because setting the array contents with the code - ``py5.np_pixels = array`` will cause an error, while the correct syntax, - ``py5.np_pixels[:] = array``, might also be unintuitive for beginners. + This function makes a call to the numpy ``cos()`` function. """ - return _py5sketch.set_np_pixels(array, bands=bands) + return Sketch.cos(angle) -def save(filename: Union[str, - Path, - BytesIO], - *, - format: str = None, - drop_alpha: bool = True, - use_thread: bool = False, - **params) -> None: - """Save the drawing surface to an image file. +def tan(angle: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """Calculates the ratio of the sine and cosine of an angle. Parameters ---------- - drop_alpha: bool = True - remove the alpha channel when saving the image - - filename: Union[str, Path, BytesIO] - output filename - - format: str = None - image format, if not determined from filename extension - - params - keyword arguments to pass to the PIL.Image save method - - use_thread: bool = False - write file in separate thread + angle: Union[float, npt.ArrayLike] + angle in radians Notes ----- - Save the drawing surface to an image file. This method uses the Python library - Pillow to write the image, so it can save images in any format that that library - supports. - - Use the ``drop_alpha`` parameter to drop the alpha channel from the image. This - defaults to ``True``. Some image formats such as JPG do not support alpha - channels, and Pillow will throw an error if you try to save an image with the - alpha channel in that format. + Calculates the ratio of the sine and cosine of an angle. This function expects + the values of the angle parameter to be provided in radians (values from ``0`` + to ``TWO_PI``). Values are returned in the range infinity to -infinity. - The ``use_thread`` parameter will save the image in a separate Python thread. - This improves performance by returning before the image has actually been - written to the file. + This function makes a call to the numpy ``tan()`` function. """ - return _py5sketch.save( - filename, - format=format, - drop_alpha=drop_alpha, - use_thread=use_thread, - **params) - -############################################################################## -# module functions from threads.py -############################################################################## + return Sketch.tan(angle) -def launch_thread( - f: Callable, - name: str = None, - *, - daemon: bool = True, - args: tuple = None, - kwargs: dict = None) -> str: - """Launch a new thread to execute a function in parallel with your Sketch code. +def asin(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """The inverse of ``sin()``, returns the arc sine of a value. Parameters ---------- - args: tuple = None - positional arguments to pass to the given function + value: Union[float, npt.ArrayLike] + value in the range of -1 to 1 whose arc sine is to be returned - daemon: bool = True - if the thread should be a daemon thread + Notes + ----- - f: Callable - function to call in the launched thread + The inverse of ``sin()``, returns the arc sine of a value. This function expects + the values in the range of -1 to 1 and values are returned in the range + ``-HALF_PI`` to ``HALF_PI``. - kwargs: dict = None - keyword arguments to pass to the given function + This function makes a call to the numpy ``asin()`` function. + """ + return Sketch.asin(value) - name: str = None - name of thread to be created - Notes - ----- +def acos(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """The inverse of ``cos()``, returns the arc cosine of a value. - Launch a new thread to execute a function in parallel with your Sketch code. - This can be useful for executing non-py5 code that would otherwise slow down the - animation thread and reduce the Sketch's frame rate. + Parameters + ---------- - The ``name`` parameter is optional but useful if you want to monitor the thread - with other methods such as ``has_thread()``. If the provided ``name`` is - identical to an already running thread, the running thread will first be stopped - with a call to ``stop_thread()`` with the ``wait`` parameter equal to ``True``. + value: Union[float, npt.ArrayLike] + value in the range of -1 to 1 whose arc cosine is to be returned - Use the ``args`` and ``kwargs`` parameters to pass positional and keyword - arguments to the function. + Notes + ----- - Use the ``daemon`` parameter to make the launched thread a daemon that will run - without blocking Python from exiting. This parameter defaults to ``True``, - meaning that function execution can be interupted if the Python process exits. - Note that if the Python process continues running after the Sketch exits, which - is typically the case when using a Jupyter Notebook, this parameter won't have - any effect unless if you try to restart the Notebook kernel. Generally speaking, - setting this parameter to ``False`` causes problems but it is available for - those who really need it. See ``stop_all_threads()`` for a better approach to - exit threads. + The inverse of ``cos()``, returns the arc cosine of a value. This function + expects the values in the range of -1 to 1 and values are returned in the range + ``0`` to ``PI``. - The new thread is a Python thread, so all the usual caveats about the Global - Interpreter Lock (GIL) apply here. + This function makes a call to the numpy ``acos()`` function. """ - return _py5sketch.launch_thread( - f, name=name, daemon=daemon, args=args, kwargs=kwargs) + return Sketch.acos(value) -def launch_promise_thread( - f: Callable, - name: str = None, - *, - daemon: bool = True, - args: tuple = None, - kwargs: dict = None) -> Py5Promise: - """Create a ``Py5Promise`` object that will store the returned result of a function - when that function completes. +def atan(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """The inverse of ``tan()``, returns the arc tangent of a value. Parameters ---------- - args: tuple = None - positional arguments to pass to the given function - - daemon: bool = True - if the thread should be a daemon thread - - f: Callable - function to call in the launched thread - - kwargs: dict = None - keyword arguments to pass to the given function - - name: str = None - name of thread to be created + value: Union[float, npt.ArrayLike] + value whose arc tangent is to be returned Notes ----- - Create a ``Py5Promise`` object that will store the returned result of a function - when that function completes. This can be useful for executing non-py5 code that - would otherwise slow down the animation thread and reduce the Sketch's frame - rate. - - The ``Py5Promise`` object has an ``is_ready`` property that will be ``True`` - when the ``result`` property contains the value function ``f`` returned. Before - then, the ``result`` property will be ``None``. - - The ``name`` parameter is optional but useful if you want to monitor the thread - with other methods such as ``has_thread()``. If the provided ``name`` is - identical to an already running thread, the running thread will first be stopped - with a call to ``stop_thread()`` with the ``wait`` parameter equal to ``True``. - - Use the ``args`` and ``kwargs`` parameters to pass positional and keyword - arguments to the function. - - Use the ``daemon`` parameter to make the launched thread a daemon that will run - without blocking Python from exiting. This parameter defaults to ``True``, - meaning that function execution can be interupted if the Python process exits. - Note that if the Python process continues running after the Sketch exits, which - is typically the case when using a Jupyter Notebook, this parameter won't have - any effect unless if you try to restart the Notebook kernel. Generally speaking, - setting this parameter to ``False`` causes problems but it is available for - those who really need it. See ``stop_all_threads()`` for a better approach to - exit threads. + The inverse of ``tan()``, returns the arc tangent of a value. This function + expects the values in the range of -Infinity to Infinity and values are returned + in the range ``-HALF_PI`` to ``HALF_PI``. - The new thread is a Python thread, so all the usual caveats about the Global - Interpreter Lock (GIL) apply here. + This function makes a call to the numpy ``atan()`` function. """ - return _py5sketch.launch_promise_thread( - f, name=name, daemon=daemon, args=args, kwargs=kwargs) + return Sketch.atan(value) -def launch_repeating_thread(f: Callable, name: str = None, *, - time_delay: float = 0, daemon: bool = True, - args: tuple = None, kwargs: dict = None) -> str: - """Launch a new thread that will repeatedly execute a function in parallel with - your Sketch code. +def atan2(y: Union[float, npt.ArrayLike], x: Union[float, + npt.ArrayLike]) -> Union[float, npt.NDArray]: + """Calculates the angle (in radians) from a specified point to the coordinate + origin as measured from the positive x-axis. Parameters ---------- - args: tuple = None - positional arguments to pass to the given function - - daemon: bool = True - if the thread should be a daemon thread - - f: Callable - function to call in the launched thread - - kwargs: dict = None - keyword arguments to pass to the given function - - name: str = None - name of thread to be created + x: Union[float, npt.ArrayLike] + x-coordinate of the point - time_delay: float = 0 - time delay in seconds between calls to the given function + y: Union[float, npt.ArrayLike] + y-coordinate of the point Notes ----- - Launch a new thread that will repeatedly execute a function in parallel with - your Sketch code. This can be useful for executing non-py5 code that would - otherwise slow down the animation thread and reduce the Sketch's frame rate. - - Use the ``time_delay`` parameter to set the time in seconds between one call to - function ``f`` and the next call. Set this parameter to ``0`` if you want each - call to happen immediately after the previous call finishes. If the function - ``f`` takes longer than expected to finish, py5 will wait for it to finish - before making the next call. There will not be overlapping calls to function - ``f``. - - The ``name`` parameter is optional but useful if you want to monitor the thread - with other methods such as ``has_thread()``. If the provided ``name`` is - identical to an already running thread, the running thread will first be stopped - with a call to ``stop_thread()`` with the ``wait`` parameter equal to ``True``. - - Use the ``args`` and ``kwargs`` parameters to pass positional and keyword - arguments to the function. - - Use the ``daemon`` parameter to make the launched thread a daemon that will run - without blocking Python from exiting. This parameter defaults to ``True``, - meaning that function execution can be interupted if the Python process exits. - Note that if the Python process continues running after the Sketch exits, which - is typically the case when using a Jupyter Notebook, this parameter won't have - any effect unless if you try to restart the Notebook kernel. Generally speaking, - setting this parameter to ``False`` causes problems but it is available for - those who really need it. See ``stop_all_threads()`` for a better approach to - exit threads. + Calculates the angle (in radians) from a specified point to the coordinate + origin as measured from the positive x-axis. Values are returned as a float in + the range from ``PI`` to ``-PI``. The ``atan2()`` function is most often used + for orienting geometry to the position of the cursor. Note: The y-coordinate of + the point is the first parameter, and the x-coordinate is the second parameter, + due the the structure of calculating the tangent. - The new thread is a Python thread, so all the usual caveats about the Global - Interpreter Lock (GIL) apply here. + This function makes a call to the numpy ``atan2()`` function. """ - return _py5sketch.launch_repeating_thread( - f, - name=name, - time_delay=time_delay, - daemon=daemon, - args=args, - kwargs=kwargs) + return Sketch.atan2(y, x) -def has_thread(name: str) -> None: - """Determine if a thread of a given name exists and is currently running. +def degrees(radians: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """Converts a radian measurement to its corresponding value in degrees. Parameters ---------- - name: str - name of thread + radians: Union[float, npt.ArrayLike] + radian value to convert to degrees Notes ----- - Determine if a thread of a given name exists and is currently running. You can - get the list of all currently running threads with ``list_threads()``. + Converts a radian measurement to its corresponding value in degrees. Radians and + degrees are two ways of measuring the same thing. There are 360 degrees in a + circle and ``2*PI`` radians in a circle. For example, ``90° = PI/2 = + 1.5707964``. All trigonometric functions in py5 require their parameters to be + specified in radians. + + This function makes a call to the numpy ``degrees()`` function. """ - return _py5sketch.has_thread(name) + return Sketch.degrees(radians) -def stop_thread(name: str, wait: bool = False) -> None: - """Stop a thread of a given name. +def radians(degrees: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """Converts a degree measurement to its corresponding value in radians. Parameters ---------- - name: str - name of thread - - wait: bool = False - wait for thread to exit before returning + degrees: Union[float, npt.ArrayLike] + degree value to convert to radians Notes ----- - Stop a thread of a given name. The ``wait`` parameter determines if the method - call will return right away or wait for the thread to exit. - - This won't do anything useful if the thread was launched with either - ``launch_thread()`` or ``launch_promise_thread()`` and the ``wait`` parameter is - ``False``. Non-repeating threads are executed once and will stop when they - complete execution. Setting the ``wait`` parameter to ``True`` will merely block - until the thread exits on its own. Killing off a running thread in Python is - complicated and py5 cannot do that for you. If you want a thread to perform some - action repeatedly and be interuptable, use ``launch_repeating_thread()`` - instead. + Converts a degree measurement to its corresponding value in radians. Radians and + degrees are two ways of measuring the same thing. There are 360 degrees in a + circle and ``2*PI`` radians in a circle. For example, ``90° = PI/2 = + 1.5707964``. All trigonometric functions in py5 require their parameters to be + specified in radians. - Use ``has_thread()`` to determine if a thread of a given name exists and - ``list_threads()`` to get a list of all thread names. Use ``stop_all_threads()`` - to stop all threads. + This function makes a call to the numpy ``radians()`` function. """ - return _py5sketch.stop_thread(name, wait=wait) + return Sketch.radians(degrees) -def stop_all_threads(wait: bool = False) -> None: - """Stop all running threads. +def constrain(amt: Union[float, + npt.NDArray], + low: Union[float, + npt.NDArray], + high: Union[float, + npt.NDArray]) -> Union[float, + npt.NDArray]: + """Constrains a value to not exceed a maximum and minimum value. Parameters ---------- - wait: bool = False - wait for thread to exit before returning + amt: Union[float, npt.NDArray] + the value to constrain - Notes - ----- + high: Union[float, npt.NDArray] + minimum limit - Stop all running threads. The ``wait`` parameter determines if the method call - will return right away or wait for the threads to exit. - - When the Sketch shuts down, ``stop_all_threads(wait=False)`` is called for you. - If you would rather the Sketch waited for threads to exit, create an ``exiting`` - method and make a call to ``stop_all_threads(wait=True)``. - """ - return _py5sketch.stop_all_threads(wait=wait) - - -def list_threads() -> None: - """List the names of all of the currently running threads. + low: Union[float, npt.NDArray] + maximum limit Notes ----- - List the names of all of the currently running threads. The names of previously - launched threads that have exited will be removed from the list. + Constrains a value to not exceed a maximum and minimum value. """ - return _py5sketch.list_threads() - -############################################################################## -# module functions from math.py -############################################################################## + return Sketch.constrain(amt, low, high) -def hex_color(color: int) -> str: - """Convert a color value to a hex color string. +def remap(value: Union[float, + npt.NDArray], + start1: Union[float, + npt.NDArray], + stop1: Union[float, + npt.NDArray], + start2: Union[float, + npt.NDArray], + stop2: Union[float, + npt.NDArray]) -> Union[float, + npt.NDArray]: + """Re-maps a number from one range to another. Parameters ---------- - color: int - any color value + start1: Union[float, npt.NDArray] + lower bound of the value's current range + + start2: Union[float, npt.NDArray] + lower bound of the value's target range + + stop1: Union[float, npt.NDArray] + upper bound of the value's current range + + stop2: Union[float, npt.NDArray] + upper bound of the value's target range + + value: Union[float, npt.NDArray] + the incoming value to be converted Notes ----- - Convert a color value to a hex color string. Processing and py5 store color - values in 32 bit integers that are inconvenient for a human to parse. To - interpret these values, one can use methods like ``red()``, ``green()``, and - ``blue()`` to extract color channel values from the 32 bit integers. This method - provides an alternative approach, converting the 32 bit integer into a string - such as ``'#0F3FF0FF'``. The hex string has 8 hexadecimal values following a - ``#`` character. The first two values represent the red value, the next two - green, the next two blue, and the last two alpha. This is similar to web colors - except for the addition of the alpha channel. + Re-maps a number from one range to another. - Conveniently, the hex color string returned by this method can also be used as - parameter for other methods that accept color values. Observe how this is done - in the example code. + In the first example, the number 0.5 is converted from a value in the range of 0 + to 1 into a value that ranges from the left edge of the window (0) to the right + edge (``width``). + + As shown in the second example, numbers outside of the range are not clamped to + the minimum and maximum parameters values, because out-of-range values are often + intentional and useful. If that isn't what you want, try pairing this function + with ``constrain()``. + + In Processing this functionality is provided by ``map()`` but was renamed in py5 + because of a name conflict with a builtin Python function. """ - return Sketch.hex_color(color) + return Sketch.remap(value, start1, stop1, start2, stop2) -def sin(angle: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """Calculates the sine of an angle. +@overload +def dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], x2: Union[float, + npt.NDArray], y2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray]: + """Calculates the distance between two points. - Parameters - ---------- + Methods + ------- - angle: Union[float, npt.ArrayLike] - angle in radians + You can use any of the following signatures: - Notes - ----- + * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] + * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], z1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], z2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] - Calculates the sine of an angle. This function expects the values of the angle - parameter to be provided in radians (values from ``0`` to ``TWO_PI``). Values - are returned in the range -1 to 1. + Parameters + ---------- - This function makes a call to the numpy ``sin()`` function. - """ - return Sketch.sin(angle) + x1: Union[float, npt.NDArray] + x-coordinate of the first point + x2: Union[float, npt.NDArray] + x-coordinate of the second point -def cos(angle: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """Calculates the cosine of an angle. + y1: Union[float, npt.NDArray] + y-coordinate of the first point - Parameters - ---------- + y2: Union[float, npt.NDArray] + y-coordinate of the second point - angle: Union[float, npt.ArrayLike] - angle in radians + z1: Union[float, npt.NDArray] + z-coordinate of the first point + + z2: Union[float, npt.NDArray] + z-coordinate of the second point Notes ----- - Calculates the cosine of an angle. This function expects the values of the angle - parameter to be provided in radians (values from ``0`` to ``TWO_PI``). Values - are returned in the range -1 to 1. - - This function makes a call to the numpy ``cos()`` function. + Calculates the distance between two points. """ - return Sketch.cos(angle) + pass -def tan(angle: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """Calculates the ratio of the sine and cosine of an angle. +@overload +def dist(x1: Union[float, + npt.NDArray], + y1: Union[float, + npt.NDArray], + z1: Union[float, + npt.NDArray], + x2: Union[float, + npt.NDArray], + y2: Union[float, + npt.NDArray], + z2: Union[float, + npt.NDArray], + /) -> Union[float, + npt.NDArray]: + """Calculates the distance between two points. - Parameters - ---------- + Methods + ------- - angle: Union[float, npt.ArrayLike] - angle in radians + You can use any of the following signatures: - Notes - ----- + * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] + * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], z1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], z2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] - Calculates the ratio of the sine and cosine of an angle. This function expects - the values of the angle parameter to be provided in radians (values from ``0`` - to ``TWO_PI``). Values are returned in the range infinity to -infinity. + Parameters + ---------- - This function makes a call to the numpy ``tan()`` function. - """ - return Sketch.tan(angle) + x1: Union[float, npt.NDArray] + x-coordinate of the first point + x2: Union[float, npt.NDArray] + x-coordinate of the second point -def asin(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """The inverse of ``sin()``, returns the arc sine of a value. + y1: Union[float, npt.NDArray] + y-coordinate of the first point - Parameters - ---------- + y2: Union[float, npt.NDArray] + y-coordinate of the second point - value: Union[float, npt.ArrayLike] - value in the range of -1 to 1 whose arc sine is to be returned + z1: Union[float, npt.NDArray] + z-coordinate of the first point + + z2: Union[float, npt.NDArray] + z-coordinate of the second point Notes ----- - The inverse of ``sin()``, returns the arc sine of a value. This function expects - the values in the range of -1 to 1 and values are returned in the range - ``-HALF_PI`` to ``HALF_PI``. - - This function makes a call to the numpy ``asin()`` function. + Calculates the distance between two points. """ - return Sketch.asin(value) + pass -def acos(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """The inverse of ``cos()``, returns the arc cosine of a value. +def dist(*args: Union[float, npt.NDArray]) -> float: + """Calculates the distance between two points. - Parameters - ---------- + Methods + ------- - value: Union[float, npt.ArrayLike] - value in the range of -1 to 1 whose arc cosine is to be returned + You can use any of the following signatures: - Notes - ----- + * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] + * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], z1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], z2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] - The inverse of ``cos()``, returns the arc cosine of a value. This function - expects the values in the range of -1 to 1 and values are returned in the range - ``0`` to ``PI``. + Parameters + ---------- - This function makes a call to the numpy ``acos()`` function. - """ - return Sketch.acos(value) + x1: Union[float, npt.NDArray] + x-coordinate of the first point + x2: Union[float, npt.NDArray] + x-coordinate of the second point -def atan(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """The inverse of ``tan()``, returns the arc tangent of a value. + y1: Union[float, npt.NDArray] + y-coordinate of the first point - Parameters - ---------- + y2: Union[float, npt.NDArray] + y-coordinate of the second point - value: Union[float, npt.ArrayLike] - value whose arc tangent is to be returned + z1: Union[float, npt.NDArray] + z-coordinate of the first point + + z2: Union[float, npt.NDArray] + z-coordinate of the second point Notes ----- - The inverse of ``tan()``, returns the arc tangent of a value. This function - expects the values in the range of -Infinity to Infinity and values are returned - in the range ``-HALF_PI`` to ``HALF_PI``. - - This function makes a call to the numpy ``atan()`` function. + Calculates the distance between two points. """ - return Sketch.atan(value) + return Sketch.dist(*args) -def atan2(y: Union[float, npt.ArrayLike], x: Union[float, - npt.ArrayLike]) -> Union[float, npt.NDArray]: - """Calculates the angle (in radians) from a specified point to the coordinate - origin as measured from the positive x-axis. +def lerp(start: Union[float, + npt.NDArray], + stop: Union[float, + npt.NDArray], + amt: Union[float, + npt.NDArray]) -> Union[float, + npt.NDArray]: + """Calculates a number between two numbers at a specific increment. Parameters ---------- - x: Union[float, npt.ArrayLike] - x-coordinate of the point + amt: Union[float, npt.NDArray] + float between 0.0 and 1.0 - y: Union[float, npt.ArrayLike] - y-coordinate of the point + start: Union[float, npt.NDArray] + first value + + stop: Union[float, npt.NDArray] + second value Notes ----- - Calculates the angle (in radians) from a specified point to the coordinate - origin as measured from the positive x-axis. Values are returned as a float in - the range from ``PI`` to ``-PI``. The ``atan2()`` function is most often used - for orienting geometry to the position of the cursor. Note: The y-coordinate of - the point is the first parameter, and the x-coordinate is the second parameter, - due the the structure of calculating the tangent. - - This function makes a call to the numpy ``atan2()`` function. + Calculates a number between two numbers at a specific increment. The ``amt`` + parameter is the amount to interpolate between the two values where 0.0 equal to + the first point, 0.1 is very near the first point, 0.5 is half-way in between, + etc. The lerp function is convenient for creating motion along a straight path + and for drawing dotted lines. If the ``amt`` parameter is greater than 1.0 or + less than 0.0, the interpolated value will be outside of the range specified by + the ``start`` and ``stop`` parameter values. """ - return Sketch.atan2(y, x) + return Sketch.lerp(start, stop, amt) -def degrees(radians: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """Converts a radian measurement to its corresponding value in degrees. +@overload +def mag(a: Union[float, npt.NDArray], + b: Union[float, npt.NDArray], /) -> float: + """Calculates the magnitude (or length) of a vector. + + Methods + ------- + + You can use any of the following signatures: + + * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], /) -> float + * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], c: Union[float, npt.NDArray], /) -> float Parameters ---------- - radians: Union[float, npt.ArrayLike] - radian value to convert to degrees + a: Union[float, npt.NDArray] + first value + + b: Union[float, npt.NDArray] + second value + + c: Union[float, npt.NDArray] + third value Notes ----- - Converts a radian measurement to its corresponding value in degrees. Radians and - degrees are two ways of measuring the same thing. There are 360 degrees in a - circle and ``2*PI`` radians in a circle. For example, ``90° = PI/2 = - 1.5707964``. All trigonometric functions in py5 require their parameters to be - specified in radians. - - This function makes a call to the numpy ``degrees()`` function. + Calculates the magnitude (or length) of a vector. A vector is a direction in + space commonly used in computer graphics and linear algebra. Because it has no + "start" position, the magnitude of a vector can be thought of as the distance + from the coordinate ``(0, 0)`` to its ``(x, y)`` value. Therefore, ``mag()`` is + a shortcut for writing ``dist(0, 0, x, y)``. """ - return Sketch.degrees(radians) + pass -def radians(degrees: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """Converts a degree measurement to its corresponding value in radians. +@overload +def mag(a: Union[float, npt.NDArray], b: Union[float, + npt.NDArray], c: Union[float, npt.NDArray], /) -> float: + """Calculates the magnitude (or length) of a vector. + + Methods + ------- + + You can use any of the following signatures: + + * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], /) -> float + * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], c: Union[float, npt.NDArray], /) -> float Parameters ---------- - degrees: Union[float, npt.ArrayLike] - degree value to convert to radians + a: Union[float, npt.NDArray] + first value + + b: Union[float, npt.NDArray] + second value + + c: Union[float, npt.NDArray] + third value Notes ----- - Converts a degree measurement to its corresponding value in radians. Radians and - degrees are two ways of measuring the same thing. There are 360 degrees in a - circle and ``2*PI`` radians in a circle. For example, ``90° = PI/2 = - 1.5707964``. All trigonometric functions in py5 require their parameters to be - specified in radians. - - This function makes a call to the numpy ``radians()`` function. + Calculates the magnitude (or length) of a vector. A vector is a direction in + space commonly used in computer graphics and linear algebra. Because it has no + "start" position, the magnitude of a vector can be thought of as the distance + from the coordinate ``(0, 0)`` to its ``(x, y)`` value. Therefore, ``mag()`` is + a shortcut for writing ``dist(0, 0, x, y)``. """ - return Sketch.radians(degrees) + pass -def constrain(amt: Union[float, - npt.NDArray], - low: Union[float, - npt.NDArray], - high: Union[float, - npt.NDArray]) -> Union[float, - npt.NDArray]: - """Constrains a value to not exceed a maximum and minimum value. +def mag(*args: Union[float, npt.NDArray]) -> float: + """Calculates the magnitude (or length) of a vector. + + Methods + ------- + + You can use any of the following signatures: + + * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], /) -> float + * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], c: Union[float, npt.NDArray], /) -> float Parameters ---------- - amt: Union[float, npt.NDArray] - the value to constrain + a: Union[float, npt.NDArray] + first value - high: Union[float, npt.NDArray] - minimum limit + b: Union[float, npt.NDArray] + second value - low: Union[float, npt.NDArray] - maximum limit + c: Union[float, npt.NDArray] + third value Notes ----- - Constrains a value to not exceed a maximum and minimum value. + Calculates the magnitude (or length) of a vector. A vector is a direction in + space commonly used in computer graphics and linear algebra. Because it has no + "start" position, the magnitude of a vector can be thought of as the distance + from the coordinate ``(0, 0)`` to its ``(x, y)`` value. Therefore, ``mag()`` is + a shortcut for writing ``dist(0, 0, x, y)``. """ - return Sketch.constrain(amt, low, high) + return Sketch.mag(*args) -def remap(value: Union[float, - npt.NDArray], - start1: Union[float, - npt.NDArray], - stop1: Union[float, - npt.NDArray], - start2: Union[float, - npt.NDArray], - stop2: Union[float, - npt.NDArray]) -> Union[float, - npt.NDArray]: - """Re-maps a number from one range to another. +def norm(value: Union[float, + npt.NDArray], + start: Union[float, + npt.NDArray], + stop: Union[float, + npt.NDArray]) -> Union[float, + npt.NDArray]: + """Normalizes a number from another range into a value between 0 and 1. Parameters ---------- - start1: Union[float, npt.NDArray] + start: Union[float, npt.NDArray] lower bound of the value's current range - start2: Union[float, npt.NDArray] - lower bound of the value's target range - - stop1: Union[float, npt.NDArray] + stop: Union[float, npt.NDArray] upper bound of the value's current range - stop2: Union[float, npt.NDArray] - upper bound of the value's target range - value: Union[float, npt.NDArray] the incoming value to be converted Notes ----- - Re-maps a number from one range to another. + Normalizes a number from another range into a value between 0 and 1. Identical + to ``remap(value, low, high, 0, 1)``. - In the first example, the number 0.5 is converted from a value in the range of 0 - to 1 into a value that ranges from the left edge of the window (0) to the right - edge (``width``). + Numbers outside of the range are not clamped to 0 and 1, because out-of-range + values are often intentional and useful. (See the second example.) If that isn't + what you want, try pairing this function with ``constrain()``. + """ + return Sketch.norm(value, start, stop) - As shown in the second example, numbers outside of the range are not clamped to - the minimum and maximum parameters values, because out-of-range values are often - intentional and useful. If that isn't what you want, try pairing this function - with ``constrain()``. - In Processing this functionality is provided by ``map()`` but was renamed in py5 - because of a name conflict with a builtin Python function. - """ - return Sketch.remap(value, start1, stop1, start2, stop2) +def sq(value: Union[float, npt.NDArray]) -> Union[float, npt.NDArray]: + """Squares a number (multiplies a number by itself). + + Parameters + ---------- + value: Union[float, npt.NDArray] + number to square -@overload -def dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], x2: Union[float, - npt.NDArray], y2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray]: - """Calculates the distance between two points. + Notes + ----- - Methods - ------- + Squares a number (multiplies a number by itself). The result is always a + positive number, as multiplying two negative numbers always yields a positive + result. For example, ``-1 * -1 = 1``. + """ + return Sketch.sq(value) - You can use any of the following signatures: - * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] - * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], z1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], z2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] +def sqrt(value: Union[float, npt.NDArray] + ) -> Union[float, complex, npt.NDArray]: + """Calculates the square root of a number. Parameters ---------- - x1: Union[float, npt.NDArray] - x-coordinate of the first point + value: Union[float, npt.NDArray] + value to calculate the square root of - x2: Union[float, npt.NDArray] - x-coordinate of the second point + Notes + ----- - y1: Union[float, npt.NDArray] - y-coordinate of the first point + Calculates the square root of a number. The square root of a positive number is + always positive, even though there may be a valid negative root. The square root + of a negative number is a complex number. In either case, the square root ``s`` + of number ``a`` is such that ``s*s = a``. It is the opposite of squaring. - y2: Union[float, npt.NDArray] - y-coordinate of the second point + Python supports complex numbers, but such values cannot be passed to py5 drawing + functions. When using the ``sqrt()`` function, you should check if the result is + complex before using the value. You can also extract the real and imaginary + components of the complex value with ``.real`` and ``.imag``. See the second + example to learn how to do both of these things. + """ + return Sketch.sqrt(value) - z1: Union[float, npt.NDArray] - z-coordinate of the first point - z2: Union[float, npt.NDArray] - z-coordinate of the second point +def floor(value: Union[float, npt.ArrayLike]) -> Union[int, npt.NDArray]: + """Calculates the closest int value that is less than or equal to the value of the + parameter. + + Parameters + ---------- + + value: Union[float, npt.ArrayLike] + number to round down Notes ----- - Calculates the distance between two points. - """ - pass + Calculates the closest int value that is less than or equal to the value of the + parameter. + This function makes a call to the numpy ``floor()`` function. + """ + return Sketch.floor(value) -@overload -def dist(x1: Union[float, - npt.NDArray], - y1: Union[float, - npt.NDArray], - z1: Union[float, - npt.NDArray], - x2: Union[float, - npt.NDArray], - y2: Union[float, - npt.NDArray], - z2: Union[float, - npt.NDArray], - /) -> Union[float, - npt.NDArray]: - """Calculates the distance between two points. - - Methods - ------- - - You can use any of the following signatures: - * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] - * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], z1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], z2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] +def ceil(value: Union[float, npt.ArrayLike]) -> Union[int, npt.NDArray]: + """Calculates the closest int value that is greater than or equal to the value of + the parameter. Parameters ---------- - x1: Union[float, npt.NDArray] - x-coordinate of the first point - - x2: Union[float, npt.NDArray] - x-coordinate of the second point - - y1: Union[float, npt.NDArray] - y-coordinate of the first point - - y2: Union[float, npt.NDArray] - y-coordinate of the second point - - z1: Union[float, npt.NDArray] - z-coordinate of the first point - - z2: Union[float, npt.NDArray] - z-coordinate of the second point + value: Union[float, npt.ArrayLike] + number to round up Notes ----- - Calculates the distance between two points. - """ - pass - - -def dist(*args: Union[float, npt.NDArray]) -> float: - """Calculates the distance between two points. + Calculates the closest int value that is greater than or equal to the value of + the parameter. - Methods - ------- + This function makes a call to the numpy ``ceil()`` function. + """ + return Sketch.ceil(value) - You can use any of the following signatures: - * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] - * dist(x1: Union[float, npt.NDArray], y1: Union[float, npt.NDArray], z1: Union[float, npt.NDArray], x2: Union[float, npt.NDArray], y2: Union[float, npt.NDArray], z2: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] +def exp(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """Returns Euler's number e (2.71828...) raised to the power of the ``n`` + parameter. Parameters ---------- - x1: Union[float, npt.NDArray] - x-coordinate of the first point + value: Union[float, npt.ArrayLike] + exponent to raise - x2: Union[float, npt.NDArray] - x-coordinate of the second point + Notes + ----- - y1: Union[float, npt.NDArray] - y-coordinate of the first point + Returns Euler's number e (2.71828...) raised to the power of the ``n`` + parameter. This function is the compliment to ``log()``. - y2: Union[float, npt.NDArray] - y-coordinate of the second point + This function makes a call to the numpy ``exp()`` function. + """ + return Sketch.exp(value) - z1: Union[float, npt.NDArray] - z-coordinate of the first point - z2: Union[float, npt.NDArray] - z-coordinate of the second point +def log(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: + """Calculates the natural logarithm (the base-e logarithm) of a number. + + Parameters + ---------- + + value: Union[float, npt.ArrayLike] + number greater than 0.0 Notes ----- - Calculates the distance between two points. + Calculates the natural logarithm (the base-e logarithm) of a number. This + function expects the ``n`` parameter to be a value greater than 0.0. This + function is the compliment to ``exp()``. + + This function makes a call to the numpy ``log()`` function. If the ``n`` + parameter is less than or equal to 0.0, you will see a ``RuntimeWarning`` and + the returned result will be numpy's Not-a-Number value, ``np.nan``. """ - return Sketch.dist(*args) + return Sketch.log(value) -def lerp(start: Union[float, - npt.NDArray], - stop: Union[float, - npt.NDArray], - amt: Union[float, - npt.NDArray]) -> Union[float, - npt.NDArray]: - """Calculates a number between two numbers at a specific increment. +np_random: np.random.Generator = None - Parameters - ---------- - amt: Union[float, npt.NDArray] - float between 0.0 and 1.0 +def random_seed(seed: int) -> None: + """Sets the seed value for py5's random functions. - start: Union[float, npt.NDArray] - first value + Parameters + ---------- - stop: Union[float, npt.NDArray] - second value + seed: int + seed value Notes ----- - Calculates a number between two numbers at a specific increment. The ``amt`` - parameter is the amount to interpolate between the two values where 0.0 equal to - the first point, 0.1 is very near the first point, 0.5 is half-way in between, - etc. The lerp function is convenient for creating motion along a straight path - and for drawing dotted lines. If the ``amt`` parameter is greater than 1.0 or - less than 0.0, the interpolated value will be outside of the range specified by - the ``start`` and ``stop`` parameter values. + Sets the seed value for py5's random functions. This includes ``random()``, + ``random_int()``, ``random_choice()``, and ``random_gaussian()``. By default, + all of these functions would produce different results each time a program is + run. Set the seed parameter to a constant value to return the same pseudo-random + numbers each time the software is run. """ - return Sketch.lerp(start, stop, amt) + return _py5sketch.random_seed(seed) @overload -def mag(a: Union[float, npt.NDArray], - b: Union[float, npt.NDArray], /) -> float: - """Calculates the magnitude (or length) of a vector. +def random() -> float: + """Generates random numbers. Methods ------- You can use any of the following signatures: - * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], /) -> float - * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], c: Union[float, npt.NDArray], /) -> float + * random() -> float + * random(high: float, /) -> float + * random(low: float, high: float, /) -> float Parameters ---------- - a: Union[float, npt.NDArray] - first value - - b: Union[float, npt.NDArray] - second value + high: float + upper limit - c: Union[float, npt.NDArray] - third value + low: float + lower limit Notes ----- - Calculates the magnitude (or length) of a vector. A vector is a direction in - space commonly used in computer graphics and linear algebra. Because it has no - "start" position, the magnitude of a vector can be thought of as the distance - from the coordinate ``(0, 0)`` to its ``(x, y)`` value. Therefore, ``mag()`` is - a shortcut for writing ``dist(0, 0, x, y)``. + Generates random numbers. Each time the ``random()`` function is called, it + returns an unexpected value within the specified range. This function's + randomness can be influenced by ``random_seed()``. + + If no parameters are passed to the function, it will return a float between zero + and one. + + If only one parameter is passed to the function, it will return a float between + zero and the value of the ``high`` parameter. For example, ``random(5)`` returns + values between 0 and 5 (starting at zero, and up to, but not including, 5). + + If two parameters are specified, the function will return a float with a value + between the two values. For example, ``random(-5, 10.2)`` returns values + starting at -5 and up to (but not including) 10.2. To convert a floating-point + random number to an integer, use the ``int()`` function, or alternatively, + consider using ``random_int()``. + + This function makes calls to numpy to generate the random values. """ pass @overload -def mag(a: Union[float, npt.NDArray], b: Union[float, - npt.NDArray], c: Union[float, npt.NDArray], /) -> float: - """Calculates the magnitude (or length) of a vector. +def random(high: float, /) -> float: + """Generates random numbers. Methods ------- You can use any of the following signatures: - * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], /) -> float - * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], c: Union[float, npt.NDArray], /) -> float + * random() -> float + * random(high: float, /) -> float + * random(low: float, high: float, /) -> float Parameters ---------- - a: Union[float, npt.NDArray] - first value - - b: Union[float, npt.NDArray] - second value + high: float + upper limit - c: Union[float, npt.NDArray] - third value + low: float + lower limit Notes ----- - Calculates the magnitude (or length) of a vector. A vector is a direction in - space commonly used in computer graphics and linear algebra. Because it has no - "start" position, the magnitude of a vector can be thought of as the distance - from the coordinate ``(0, 0)`` to its ``(x, y)`` value. Therefore, ``mag()`` is - a shortcut for writing ``dist(0, 0, x, y)``. + Generates random numbers. Each time the ``random()`` function is called, it + returns an unexpected value within the specified range. This function's + randomness can be influenced by ``random_seed()``. + + If no parameters are passed to the function, it will return a float between zero + and one. + + If only one parameter is passed to the function, it will return a float between + zero and the value of the ``high`` parameter. For example, ``random(5)`` returns + values between 0 and 5 (starting at zero, and up to, but not including, 5). + + If two parameters are specified, the function will return a float with a value + between the two values. For example, ``random(-5, 10.2)`` returns values + starting at -5 and up to (but not including) 10.2. To convert a floating-point + random number to an integer, use the ``int()`` function, or alternatively, + consider using ``random_int()``. + + This function makes calls to numpy to generate the random values. """ pass -def mag(*args: Union[float, npt.NDArray]) -> float: - """Calculates the magnitude (or length) of a vector. +@overload +def random(low: float, high: float, /) -> float: + """Generates random numbers. Methods ------- You can use any of the following signatures: - * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], /) -> float - * mag(a: Union[float, npt.NDArray], b: Union[float, npt.NDArray], c: Union[float, npt.NDArray], /) -> float + * random() -> float + * random(high: float, /) -> float + * random(low: float, high: float, /) -> float Parameters ---------- - a: Union[float, npt.NDArray] - first value - - b: Union[float, npt.NDArray] - second value + high: float + upper limit - c: Union[float, npt.NDArray] - third value - - Notes - ----- - - Calculates the magnitude (or length) of a vector. A vector is a direction in - space commonly used in computer graphics and linear algebra. Because it has no - "start" position, the magnitude of a vector can be thought of as the distance - from the coordinate ``(0, 0)`` to its ``(x, y)`` value. Therefore, ``mag()`` is - a shortcut for writing ``dist(0, 0, x, y)``. - """ - return Sketch.mag(*args) - - -def norm(value: Union[float, - npt.NDArray], - start: Union[float, - npt.NDArray], - stop: Union[float, - npt.NDArray]) -> Union[float, - npt.NDArray]: - """Normalizes a number from another range into a value between 0 and 1. - - Parameters - ---------- - - start: Union[float, npt.NDArray] - lower bound of the value's current range - - stop: Union[float, npt.NDArray] - upper bound of the value's current range - - value: Union[float, npt.NDArray] - the incoming value to be converted - - Notes - ----- - - Normalizes a number from another range into a value between 0 and 1. Identical - to ``remap(value, low, high, 0, 1)``. - - Numbers outside of the range are not clamped to 0 and 1, because out-of-range - values are often intentional and useful. (See the second example.) If that isn't - what you want, try pairing this function with ``constrain()``. - """ - return Sketch.norm(value, start, stop) - - -def sq(value: Union[float, npt.NDArray]) -> Union[float, npt.NDArray]: - """Squares a number (multiplies a number by itself). - - Parameters - ---------- - - value: Union[float, npt.NDArray] - number to square - - Notes - ----- - - Squares a number (multiplies a number by itself). The result is always a - positive number, as multiplying two negative numbers always yields a positive - result. For example, ``-1 * -1 = 1``. - """ - return Sketch.sq(value) - - -def sqrt(value: Union[float, npt.NDArray] - ) -> Union[float, complex, npt.NDArray]: - """Calculates the square root of a number. - - Parameters - ---------- - - value: Union[float, npt.NDArray] - value to calculate the square root of - - Notes - ----- - - Calculates the square root of a number. The square root of a positive number is - always positive, even though there may be a valid negative root. The square root - of a negative number is a complex number. In either case, the square root ``s`` - of number ``a`` is such that ``s*s = a``. It is the opposite of squaring. - - Python supports complex numbers, but such values cannot be passed to py5 drawing - functions. When using the ``sqrt()`` function, you should check if the result is - complex before using the value. You can also extract the real and imaginary - components of the complex value with ``.real`` and ``.imag``. See the second - example to learn how to do both of these things. - """ - return Sketch.sqrt(value) - - -def floor(value: Union[float, npt.ArrayLike]) -> Union[int, npt.NDArray]: - """Calculates the closest int value that is less than or equal to the value of the - parameter. - - Parameters - ---------- - - value: Union[float, npt.ArrayLike] - number to round down - - Notes - ----- - - Calculates the closest int value that is less than or equal to the value of the - parameter. - - This function makes a call to the numpy ``floor()`` function. - """ - return Sketch.floor(value) - - -def ceil(value: Union[float, npt.ArrayLike]) -> Union[int, npt.NDArray]: - """Calculates the closest int value that is greater than or equal to the value of - the parameter. - - Parameters - ---------- - - value: Union[float, npt.ArrayLike] - number to round up - - Notes - ----- - - Calculates the closest int value that is greater than or equal to the value of - the parameter. - - This function makes a call to the numpy ``ceil()`` function. - """ - return Sketch.ceil(value) - - -def exp(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """Returns Euler's number e (2.71828...) raised to the power of the ``n`` - parameter. - - Parameters - ---------- - - value: Union[float, npt.ArrayLike] - exponent to raise - - Notes - ----- - - Returns Euler's number e (2.71828...) raised to the power of the ``n`` - parameter. This function is the compliment to ``log()``. - - This function makes a call to the numpy ``exp()`` function. - """ - return Sketch.exp(value) - - -def log(value: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]: - """Calculates the natural logarithm (the base-e logarithm) of a number. - - Parameters - ---------- - - value: Union[float, npt.ArrayLike] - number greater than 0.0 - - Notes - ----- - - Calculates the natural logarithm (the base-e logarithm) of a number. This - function expects the ``n`` parameter to be a value greater than 0.0. This - function is the compliment to ``exp()``. - - This function makes a call to the numpy ``log()`` function. If the ``n`` - parameter is less than or equal to 0.0, you will see a ``RuntimeWarning`` and - the returned result will be numpy's Not-a-Number value, ``np.nan``. - """ - return Sketch.log(value) - - -np_random: np.random.Generator = None - - -def random_seed(seed: int) -> None: - """Sets the seed value for py5's random functions. - - Parameters - ---------- - - seed: int - seed value - - Notes - ----- - - Sets the seed value for py5's random functions. This includes ``random()``, - ``random_int()``, ``random_choice()``, and ``random_gaussian()``. By default, - all of these functions would produce different results each time a program is - run. Set the seed parameter to a constant value to return the same pseudo-random - numbers each time the software is run. - """ - return _py5sketch.random_seed(seed) - - -@overload -def random() -> float: - """Generates random numbers. - - Methods - ------- - - You can use any of the following signatures: - - * random() -> float - * random(high: float, /) -> float - * random(low: float, high: float, /) -> float - - Parameters - ---------- - - high: float - upper limit - - low: float - lower limit + low: float + lower limit Notes ----- @@ -18825,8 +18459,7 @@ def random() -> float: pass -@overload -def random(high: float, /) -> float: +def random(*args: float) -> float: """Generates random numbers. Methods @@ -18869,138 +18502,45 @@ def random(high: float, /) -> float: This function makes calls to numpy to generate the random values. """ - pass + return _py5sketch.random(*args) @overload -def random(low: float, high: float, /) -> float: - """Generates random numbers. +def random_int() -> int: + """Generates random integers. Methods ------- You can use any of the following signatures: - * random() -> float - * random(high: float, /) -> float - * random(low: float, high: float, /) -> float + * random_int() -> int + * random_int(high: int, /) -> int + * random_int(low: int, high: int, /) -> int Parameters ---------- - high: float + high: int upper limit - low: float + low: int lower limit Notes ----- - Generates random numbers. Each time the ``random()`` function is called, it - returns an unexpected value within the specified range. This function's + Generates random integers. Each time the ``random_int()`` function is called, it + returns an unexpected integer within the specified range. This function's randomness can be influenced by ``random_seed()``. - If no parameters are passed to the function, it will return a float between zero - and one. + If no parameters are passed to the function, it will return either 0 or 1. + Recall that in a Python boolean expression, 0 evaluates to ``False`` and 1 + evaluates to ``True``. This is equivalent to a coin toss. - If only one parameter is passed to the function, it will return a float between - zero and the value of the ``high`` parameter. For example, ``random(5)`` returns - values between 0 and 5 (starting at zero, and up to, but not including, 5). - - If two parameters are specified, the function will return a float with a value - between the two values. For example, ``random(-5, 10.2)`` returns values - starting at -5 and up to (but not including) 10.2. To convert a floating-point - random number to an integer, use the ``int()`` function, or alternatively, - consider using ``random_int()``. - - This function makes calls to numpy to generate the random values. - """ - pass - - -def random(*args: float) -> float: - """Generates random numbers. - - Methods - ------- - - You can use any of the following signatures: - - * random() -> float - * random(high: float, /) -> float - * random(low: float, high: float, /) -> float - - Parameters - ---------- - - high: float - upper limit - - low: float - lower limit - - Notes - ----- - - Generates random numbers. Each time the ``random()`` function is called, it - returns an unexpected value within the specified range. This function's - randomness can be influenced by ``random_seed()``. - - If no parameters are passed to the function, it will return a float between zero - and one. - - If only one parameter is passed to the function, it will return a float between - zero and the value of the ``high`` parameter. For example, ``random(5)`` returns - values between 0 and 5 (starting at zero, and up to, but not including, 5). - - If two parameters are specified, the function will return a float with a value - between the two values. For example, ``random(-5, 10.2)`` returns values - starting at -5 and up to (but not including) 10.2. To convert a floating-point - random number to an integer, use the ``int()`` function, or alternatively, - consider using ``random_int()``. - - This function makes calls to numpy to generate the random values. - """ - return _py5sketch.random(*args) - - -@overload -def random_int() -> int: - """Generates random integers. - - Methods - ------- - - You can use any of the following signatures: - - * random_int() -> int - * random_int(high: int, /) -> int - * random_int(low: int, high: int, /) -> int - - Parameters - ---------- - - high: int - upper limit - - low: int - lower limit - - Notes - ----- - - Generates random integers. Each time the ``random_int()`` function is called, it - returns an unexpected integer within the specified range. This function's - randomness can be influenced by ``random_seed()``. - - If no parameters are passed to the function, it will return either 0 or 1. - Recall that in a Python boolean expression, 0 evaluates to ``False`` and 1 - evaluates to ``True``. This is equivalent to a coin toss. - - If only one parameter is passed to the function, it will return an integer - between zero and the value of the ``high`` parameter, inclusive. For example, - ``random(5)`` returns one of 0, 1, 2, 3, 4, or 5. + If only one parameter is passed to the function, it will return an integer + between zero and the value of the ``high`` parameter, inclusive. For example, + ``random(5)`` returns one of 0, 1, 2, 3, 4, or 5. If two parameters are specified, the function will return an integer with a value between the two values, inclusive. For example, ``random(2, 5)`` returns @@ -19952,162 +19492,663 @@ def os_noise(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], z: Unio Parameters ---------- - w: Union[float, npt.NDArray] - w-coordinate in noise space + w: Union[float, npt.NDArray] + w-coordinate in noise space + + x: Union[float, npt.NDArray] + x-coordinate in noise space + + y: Union[float, npt.NDArray] + y-coordinate in noise space + + z: Union[float, npt.NDArray] + z-coordinate in noise space + + Notes + ----- + + Generate pseudo-random noise values for specific coodinates using the + OpenSimplex 2 algorithm (smooth version / SuperSimplex). Noise functions are + random sequence generators that produce a more natural, harmonic succession of + numbers compared to the ``random()`` method. + + In contrast to the ``random()`` method, noise is defined in an n-dimensional + space, in which each coordinate corresponds to a fixed pseudo-random value + (fixed only for the lifespan of the program). The noise value can be animated by + moving through the noise space, as demonstrated in the examples. Any dimension + can also be interpreted as time. An easy way to animate the noise value is to + pass the ``os_noise()`` method the ``frame_count`` divided by a scaling factor, + as is done in a few of the examples. + + The generated noise values for this method will be between -1 and 1, and can be + generated in 2, 3, or 4 dimensions. To generate noise in 1 dimension, add a + constant value as an extra parameter, as shown in a few examples. Py5 also + provides the ``noise()`` method, which generates noise using Processing's noise + algorithm. That algorithm typically generates noise values between 0 and 1, and + can be generated in 1, 2, or 3 dimensions. Be aware of both of these differences + when modifying your code to switch from one to the other. There are other + differences in the character of the noise values generated by both methods, so + you'll need to do some experimentation to get the results you want. + + The nature of the noise values returned can be adjusted with + ``os_noise_seed()``. + + Another way to adjust the character of the resulting sequence is the scale of + the input coordinates. As the method works within an infinite space, the value + of the coordinates doesn't matter as such; only the distance between successive + coordinates is important. As a general rule, the smaller the difference between + coordinates, the smoother the resulting noise sequence. Steps of 0.005-0.03 work + best for most applications, but this will differ depending on the use case and + the noise settings. + + Py5's ``os_noise()`` method can also accept numpy arrays as parameters. It will + use broadcasting when needed and calculate the values efficiently. Using numpy + array parameters will be much faster and efficient than calling the + ``os_noise()`` method repeatedly in a loop. See the examples to see how this can + be done. The noise algorithm for this method is implemented in Java. + + Noise generation is a rich and complex topic, and there are many noise + algorithms and libraries available that are worth learning about. Early versions + of py5 used the Python "noise" library, which can generate noise using the + "Improved Perlin Noise" algorithm (as described in Ken Perlin's 2002 SIGGRAPH + paper) and the Simplex Noise algorithm (also developed by Ken Perlin). That + Python library was removed from py5 because it has some bugs and hasn't had a + release in years. Nevertheless, it might be useful to you, and can be installed + separately like any other Python package. You can also try the Python library + "vnoise", which is a pure Python implementation of the Improved Perlin Noise + algorithm. Note that py5 can also employ Java libraries, so consider "FastNoise + Lite" to experiment with a large selection of noise algorithms with efficient + implementations. + """ + pass + + +def os_noise(*args) -> Union[float, npt.NDArray]: + """Generate pseudo-random noise values for specific coodinates using the + OpenSimplex 2 algorithm (smooth version / SuperSimplex). + + Methods + ------- + + You can use any of the following signatures: + + * os_noise(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] + * os_noise(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], z: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] + * os_noise(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], z: Union[float, npt.NDArray], w: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] + + Parameters + ---------- + + w: Union[float, npt.NDArray] + w-coordinate in noise space + + x: Union[float, npt.NDArray] + x-coordinate in noise space + + y: Union[float, npt.NDArray] + y-coordinate in noise space + + z: Union[float, npt.NDArray] + z-coordinate in noise space + + Notes + ----- + + Generate pseudo-random noise values for specific coodinates using the + OpenSimplex 2 algorithm (smooth version / SuperSimplex). Noise functions are + random sequence generators that produce a more natural, harmonic succession of + numbers compared to the ``random()`` method. + + In contrast to the ``random()`` method, noise is defined in an n-dimensional + space, in which each coordinate corresponds to a fixed pseudo-random value + (fixed only for the lifespan of the program). The noise value can be animated by + moving through the noise space, as demonstrated in the examples. Any dimension + can also be interpreted as time. An easy way to animate the noise value is to + pass the ``os_noise()`` method the ``frame_count`` divided by a scaling factor, + as is done in a few of the examples. + + The generated noise values for this method will be between -1 and 1, and can be + generated in 2, 3, or 4 dimensions. To generate noise in 1 dimension, add a + constant value as an extra parameter, as shown in a few examples. Py5 also + provides the ``noise()`` method, which generates noise using Processing's noise + algorithm. That algorithm typically generates noise values between 0 and 1, and + can be generated in 1, 2, or 3 dimensions. Be aware of both of these differences + when modifying your code to switch from one to the other. There are other + differences in the character of the noise values generated by both methods, so + you'll need to do some experimentation to get the results you want. + + The nature of the noise values returned can be adjusted with + ``os_noise_seed()``. + + Another way to adjust the character of the resulting sequence is the scale of + the input coordinates. As the method works within an infinite space, the value + of the coordinates doesn't matter as such; only the distance between successive + coordinates is important. As a general rule, the smaller the difference between + coordinates, the smoother the resulting noise sequence. Steps of 0.005-0.03 work + best for most applications, but this will differ depending on the use case and + the noise settings. + + Py5's ``os_noise()`` method can also accept numpy arrays as parameters. It will + use broadcasting when needed and calculate the values efficiently. Using numpy + array parameters will be much faster and efficient than calling the + ``os_noise()`` method repeatedly in a loop. See the examples to see how this can + be done. The noise algorithm for this method is implemented in Java. + + Noise generation is a rich and complex topic, and there are many noise + algorithms and libraries available that are worth learning about. Early versions + of py5 used the Python "noise" library, which can generate noise using the + "Improved Perlin Noise" algorithm (as described in Ken Perlin's 2002 SIGGRAPH + paper) and the Simplex Noise algorithm (also developed by Ken Perlin). That + Python library was removed from py5 because it has some bugs and hasn't had a + release in years. Nevertheless, it might be useful to you, and can be installed + separately like any other Python package. You can also try the Python library + "vnoise", which is a pure Python implementation of the Improved Perlin Noise + algorithm. Note that py5 can also employ Java libraries, so consider "FastNoise + Lite" to experiment with a large selection of noise algorithms with efficient + implementations. + """ + return _py5sketch.os_noise(*args) + +############################################################################## +# module functions from pixels.py +############################################################################## + + +def load_np_pixels() -> None: + """Loads the pixel data of the current display window into the ``np_pixels[]`` + array. + + Notes + ----- + + Loads the pixel data of the current display window into the ``np_pixels[]`` + array. This method must always be called before reading from or writing to + ``np_pixels[]``. Subsequent changes to the display window will not be reflected + in ``np_pixels[]`` until ``load_np_pixels()`` is called again. + + The ``load_np_pixels()`` method is similar to ``load_pixels()`` in that + ``load_np_pixels()`` must be called before reading from or writing to + ``np_pixels[]`` just as ``load_pixels()`` must be called before reading from or + writing to ``pixels[]``. + + Note that ``load_np_pixels()`` will as a side effect call ``load_pixels()``, so + if your code needs to read ``np_pixels[]`` and ``pixels[]`` simultaneously, + there is no need for a separate call to ``load_pixels()``. However, be aware + that modifying both ``np_pixels[]`` and ``pixels[]`` simultaneously will likely + result in the updates to ``pixels[]`` being discarded. + """ + return _py5sketch.load_np_pixels() + + +def update_np_pixels() -> None: + """Updates the display window with the data in the ``np_pixels[]`` array. + + Notes + ----- + + Updates the display window with the data in the ``np_pixels[]`` array. Use in + conjunction with ``load_np_pixels()``. If you're only reading pixels from the + array, there's no need to call ``update_np_pixels()`` — updating is only + necessary to apply changes. + + The ``update_np_pixels()`` method is similar to ``update_pixels()`` in that + ``update_np_pixels()`` must be called after modifying ``np_pixels[]`` just as + ``update_pixels()`` must be called after modifying ``pixels[]``. + """ + return _py5sketch.update_np_pixels() + + +np_pixels: npt.NDArray[np.uint8] = None + + +def set_np_pixels(array: npt.NDArray[np.uint8], bands: str = 'ARGB') -> None: + """Set the entire contents of ``np_pixels[]`` to the contents of another properly + sized and typed numpy array. + + Parameters + ---------- + + array: npt.NDArray[np.uint8] + properly sized numpy array to be copied to np_pixels[] + + bands: str = 'ARGB' + color channels in the array's third dimension + + Notes + ----- + + Set the entire contents of ``np_pixels[]`` to the contents of another properly + sized and typed numpy array. The size of ``array``'s first and second dimensions + must match the height and width of the Sketch window, respectively. The array's + ``dtype`` must be ``np.uint8``. + + The ``bands`` parameter is used to interpret the ``array``'s color channel + dimension (the array's third dimension). It can be one of ``'L'`` (single- + channel grayscale), ``'ARGB'``, ``'RGB'``, or ``'RGBA'``. If there is no alpha + channel, ``array`` is assumed to have no transparency, but recall that the + display window's pixels can never be transparent so any transparency in + ``array`` will have no effect. If the ``bands`` parameter is ``'L'``, + ``array``'s third dimension is optional. + + This method makes its own calls to ``load_np_pixels()`` and + ``update_np_pixels()`` so there is no need to call either explicitly. + + This method exists because setting the array contents with the code + ``py5.np_pixels = array`` will cause an error, while the correct syntax, + ``py5.np_pixels[:] = array``, might also be unintuitive for beginners. + """ + return _py5sketch.set_np_pixels(array, bands=bands) + + +def save(filename: Union[str, + Path, + BytesIO], + *, + format: str = None, + drop_alpha: bool = True, + use_thread: bool = False, + **params) -> None: + """Save the drawing surface to an image file. + + Parameters + ---------- + + drop_alpha: bool = True + remove the alpha channel when saving the image + + filename: Union[str, Path, BytesIO] + output filename + + format: str = None + image format, if not determined from filename extension + + params + keyword arguments to pass to the PIL.Image save method + + use_thread: bool = False + write file in separate thread + + Notes + ----- + + Save the drawing surface to an image file. This method uses the Python library + Pillow to write the image, so it can save images in any format that that library + supports. + + Use the ``drop_alpha`` parameter to drop the alpha channel from the image. This + defaults to ``True``. Some image formats such as JPG do not support alpha + channels, and Pillow will throw an error if you try to save an image with the + alpha channel in that format. + + The ``use_thread`` parameter will save the image in a separate Python thread. + This improves performance by returning before the image has actually been + written to the file. + """ + return _py5sketch.save( + filename, + format=format, + drop_alpha=drop_alpha, + use_thread=use_thread, + **params) + +############################################################################## +# module functions from print_tools.py +############################################################################## + + +def set_println_stream(println_stream: Any) -> None: + """Customize where the output of ``println()`` goes. + + Parameters + ---------- + + println_stream: Any + println stream object to be used by println method + + Notes + ----- + + Customize where the output of ``println()`` goes. + + When running a Sketch asynchronously through Jupyter Notebook, any ``print`` + statements using Python's builtin function will always appear in the output of + the currently active cell. This will rarely be desirable, as the active cell + will keep changing as the user executes code elsewhere in the notebook. The + ``println()`` method was created to provide users with print functionality in a + Sketch without having to cope with output moving from one cell to the next. Use + ``set_println_stream`` to change how the output is handled. The + ``println_stream`` object must provide ``init()`` and ``print()`` methods, as + shown in the example. The example demonstrates how to configure py5 to output + text to an IPython Widget. + """ + return _py5sketch.set_println_stream(println_stream) + + +def println( + *args, + sep: str = ' ', + end: str = '\n', + stderr: bool = False) -> None: + """Print text or other values to the screen. + + Parameters + ---------- + + args + values to be printed + + end: str = '\\n' + string appended after the last value, defaults to newline character + + sep: str = ' ' + string inserted between values, defaults to a space + + stderr: bool = False + use stderr instead of stdout + + Notes + ----- + + Print text or other values to the screen. For a Sketch running outside of a + Jupyter Notebook, this method will behave the same as the Python's builtin + ``print`` method. For Sketches running in a Jupyter Notebook, this will place + text in the output of the cell that made the ``run_sketch()`` call. + + When running a Sketch asynchronously through Jupyter Notebook, any ``print`` + statements using Python's builtin function will always appear in the output of + the currently active cell. This will rarely be desirable, as the active cell + will keep changing as the user executes code elsewhere in the notebook. This + method was created to provide users with print functionality in a Sketch without + having to cope with output moving from one cell to the next. + + Use ``set_println_stream()`` to customize the behavior of ``println()``. + """ + return _py5sketch.println(*args, sep=sep, end=end, stderr=stderr) + +############################################################################## +# module functions from threads.py +############################################################################## + + +def launch_thread( + f: Callable, + name: str = None, + *, + daemon: bool = True, + args: tuple = None, + kwargs: dict = None) -> str: + """Launch a new thread to execute a function in parallel with your Sketch code. + + Parameters + ---------- + + args: tuple = None + positional arguments to pass to the given function + + daemon: bool = True + if the thread should be a daemon thread + + f: Callable + function to call in the launched thread + + kwargs: dict = None + keyword arguments to pass to the given function + + name: str = None + name of thread to be created + + Notes + ----- + + Launch a new thread to execute a function in parallel with your Sketch code. + This can be useful for executing non-py5 code that would otherwise slow down the + animation thread and reduce the Sketch's frame rate. + + The ``name`` parameter is optional but useful if you want to monitor the thread + with other methods such as ``has_thread()``. If the provided ``name`` is + identical to an already running thread, the running thread will first be stopped + with a call to ``stop_thread()`` with the ``wait`` parameter equal to ``True``. + + Use the ``args`` and ``kwargs`` parameters to pass positional and keyword + arguments to the function. + + Use the ``daemon`` parameter to make the launched thread a daemon that will run + without blocking Python from exiting. This parameter defaults to ``True``, + meaning that function execution can be interupted if the Python process exits. + Note that if the Python process continues running after the Sketch exits, which + is typically the case when using a Jupyter Notebook, this parameter won't have + any effect unless if you try to restart the Notebook kernel. Generally speaking, + setting this parameter to ``False`` causes problems but it is available for + those who really need it. See ``stop_all_threads()`` for a better approach to + exit threads. + + The new thread is a Python thread, so all the usual caveats about the Global + Interpreter Lock (GIL) apply here. + """ + return _py5sketch.launch_thread( + f, name=name, daemon=daemon, args=args, kwargs=kwargs) + + +def launch_promise_thread( + f: Callable, + name: str = None, + *, + daemon: bool = True, + args: tuple = None, + kwargs: dict = None) -> Py5Promise: + """Create a ``Py5Promise`` object that will store the returned result of a function + when that function completes. + + Parameters + ---------- + + args: tuple = None + positional arguments to pass to the given function + + daemon: bool = True + if the thread should be a daemon thread + + f: Callable + function to call in the launched thread + + kwargs: dict = None + keyword arguments to pass to the given function + + name: str = None + name of thread to be created + + Notes + ----- + + Create a ``Py5Promise`` object that will store the returned result of a function + when that function completes. This can be useful for executing non-py5 code that + would otherwise slow down the animation thread and reduce the Sketch's frame + rate. + + The ``Py5Promise`` object has an ``is_ready`` property that will be ``True`` + when the ``result`` property contains the value function ``f`` returned. Before + then, the ``result`` property will be ``None``. + + The ``name`` parameter is optional but useful if you want to monitor the thread + with other methods such as ``has_thread()``. If the provided ``name`` is + identical to an already running thread, the running thread will first be stopped + with a call to ``stop_thread()`` with the ``wait`` parameter equal to ``True``. + + Use the ``args`` and ``kwargs`` parameters to pass positional and keyword + arguments to the function. + + Use the ``daemon`` parameter to make the launched thread a daemon that will run + without blocking Python from exiting. This parameter defaults to ``True``, + meaning that function execution can be interupted if the Python process exits. + Note that if the Python process continues running after the Sketch exits, which + is typically the case when using a Jupyter Notebook, this parameter won't have + any effect unless if you try to restart the Notebook kernel. Generally speaking, + setting this parameter to ``False`` causes problems but it is available for + those who really need it. See ``stop_all_threads()`` for a better approach to + exit threads. + + The new thread is a Python thread, so all the usual caveats about the Global + Interpreter Lock (GIL) apply here. + """ + return _py5sketch.launch_promise_thread( + f, name=name, daemon=daemon, args=args, kwargs=kwargs) + + +def launch_repeating_thread(f: Callable, name: str = None, *, + time_delay: float = 0, daemon: bool = True, + args: tuple = None, kwargs: dict = None) -> str: + """Launch a new thread that will repeatedly execute a function in parallel with + your Sketch code. + + Parameters + ---------- + + args: tuple = None + positional arguments to pass to the given function - x: Union[float, npt.NDArray] - x-coordinate in noise space + daemon: bool = True + if the thread should be a daemon thread - y: Union[float, npt.NDArray] - y-coordinate in noise space + f: Callable + function to call in the launched thread - z: Union[float, npt.NDArray] - z-coordinate in noise space + kwargs: dict = None + keyword arguments to pass to the given function + + name: str = None + name of thread to be created + + time_delay: float = 0 + time delay in seconds between calls to the given function Notes ----- - Generate pseudo-random noise values for specific coodinates using the - OpenSimplex 2 algorithm (smooth version / SuperSimplex). Noise functions are - random sequence generators that produce a more natural, harmonic succession of - numbers compared to the ``random()`` method. - - In contrast to the ``random()`` method, noise is defined in an n-dimensional - space, in which each coordinate corresponds to a fixed pseudo-random value - (fixed only for the lifespan of the program). The noise value can be animated by - moving through the noise space, as demonstrated in the examples. Any dimension - can also be interpreted as time. An easy way to animate the noise value is to - pass the ``os_noise()`` method the ``frame_count`` divided by a scaling factor, - as is done in a few of the examples. + Launch a new thread that will repeatedly execute a function in parallel with + your Sketch code. This can be useful for executing non-py5 code that would + otherwise slow down the animation thread and reduce the Sketch's frame rate. - The generated noise values for this method will be between -1 and 1, and can be - generated in 2, 3, or 4 dimensions. To generate noise in 1 dimension, add a - constant value as an extra parameter, as shown in a few examples. Py5 also - provides the ``noise()`` method, which generates noise using Processing's noise - algorithm. That algorithm typically generates noise values between 0 and 1, and - can be generated in 1, 2, or 3 dimensions. Be aware of both of these differences - when modifying your code to switch from one to the other. There are other - differences in the character of the noise values generated by both methods, so - you'll need to do some experimentation to get the results you want. + Use the ``time_delay`` parameter to set the time in seconds between one call to + function ``f`` and the next call. Set this parameter to ``0`` if you want each + call to happen immediately after the previous call finishes. If the function + ``f`` takes longer than expected to finish, py5 will wait for it to finish + before making the next call. There will not be overlapping calls to function + ``f``. - The nature of the noise values returned can be adjusted with - ``os_noise_seed()``. + The ``name`` parameter is optional but useful if you want to monitor the thread + with other methods such as ``has_thread()``. If the provided ``name`` is + identical to an already running thread, the running thread will first be stopped + with a call to ``stop_thread()`` with the ``wait`` parameter equal to ``True``. - Another way to adjust the character of the resulting sequence is the scale of - the input coordinates. As the method works within an infinite space, the value - of the coordinates doesn't matter as such; only the distance between successive - coordinates is important. As a general rule, the smaller the difference between - coordinates, the smoother the resulting noise sequence. Steps of 0.005-0.03 work - best for most applications, but this will differ depending on the use case and - the noise settings. + Use the ``args`` and ``kwargs`` parameters to pass positional and keyword + arguments to the function. - Py5's ``os_noise()`` method can also accept numpy arrays as parameters. It will - use broadcasting when needed and calculate the values efficiently. Using numpy - array parameters will be much faster and efficient than calling the - ``os_noise()`` method repeatedly in a loop. See the examples to see how this can - be done. The noise algorithm for this method is implemented in Java. + Use the ``daemon`` parameter to make the launched thread a daemon that will run + without blocking Python from exiting. This parameter defaults to ``True``, + meaning that function execution can be interupted if the Python process exits. + Note that if the Python process continues running after the Sketch exits, which + is typically the case when using a Jupyter Notebook, this parameter won't have + any effect unless if you try to restart the Notebook kernel. Generally speaking, + setting this parameter to ``False`` causes problems but it is available for + those who really need it. See ``stop_all_threads()`` for a better approach to + exit threads. - Noise generation is a rich and complex topic, and there are many noise - algorithms and libraries available that are worth learning about. Early versions - of py5 used the Python "noise" library, which can generate noise using the - "Improved Perlin Noise" algorithm (as described in Ken Perlin's 2002 SIGGRAPH - paper) and the Simplex Noise algorithm (also developed by Ken Perlin). That - Python library was removed from py5 because it has some bugs and hasn't had a - release in years. Nevertheless, it might be useful to you, and can be installed - separately like any other Python package. You can also try the Python library - "vnoise", which is a pure Python implementation of the Improved Perlin Noise - algorithm. Note that py5 can also employ Java libraries, so consider "FastNoise - Lite" to experiment with a large selection of noise algorithms with efficient - implementations. + The new thread is a Python thread, so all the usual caveats about the Global + Interpreter Lock (GIL) apply here. """ - pass + return _py5sketch.launch_repeating_thread( + f, + name=name, + time_delay=time_delay, + daemon=daemon, + args=args, + kwargs=kwargs) -def os_noise(*args) -> Union[float, npt.NDArray]: - """Generate pseudo-random noise values for specific coodinates using the - OpenSimplex 2 algorithm (smooth version / SuperSimplex). +def has_thread(name: str) -> None: + """Determine if a thread of a given name exists and is currently running. - Methods - ------- + Parameters + ---------- - You can use any of the following signatures: + name: str + name of thread - * os_noise(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] - * os_noise(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], z: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] - * os_noise(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], z: Union[float, npt.NDArray], w: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray] + Notes + ----- + + Determine if a thread of a given name exists and is currently running. You can + get the list of all currently running threads with ``list_threads()``. + """ + return _py5sketch.has_thread(name) + + +def stop_thread(name: str, wait: bool = False) -> None: + """Stop a thread of a given name. Parameters ---------- - w: Union[float, npt.NDArray] - w-coordinate in noise space + name: str + name of thread - x: Union[float, npt.NDArray] - x-coordinate in noise space + wait: bool = False + wait for thread to exit before returning - y: Union[float, npt.NDArray] - y-coordinate in noise space + Notes + ----- - z: Union[float, npt.NDArray] - z-coordinate in noise space + Stop a thread of a given name. The ``wait`` parameter determines if the method + call will return right away or wait for the thread to exit. + + This won't do anything useful if the thread was launched with either + ``launch_thread()`` or ``launch_promise_thread()`` and the ``wait`` parameter is + ``False``. Non-repeating threads are executed once and will stop when they + complete execution. Setting the ``wait`` parameter to ``True`` will merely block + until the thread exits on its own. Killing off a running thread in Python is + complicated and py5 cannot do that for you. If you want a thread to perform some + action repeatedly and be interuptable, use ``launch_repeating_thread()`` + instead. + + Use ``has_thread()`` to determine if a thread of a given name exists and + ``list_threads()`` to get a list of all thread names. Use ``stop_all_threads()`` + to stop all threads. + """ + return _py5sketch.stop_thread(name, wait=wait) + + +def stop_all_threads(wait: bool = False) -> None: + """Stop all running threads. + + Parameters + ---------- + + wait: bool = False + wait for thread to exit before returning Notes ----- - Generate pseudo-random noise values for specific coodinates using the - OpenSimplex 2 algorithm (smooth version / SuperSimplex). Noise functions are - random sequence generators that produce a more natural, harmonic succession of - numbers compared to the ``random()`` method. - - In contrast to the ``random()`` method, noise is defined in an n-dimensional - space, in which each coordinate corresponds to a fixed pseudo-random value - (fixed only for the lifespan of the program). The noise value can be animated by - moving through the noise space, as demonstrated in the examples. Any dimension - can also be interpreted as time. An easy way to animate the noise value is to - pass the ``os_noise()`` method the ``frame_count`` divided by a scaling factor, - as is done in a few of the examples. + Stop all running threads. The ``wait`` parameter determines if the method call + will return right away or wait for the threads to exit. - The generated noise values for this method will be between -1 and 1, and can be - generated in 2, 3, or 4 dimensions. To generate noise in 1 dimension, add a - constant value as an extra parameter, as shown in a few examples. Py5 also - provides the ``noise()`` method, which generates noise using Processing's noise - algorithm. That algorithm typically generates noise values between 0 and 1, and - can be generated in 1, 2, or 3 dimensions. Be aware of both of these differences - when modifying your code to switch from one to the other. There are other - differences in the character of the noise values generated by both methods, so - you'll need to do some experimentation to get the results you want. + When the Sketch shuts down, ``stop_all_threads(wait=False)`` is called for you. + If you would rather the Sketch waited for threads to exit, create an ``exiting`` + method and make a call to ``stop_all_threads(wait=True)``. + """ + return _py5sketch.stop_all_threads(wait=wait) - The nature of the noise values returned can be adjusted with - ``os_noise_seed()``. - Another way to adjust the character of the resulting sequence is the scale of - the input coordinates. As the method works within an infinite space, the value - of the coordinates doesn't matter as such; only the distance between successive - coordinates is important. As a general rule, the smaller the difference between - coordinates, the smoother the resulting noise sequence. Steps of 0.005-0.03 work - best for most applications, but this will differ depending on the use case and - the noise settings. +def list_threads() -> None: + """List the names of all of the currently running threads. - Py5's ``os_noise()`` method can also accept numpy arrays as parameters. It will - use broadcasting when needed and calculate the values efficiently. Using numpy - array parameters will be much faster and efficient than calling the - ``os_noise()`` method repeatedly in a loop. See the examples to see how this can - be done. The noise algorithm for this method is implemented in Java. + Notes + ----- - Noise generation is a rich and complex topic, and there are many noise - algorithms and libraries available that are worth learning about. Early versions - of py5 used the Python "noise" library, which can generate noise using the - "Improved Perlin Noise" algorithm (as described in Ken Perlin's 2002 SIGGRAPH - paper) and the Simplex Noise algorithm (also developed by Ken Perlin). That - Python library was removed from py5 because it has some bugs and hasn't had a - release in years. Nevertheless, it might be useful to you, and can be installed - separately like any other Python package. You can also try the Python library - "vnoise", which is a pure Python implementation of the Improved Perlin Noise - algorithm. Note that py5 can also employ Java libraries, so consider "FastNoise - Lite" to experiment with a large selection of noise algorithms with efficient - implementations. + List the names of all of the currently running threads. The names of previously + launched threads that have exited will be removed from the list. """ - return _py5sketch.os_noise(*args) + return _py5sketch.list_threads() ############################################################################## # module functions from sketch.py @@ -20481,6 +20522,44 @@ def select_output( prompt, callback, default_file=default_file) +def create_image_from_numpy( + array: npt.NDArray[np.uint8], bands: str = 'ARGB', *, dst: Py5Image = None) -> Py5Image: + """Convert a numpy array into a Py5Image object. + + Parameters + ---------- + + array: npt.NDArray[np.uint8] + numpy image array + + bands: str = 'ARGB' + color channels in array + + dst: Py5Image = None + existing Py5Image object to put the image data into + + Notes + ----- + + Convert a numpy array into a Py5Image object. The numpy array must have 3 + dimensions and the array's ``dtype`` must be ``np.uint8``. The size of + ``array``'s first and second dimensions will be the image's height and width, + respectively. The third dimension is for the array's color channels. + + The ``bands`` parameter is used to interpret the ``array``'s color channel + dimension (the array's third dimension). It can be one of ``'L'`` (single- + channel grayscale), ``'ARGB'``, ``'RGB'``, or ``'RGBA'``. If there is no alpha + channel, ``array`` is assumed to have no transparency. If the ``bands`` + parameter is ``'L'``, ``array``'s third dimension is optional. + + The caller can optionally pass an existing Py5Image object to put the image data + into using the ``dst`` parameter. This can have performance benefits in code + that would otherwise continuously create new Py5Image objects. The array's width + and height must match that of the recycled Py5Image object. + """ + return _py5sketch.create_image_from_numpy(array, bands=bands, dst=dst) + + def convert_image(obj: Any, *, dst: Py5Image = None) -> Py5Image: """Convert non-py5 image objects into Py5Image objects. diff --git a/py5/graphics.py b/py5/graphics.py index 91b4149..9a075fd 100644 --- a/py5/graphics.py +++ b/py5/graphics.py @@ -894,52 +894,52 @@ def apply_matrix(self, n00: float, n01: float, n02: float, ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -994,52 +994,52 @@ def apply_matrix( ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -1076,52 +1076,52 @@ def apply_matrix(self, source: npt.NDArray[np.floating], /) -> None: ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -1157,52 +1157,52 @@ def apply_matrix(self, *args): ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms diff --git a/py5/jars/core.jar b/py5/jars/core.jar index dfbd5cc..6e5f32d 100644 Binary files a/py5/jars/core.jar and b/py5/jars/core.jar differ diff --git a/py5/jars/dxf/dxf.jar b/py5/jars/dxf/dxf.jar index fb10b08..7be9032 100644 Binary files a/py5/jars/dxf/dxf.jar and b/py5/jars/dxf/dxf.jar differ diff --git a/py5/jars/pdf/pdf.jar b/py5/jars/pdf/pdf.jar index e990474..a8f6fb3 100644 Binary files a/py5/jars/pdf/pdf.jar and b/py5/jars/pdf/pdf.jar differ diff --git a/py5/jars/py5.jar b/py5/jars/py5.jar index c0628ef..9a17ba1 100644 Binary files a/py5/jars/py5.jar and b/py5/jars/py5.jar differ diff --git a/py5/jars/svg/svg.jar b/py5/jars/svg/svg.jar index 367e954..1a31e1a 100644 Binary files a/py5/jars/svg/svg.jar and b/py5/jars/svg/svg.jar differ diff --git a/py5/mixins/math.py b/py5/mixins/math.py index 6894c70..8e52f32 100644 --- a/py5/mixins/math.py +++ b/py5/mixins/math.py @@ -70,8 +70,8 @@ def hex_color(cls, color: int) -> str: provides an alternative approach, converting the 32 bit integer into a string such as ``'#0F3FF0FF'``. The hex string has 8 hexadecimal values following a ``#`` character. The first two values represent the red value, the next two - green, the next two blue, and the last two alpha. This is similar to web colors - except for the addition of the alpha channel. + green, the next two blue, and the last two alpha. This is consistent with CSS 8 + digit hex colors. Conveniently, the hex color string returned by this method can also be used as parameter for other methods that accept color values. Observe how this is done diff --git a/py5/mixins/print_tools.py b/py5/mixins/print_tools.py index 9d8d023..cf8308e 100644 --- a/py5/mixins/print_tools.py +++ b/py5/mixins/print_tools.py @@ -17,6 +17,8 @@ # along with this library. If not, see . # # ***************************************************************************** +import sys + from typing import Any @@ -96,5 +98,8 @@ def println( having to cope with output moving from one cell to the next. Use ``set_println_stream()`` to customize the behavior of ``println()``.""" - self._println_stream.print(sep.join(str(x) - for x in args), end=end, stderr=stderr) + msg = sep.join(str(x) for x in args) + if self._println_stream is None: + print(msg, end=end, file=sys.stderr if stderr else sys.stdout) + else: + self._println_stream.print(msg, end=end, stderr=stderr) diff --git a/py5/reference.py b/py5/reference.py index ca67c21..65cb9dd 100644 --- a/py5/reference.py +++ b/py5/reference.py @@ -235,22 +235,9 @@ (('Sketch', 'window_resize'), ['(new_width: int, new_height: int, /) -> None']), (('Sketch', 'window_title'), ['(title: str, /) -> None']), (('Sketch', 'year'), ['() -> int']), - (('Sketch', 'set_println_stream'), ['(println_stream: Any) -> None']), - (('Sketch', 'println'), ["(*args, sep: str = ' ', end: str = '\\n', stderr: bool = False) -> None"]), (('Sketch', 'load_json'), ['(json_path: Union[str, Path], **kwargs: dict[str, Any]) -> Any']), (('Sketch', 'save_json'), ['(json_data: Any, filename: Union[str, Path], **kwargs: dict[str, Any]) -> None']), (('Sketch', 'parse_json'), ['(serialized_json: Any, **kwargs: dict[str, Any]) -> Any']), - (('Sketch', 'load_np_pixels'), ['() -> None']), - (('Sketch', 'update_np_pixels'), ['() -> None']), - (('Sketch', 'set_np_pixels'), ["(array: npt.NDArray[np.uint8], bands: str = 'ARGB') -> None"]), - (('Sketch', 'save'), ['(filename: Union[str, Path, BytesIO], *, format: str = None, drop_alpha: bool = True, use_thread: bool = False, **params) -> None']), - (('Sketch', 'launch_thread'), ['(f: Callable, name: str = None, *, daemon: bool = True, args: tuple = None, kwargs: dict = None) -> str']), - (('Sketch', 'launch_promise_thread'), ['(f: Callable, name: str = None, *, daemon: bool = True, args: tuple = None, kwargs: dict = None) -> Py5Promise']), - (('Sketch', 'launch_repeating_thread'), ['(f: Callable, name: str = None, *, time_delay: float = 0, daemon: bool = True, args: tuple = None, kwargs: dict = None) -> str']), - (('Sketch', 'has_thread'), ['(name: str) -> None']), - (('Sketch', 'stop_thread'), ['(name: str, wait: bool = False) -> None']), - (('Sketch', 'stop_all_threads'), ['(wait: bool = False) -> None']), - (('Sketch', 'list_threads'), ['() -> None']), (('Sketch', 'hex_color'), ['(color: int) -> str']), (('Sketch', 'sin'), ['(angle: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]']), (('Sketch', 'cos'), ['(angle: Union[float, npt.ArrayLike]) -> Union[float, npt.NDArray]']), @@ -280,6 +267,19 @@ (('Sketch', 'random_gaussian'), ['() -> float', '(loc: float, /) -> float', '(loc: float, scale: float, /) -> float']), (('Sketch', 'noise'), ['(x: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray]', '(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray]', '(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], z: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray]']), (('Sketch', 'os_noise'), ['(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray]', '(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], z: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray]', '(x: Union[float, npt.NDArray], y: Union[float, npt.NDArray], z: Union[float, npt.NDArray], w: Union[float, npt.NDArray], /) -> Union[float, npt.NDArray]']), + (('Sketch', 'load_np_pixels'), ['() -> None']), + (('Sketch', 'update_np_pixels'), ['() -> None']), + (('Sketch', 'set_np_pixels'), ["(array: npt.NDArray[np.uint8], bands: str = 'ARGB') -> None"]), + (('Sketch', 'save'), ['(filename: Union[str, Path, BytesIO], *, format: str = None, drop_alpha: bool = True, use_thread: bool = False, **params) -> None']), + (('Sketch', 'set_println_stream'), ['(println_stream: Any) -> None']), + (('Sketch', 'println'), ["(*args, sep: str = ' ', end: str = '\\n', stderr: bool = False) -> None"]), + (('Sketch', 'launch_thread'), ['(f: Callable, name: str = None, *, daemon: bool = True, args: tuple = None, kwargs: dict = None) -> str']), + (('Sketch', 'launch_promise_thread'), ['(f: Callable, name: str = None, *, daemon: bool = True, args: tuple = None, kwargs: dict = None) -> Py5Promise']), + (('Sketch', 'launch_repeating_thread'), ['(f: Callable, name: str = None, *, time_delay: float = 0, daemon: bool = True, args: tuple = None, kwargs: dict = None) -> str']), + (('Sketch', 'has_thread'), ['(name: str) -> None']), + (('Sketch', 'stop_thread'), ['(name: str, wait: bool = False) -> None']), + (('Sketch', 'stop_all_threads'), ['(wait: bool = False) -> None']), + (('Sketch', 'list_threads'), ['() -> None']), (('Sketch', 'sketch_path'), ['() -> Path', '(where: str, /) -> Path']), (('Sketch', 'hot_reload_draw'), ['(draw: Callable) -> None']), (('Sketch', 'profile_functions'), ['(function_names: list[str]) -> None']), @@ -289,6 +289,7 @@ (('Sketch', 'select_folder'), ['(prompt: str, callback: Callable, default_folder: str = None) -> None']), (('Sketch', 'select_input'), ['(prompt: str, callback: Callable, default_file: str = None) -> None']), (('Sketch', 'select_output'), ['(prompt: str, callback: Callable, default_file: str = None) -> None']), + (('Sketch', 'create_image_from_numpy'), ["(array: npt.NDArray[np.uint8], bands: str = 'ARGB', *, dst: Py5Image = None) -> Py5Image"]), (('Sketch', 'convert_image'), ['(obj: Any, *, dst: Py5Image = None) -> Py5Image']), (('Sketch', 'load_image'), ['(image_path: Union[str, Path], *, dst: Py5Image = None) -> Py5Image']), (('Sketch', 'request_image'), ['(image_path: Union[str, Path]) -> Py5Promise']), diff --git a/py5/shape.py b/py5/shape.py index 50512dc..8aca973 100644 --- a/py5/shape.py +++ b/py5/shape.py @@ -476,52 +476,52 @@ def apply_matrix(self, n00: float, n01: float, n02: float, ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -578,52 +578,52 @@ def apply_matrix( ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -662,52 +662,52 @@ def apply_matrix(self, source: npt.NDArray[np.floating], /) -> None: ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -745,52 +745,52 @@ def apply_matrix(self, *args): ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms diff --git a/py5/sketch.py b/py5/sketch.py index a14af42..62ed4c6 100644 --- a/py5/sketch.py +++ b/py5/sketch.py @@ -18,7 +18,6 @@ # # ***************************************************************************** from __future__ import annotations -from re import S import time import os @@ -879,6 +878,14 @@ def select_folder(self, prompt: str, callback: Callable, the Sketch is run through a Jupyter notebook. On Windows, Sketches using the OpenGL renderers (``P2D`` or ``P3D``) will be minimized while the select dialog box is open. This method only uses native dialog boxes on OSX.""" + if not isinstance( + prompt, + str) or not callable(callback) or ( + default_folder is not None and not isinstance( + default_folder, + str)): + raise TypeError( + "This method's signature is select_folder(prompt: str, callback: Callable, default_folder: str)") self._generic_select( self._instance.py5SelectFolder, 'select_folder', @@ -920,6 +927,14 @@ def select_input( the Sketch is run through a Jupyter notebook. On Windows, Sketches using the OpenGL renderers (``P2D`` or ``P3D``) will be minimized while the select dialog box is open. This method only uses native dialog boxes on OSX.""" + if not isinstance( + prompt, + str) or not callable(callback) or ( + default_file is not None and not isinstance( + default_file, + str)): + raise TypeError( + "This method's signature is select_input(prompt: str, callback: Callable, default_file: str)") self._generic_select( self._instance.py5SelectInput, 'select_input', @@ -961,6 +976,14 @@ def select_output( the Sketch is run through a Jupyter notebook. On Windows, Sketches using the OpenGL renderers (``P2D`` or ``P3D``) will be minimized while the select dialog box is open. This method only uses native dialog boxes on OSX.""" + if not isinstance( + prompt, + str) or not callable(callback) or ( + default_file is not None and not isinstance( + default_file, + str)): + raise TypeError( + "This method's signature is select_output(prompt: str, callback: Callable, default_file: str)") self._generic_select( self._instance.py5SelectOutput, 'select_output', @@ -2710,52 +2733,52 @@ def apply_matrix(self, n00: float, n01: float, n02: float, ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -2807,52 +2830,52 @@ def apply_matrix( ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -2886,52 +2909,52 @@ def apply_matrix(self, source: npt.NDArray[np.floating], /) -> None: ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -2964,52 +2987,52 @@ def apply_matrix(self, *args): ---------- n00: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 0 of the matrix n01: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 1 of the matrix n02: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 2 of the matrix n03: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 0 and column 3 of the matrix n10: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 0 of the matrix n11: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 1 of the matrix n12: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 2 of the matrix n13: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 1 and column 3 of the matrix n20: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 0 of the matrix n21: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 1 of the matrix n22: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 2 of the matrix n23: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 2 and column 3 of the matrix n30: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 0 of the matrix n31: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 1 of the matrix n32: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 2 of the matrix n33: float - numbers which define the 4x4 matrix to be multiplied + numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ -12789,6 +12812,9 @@ def push(self) -> None: ``push_matrix()``, ``pop_matrix()``, ``push_style()``, and ``pop_style()``. The difference is that ``push()`` and ``pop()`` control both the transformations (rotate, scale, translate) and the drawing styles at the same time. + + This method can be used as a context manager to ensure that ``pop()`` always + gets called, as shown in the last example. """ return self._instance.push() @@ -12808,6 +12834,9 @@ def push_matrix(self) -> None: ``push_matrix()`` and ``pop_matrix()`` are used in conjuction with the other transformation functions and may be embedded to control the scope of the transformations. + + This method can be used as a context manager to ensure that ``pop_matrix()`` + always gets called, as shown in the last example. """ return self._instance.pushMatrix() @@ -12835,6 +12864,9 @@ def push_style(self) -> None: ``ellipse_mode()``, ``shape_mode()``, ``color_mode()``, ``text_align()``, ``text_font()``, ``text_mode()``, ``text_size()``, ``text_leading()``, ``emissive()``, ``specular()``, ``shininess()``, and ``ambient()``. + + This method can be used as a context manager to ensure that ``pop_style()`` + always gets called, as shown in the last example. """ return self._instance.pushStyle() @@ -14730,6 +14762,14 @@ def size(self, width: int, height: int, /) -> None: * ``SVG``: The ``SVG`` renderer draws 2D graphics directly to an SVG file. This is great for importing into other vector programs or using for digital fabrication. + + When using the ``PDF`` and ``SVG`` renderers with the ``size()`` method, you + must use the ``path`` parameter to specify the file to write the output to. No + window will open while the Sketch is running. You must also call + ``exit_sketch()`` to exit the Sketch and write the completed output to the file. + Without this call, the Sketch will not exit and the output file will be empty. + If you would like to draw 3D objects to a PDF or SVG file, use the ``P3D`` + renderer and the strategy described in ``begin_raw()``. """ pass @@ -14821,6 +14861,14 @@ def size(self, width: int, height: int, renderer: str, /) -> None: * ``SVG``: The ``SVG`` renderer draws 2D graphics directly to an SVG file. This is great for importing into other vector programs or using for digital fabrication. + + When using the ``PDF`` and ``SVG`` renderers with the ``size()`` method, you + must use the ``path`` parameter to specify the file to write the output to. No + window will open while the Sketch is running. You must also call + ``exit_sketch()`` to exit the Sketch and write the completed output to the file. + Without this call, the Sketch will not exit and the output file will be empty. + If you would like to draw 3D objects to a PDF or SVG file, use the ``P3D`` + renderer and the strategy described in ``begin_raw()``. """ pass @@ -14913,6 +14961,14 @@ def size(self, width: int, height: int, * ``SVG``: The ``SVG`` renderer draws 2D graphics directly to an SVG file. This is great for importing into other vector programs or using for digital fabrication. + + When using the ``PDF`` and ``SVG`` renderers with the ``size()`` method, you + must use the ``path`` parameter to specify the file to write the output to. No + window will open while the Sketch is running. You must also call + ``exit_sketch()`` to exit the Sketch and write the completed output to the file. + Without this call, the Sketch will not exit and the output file will be empty. + If you would like to draw 3D objects to a PDF or SVG file, use the ``P3D`` + renderer and the strategy described in ``begin_raw()``. """ pass @@ -15003,6 +15059,14 @@ def size(self, *args): * ``SVG``: The ``SVG`` renderer draws 2D graphics directly to an SVG file. This is great for importing into other vector programs or using for digital fabrication. + + When using the ``PDF`` and ``SVG`` renderers with the ``size()`` method, you + must use the ``path`` parameter to specify the file to write the output to. No + window will open while the Sketch is running. You must also call + ``exit_sketch()`` to exit the Sketch and write the completed output to the file. + Without this call, the Sketch will not exit and the output file will be empty. + If you would like to draw 3D objects to a PDF or SVG file, use the ``P3D`` + renderer and the strategy described in ``begin_raw()``. """ return self._instance.size(*args) diff --git a/py5/vector.py b/py5/vector.py index 848ee9a..2c32244 100644 --- a/py5/vector.py +++ b/py5/vector.py @@ -76,6 +76,7 @@ class Py5Vector(Sequence): the ``copy`` parameter to ``False``, such as ``v6 = py5.Py5Vector(arr, copy=False)``. """ + _DEFAULT_DIM = 3 def __new__( cls, @@ -86,7 +87,8 @@ def __new__( kwarg_dim = dim kwarg_dtype = dtype - dim = 3 if dim is None else dim + used_default_dim = len(args) == 0 and dim is None + dim = Py5Vector._DEFAULT_DIM if dim is None else dim dtype = np.float_ if dtype is None else dtype if not isinstance( @@ -180,6 +182,7 @@ def __new__( raise RuntimeError(f'Why is dim == {dim}? Please report bug') v._data = data + v._used_default_dim = used_default_dim return v @@ -229,6 +232,16 @@ def __str__(self): def __repr__(self): return f'Py5Vector{self._data.size}D{repr(self._data)[5:]}' + def _check_used_default_dim(self, other): + if self._used_default_dim or ( + isinstance( + other, + Py5Vector) and other._used_default_dim): + other_dim = self._data.size + other._data.size - Py5Vector._DEFAULT_DIM + return f" Note that one of the Py5Vectors was created with Py5Vector(), and is therefore by default a {Py5Vector._DEFAULT_DIM}D vector. If you wanted a {other_dim}D vector instead, use the `dim` parameter, like this: Py5Vector(dim={other_dim})." + else: + return "" + def _run_op( self, op, @@ -243,7 +256,8 @@ def _run_op( f"Cannot perform {opname} operation on two Py5Vectors. If you want to do {opname} on the Py5Vector's data elementwise, use the `.data` attribute to access the Py5Vector's data as a numpy array.") elif self._data.size != other._data.size: raise RuntimeError( - f"Cannot perform {opname} operation on a {self._data.size}D Py5Vector a {other._data.size}D Py5Vector. The dimensions must be the same.") + f"Cannot perform {opname} operation on a {self._data.size}D Py5Vector and a {other._data.size}D Py5Vector. The dimensions must be the same." + + self._check_used_default_dim(other)) elif inplace: op(self._data[:other._data.size], other._data[:other._data.size]) @@ -580,7 +594,8 @@ def _run_calc(self, other, calc, name, maybe_vector=False): other = other._data else: raise RuntimeError( - f'Py5Vector dimensions must be the same to calculate the {name} two Py5Vectors') + f'Py5Vector dimensions must be the same to calculate the {name} two Py5Vectors.' + + self._check_used_default_dim(other)) if isinstance(other, np.ndarray): try: diff --git a/py5_tools/__init__.py b/py5_tools/__init__.py index c9bb602..9e6897d 100644 --- a/py5_tools/__init__.py +++ b/py5_tools/__init__.py @@ -28,4 +28,4 @@ from . import translators # noqa -__version__ = '0.8.1a1' +__version__ = '0.8.2a1' diff --git a/py5_tools/imported.py b/py5_tools/imported.py index a28d0c0..714bb45 100644 --- a/py5_tools/imported.py +++ b/py5_tools/imported.py @@ -91,10 +91,9 @@ def setup(): ) """ -_CODE_FRAMEWORK = """ -__file__ = "{4}" +_CODE_FRAMEWORK = """{0} + -{0} run_sketch(block=True, py5_options={2}, sketch_args={3}) if {1} and is_dead_from_error: @@ -214,8 +213,7 @@ def _run_sketch(sketch_path, classpath, exit_if_error): with open(sketch_path, 'r', encoding='utf8') as f: sketch_code = _CODE_FRAMEWORK.format( - f.read(), exit_if_error, py5_options_str, sketch_args_str, re.sub( - r"""(\"|\')""", r'\\\1', str(original_sketch_path))) + f.read(), exit_if_error, py5_options_str, sketch_args_str) # does the code parse? if not, display an error message try: @@ -253,6 +251,7 @@ def _run_sketch(sketch_path, classpath, exit_if_error): sys.path.extend([str(sketch_path.absolute().parent), os.getcwd()]) py5_ns = dict() py5_ns.update(py5.__dict__) + py5_ns['__file__'] = str(original_sketch_path) exec(sketch_compiled, py5_ns) diff --git a/py5_tools/kernel/kernel.py b/py5_tools/kernel/kernel.py index 11fe955..c4ffeea 100644 --- a/py5_tools/kernel/kernel.py +++ b/py5_tools/kernel/kernel.py @@ -80,7 +80,7 @@ class Py5Kernel(IPythonKernel): *_PY5_HELP_LINKS]).tag(config=True) implementation = 'py5' - implementation_version = '0.8.1a1' + implementation_version = '0.8.2a1' class Py5App(IPKernelApp): diff --git a/py5_tools/py5bot/kernel.py b/py5_tools/py5bot/kernel.py index fe76eea..da6a714 100644 --- a/py5_tools/py5bot/kernel.py +++ b/py5_tools/py5bot/kernel.py @@ -87,7 +87,7 @@ class Py5BotKernel(Py5Kernel): shell_class = Type(Py5BotShell) implementation = 'py5bot' - implementation_version = '0.8.1a1' + implementation_version = '0.8.2a1' class Py5BotApp(IPKernelApp): diff --git a/py5_tools/reference.py b/py5_tools/reference.py index da913b1..1390d82 100644 --- a/py5_tools/reference.py +++ b/py5_tools/reference.py @@ -107,6 +107,7 @@ 'create_font_file', 'create_graphics', 'create_image', + 'create_image_from_numpy', 'create_shape', 'CROSS', 'cursor', @@ -572,6 +573,7 @@ 'create_font_file', 'create_graphics', 'create_image', + 'create_image_from_numpy', 'create_shape', 'CROSS', 'cursor', diff --git a/py5_tools/split_setup.py b/py5_tools/split_setup.py index 668a207..46e9ff4 100644 --- a/py5_tools/split_setup.py +++ b/py5_tools/split_setup.py @@ -25,7 +25,8 @@ COMMENT_LINE = re.compile(r'^\s*#.*' + chr(36), flags=re.MULTILINE) -DOCSTRING = re.compile(r'^\s*"""[^"]*"""', flags=re.MULTILINE | re.DOTALL) +DOCSTRING = re.compile(r'^\s*""".*?"""', flags=re.MULTILINE | re.DOTALL) +SETUP_LINE = re.compile(r'^def setup[^:]*:') MODULE_MODE_METHOD_LINE = re.compile(r'^\s*py5\.(\w+)\([^\)]*\)') IMPORTED_MODE_METHOD_LINE = re.compile(r'^\s*(\w+)\([^\)]*\)') GLOBAL_STATEMENT_LINE = re.compile( @@ -66,7 +67,7 @@ def find_cutoffs(code, mode, static_mode=False): for i, line in enumerate(code.split('\n')): if not line.strip(): continue - if not static_mode and line == 'def setup():': + if not static_mode and SETUP_LINE.match(line): def_statement = True continue diff --git a/py5_tools/utilities.py b/py5_tools/utilities.py index 45ccb90..e18024d 100644 --- a/py5_tools/utilities.py +++ b/py5_tools/utilities.py @@ -59,21 +59,21 @@ class Py5Utilities { py5 py5-processing4 - 0.8.1a1 + 0.8.2a1 system ${{jarlocation}}/core.jar py5 py5-jogl - 0.8.1a1 + 0.8.2a1 system ${{jarlocation}}/jogl-all.jar py5 py5 - 0.8.1a1 + 0.8.2a1 system ${{jarlocation}}/py5.jar diff --git a/setup.py b/setup.py index 96d8ca7..425bb6d 100644 --- a/setup.py +++ b/setup.py @@ -23,7 +23,7 @@ with open('README.md') as f: README = f.read() -VERSION = '0.8.1a1' +VERSION = '0.8.2a1' INSTALL_REQUIRES = [ 'autopep8>=1.5',