feat(receiver file): add command to add output_spec

Add a new function and command to add output_spec to rfluxmtx control parameters.

honeybee_radiance_folder/cli.py

@@ -7,7 +7,7 @@
 import re
 
 from honeybee_radiance_folder.folder import ModelFolder as Folder
-from honeybee_radiance_folder.folderutil import _as_posix
+from honeybee_radiance_folder.folderutil import _as_posix, add_output_spec_to_receiver
 
 
 # command group for all radiance extension commands.
@@ -209,6 +209,35 @@ def aperture_groups(radiance_folder, model, exterior, log_file):
         sys.exit(0)
 
 
+@folder.command('add-output-spec')
+@click.argument(
+    'receiver-file', type=click.Path(exists=True, file_okay=True, resolve_path=False)
+)
+@click.argument('output-spec', type=click.STRING)
+@click.option(
+    '-o', '--output-file', help='Optional path for an output file. By default this '
+    'command modifies the input receiver file.', default=None, show_default=True
+)
+def add_output_spec(receiver_file, output_spec, output_file):
+    """Add output spec to a receiver file.
+    
+    Args:
+        receiver_file: Path to a receiver file. You can find these files under the
+            ``aperture_group`` subfolder.
+        output_spec: A string for receiver output spec.
+    """
+    try:
+        add_output_spec_to_receiver(
+            receiver_file=receiver_file, output_spec=output_spec,
+            output_file=output_file
+        )
+    except Exception as e:
+        _logger.exception('Failed to add output spec to receiver.\n{}'.format(e))
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+
 @folder.command('dynamic-scene')
 @click.argument(
     'radiance-folder', type=click.Path(exists=True, file_okay=False, resolve_path=True)

honeybee_radiance_folder/folderutil.py

@@ -2,6 +2,7 @@
 """Utilities for Radiance folder structure."""
 import os
 import json
+import re
 
 
 def _as_posix(path):
@@ -358,6 +359,42 @@ def parse_dynamic_scene(states_file, validate=True):
     return geometries
 
 
+def add_output_spec_to_receiver(receiver_file, output_spec, output_file=None):
+    """Add output spec to a receiver file.
+
+    Args:
+        receiver_file: Path to a receiver file. You can find these files under the
+            ``aperture_group`` subfolder.
+        output_spec: A string for receiver output spec.
+        output_file: An optional output file to write the modified receiver. By default
+            this function overwrites the original file.
+    """
+    # find and replace
+    if not os.path.isfile(receiver_file):
+        raise ValueError('Failed to find %s' % receiver_file)
+
+    with open(receiver_file, 'r') as f:
+        content = f.read()
+    try:
+        value = re.search(r'^#@rfluxmtx[\s\S].*$', content, re.MULTILINE).group(0)
+    except AttributeError:
+        raise ValueError(
+            '%s is not a valid receiver file with '
+            'RfluxmtxControlParameters.' % receiver_file
+        )
+
+    if 'o=' in value:
+        raise ValueError('%s already has output_spec' % value)
+
+    ctrl_params = value.strip() + ' o=%s' % output_spec
+
+    updated_content = re.sub(value, ctrl_params, content)
+
+    out_file = output_file or receiver_file
+    with open(out_file, 'w') as outf:
+        outf.write(updated_content)
+
+
 def _nukedir(target_dir, rmdir=True):
     """Delete all the files inside target_dir.
     Usage:

tests/aperture_group_test.py

@@ -1,5 +1,8 @@
 # -*- coding: utf-8 -*-
+import os
+
 from honeybee_radiance_folder import ModelFolder as Folder
+from honeybee_radiance_folder.folderutil import add_output_spec_to_receiver
 
 
 def test_static_aperture():
@@ -20,3 +23,13 @@ def test_aperture_group():
     assert ap.states[0].default == 'south_window..default..000.rad'
     assert ap.states[1].identifier == '1_diffuse'
     assert ap.states[1].default == 'south_window..default..001.rad'
+
+
+def test_add_output_spec():
+    re_file = r'./tests/assets/project_folder/model/aperture_group/south_window..mtx.rad'
+    out_file = r'./tests/assets/temp/south_window..mtx.rad'
+    add_output_spec_to_receiver(re_file, 'cubical.vmx', out_file)
+    assert os.path.isfile(out_file)
+    with open(out_file) as outf:
+        content = outf.read()
+    assert '#@rfluxmtx h=kf u=0,0,1.0 o=cubical.vmx' in content