Module viiaPictures

These modules contain the functions to create pictures or plots for the VIIA process. In the viiaPackage we refer to pictures when the image is generated in engineering software. If the image is generated in python we refer to it as plot.

Create pictures and plots

These are the pictures of the model generated in the structural software (DIANA or ABAQUS).

viiapackage.viiaPictures.viia_model_pictures(project: ViiaProject, backside: bool = False, odb_file: str = None, software: str = 'diana', add_legend: bool = True, legend_loc: str = 'upper right', legend_fontsize: int = 7)[source]

This function creates the model pictures. It will place them in the default model picture folder (viiaStatus). If DIANA is used, this function will only be performed if running in DIANA and when model is created and the results are loaded.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
backside (bool): If set to True, also the pictures in the opposite direction are created.
odb_file (str): Name of odb_file used to make model pictures in Abaqus.
software (str): Software that is used to create the model pictures. Options are ‘diana’ and ‘abaqus’. Default value is ‘diana’.
add_legend (bool): Indicates if a legend should be added to the pictures.
legend_loc (str): The legend location which is used for matplotlib. Default location is upper right.
fontsize (int): The font size of the legend used for matplotlib. Default value 7.

Output:

The default views are generated.
The pictures are generated in the model picture folder with the current time stamp and version.

Helper-functions for generic plots

These are the images in python for general purpose.

viiapackage.pictures.generic_plots.viia_create_response_spectrum_graph.viia_create_response_spectrum_graph(project: ViiaProject, response_spectrum: NPRResponseSpectrum, title: str = 'Horizontal Response Spectrum', save_folder: Optional[Path] = None, q_factor: float = 1, ductile: bool = False) → Path[source]

This function creates a picture with the requested response spectrum graph.

Input:

project (obj): Project object containing collections and of fem objects and project variables.
response_spectrum (obj): Object reference of the ResponseSpectrumNPR instance to be used in the plot.
title (str): Title that will be shown on top of the plot. Default value ‘Horizontal Response Spectrum’.
save_folder (Path): Specify the folder location where the plot should be created. Default value is None, creating the plot in the default images folder defined for the project.
q_factor (float): Behaviour factor for ductility. Default value 1.
ductile: Option to calculate the response spectrum acceleration considering ductility, default set to False.

Output:

The function collects the data and creates the requested response spectrum graph plot.
Returns the file reference of the created png-image in the requested folder.

Helper-functions for model pictures

These are the images with the model generated in the structural software (DIANA or ABAQUS).

viiapackage.pictures.model_pictures.model_pictures.viia_create_model_pictures(project: ViiaProject, backside: bool = False) → List[ModelPicture][source]

This function creates the model pictures for VIIA. The instances of ModelPicture class are created and added to project. The images will only be created when this function is used in DIANA (in development for ABAQUS) and when the model is created and meshed. The images are saved to the image folder set in ViiaStatus.

Warning

Currently piles and reinforcements are not supported. Backside input argument is not available yet.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
backside(bool): If set to True, also the pictures in the opposite direction are created.

Output:

Returns list of instances of ModelPicture class with all model pictures required for VIIA.
The images are created in the model picture folder with the current time stamp and version, in the software where script is running.

viiapackage.pictures.model_pictures.helper_functions.add_model_picture_legends.viia_add_legend_model_pictures(project: ViiaProject, json_dir: Path, output_dir: Optional[Path] = None, legend_loc: str = 'upper right', fontsize: int = 7) → None[source]

This function will add a legend to the existing figures in the model picture folder according to the legend_data json-file in the folder.

Input:

project (obj): Project object containing collections and of fem objects and project variables.
json_dir (Path): Path that contains the legend_data.json and model pictures.
output_dir (Path): Path that output the model pictures with legends. Default value None, using the work folder to store the pictures.
legend_loc (str): The legend location which is used for matplotlib. Default location is upper right.
fontsize (int): The font size of the legend used for matplotlib. Default value 7.

Output:

A json-file containing all picture color codes and names will be created.

viiapackage.pictures.model_pictures.helper_functions.add_model_picture_legends.viia_model_picture_legend_data(project: ViiaProject, model_picture_name: str, json_dir: Path, shape_colours: List[str], shapes: List[Shapes], element: str = None) → Optional[Union[Dict[str, str], Dict[str, Dict[str, str]]]][source]

This function will write a json file to output the project pictures information. Each picture is output with all color codes in that picture and a name associated with each color code.

Input:

project (obj): Project object containing collections and of fem objects and project variables.
model_picture_name (str): The name of the model picture to add the legend data.
json_dir (Path): Path that json file will be created in.
shapes_colours (list of str): The list contains the colour codes included in the model picture.
shapes (list of shapes): The list contains the shapes included in the model picture.
element (str): The string indicates the element category, e.g., beam.

Output:

