fix(extra): Add component for 2D screen-oriented legends

dev-requirements.txt

@@ -4,6 +4,6 @@ coveralls==3.1.0
 pytest==6.2.4
 pytest-cov==2.12.0
 twine==3.4.1
-wheel==0.36.2
-setuptools==57.0.0
+wheel==0.38.1
+setuptools==65.5.1
 importlib-metadata==4.0.1

ladybug_grasshopper/json/LB_Dump_Data.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.5.0", 
+  "version": "1.5.1", 
   "nickname": "DumpData", 
   "outputs": [
     [
@@ -44,7 +44,7 @@
     {
       "access": "item", 
       "name": "_dump", 
-      "description": "Set to \"True\" to save the honeybee objects to file.", 
+      "description": "Set to \"True\" to save the data collection to a file.", 
       "type": "bool", 
       "default": null
     }

ladybug_grasshopper/json/LB_Dump_VisualizationSet.json

@@ -0,0 +1,57 @@
+{
+  "version": "1.5.0", 
+  "nickname": "DumpVisSet", 
+  "outputs": [
+    [
+      {
+        "access": "None", 
+        "name": "vs_file", 
+        "description": "The path of the file where the VisualisationSet is saved.", 
+        "type": null, 
+        "default": null
+      }
+    ]
+  ], 
+  "inputs": [
+    {
+      "access": "item", 
+      "name": "_vs", 
+      "description": "A VisualizationSet object to be written to a file. Typically, this is\nthe output from the \"LB Preview VisualizationSet\" component but\nit can also be a custom VisualiztionSet object created with the\nLadybug Tools SDK.", 
+      "type": "System.Object", 
+      "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "_format_", 
+      "description": "Text or an integer to set the format of the output file.\nChoose from the options below. (Default: JSON).\n* 0 = JSON - Cross-language and handles any types of collections\n* 1 = PKL - Compressed format only readable with Python", 
+      "type": "string", 
+      "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "_name_", 
+      "description": "A name for the file to which the VisualizationSet will be written.\nThe default is derived from the identifier of the visualization set.", 
+      "type": "string", 
+      "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "_folder_", 
+      "description": "An optional directory into which the VisualizationSet will be\nwritten.  The default is set to a user-specific simulation folder.", 
+      "type": "string", 
+      "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "_dump", 
+      "description": "Set to \"True\" to save the VisualizationSet to a file.", 
+      "type": "bool", 
+      "default": null
+    }
+  ], 
+  "subcategory": "4 :: Extra", 
+  "code": "\nimport os\n\ntry:\n    from ladybug.config import folders\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug:\\n\\t{}'.format(e))\n\ntry:  # import the core ladybug_{{cad}} dependencies\n    from ladybug_{{cad}}.{{plugin}} import all_required_inputs\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_{{cad}}:\\n\\t{}'.format(e))\n\nFORMAT_MAP = {\n    '0': 'json',\n    '1': 'pkl',\n    'json': 'json',\n    'pkl': 'pkl'\n}\n\n\nif all_required_inputs(ghenv.Component) and _dump:\n        # extract the VisualizationSet object if the input is the bake-able form\n    if hasattr(_vs, 'vis_set'):\n        _vs = _vs.vis_set\n\n    # set the component defaults\n    name = _name_ if _name_ is not None else _vs.identifier\n    home_folder = os.getenv('HOME') or os.path.expanduser('~')\n    folder = _folder_ if _folder_ is not None else \\\n        os.path.join(home_folder, 'simulation')\n    file_format = 'json' if _format_ is None else FORMAT_MAP[_format_.lower()]\n\n    # write the data into the appropriate format\n    if file_format == 'json':\n        vs_file = _vs.to_json(name, folder)\n    elif file_format == 'pkl':\n        vs_file = _vs.to_pkl(name, folder)\n", 
+  "category": "Ladybug", 
+  "name": "LB Dump VisualizationSet", 
+  "description": "Dump a Ladybug VisualiztionSet into a file.\n_\nThe \"LB Preview VisualizationSet\" component can be used to visualize the content\nfrom the file back into Grasshopper.\n-"
+}

ladybug_grasshopper/json/LB_Legend_2D_Parameters.json

@@ -0,0 +1,57 @@
+{
+  "version": "1.5.0", 
+  "nickname": "Legend2D", 
+  "outputs": [
+    [
+      {
+        "access": "None", 
+        "name": "leg_par2d", 
+        "description": "A legend parameter object that can be plugged into any of the\nLadybug components with a legend.", 
+        "type": null, 
+        "default": null
+      }
+    ]
+  ], 
+  "inputs": [
+    {
+      "access": "item", 
+      "name": "origin_x_", 
+      "description": "An integer in pixels to note the X coordinate of the base point from\nwhere the 2D legend will be generated (assuming an origin in the\nupper-left corner of the screen with higher positive values of\nX moving to the right). Alternatively, this can be a text string\nending in a % sign to denote the percentage of the screen where\nthe X coordinate exists (eg. 5%). The default is set to make the\nlegend clearly visible in the upper-left corner of the\nscreen (10 pixels).", 
+      "type": "string", 
+      "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "origin_y_", 
+      "description": "An integer in pixels to note the Y coordinate of the base point from\nwhere the legend will be generated (assuming an origin in the\nupper-left corner of the screen with higher positive values of\nY moving downward). Alternatively, this can be a text string\nending in a % sign to denote the percentage of the screen where\nthe X coordinate exists (eg. 5%). The default is set to make the\nlegend clearly visible in the upper-left corner of the\nscreen (50 pixels).", 
+      "type": "string", 
+      "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "seg_height_", 
+      "description": "A integer in pixels to note the height for each of the legend segments.\nAlternatively, this can be a text string ending in a % sign to\ndenote the percentage of the screen (eg. 5%). The default is set\nto make most legends readable on standard resolution\nscreens (25px for horizontal and 36px for vertical).", 
+      "type": "string", 
+      "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "seg_width_", 
+      "description": "An integer in pixels to set the width of each of the legend segments.\nAlternatively, this can be a text string ending in a % sign to\ndenote the percentage of the screen (eg. 5%). The default is set\nto make most legends readable on standard resolution\nscreens (36px for horizontal and 25px for vertical).", 
+      "type": "string", 
+      "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "text_height_", 
+      "description": "An integer in pixels to set the height for the legend text.\nAlternatively, this can be a text string ending in a % sign to\ndenote the percentage of the screen (eg. 2%).", 
+      "type": "string", 
+      "default": null
+    }
+  ], 
+  "subcategory": "4 :: Extra", 
+  "code": "\n\ntry:\n    from ladybug.legend import Legend2DParameters\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug:\\n\\t{}'.format(e))\n\n\ndef parse_dim_text(dim_text):\n    \"\"\"Parse text representing a dimension into an input for legend parameters.\"\"\"\n    try:\n        px_txt = int(dim_text)\n        return '{}px'.format(px_txt)\n    except ValueError:\n        return dim_text\n\n\n# parse all of the inputs\norigin_x_ = parse_dim_text(origin_x_) if origin_x_ is not None else None\norigin_y_ = parse_dim_text(origin_y_) if origin_y_ is not None else None\nseg_height_ = parse_dim_text(seg_height_) if seg_height_ is not None else None\nseg_width_ = parse_dim_text(seg_width_) if seg_width_ is not None else None\ntext_height_ = parse_dim_text(text_height_) if text_height_ is not None else None\n\n# make the 2D legend parameters\nleg_par2d = Legend2DParameters(origin_x_, origin_y_, seg_height_, seg_width_, text_height_)\n", 
+  "category": "Ladybug", 
+  "name": "LB Legend 2D Parameters", 
+  "description": "Use this component to change the colors, numerical range, and/or number of divisions\nof any Ladybug legend along with the corresponding colored mesh that the legend refers to.\n-\nAny Ladybug component that outputs a colored mesh and a legend will have an input\nthat can accept Legend Parameters from this component.\n-"
+}

ladybug_grasshopper/src/LB Dump Data.py

@@ -24,7 +24,7 @@
             written. (Default: 'data').
         _folder_: An optional directory into which the data collections will be
             written.  The default is set to a user-specific simulation folder.
-        _dump: Set to "True" to save the honeybee objects to file.
+        _dump: Set to "True" to save the data collection to a file.
 
     Returns:
         report: Errors, warnings, etc.
@@ -33,7 +33,7 @@
 
 ghenv.Component.Name = 'LB Dump Data'
 ghenv.Component.NickName = 'DumpData'
-ghenv.Component.Message = '1.5.0'
+ghenv.Component.Message = '1.5.1'
 ghenv.Component.Category = 'Ladybug'
 ghenv.Component.SubCategory = '4 :: Extra'
 ghenv.Component.AdditionalHelpFromDocStrings = '5'

ladybug_grasshopper/src/LB Dump VisualizationSet.py

@@ -0,0 +1,81 @@
+# Ladybug: A Plugin for Environmental Analysis (GPL)
+# This file is part of Ladybug.
+#
+# Copyright (c) 2022, Ladybug Tools.
+# You should have received a copy of the GNU Affero General Public License
+# along with Ladybug; If not, see <http://www.gnu.org/licenses/>.
+# 
+# @license AGPL-3.0-or-later <https://spdx.org/licenses/AGPL-3.0-or-later>
+
+
+"""
+Dump a Ladybug VisualiztionSet into a file.
+_
+The "LB Preview VisualizationSet" component can be used to visualize the content
+from the file back into Grasshopper.
+-
+
+    Args:
+        _vs: A VisualizationSet object to be written to a file. Typically, this is
+            the output from the "LB Preview VisualizationSet" component but
+            it can also be a custom VisualiztionSet object created with the
+            Ladybug Tools SDK.
+        _format_: Text or an integer to set the format of the output file.
+            Choose from the options below. (Default: JSON).
+                * 0 = JSON - Cross-language and handles any types of collections
+                * 1 = PKL - Compressed format only readable with Python
+        _name_: A name for the file to which the VisualizationSet will be written.
+            The default is derived from the identifier of the visualization set.
+        _folder_: An optional directory into which the VisualizationSet will be
+            written.  The default is set to a user-specific simulation folder.
+        _dump: Set to "True" to save the VisualizationSet to a file.
+
+    Returns:
+        report: Errors, warnings, etc.
+        vs_file: The path of the file where the VisualisationSet is saved.
+"""
+
+ghenv.Component.Name = 'LB Dump VisualizationSet'
+ghenv.Component.NickName = 'DumpVisSet'
+ghenv.Component.Message = '1.5.0'
+ghenv.Component.Category = 'Ladybug'
+ghenv.Component.SubCategory = '4 :: Extra'
+ghenv.Component.AdditionalHelpFromDocStrings = '0'
+
+import os
+
+try:
+    from ladybug.config import folders
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug:\n\t{}'.format(e))
+
+try:  # import the core ladybug_rhino dependencies
+    from ladybug_rhino.grasshopper import all_required_inputs
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_rhino:\n\t{}'.format(e))
+
+FORMAT_MAP = {
+    '0': 'json',
+    '1': 'pkl',
+    'json': 'json',
+    'pkl': 'pkl'
+}
+
+
+if all_required_inputs(ghenv.Component) and _dump:
+        # extract the VisualizationSet object if the input is the bake-able form
+    if hasattr(_vs, 'vis_set'):
+        _vs = _vs.vis_set
+
+    # set the component defaults
+    name = _name_ if _name_ is not None else _vs.identifier
+    home_folder = os.getenv('HOME') or os.path.expanduser('~')
+    folder = _folder_ if _folder_ is not None else \
+        os.path.join(home_folder, 'simulation')
+    file_format = 'json' if _format_ is None else FORMAT_MAP[_format_.lower()]
+
+    # write the data into the appropriate format
+    if file_format == 'json':
+        vs_file = _vs.to_json(name, folder)
+    elif file_format == 'pkl':
+        vs_file = _vs.to_pkl(name, folder)

ladybug_grasshopper/src/LB Legend 2D Parameters.py

@@ -0,0 +1,86 @@
+# Ladybug: A Plugin for Environmental Analysis (GPL)
+# This file is part of Ladybug.
+#
+# Copyright (c) 2022, Ladybug Tools.
+# You should have received a copy of the GNU Affero General Public License
+# along with Ladybug; If not, see <http://www.gnu.org/licenses/>.
+# 
+# @license AGPL-3.0-or-later <https://spdx.org/licenses/AGPL-3.0-or-later>
+
+"""
+Use this component to change the colors, numerical range, and/or number of divisions
+of any Ladybug legend along with the corresponding colored mesh that the legend refers to.
+-
+Any Ladybug component that outputs a colored mesh and a legend will have an input
+that can accept Legend Parameters from this component.
+-
+
+    Args:
+        origin_x_: An integer in pixels to note the X coordinate of the base point from
+            where the 2D legend will be generated (assuming an origin in the
+            upper-left corner of the screen with higher positive values of
+            X moving to the right). Alternatively, this can be a text string
+            ending in a % sign to denote the percentage of the screen where
+            the X coordinate exists (eg. 5%). The default is set to make the
+            legend clearly visible in the upper-left corner of the
+            screen (10 pixels).
+        origin_y_: An integer in pixels to note the Y coordinate of the base point from
+            where the legend will be generated (assuming an origin in the
+            upper-left corner of the screen with higher positive values of
+            Y moving downward). Alternatively, this can be a text string
+            ending in a % sign to denote the percentage of the screen where
+            the X coordinate exists (eg. 5%). The default is set to make the
+            legend clearly visible in the upper-left corner of the
+            screen (50 pixels).
+        seg_height_: A integer in pixels to note the height for each of the legend segments.
+            Alternatively, this can be a text string ending in a % sign to
+            denote the percentage of the screen (eg. 5%). The default is set
+            to make most legends readable on standard resolution
+            screens (25px for horizontal and 36px for vertical).
+        seg_width_: An integer in pixels to set the width of each of the legend segments.
+            Alternatively, this can be a text string ending in a % sign to
+            denote the percentage of the screen (eg. 5%). The default is set
+            to make most legends readable on standard resolution
+            screens (36px for horizontal and 25px for vertical).
+        text_height_: An integer in pixels to set the height for the legend text.
+            Alternatively, this can be a text string ending in a % sign to
+            denote the percentage of the screen (eg. 2%).
+
+    Returns:
+        leg_par: A legend parameter object that can be plugged into the "LB Preview
+            VisualizationSet" component to specify the properties of a
+            screen-oriented legend.
+"""
+
+ghenv.Component.Name = 'LB Legend 2D Parameters'
+ghenv.Component.NickName = 'Legend2D'
+ghenv.Component.Message = '1.5.0'
+ghenv.Component.Category = 'Ladybug'
+ghenv.Component.SubCategory = '4 :: Extra'
+ghenv.Component.AdditionalHelpFromDocStrings = '0'
+
+
+try:
+    from ladybug.legend import Legend2DParameters
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug:\n\t{}'.format(e))
+
+
+def parse_dim_text(dim_text):
+    """Parse text representing a dimension into an input for legend parameters."""
+    try:
+        px_txt = int(dim_text)
+        return '{}px'.format(px_txt)
+    except ValueError:
+        return dim_text
+
+
+# parse all of the inputs
+origin_x_ = parse_dim_text(origin_x_) if origin_x_ is not None else None
+origin_y_ = parse_dim_text(origin_y_) if origin_y_ is not None else None
+seg_height_ = parse_dim_text(seg_height_) if seg_height_ is not None else None
+seg_width_ = parse_dim_text(seg_width_) if seg_width_ is not None else None
+text_height_ = parse_dim_text(text_height_) if text_height_ is not None else None
+
+# make the 2D legend parameters
+leg_par2d = Legend2DParameters(origin_x_, origin_y_, seg_height_, seg_width_, text_height_)