.. _ws_shape_icon:


ws_shape
===============================================

.. container::
    
    .. container:: leftside

        .. image:: /_static/WS_SHAPE.png
           :width: 48px

    .. container:: rightside

		Defines a shape :ref:`Weather Symbol Object <weather_symbols>` that can be visualised with :func:`plot`.
		
		.. include:: /api/icon_desc/include/ws.rst


		.. note:: This function performs the same task as the **Ws Shape** icon in Metview’s :ref:`user interface <user_interface>`. It accepts its parameters as keyword arguments, described below.


.. py:function:: ws_shape(**kwargs)
  
    Defines a shape :ref:`Weather Symbol Object <weather_symbols>`.


    :param type: Specifies the shape type. This also implicitly specifies the type of data which will be entered. The available types are as follows:
		
		* "line": straight line in all the projections
		* "polyline": points connected with straight lines in all the projections
		* "curve": points connected with a B-spline curve
		* "polygon": points forming a closed shape, connected with straight lines in all the projections
		* "closed_curve": points forming a closed shape, connected with a B-Spline curve
		* "rectangle": rectangle with straight edges. The corner points will be adjusted when the projection changes to preserve the rectangular shape.
		* "proj_line": a line sampled in lat-lon. The shape changes according to the projection.
		* "proj_polyline": points connected with edges sampled in lat-lon. The edge shapes change according to the projection.
		* "proj_polygon": points forming a closed shape, with edges sampled in lat-lon. The edge shapes change according to the projection.
		* "proj_quad": a lat-lon rectangle with edges sampled in lat-lon. The shape changes into various quadrilaterals according to the current projection.
    :type type: str, default: "line"

    :param line: Enable to draw the line/outline.
    :type line: {"on", "off"}, default: "on"

    :param line_colour: Colour of the line/outline. Enabled when ``line`` is "on".
    :type line_colour: str, default: "black"

    :param line_thickness: Thickness of the line/outline. Enabled when ``line`` is "on".
    :type line_thickness: number, default: 1

    :param line_style: Style of the line/outline. Enabled when ``line`` is "on".
    :type line_style: line_style, default: solid

    :param line_start_ptype: Defines the arrow head for the start of the line. Enabled when ``type`` is "line", "polyline", "curve", "proj_line" or "proj_polyline".
    :type line_start_ptype: {"none", "open_arrow", "filled_arrow"}, default: "none"

    :param line_end_ptype: Defines the arrow head for the end of the line. Enabled when ``type`` is "line", "polyline", "curve", "proj_line" or "proj_polyline".
    :type line_end_ptype: {"none", "open_arrow", "filled_arrow"}, default: "none"

    :param arrow_length: The length of the arrow head. Enabled when either ``line_start_ptype`` or `line_end_ptype`` is not 'none'.
    :type arrow_length: number, default: 10

    :param fill: Enable to fill the shape.
    :type fill: {"on", "off"}, default: "on"

    :param fill_colour: Fill colour of the shape. Enabled when ``fill`` is "on".
    :type fill_colour: str, default: "rgba(0,0,1,0.3)"

    :param segment_dateline_cross: special
    :type segment_dateline_cross: ndarray or list of numbers

    :param segment_dx: special
    :type segment_dx: ndarray or list of numbers

    :param x: The x coordinates of the points making up the shape. The number of points required depends on the ``type``:
		
		* For "line" and "proj_line" exactly 2 points are needed. 
		* For "polyline", "curve" and "proj_polyline" minimum 2 points are needed. 
		* For "polygon", "closed_curve" and "proj_polygon" minimum 3 points are needed.
		* For "rectangle" and "proj_quad" exactly 4 points are needed. 
    :type x: ndarray or list of numbers, default: 0

    :param y: The y coordinates of the points making up the shape.  For the number of points required please see ``x``.
    :type y: ndarray or list of numbers, default: 0

    :param geolock: Sets the geolock on the item for interactive editing in the plot window.
    :type geolock: on_off, default: off

    :param tooltip: Text that appears as a tooltip when the visualised object is hovered over in Metview's plot window.
    :type tooltip: str

    :rtype: :class:`Request`

.. mv-minigallery:: ws_shape