Skip to content

Commit

Permalink
see CHANGELOG
Browse files Browse the repository at this point in the history
  • Loading branch information
@ThoHiller
ThoHiller committed Sep 5, 2023
1 parent 27ead7b commit fc54792
Show file tree
Hide file tree
Showing 32 changed files with 1,047 additions and 322 deletions.
18 changes: 18 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Changelog

## [0.1.1] - 2023-09-05

### Added
- A cleaner handling of targets.
- More targets from the paper included
- Manual setting of PML boundary widths

### Changed
- Minor GUI improvements and consistency clean ups.

## [0.1.0] - 2023-07-14

Initial Version

[0.1.1]: https://github.com/ThoHiller/gprgravel/compare/v0.1.0...v0.1.1
[0.1.0]: https://github.com/ThoHiller/gprgravel/releases/tag/v0.1.0
4 changes: 2 additions & 2 deletions GPRGRAVEL/GPRGRAVEL.m
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@
%------------- BEGIN CODE --------------

%% GUI 'header' info and default GUI settings
myui.version = '0.1.0';
myui.date = '14.07.2023';
myui.version = '0.1.1';
myui.date = '05.09.2023';
myui.author = 'Thomas Hiller';

myui.fontsize = 8;
Expand Down
3 changes: 2 additions & 1 deletion GPRGRAVEL/GPRGRAVEL_createGUI.m
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,8 @@ function GPRGRAVEL_createGUI(h,wbon)
% maximal height of each panel
grains_max = 6*edith+7*spacing+headerh;
% params_max = 8*edith+9*spacing+headerh-14;
params_max = 13*edith+14*spacing+headerh-5;
% params_max = 13*edith+14*spacing+headerh-5;
params_max = 17*edith+18*spacing+headerh-9;
domain_max = 8*edith+9*spacing+headerh;
% save the heights information (needed for minimizing the panels)
myui.heights = [22 22 22 -1; grains_max domain_max params_max -1];
Expand Down
125 changes: 113 additions & 12 deletions GPRGRAVEL/GPRGRAVEL_createPanelParameter.m
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@
surfacepanel = uipanel('Parent',gui.panels.Params.VBox,'Title','Surface');
satprofilepanel = uipanel('Parent',gui.panels.Params.VBox,'Title','Saturation Profile');
miscpanel = uipanel('Parent',gui.panels.Params.VBox,'Title','Misc');
set(gui.panels.Params.VBox,'heights',[22*5+3*6+15 -1 22*3+3*5+12 -1]);
exportpanel = uipanel('Parent',gui.panels.Params.VBox,'Title','Export');
set(gui.panels.Params.VBox,'heights',[5*22+6*3+15 22+2*3+17 3*22+5*3+12 22+2*3+17 3*22+5*3+12]);

%% Parameter - Target
targetvbox = uix.VBox('Parent', targetpanel,'Spacing',3,'Padding',3);
Expand Down Expand Up @@ -132,24 +133,24 @@
'FontSize',myui.fontsize);