A json file containing all picture colour codes and names will be created.

viiapackage.pictures.model_pictures.helper_functions.get_model_picture_name.viia_get_model_picture_name(layer: Layer, element: str) → str[source]

Function to get the model picture name for the model picture.

Input:

layer (obj): The layer object where the name of the layer is decided..
element (str): The scope of the model picture, this will be appended directly after the layer to make the picture name.

Output:

Returns the name of the model picture according VIIA naming convention.

Helper-functions for model plots

These are the images with the model generated in python.

Helper-functions for PSSE-NSCE plots

These are the images with results generated in python for PSSE-NSCE overview.

class viiapackage.pictures.psse_nsce_plots.viia_plot_psse_nsce.PSSENSCEPlotSettings(psse_color: str = '#C00040', nsce_color: str = '#4040C0', psse_linewidth: float = 3, nsce_linewidth: float = 3, figsize: Tuple = (10, 10), subfolder: str = 'PSSE NSCE', file_base_name: str = 'Element Classification')[source]

Bases: object

Helper class for storing settings for PSSE and NSCE plots.

viiapackage.pictures.psse_nsce_plots.viia_plot_psse_nsce.viia_plot_psse_nsce(project: ViiaProject, settings: PSSENSCEPlotSettings = PSSENSCEPlotSettings(psse_color='#C00040', nsce_color='#4040C0', psse_linewidth=3, nsce_linewidth=3, figsize=(10, 10), subfolder='PSSE NSCE', file_base_name='Element Classification'), show: bool = False, grid: Optional[Grid] = None) → List[Path][source]

Function to create the psse and nsce plots. By default, psse’s are plotted in red and nsce’s in blue. All shapes that have either structural type PSSE or NSCE defined in their metadata are included in the plots. A separate image is created for each layer.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
settings (obj): Settings object for the plot, including styling and save location.
show (bool): Toggle to show the plot. Default is False.
grid (Grid): Optional grid object to plot behind the shapes. Default is the first grid in the collections.

Output:

Plots are created in the specified folder. Default location is workfolder/Appendix Pictures/PSSE NSCE.

Helper-functions for result pictures

These are the images with results generated in the structural software (DIANA or ABAQUS).

viiapackage.pictures.result_pictures.result_pictures_eigenvalue.viia_create_result_pictures_eigenvalue(project: ViiaProject, analysis: Analysis, view: Optional[View] = None) → List[ResultPicture][source]

Function to create the eigenvalue analysis result pictures.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
analysis (obj): Object reference of analysis, to retrieve the result case, result items, result file and relevant information.
view (obj): View that should be used for the pictures. When None the default view will be used. Default is None.

Output:

Returns the result pictures created for eigenvalue analysis.

viiapackage.pictures.result_pictures.result_pictures_nls.viia_create_result_pictures_nls(project: ViiaProject, analysis: Analysis, view: Optional[View] = None) → List[ResultPicture][source]

Function to create the nonlinear static analysis result pictures.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
analysis (obj): Object reference of analysis, to retrieve the result case, result items, result file and relevant information.
view (obj): View that should be used for the pictures. When None the default view will be used. Default is None.

Output:

Returns the result pictures created for nonlinear static analysis.

viiapackage.pictures.result_pictures.result_pictures_nlth.viia_create_result_pictures_nlth(project: ViiaProject, analysis: Analysis, view: Optional[View] = None) → List[ResultPicture][source]

Function to create the NLTH analysis result pictures.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
analysis (obj): Object reference of analysis, to retrieve the result case, result items, result file and relevant information. If None is provided it will be checked if there is only one analysis and that one will be taken. Default is None.
view (obj): View that should be used for the pictures. When None the default view will be used. Default is None.

Output:

Returns the result pictures created for nonlinear time-history analysis.

Helper-functions for result plots

These are the images with results generated in python.

viiapackage.pictures.result_pictures.result_plots_nlth.viia_create_result_plots_nlth(project: ViiaProject, analysis: Analysis = None) → List[ResultPicture][source]

Function to create the NLTH analysis result plots.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
analysis (obj): Object reference of analysis, to retrieve the result case, result items, result file and relevant information. If None is provided it will be checked if there is only one analysis and that one will be taken. Default is None.

Output:

Returns the result plots created for nonlinear time-history analysis.

Other helper-functions

viiapackage.pictures.model_pictures.helper_functions.add_model_picture_legends.viia_add_legend_model_pictures(project: ViiaProject, json_dir: Path, output_dir: Optional[Path] = None, legend_loc: str = 'upper right', fontsize: int = 7) → None[source]

This function will add a legend to the existing figures in the model picture folder according to the legend_data json-file in the folder.

Input:

project (obj): Project object containing collections and of fem objects and project variables.
json_dir (Path): Path that contains the legend_data.json and model pictures.
output_dir (Path): Path that output the model pictures with legends. Default value None, using the work folder to store the pictures.
legend_loc (str): The legend location which is used for matplotlib. Default location is upper right.
fontsize (int): The font size of the legend used for matplotlib. Default value 7.

Output:

A json-file containing all picture color codes and names will be created.

viiapackage.pictures.model_pictures.helper_functions.add_model_picture_legends.viia_model_picture_legend_data(project: ViiaProject, model_picture_name: str, json_dir: Path, shape_colours: List[str], shapes: List[Shapes], element: str = None) → Optional[Union[Dict[str, str], Dict[str, Dict[str, str]]]][source]

This function will write a json file to output the project pictures information. Each picture is output with all color codes in that picture and a name associated with each color code.

Input:

project (obj): Project object containing collections and of fem objects and project variables.
model_picture_name (str): The name of the model picture to add the legend data.
json_dir (Path): Path that json file will be created in.
shapes_colours (list of str): The list contains the colour codes included in the model picture.
shapes (list of shapes): The list contains the shapes included in the model picture.
element (str): The string indicates the element category, e.g., beam.

Output:

A json file containing all picture colour codes and names will be created.

viiapackage.pictures.model_pictures.helper_functions.get_model_picture_name.viia_get_model_picture_name(layer: Layer, element: str) → str[source]

Function to get the model picture name for the model picture.

Input:

layer (obj): The layer object where the name of the layer is decided..
element (str): The scope of the model picture, this will be appended directly after the layer to make the picture name.

Output:

Returns the name of the model picture according VIIA naming convention.

viiapackage.pictures.result_pictures.helper_functions.get_legend_colours.viia_get_legend_colours(pic_type: str, critical_boundary_colour: str = '#ff0000', non_critical_boundary_colour: str = '#0000ff') → Tuple[str, str][source]

This function sets the upper-bound and lower-bound colours.

Input:

pic_type (str): The result type of the result picture, this is defined in the viia-result_pictures yaml file. Used to check for maximum or minimum critical boundary (or crackwidth).
critical_boundary_colour (str): The colour to be used for the critical boundary. Default value ‘#ff0000’.
non_critical_boundary_colour (str): The colour to be used for the non-critical boundary. Default value ‘#0000ff’.

Output:

Returns the order to be used in the legend of the boundary colours. Returns list of two strings.

viiapackage.pictures.result_pictures.helper_functions.get_legend_values.viia_get_legend_values(max_value: float, min_value: float, pic_type: str, nr_level: int = 9, fraction_digits: int = 4) → List[float][source]

Function to get the values for the legend.

Input:

max_value (float): Maximum value of the legend.
min_value (float): Minimum value of the legend.
pic_type (str): The result type of the result picture, this is defined in the viia-result_pictures yaml file. Used to check for maximum or minimum critical boundary (or crackwidth).
nr_level (int): Number of levels to be applied in the picture. Default value is 9 levels.
fraction_digits (int): Precision for the rounding of the values of the legend.

Output:

Returns list with values for the legend of the picture.

viiapackage.pictures.result_pictures.helper_functions.get_limits.viia_get_limits(project: ViiaProject, shape_set: Union[Dict, List], output_item: OutputItem, pic_type: str, scope: str, component: str, material: str = None) → Tuple[Optional[float], Optional[float], Optional[bool]][source]

This function returns the limit values (maximum and minimum) for the NLTH result pictures. The limits comply to the check mentioned in the most recent Bass of Design report.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
shape_set (dictionary or list): List of shapes or dictionary with subdivisions for different sets of shapes or connections.
output_item (obj): Instance of output item for what the limits should be found.
pic_type (str): The result type of the result picture, this is defined in the viia-result_pictures yaml-file.
scope (str): The scope of the result picture, this is defined in the viia-result_pictures yaml-file.
component (str): Component of the plot result type.
material (str): Material name of the shape. Default value is None.

Output:

Returns the maximum and minimum value for different scope and shape sets.

viiapackage.pictures.result_pictures.helper_functions.get_output_item.viia_get_output_item(project: ViiaProject, picture_type: Dict[str, str], output_item_lst: List[OutputItem], component: Union[str, int]) → Optional[OutputItem][source]

Function to get the correct output-item to be used for the result picture.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
picture_type (dict): Dictionary with info from yaml to get the correct output-item. The dictionary should contain ‘output’ and ‘theoretical_formulation’. Optional is ‘component’ key. The dictionary should contain:
output_item_lst (list): The output item list containing a list of output items used to search for the item for result pictures.
component (str): The component of the requested output item.

Output:

The instance of OutputItem class that should be used for the result picture.

viiapackage.pictures.result_pictures.helper_functions.get_plot_shapes.viia_get_scope_shape_sets(project: ViiaProject, scope: str, pic_type: str) → Union[Dict[str, List[Shapes]], Dict[str, Dict[str, List[Union[Shapes, Connections]]]]][source]

