Merge pull request #1 from cserteGT3/initial-design

Transition initial design from closed source code

.gitignore

@@ -1,3 +1,4 @@
 /Manifest.toml
 /docs/Manifest.toml
 /docs/build/
+*.bat

Project.toml

@@ -3,7 +3,21 @@ uuid = "dc39d501-6ffa-4c27-9708-7dc7e3b1a5c3"
 authors = ["Tamás Cserteg <[email protected]>", "András Kovács <[email protected]> and contributors"]
 version = "1.0.0-DEV"
 
+[deps]
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+Meshes = "eacbb407-ea5a-433e-ab97-5258b1ca43fa"
+PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+Rotations = "6038ab10-8711-5258-84ad-4b1120ba62dc"
+
 [compat]
+DataFrames = "1"
+JuMP = "1.4"
+Meshes = "0.32"
+PrettyTables = "2"
 julia = "1.6"
 
 [extras]

README.md

@@ -3,3 +3,51 @@
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://cserteGT3.github.io/BlankLocalizationCore.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://cserteGT3.github.io/BlankLocalizationCore.jl/dev/)
 [![Build Status](https://github.com/cserteGT3/BlankLocalizationCore.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/cserteGT3/BlankLocalizationCore.jl/actions/workflows/CI.yml?query=branch%3Amain)
+
+This repository contains the reference implentation for the multi operation blank localization technique described in our paper _Multi-operation optimal blank localization for near net shape machining_.
+The paper is available is here: <https://www.sciencedirect.com/science/article/pii/S0007850623000884>.
+
+The goal of multi operation blank localization is to align the CNC machining code for the rough (e.g. cast, 3D printed, etc.) parts.
+When doing so, one must consider two important factors:
+
+- leaving enough material to be removed by the tool (machining allowance)
+- respecting the dimensional tolerances between features (defined on the part drawing)
+
+Our paper proposes a method, that ensures a proper machining allowance (minimum requirement), while trying to optimize to the center of the tolerance fields between features.
+
+The documentation goes through a detailed example of the process while showing how to use the package.
+
+The package is not yet registered, so it needs to be installed by its URL:
+
+```julia
+using Pkg
+Pkg.add(url="https://github.com/cserteGT3/BlankLocalizationCore.jl")
+```
+
+## Design goals
+
+This is a one on one implementation of the optimization model described in the above mentioned paper.
+As processing different types of measurement data (such as coordinate measurement machine, or a 3D scanner) requires different methods and techniqes, a well designed interface is available.
+The aim is to make it easy to adapt our methodology to any measurement types available.
+
+If you use find this work useful, please cite our paper:
+
+```txt
+@article{cserteg:2023_MultioperationOptimalBlank,
+  title = {Multi-Operation Optimal Blank Localization for near Net Shape Machining},
+  author = {Cserteg, Tamás and Kovács, András and Váncza, József},
+  year = {2023},
+  month = jun,
+  journal = {CIRP Annals},
+  issn = {0007-8506},
+  doi = {10.1016/j.cirp.2023.04.049},
+}
+```
+
+## Acknowledgements
+
+This package couldn't have been created without the great people behind the following projects (as well as the whole Julia ecosystem):
+
+* [Meshes.jl](https://github.com/JuliaGeometry/Meshes.jl), [MeshViz.jl](https://github.com/JuliaGeometry/MeshViz.jl) and the [Makie.jl](https://github.com/MakieOrg/Makie.jl) ecosystem
+* [JuMP.jl](https://jump.dev/)
+* [DataFrames.jl](https://github.com/JuliaData/DataFrames.jl) and [PrettyTables.jl](https://github.com/ronisbr/PrettyTables.jl)

docs/make.jl

@@ -16,6 +16,9 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
+        "Example" => "example.md",
+        "API extension" => "api.md",
+        "Reference" => "reference.md"
     ],
 )
 

docs/src/api.md

@@ -0,0 +1,56 @@
+# Using the API to extend the geometry types
+
+The solver handles hole and face (plane) features that are either [`IsPrimitive`](@ref) or [`IsFreeForm`](@ref).
+A few basic types are defined like [`SimpleHole`](@ref) and [`MeshHole`](@ref), but new ones can be also defined.
+For example for point clouds, that don't have faces, like a mesh, only points.
+
+This capability is properly documented, as a major API rewrite is going on in [#3](https://github.com/cserteGT3/BlankLocalizationCore.jl/pull/3).
+
+## Defining a new geometry
+
+Defining a new geometry is pretty easy:
+
+* It has to be the subtype of either [`AbstractHoleGeometry`](@ref) or [`AbstractPlaneGeometry`](@ref).
+* The [`GeometryStyle`](@ref) trait is need to be defined: it is either a [`IsPrimitive`](@ref) or [`IsFreeForm`](@ref) geometry.
+* `IsFreeForm` geometries need to define the [`surfacepoints`](@ref) and [`filteredsurfacepoints`](@ref) functions.
+* `IsPrimitive` geometries need to define the [`featurepoint`](@ref) functions
+* Those `IsPrimitive` geometries that are subtype of `AbstractHoleGeometry` also need to define the [`featureradius`](@ref) function
+* Finally, for visualization purposes the [`visualizationgeometry`](@ref) function should be defined, that returns an object, that can be used with the `Meshviz.viz()` function.
+
+## An example
+
+Let's assume that we want to define a new holelike type: `MyDisk`, which has a featurepoint, a normal, and a radius.
+
+```julia
+using BlankLocalizationCore
+
+struct MyDisk <: AbstractHoleGeometry
+    point::Vector{Float64}
+    normal::Vector{Float64}
+    diameter::Float64
+end
+
+GeometryStyle(::Type{MyDisk}) = IsPrimitive()
+```
+
+It is an `IsPrimitive` and holelike feature, therefore we need to define the:
+
+* `featurepoint`
+* `featureradius`
+* `visualizationgeometry`
+
+functions.
+These look like as follows:
+
+```julia
+featurepoint(::IsPrimitive, x::MyDisk) = x.point
+featureradius(::IsPrimitive, x::MyDisk) = x.diameter/2
+
+using Meshes
+
+function visualizationgeometry(geom::MyDisk)
+    plane = Plane(Point3(geom.point), Vec3(geom.normal))
+    return Disk(plane, geom.diameter/2)
+end
+
+```