tstr = 'Set polar angle';
gui.edit_handles.targetp = uicontrol('Style','Edit',...
gui.edit_handles.targetTheta = uicontrol('Style','Edit',...
'Parent',edittarget2,...
'String',sprintf('%4.3f',data.params.targetOrient(1)),...
'Tag','params_targetOrientp',...
'String',sprintf('%4.3f',data.params.targetTheta),...
'Tag','params_targetTheta',...
'TooltipString',tstr,...
'FontSize',myui.fontsize,...
'Enable','off',...
'UserData',struct('Tooltipstr',tstr,'defaults',[data.params.targetOrient(1) -180 180]),...
'UserData',struct('Tooltipstr',tstr,'defaults',[data.params.targetTheta 0 180]),...
'Callback',@onEditValue);
tstr = 'Set azimuthal angle';
gui.edit_handles.targeta = uicontrol('Style','Edit',...
gui.edit_handles.targetPhi = uicontrol('Style','Edit',...
'Parent',edittarget2,...
'String',sprintf('%4.3f',data.params.targetOrient(2)),...
'Tag','params_targetOrienta',...
'String',sprintf('%4.3f',data.params.targetPhi),...
'Tag','params_targetPhi',...
'TooltipString',tstr,...
'FontSize',myui.fontsize,...
'Enable','off',...
'UserData',struct('Tooltipstr',tstr,'defaults',[data.params.targetOrient(2) -180 180]),...
'UserData',struct('Tooltipstr',tstr,'defaults',[data.params.targetPhi -180 180]),...
'Callback',@onEditValue);
set(edittarget2,'Widths',[-1 -1]);

Expand All @@ -158,7 +159,7 @@
% textSurface = uix.HBox('Parent',surfacevbox,'Spacing',3);
setSurface = uix.HBox('Parent',surfacevbox,'Spacing',3);

tstr = ['<HTML>If activated, the surface is closed an no grain smaller<br>',...
tstr = ['<HTML>If activated, the surface is closed and no grain smaller<br>',...
'than the threshold radius can stick out.'];
gui.radio_handles.closedSurface = uicontrol('Style','checkbox',...
'Parent',setSurface,...
Expand Down Expand Up @@ -253,7 +254,7 @@
% RNG
miscRNG = uix.HBox('Parent',miscvbox,'Spacing',3);

tstr = ['<HTML>If activated, one can enter an arbitrary RNG seed value so that always the same packing is created.'];
tstr = '<HTML>If activated, one can enter an arbitrary RNG seed value so that always the same packing is created.';
gui.radio_handles.customRNG = uicontrol('Style','checkbox',...
'Parent',miscRNG,...
'String','fix RNG seed',...
Expand All @@ -264,7 +265,7 @@
'UserData',struct('Tooltipstr',tstr),...
'Callback',@onRadioFixRNG);

tstr = ['<HTML>Enter a custom RNG seed value.'];
tstr = '<HTML>Enter a custom RNG seed value.';
gui.edit_handles.customRNG = uicontrol('Style','Edit',...
'Parent',miscRNG,...
'String',sprintf('%d',data.params.customRNGSEED),...
Expand All @@ -282,6 +283,100 @@

set(miscRNG,'Widths',[-1 -1 -1]);

%% Export
exportvbox = uix.VBox('Parent',exportpanel,'Spacing',3,'Padding',3);
setExport = uix.HBox('Parent',exportvbox,'Spacing',3);
textSetPML = uix.HBox('Parent',exportvbox,'Spacing',3);
editSetPML = uix.HBox('Parent',exportvbox,'Spacing',3);

tstr = 'If activated, PML boundaries are used for export within the HDF5 file.';
gui.radio_handles.ExportPML = uicontrol('Style','checkbox',...
'Parent',setExport,...
'String','use PML',...
'Tag','PML',...
'TooltipString',tstr,...
'FontSize',myui.fontsize,...
'Enable','on',...
'Value',1,...
'UserData',struct('Tooltipstr',tstr),...
'Callback',@onRadioExport);
tstr = 'If activated, a HDF5 file is used for export.';
gui.radio_handles.ExportHDF5 = uicontrol('Style','checkbox',...
'Parent',setExport,...
'String','HDF5',...
'Tag','HDF5',...
'TooltipString',tstr,...
'FontSize',myui.fontsize,...
'Enable','on',...
'Value',1,...
'UserData',struct('Tooltipstr',tstr),...
'Callback',@onRadioExport);
tstr = 'If activated, a mat-file is used for export.';
gui.radio_handles.ExportMAT = uicontrol('Style','checkbox',...
'Parent',setExport,...
'String','MAT',...
'Tag','MAT',...
'TooltipString',tstr,...
'FontSize',myui.fontsize,...
'Enable','on',...
'Value',1,...
'UserData',struct('Tooltipstr',tstr),...
'Callback',@onRadioExport);
tstr = 'If activated, a fig- and a png-file is exported.';
gui.radio_handles.ExportFIG = uicontrol('Style','checkbox',...
'Parent',setExport,...
'String','FIG/PNG',...
'Tag','FIG',...
'TooltipString',tstr,...
'FontSize',myui.fontsize,...
'Enable','on',...
'Value',1,...
'UserData',struct('Tooltipstr',tstr),...
'Callback',@onRadioExport);

gui.text_handles.PMLx = uicontrol('Style','Text',...
'Parent',textSetPML,...
'String','PML x [cells]',...
'FontSize',myui.fontsize);
gui.text_handles.PMLy = uicontrol('Style','Text',...
'Parent',textSetPML,...
'String','PML y [cells]',...
'FontSize',myui.fontsize);
gui.text_handles.PMLz = uicontrol('Style','Text',...
'Parent',textSetPML,...
'String','PML z [cells]',...
'FontSize',myui.fontsize);

tstr = 'PML width in x-direction';
gui.edit_handles.PMLx = uicontrol('Style','Edit',...
'Parent',editSetPML,...
'String',sprintf('%d',data.params.pml_w(1)),...
'Tag','params_PMLx',...
'TooltipString',tstr,...
'FontSize',myui.fontsize,...
'Enable','on',...
'UserData',struct('Tooltipstr',tstr,'defaults',[data.params.pml_w(1) 0 1000]),...
'Callback',@onEditValue);
tstr = 'PML width in y-direction';
gui.edit_handles.PMLy = uicontrol('Style','Edit',...
'Parent',editSetPML,...
'String',sprintf('%d',data.params.pml_w(2)),...
'Tag','params_PMLy',...
'TooltipString',tstr,...
'FontSize',myui.fontsize,...
'Enable','on',...
'UserData',struct('Tooltipstr',tstr,'defaults',[data.params.pml_w(2) 0 1000]),...
'Callback',@onEditValue);
tstr = 'PML width in z-direction';
gui.edit_handles.PMLz = uicontrol('Style','Edit',...
'Parent',editSetPML,...
'String',sprintf('%d',data.params.pml_w(3)),...
'Tag','params_PMLz',...
'TooltipString',tstr,...
'FontSize',myui.fontsize,...
'Enable','on',...
'UserData',struct('Tooltipstr',tstr,'defaults',[data.params.pml_w(3) 0 1000]),...
'Callback',@onEditValue);

%% Java Hack to adjust the text fields vertical alignment
jh = findjobj(gui.text_handles.usetarget);
Expand All @@ -304,6 +399,12 @@
jh.setVerticalAlignment(javax.swing.JLabel.CENTER)
jh = findjobj(gui.text_handles.customRNG);
jh.setVerticalAlignment(javax.swing.JLabel.CENTER)
jh = findjobj(gui.text_handles.PMLx);
jh.setVerticalAlignment(javax.swing.JLabel.CENTER)
jh = findjobj(gui.text_handles.PMLy);
jh.setVerticalAlignment(javax.swing.JLabel.CENTER)
jh = findjobj(gui.text_handles.PMLz);
jh.setVerticalAlignment(javax.swing.JLabel.CENTER)

return

Expand Down
7 changes: 5 additions & 2 deletions GPRGRAVEL/GPRGRAVEL_loadDefaults.m
View file
Original file line number Diff line number Diff line change
Expand Up @@ -106,8 +106,9 @@
init.params.useTarget = false;
% target center point
init.params.targetCenter = [init.domain.xm(1)/2 init.domain.ym(1)/2 init.domain.zm(1)/2];
% phi and theta angles to orient the target
init.params.targetOrient = [0 0];
% theta and phi angles to orient the target
init.params.targetTheta = 0;
init.params.targetPhi = 0;

% saturation profile (you can switch it on/off here)
init.params.useSatProfile = false;
Expand Down Expand Up @@ -156,8 +157,10 @@
init.params.exportMAT = true;
init.params.exportH5 = true;
init.params.exportPML = true;
init.params.exportFIG = true;
init.params.PMLduplicate = false;
init.params.PMLtruncate = false;
% thickness of PML layer (x,y,z)
init.params.pml_w = [10,10,50];

init.monitor = getMonitordata;
Expand Down
40 changes: 27 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@

<img src="logo.png" alt="GPRGRAVEL icon" width="96">

A simple **GPR** **GRAVEL** generator
A simple GPR gravel generator

[![release](https://img.shields.io/github/release/ThoHiller/gprgravel.svg)](https://github.com/ThoHiller/gprgravel/releases/latest)
[![DOI](https://zenodo.org/badge/666438181.svg)](https://zenodo.org/badge/latestdoi/666438181)

- - -

Expand All @@ -19,16 +22,24 @@ A simple **GPR** **GRAVEL** generator
<a name="about"></a>
### About

**GPRGRAVEL** is a set of MATLAB<sup>TM</sup> tools to generate grain (gravel) "packings" to be used with 3D FDTD GPR simulations. The "packings" are created based on user defined grain size distributions. Please note that **GPRGRAVEL** creates a "packing" by randomly placing grains at arbitrary positions inside a given container. No gravimetric settlement of the grains is applied.
**GPRGRAVEL** is a set of MATLAB<sup>TM</sup> tools to generate grain (gravel) "packings" to be used with 3D FDTD GPR simulation software [**gprMax**](https://www.gprmax.com/). The "packings" are created based on user defined grain size distributions. Please note that **GPRGRAVEL** creates a "packing" by randomly placing grains at arbitrary positions inside a given container. No gravimetric settlement of the grains is applied.

#### Basic features:
1. Choose between different grain shapes (*Sphere* or *Ellipsoid*)
2. Set a desired porosity and corresponding water and air fractions
3. Place an object (target) into the domain
4. Set a water saturation profile (*linear* or *exponential*)
5. etc.
3. Let the surface dip into x- or y-direction
4. Place an object (target) into the domain
5. Set a water saturation profile (*linear* or *exponential*)
6. etc.

<!---
<img src="gprgravel_gui.png" alt="GPRGRAVEL" width="400">
<img src="mortar_horz_volume_cut.png" alt="Mortar result" width="400">
-->

| <div style="width:400px">![GPRGRAVEL GUI](gprgravel_gui.png)</div> | <div style="width:400px">![Result example - mortar](mortar_horz_volume_cut.png)</div>
|:---:| :---: |
| GUI example with a mortar as target | Output volume with grains and target (for visibility reasons water is not shown and domain is cut at the center) |

- - -
<a name="requirements"></a>
Expand All @@ -39,11 +50,13 @@ In order to work properly you need to meet the following requirements:
1. The [Mathworks](https://www.mathworks.com) MATLAB<sup>TM</sup> software development environment (tested with R2019a and newer)
2. The GUI Layout Toolbox (get it from [FEX](https://de.mathworks.com/matlabcentral/fileexchange/47982-gui-layout-toolbox)) (<span style="color:red">required</span>)
3. `findjobj` (get it from [FEX](https://de.mathworks.com/matlabcentral/fileexchange/14317-findjobj-find-java-handles-of-matlab-graphic-objects)) (<span style="color:red">required</span>)
4. `VoxelSurf` (get it from [FEX](https://de.mathworks.com/matlabcentral/fileexchange/66204-voxelsurf)) (optional)
4. `inpolyhedron` (get it from [FEX](https://de.mathworks.com/matlabcentral/fileexchange/37856-inpolyhedron-are-points-inside-a-triangulated-volume)) (<span style="color:red">required</span>)
5. `VoxelSurf` (get it from [FEX](https://de.mathworks.com/matlabcentral/fileexchange/66204-voxelsurf)) (optional)


#### Operating System

I tested it successfully under Windows 7 (64bit) and 10 (64bit) with Matlab R2019a and newer. Always with the latest version of the GUI Layout Toolbox (current version is afaik v2.3.5)
I tested it successfully with Windows 10 (64bit) and Matlab R2019a and newer. Always with the latest version of the GUI Layout Toolbox (current version is afaik v2.3.6)

**NOTE:** So far I did not test anything on Linux or a Mac. If you get it to work on either of the two systems (which it basically should I guess) please let me know.

Expand All @@ -60,28 +73,29 @@ I tested it successfully under Windows 7 (64bit) and 10 (64bit) with Matlab R201

1. By executing the start script (see above)
2. Simply type `GPRGRAVEL` on the MATLAB<sup>TM</sup> prompt (make sure the `GPRGRAVEL` folder is on the MATLAB<sup>TM</sup> path)

3. Check the example scripts for the usage of the core functions without the GUI (inside the `scripts` folder)


- - -
<a name="todo"></a>
### ToDo

In no particular order and without guarantee that it will ever happen :-) :

1. Add some more auxiliary options to the *Parameter* panel
2. Give the different export options via the GUI itself
3. Finalize the menu import/export routines
4. ...
1. Clean-up (refactoring) of the code base
2. A manual
3. ...


- - -
<a name="references"></a>
### Cite as
If you use GPRGRAVEL for your research, please cite it as:

Thomas Hiller. (2023, July 14). ThoHiller/gprgravel: v0.1.0 (Version v0.1.0). GitHub. [https://github.com/ThoHiller/gprgravel]
Thomas Hiller. (2023, September 05). ThoHiller/gprgravel: v0.1.1 (Version v0.1.1). Zenodo. [https://doi.org/10.5281/zenodo.8148692]

Note: This repository will be made available via Zenodo and will have a citable DOI. Even though the version number might change due to updates, this DOI is permanent (represents all versions) and always links to the latest version.
Note: Even though the version number might change due to updates, this DOI is permanent (represents all versions) and always links to the latest version.


### References
Expand Down
Loading

0 comments on commit fc54792

Please sign in to comment.