This function collects the required shape-sets for the result pictures based on the scope definition. For example the ‘NoRoof’ scope will hide the roof shapes for the result pictures.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
scope (str): The scope that defines the selection of shapes to be visible on the result picture. Select from ‘building’, ‘noroof’, ‘floors-interstorey’, ‘walls-storey’, ‘beams-material-storey’, ‘columns-material-storey’, ‘floors-material-storey’, ‘interfaces-storey’, ‘floors-timber-storey’, ‘roofs-timber’ or ‘reinforcements-storey’.

Output:

Returns list of shapes, or dictionary with subdivisions for different sets of shapes or connections. In the last case multiple pictures are to be generated based on scope.

viiapackage.pictures.result_pictures.helper_functions.get_plot_shapes.viia_update_plot_config(project: ViiaProject, current_config: dict, component: str)[source]: Helper function to update the result plot config with the correct dnb file name.

viiapackage.pictures.result_pictures.helper_functions.get_result_case.viia_get_resultcase_info(analysis: Analysis, analysis_block: AnalysisBlock, case: Optional[str] = None, eigenfrequencies: Optional[Dict[int, List[float]]] = None) → Tuple[Tuple[float, Union[float, str]], AnalysisBlock][source]

Function returns the input for step in the result picture create function.

Input:

analysis (obj): Object reference of analysis.
analysis_block (obj): Object reference of the analysis-block of which results are to be plotted.
case (str): Specifying the case or scope to be collected. Optional parameter, should be provided for LTH and NLTH: select from ‘last timestep’ or ‘last loadstep’. It should be provided for the eigenvalue analysis result pictures: select from ‘ModeGovX1’, ‘ModeGovX1-NoRoof’, ‘ModeGovX2’, ‘ModeGovX2-NoRoof’, ‘ModeGovY1’, ‘ModeGovY1-NoRoof’, ‘ModeGovY2’, ‘ModeGovY2-NoRoof’, ‘ModeGovZ’ or ‘ModeGovZ-NoRoof’. These are defined in the viia-result_pictures yaml file. Default value is None.
eigenfrequencies (list): List with modes and eigenfrequencies. Only used for eigenvalue result pictures (analysis A3 and A7). Default value is None.

Output:

Returns a tuple of two items. The first item is the step or a tuple with mode and eigenfrequency. The second item is the execute block to be used for the result picture.

viiapackage.pictures.result_pictures.helper_functions.get_result_picture_name.viia_get_result_picture_name(diana_component_abbreviation: str = 'DtZ', scope: str = 'Building', pic_type_key: str = None, layer: str = None, material_type: str = None, analysis_type: str = 'nlth') → str[source]

Function to get the result picture name for the result picture.

Input:

diana_component_abbreviation (str): Abbreviation of component in diana style of the plot result type.
scope (str): The scope of the result picture, this is defined in the viia-result_pictures yaml file.
pic_type_key (str): The result type of the result picture, this is defined in the viia-result_pictures yaml file.
layer (str): The result layer of the result type, this is defined in the viia-result_pictures yaml file.
material_type (str): Used to differentiate materials.
analysis_type (str): The analysis type of the result picture.

Output:

Returns the name of the result picture according VIIA naming convention.

viiapackage.pictures.result_pictures.helper_functions.read_result_yaml.viia_load_result_picture_yaml(project: ViiaProject) → Optional[Dict][source]

Helper function to get the data for the result pictures.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.

Output:

Return the data read from the yaml file.

viiapackage.pictures.result_pictures.helper_functions.result_pictures_and_plots.viia_create_result_pictures_plots(project: ViiaProject, analysis: Analysis = None, pictures: bool = True, view: Optional[View] = None) → Union[List[ResultPicture], List[Path]][source]

Function to create the analysis result pictures or plots.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
analysis (obj): Object reference of analysis, to retrieve the result case, result items, result file and relevant information. If None is provided it will be checked if there is only one analysis and that one will be taken. Default is None.
pictures (bool): Indicates if pictures (to be made in the software gui) of plots (from python memory) should be made.
view (obj): View that should be used for the pictures. When None the default view will be used. Default is None.

Output:

Returns the result pictures created for nonlinear time-history analysis.

viiapackage.pictures.result_pictures.helper_functions.setup_model_and_analysis.viia_set_model_and_analysis_diana(project: ViiaProject, analysis: Analysis)[source]

Function used to import the dat-file of the project and setup the analysis of specified in DIANA.

Input:

project (obj): VIIA project object containing collections of fem objects and project variables.
analysis (obj): Object reference of the analysis of which results are to plot.
datfile (Path): Location of the dat-file of the model in DIANA.

Output:

No output. Model is set up ready for result picture in DIANA.