====== Marine Weight Schedule - User Manual ======
===== Introduction =====
//Marine Weight Schedule// is a plugin for Rhino 3D designed to generate - from a vessel’s 3D model - a bill of masses/inertias, as well as a Bill Of Materials. It takes into account points, curves, surfaces, solids and blocks, and uses the parameters from the layers' names to apply the unitary/lineic/surfacic/volumic masses, with a margin percentage applied.

A command is also provided to generate a hydrostatic report at a given height interval (based on Rhino hydrostatics features)

Both reports will be generated as excel files (.xlsx) based on a customizable template, but Microsoft excel doesn’t need to be installed on the computer.
===== Plugin installation =====
==== Overview ====
The plugin installer can be downloaded at: [[https://www.tomkod.com/product/marine-weight-schedule/]] \\ 
A free trial is included, and yearly licenses can be purchased on the aforementioned page.\\ 
//Marine Weight Schedule // works with Rhino 6((Rhino 6.15 or higher)) and Rhino7((Rhino 7.5 or higher)).

{{page>start:plugins:common#[Yak]&noindent&nofooter&nodate}}

{{page>start:plugins:common#[License activation]&noindent&nofooter&nodate}}

{{page>start:plugins:common#[Toolbar]&noindent&nofooter&nodate}}
{{ :start:plugins:marineweightschedule:mws_toolbar.jpg?nolink |}}
===== Features and commands =====
==== MWS_About ====
This command can be used only from the command line prompt. It displays the plugin's current revision and license status.
{{ :start:plugins:marineweightschedule:mws_about.jpg?nolink&400 |}}
==== MWS_License ====
This command can be used only from the command line prompt. It displays the plugin's activation form.

See [[mws-usermanual#license_activation]].

==== ProjectWeightReport ====
Computes the whole model masses,  __as well as a Bill Of Materials__((v1.0.4 and later versions)) and generates an excel report.
=== Walkthrough ===
For each layer((The whole model or worksession will be used)), the command will retrieve the //Mass//, //Margin// and //Vertical offset// values from the layer name((Read "Model preparation" below)), then:
  - For each rhino object, the actual mass and gravity center will be computed, using the layer values. The layer's //Mass// will be used differently, depending on the object's type: punctual mass for Points, lineic mass for curves, surface mass for surfaces((To avoid errors, opened polysurfaces won't be allowed)), and volumic mass for closed polysurfaces.
  - At the same time, the Bill-of-Materials will be created internally.
  - An excel report will be created.
{{ :start:plugins:marineweightschedule:mws_walkthrough.gif?nolink |}}
=== Model preparation ===
The fundamental idea of this plugin is to match data from the model's objects and their layer. For this reason, each layer should contain only one specific material.//
For example: // 
  * The layer **''%%Deck1:SectionB:Nuts%%''** could contain only points, and the layer's //(mass)// information would be used as a punctual mass for each nut.
  * The layer **''%%Deck1:SectionB:plates%%''** could contain only surfaces, and the layer's //(mass)// information would be used as a surface mass for each plate.
== Layers naming convention ==
The document's layers should follow the following naming convention:
<code>LayerName *MaterialName* (Mass) %Margin% |VerticalOffset|</code>
where:
  * **''%%Mass%%''** will be the ponctual/lineic/surfacic/volumic mass
  * **''%%Margin%%''** (optional) will be the percentage to add to the object's mass.
  * **''%%VerticalOffset%%''** (optional) will be the the vertical offset to apply to the layer's masses
  * **''%%MaterialName%%''**((Since v1.1.3)) (optional) will the material's name. In the Bill-of-Material, the materials are displayed in a specific column. 
Two layers with the same name but different materials will not be grouped together.
{{ :start:plugins:marineweightschedule:pwr_layers2.jpg?nolink |}}

== Particular case for Stiffeners ==
A specific naming convention has been added to properly count the stiffeners in the Bill-of-Materials, to consider the scenarii explained below.
<WRAP center round info 60%>
Those particular cases only impact how materials will be counted in the Bill-of-Material tab. __The weight report results won't be impacted__.
</WRAP>

  * **Implicit stiffeners**
There are some cases where you don't want/need to create an actual geometry for your structure stiffeners, for example when you are at the early stage of your project. //Implicit stiffeners// let you count the required stiffener lengths relative to the layer's metal sheet's areas.
<code>LAYERNAME:   MyLayerName (Mass) %Margin% |VerticalOffset| [StiffenerName s=value]</code>
In the Bill-of-Material, this would create two outputs: an area for the surfaces in //"MyLayerName"//, and a length for their stiffeners.
<WRAP center round info 80%>
'StiffenerName Length' = 'MyLayerName Area' / s
</WRAP>
For example:
{{ :start:plugins:marineweightschedule:pwr_layersimplicitstiffeners.jpg?nolink |}}
<WRAP center round tip 90%>
Since v1.1.3, the implicit stiffeners can also have their material names defined with a specific syntax:
<code>LAYERNAME:   MyLayerName *MaterialName* (Mass) %Margin% |VerticalOffset| [StiffenerName s=value *MaterialName*]</code>
</WRAP>
  * **Stiffeners defined as curves in the model**
Two kind of curves-defined stiffeners can be used:
    * Folded plates
<code>LAYERNAME:   W:120x6 BF60</code>
This will be counted as one surface, Thickness 6, width=120+60. Thus the result in the Bill-of-materials will be:
<WRAP center round info 80%>
'Th.6 plate Area' = length x (120+60)
</WRAP>
    * Profile with flat plate
<code>W:120x6 F:80x8</code>
This will count as one surface, Thickness 6, width=120, plus one profile 80x8 
<WRAP center round info 80%>
In this case, the command will output an area for the plate and a length for the profile:

'Th.6 plate Area' = length x 120

'80x8 profile length ' =length
</WRAP>
  * **Stiffeners defined as surfaces in the model**
In some cases, you might want to represent your stiffeners as a 3D surface in the model, but count them as lineic outputs in the Bill-of-Materials because they are technically profiles. 
<code>LAYERNAME:   F:80x8</code>
This would output:
<WRAP center round info 80%>
'80x8 profile Length' = area / 80
</WRAP>
As for the weight estimate, the layer's optional %Tolerance% will be considered:
<code>LAYERNAME:   F:80x8 |34.1| (87.2) %3.4%</code>
This would output:
<WRAP center round info 60%>
'80x8 profile Length' = (area / 80) + (area / 80) * 3.4/100
</WRAP>

== Particular case for Blocks ==
By default, rhino(r) blocks((instances references)) are ignored by the command. However, we provide several commands to transform blocks into GBlocks, which are considered in the reports as punctual masses.

See [[start:plugins:marineweightschedule:mws-usermanual#gblock_setdata|gblock_setdata]]

<WRAP center round important 90%>
When the command will process GBlocks, their layer properties will be ignored, and their internal definition will be used instead (Name, gravity center, mass).
</WRAP>


=== Output ===
When the whole model has been processed, an excel((.xlsx)) report is generated, and the user is invited to pick a name and location for the resulting file.
Bill of masses main sheet:

{{:start:plugins:marineweightschedule:pwr_excel_results.jpg?nolink|}}

Bill of masses detailed sheets for Volumes, surfaces, curves, and points:

{{:start:plugins:marineweightschedule:pwr_excel_volumes.jpg?nolink|}}

{{:start:plugins:marineweightschedule:pwr_excel_points.jpg?nolink|}}

Bill of materials:

{{:start:plugins:marineweightschedule:pwr_excel_bom.jpg?nolink|}}

A custom ViewPort is created with the gravity center displayed:

{{:start:plugins:marineweightschedule:pwr_viewport2.jpg?nolink|}}
===  Options === 
No option available.
=== Scripted mode ===
Using the command's scripted mode //-ProjectWeightReportByHullSection// will enable an hidden option:
  * **AxisLengthInMeters**: Enter the gravity center's preview axis length used in the result views
=== Customization ===
This command behavior can be customized, by editing some files in the install directory((If you installed from Rhino's package manager, the installation path is usually: ''%%%appdata%\McNeel\Rhinoceros\7.0\Plug-ins%%'')).
== Excel templates ==
The excel report template "PWE_Model.xlsx" can be modified to fit your graphical needs, however, it is recommended to edit only the text values, the column sizes, and the logos while keeping the document's general layout.
== Naming conventions for the layers ==
The naming convention for information specified in the layer's names is based on REGEX (Regular expression), which is the most common way to match a text string to a pattern. The default values can be edited in the file "MWS_CustomRegex.yaml" with any standard text editor.
<WRAP center round tip 90%>
We recommend using the free text editor NotePad++ will make the YAML format more readable:
{{ :start:plugins:marineweightschedule:mws_customregex.jpg?nolink |}}
</WRAP>
You can test in real-time your customized regular expressions at [[https://regex101.com/|https://regex101.com/]], and see if your pattern matches your layer's names.

**Example1**: [[https://regex101.com/r/0C2262/1|The default regular expression to match the implicit stiffeners between square brackets]]: ''%%[StiffenerName s=value *MaterialName*]%%''

**Example2**: [[https://regex101.com/r/qIbMNb/1|The edited regular expression to match the implicit stiffeners between either square brackets or exclamation marks]]: ''%%[StiffenerName s=value *MaterialName*]%%'' or ''%%!StiffenerName s=value *MaterialName*!%%''
----
==== ProjectWeightReportByHullSection ====
This command((From v1.2.0)) splits the model into sections, then runs //[[start:plugins:marineweightschedule:mws-usermanual#projectweightreport|ProjectWeightReport]]// on each section.
The resulting Excel file will contain the usual model-wide report, plus independent reports for every section. (Named from S001 to Sxxx)
{{ :start:plugins:marineweightschedule:pwr_hs.jpg?nolink |}}
=== Walkthrough ===
  - Run the command //ProjectWeightReportByHullSection//
  - Pick the x-axis coordinates delimiting the sections((The coordinates can be registered either by clicking on the model or by entering numbers in the command line.)).
  - The script will split internally the curves and surfaces, and sort points and volumes by each section's bounding box. GBlocks will be allocated using the location of their gravity centers.
<WRAP center round important 90%>
Items((Volumes, surfaces, curves, points, or GBlocks)) located on the plane between two sections will be counted in both sections, leading to a difference between the global weight and the sum of every section's weight. A solution is to offset the cutting plane by a few millimeters.
</WRAP>
<WRAP center round info 90%>
Solids((Closed polysurfaces)) __must not__ by split, because the result would be opened polysurfaces, which is forbidden when creating a //ProjectWeightReport//
</WRAP>

=== Scripted mode ===
Using the command's scripted mode //-ProjectWeightReportByHullSection// will enable two hidden options:
  * **AxisLengthInMeters**: Enter the gravity center's preview axis length used in the result views
  * **DrawSplittedGeometries**: When enabled, a layer //ProjectWeightReportByHullSection// will be added to the model, with the split geometry. This is useful to check if no curves/surfaces were lost in the sections' splitting operations.
----
==== HydrostaticReport ====
Computes a hydrostatic analysis at different heights and generates an excel report.
=== Walkthrough ===
The hull's surface or polysurface is selected as input.
Once validated, Rhino's hydrostatic calculation is run at various heights as defined in options, and an excel report is generated.
 {{ :start:plugins:marineweightschedule:ext_hydro.jpg?nolink |}}
===  Options === 
^ TEMin | Minimum height (mm)|
^ TEmax | Maximum height (mm)|
^ Delta | Distance between two tested height (mm)|
^ Density | Water Density|
^ AutoMinMax | Detect TEMin and TEmax values from geometry (Only available when a geometry is selected)|
=== Customization ===
The excel report template "Hydro_Model.xlsx" can be modified in the plugin's install directory, usually:

<wrap hi>%AppData%\McNeel\Rhinoceros\7.0\Plug-ins\Marine Weight Schedule for RH6-RH7 (dac6da37-23fc-4ad6-9b46-33a2cad9e13b)\//VersionNumber//</wrap> \\ (Adapt Rhino's version if needed, as well as the plugin's version)
It is recommended to edit only the text values and the logos while keeping the document's general layout.
----
==== GBlock_SetData ====
Adds gravity center and mass information to a block. GBlocks are considered by the command //ProjectWeightReport //, which makes them extremely useful for your pieces of equipment.
<WRAP center round info 90%>
When using this command on an existing GBlock, its gravity center, mass information, and name will be overridden.

This is the only way to edit a GBlock name or data.
</WRAP>
=== Walkthrough ===
  - Start the command
  - Pick a rhino block((Instance reference)) in the model
  - Pick the GBlock's gravity center
  - Enter the GBlock's mass
  - Enter the GBlock's name (By default, Rhino's block name is used)
  - Click OK or press Enter
{{ :start:plugins:marineweightschedule:gblock_setdata_walkthrough.gif?nolink |}}

==== GBlock_GetList ====
Lists every existing GBlock name and masses to the command line.
=== Walkthrough ===
  - Start the command
  - A window is shown with details about every block instances in the model
{{ :start:plugins:marineweightschedule:gblock_getlist_walkthrough.gif?nolink |}}

==== GBlock_ReadData ====
Reads a GBlock data.
=== Walkthrough ===
  - Select a GBlock
  - The data is shown in the command line:
{{:start:plugins:marineweightschedule:gblock_readdata_walkthrough.jpg?nolink|}}

==== Gblock_Select ====
Select a block by their GBlock Name. (From a list of available GBlock names)
=== Walkthrough ===
  - Launch the command
  - Pick a GBlock name from the list
  - Every instance of this GBlock will be selected in the model
{{ :start:plugins:marineweightschedule:gblock_select_walkthrough.gif?nolink |}}

==== GBlock_SelectNextMissingData ====
Selects the next block in the document which is not a GBlock (gravity center and mass are undefined)
=== Walkthrough ===
  - Launch the command
  - The commands loops between the non-GBlocks instances in the model. (Press ESC to leave) 
{{ :start:plugins:marineweightschedule:gblock_selectnextmissingdata_walkthrough.gif?nolink |}}

==== GBlock_Rename ====
Renames a GBlock definition (Every instance will be renamed)
=== Walkthrough ===
  - Launch the command
  - Pick a Gblock from the list
  - Enter a new name for the GBlock