README.md in aixm-0.2.3 vs README.md in aixm-0.3.0

- old
+ new

@@ -4,13 +4,13 @@ [![Gitter](https://img.shields.io/gitter/room/svoop/aixm.svg?style=flat)](https://gitter.im/svoop/aixm) [![Donorbox](https://img.shields.io/badge/donate-on_donorbox-yellow.svg)](https://donorbox.org/bitcetera) # AIXM -Partial implementation of the [Aeronautical Information Exchange Model (AIXM 4.5)](http://aixm.aero) for Ruby. +Partial implementation of the [Aeronautical Information Exchange Model (AIXM 4.5)](http://aixm.aero) and it's dialect [Open FlightMaps eXchange format (OFMX 0)](https://github.com/openflightmaps/ofmx) for Ruby. -For now, only the parts needed to automize the AIP import of [Open Flightmaps](https://openflightmaps.org) are part of this gem. Most notably, the gem is only a builder of AIXM 4.5 snapshot files and does not parse them. +For now, only the parts needed to automize the AIP import of [Open Flightmaps](https://openflightmaps.org) are part of this gem. Most notably, the gem is only a builder for snapshot files and does not parse them. * [Homepage](https://github.com/svoop/aixm) * [API](http://www.rubydoc.info/gems/aixm) * Author: [Sven Schwyn - Bitcetera](http://www.bitcetera.com) @@ -22,296 +22,103 @@ gem aixm ``` ## Usage -You can initialize all elements either traditionally or by use of shorter AIXM class methods: +Here's how to build a document object, populate it with a simple feature and then render it as AIXM: ```ruby -AIXM.airspace(...) -AIXM.airspace(...) -``` - -### Fundamentals - -All fundamentals are subclasses of `AIXM::Base`. - -### Document - -The document is the root container of the AIXM snapshot file to be generated. It's essentially a collection of features: - -```ruby -document = AIXM.document(created_at: Time.now, effective_at: Time.now) -document.features << AIXM.airspace(...) -``` - -To give you an overview of the AIXM building blocks, the remainder of this guide will use pseudo code to describe the initializer arguments, writer methods etc: - -```ruby -document = AIXM.document( - created_at: Time or Date or String - effective_at: Time or Date or String +document = AIXM.document +document.features << AIXM.designated_point( + id: "ABIXI", + xy: AIXM.xy(lat: %q(46°31'54.3"N), long: %q(002°19'55.2"W)), + type: :icao ) -document.features << AIXM::Feature +document.aixm! # not really necessary since AIXM is the default schema +document.to_xml ``` -See [the API documentation](http://www.rubydoc.info/gems/aixm) for details and [spec/factory.rb](https://github.com/svoop/aixm/blob/master/spec/factory.rb) for examples. +You can initialize all elements either traditionally or by use of shorter AIXM class methods. The following two statements are identical: -#### Coordinate - -All of the below are equivalent: - ```ruby -AIXM.xy(lat: %q(11°22'33.44"), long: %q(-111°22'33.44")) -AIXM.xy(lat: '112233.44N', long: '1112233.44W') -AIXM.xy(lat: 11.375955555555556, long: -111.37595555555555) +AIXM::Feature::NavigationalAid::DesignatedPoint.new(...) +AIXM.designated_point(...) ``` -#### Altitude and Heights +## Configuration -Altitudes and heights exist in three different forms: +The following configuration options are available for setting and getting: ```ruby -AIXM.z(1000, :qfe) # height: 1000ft above ground -AIXM.z(2000, :qnh) # altitude: of 2000ft above mean sea level -AIXM.z(45, :qne) # altitude: flight level 45 +AIXM.config.schema # either :aixm (default) or :ofmx +AIXM.config.region # fallback region +AIXM.config.ignored_errors # ignore XML schema errors which match this regex ``` -#### Frequency +There are shortcuts to set and get the schema: ```ruby -AIXM.f(123.35, :mhz) +AIXM.schema # => :aixm +AIXM.aixm? # => true +AIXM.ofmx! # => :ofmx +AIXM.ofmx? # => true +AIXM.schema # => :ofmx +AIXM.schema(:version) # => 0 ``` -### Features +## Validation -All features are subclasses of `AIXM::Feature::Base`. +`AIXM::Document#valid?` validates the resulting AIXM or OFMX against its XML schema. If any, you find the errors in `AIXM::Document#errors`. -#### Airspace +## Model -```ruby -airspace = AIXM.airspace( - name: String - short_name: String or nil - type: String or Symbol -) -airspace.schedule = AIXM.schedule -airspace.geometry << AIXM.point or AIXM.arc or AIXM.border or AIXM.circle -airspace.class_layers << AIXM.class_layer -airspace.remarks = String -``` +### Fundamentals +* [Document](http://www.rubydoc.info/gems/aixm/AIXM/Document.html) +* [XY (longitude and latitude)](http://www.rubydoc.info/gems/aixm/AIXM/XY.html) +* [Z (height, elevation or altitude)](http://www.rubydoc.info/gems/aixm/AIXM/Z.html) +* [F (frequency)](http://www.rubydoc.info/gems/aixm/AIXM/F.html) -#### Navigational Aids +### Features +* [Organisation](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Organisation.html) +* [Unit](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Unit.html) +* [Airport](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Airport.html) +* [Airspace](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Airspace.html) +* [Navigational aid](http://www.rubydoc.info/gems/aixm/AIXM/NavigationalAid.html) + * [Designated point](http://www.rubydoc.info/gems/aixm/AIXM/Feature/DesignatedPoint.html) + * [DME](http://www.rubydoc.info/gems/aixm/AIXM/Feature/DME.html) + * [Marker](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Marker.html) + * [NDB](http://www.rubydoc.info/gems/aixm/AIXM/Feature/NDB.html) + * [TACAN](http://www.rubydoc.info/gems/aixm/AIXM/Feature/TACAN.html) + * [VOR](http://www.rubydoc.info/gems/aixm/AIXM/Feature/VOR.html) -##### Designated Point - -```ruby -designated_point = AIXM.designated_point( - id: String - name: String or nil - xy: AIXM.xy - z: AIXM.z or nil - type: :icao or :adhp, or :coordinates -) -designated_point.schedule = AIXM.schedule -designated_point.remarks = String -``` - -##### DME - -```ruby -dme = AIXM.dme( - id: String - name: String - xy: AIXM.xy - z: AIXM.z or nil - channel: String -) -dme.schedule = AIXM.schedule -dme.remarks = String -``` - -##### NDB - -```ruby -ndb = AIXM.ndb( - id: String - name: String - xy: AIXM.xy - z: AIXM.z or nil - type: :en_route, :locator or :marine - f: AIXM.f -) -ndb.schedule = AIXM.schedule -ndb.remarks = String -``` - -##### Marker - -WARNING: Marker are not fully implemented because they usually have to be -associated with ILS which are not yet implemented. - -```ruby -marker = AIXM.marker( - id: String - name: String - xy: AIXM.xy - z: AIXM.z or nil - type: :outer, :middle, :inner or :backcourse -) -marker.schedule = AIXM.schedule -marker.remarks = String -``` - -##### TACAN - -```ruby -tacan = AIXM.tacan( - id: String - name: String - xy: AIXM.xy - z: AIXM.z or nil - channel: String -) -tacan.schedule = AIXM.schedule -tacan.remarks = String -``` - -##### VOR - -```ruby -vor = AIXM.vor( - id: String - name: String - xy: AIXM.xy - z: AIXM.z or nil - type: :conventional or :doppler - f: AIXM.f - north: :geographic or :grid or :magnetic -) -vor.schedule = AIXM.schedule -vor.remarks = String -vor.associate_dme(channel: String) # turns the VOR into a VOR/DME -vor.associate_tacan(channel: String) # turns the VOR into a VORTAC -``` - ### Components +* [Service](http://www.rubydoc.info/gems/aixm/AIXM/Component/Service.html) +* [Frequency](http://www.rubydoc.info/gems/aixm/AIXM/Component/Frequency.html) +* [Geometry](http://www.rubydoc.info/gems/aixm/AIXM/Component/Geometry.html) + * [Point](http://www.rubydoc.info/gems/aixm/AIXM/Component/Point.html) + * [Arc](http://www.rubydoc.info/gems/aixm/AIXM/Component/Arc.html) + * [Border](http://www.rubydoc.info/gems/aixm/AIXM/Component/Border.html) + * [Circle](http://www.rubydoc.info/gems/aixm/AIXM/Component/Circle.html) +* [Runway](http://www.rubydoc.info/gems/aixm/AIXM/Component/Runway.html) +* [Helipad](http://www.rubydoc.info/gems/aixm/AIXM/Component/Helipad.html) +* [Layer](http://www.rubydoc.info/gems/aixm/AIXM/Component/Layer.html) +* [Vertical limits](http://www.rubydoc.info/gems/aixm/AIXM/Component/VerticalLimits.html) +* [Timetable](http://www.rubydoc.info/gems/aixm/AIXM/Component/Timetable.html) -All components are subclasses of `AIXM::Component::Base`. - -#### Schedule - -```ruby -schedule = AIXM.schedule( - code: String or Symbol -) -``` - -#### Class Layer - -```ruby -class_layer = AIXM.class_layer( - class: String or nil - vertical_limits: AIXM.vertical_limits -) -``` - -#### Vertical Limits - -```ruby -vertical_limits = AIXM.vertical_limits( - max_z: AIXM.z or nil - upper_z: AIXM.z - lower_z: AIXM.z - min_z: AIXM.z or nil -) -``` - -#### Point, Arc, Border and Circle - -```ruby -point = AIXM.point( - xy: AIXM.xy -) -arc = AIXM.arc( - xy: AIXM.xy - center_xy: AIXM.xy - cloclwise: true or false -) -border = AIXM.border( - xy: AIXM.xy - name: String -) -circle = AIXM.circle( - center_xy: AIXM.xy - radius: Numeric -) -``` - -#### Geometry - -```ruby -geometry = AIXM.geometry -geometry << AIXM.point or AIXM.arc or AIXM.border or AIXM.circle -``` - -For a geometry to be complete, it must be comprised of either: - -* exactly one circle -* at least three points, arcs or borders (the last of which a point with identical coordinates as the first) - -## Validation - -Use `AIXM::Document#complete?` to check whether all mandatory information is present. Airspaces, geometries etc have `complete?` methods as well. - -Use `AIXM::Document#valid?` to validate the resulting AIXM against the XSD schema. If any, you find the errors in `AIXM::Document#errors`. Since the data model is not fully implemented, some associations cannot be assigned and have to be left empty. The resulting validation errors are silently ignored: - -* OrgUid - organizations may be empty tags - -## Rendering - -```ruby -document.to_aixm # render AIXM 4.5 compliant XML -document.to_aixm(:ofm) # render AIXM 4.5 + OFM extensions XML -``` - -## Constants - -* `AIXM::GROUND` - height: 0ft above ground -* `AIXM::UNLIMITED` - altitude: FL 999 -* `AIXM::H24` - continuous schedule - ## Refinements -By `using AIXM::Refinements` you get the following general purpose methods: +By `using AIXM::Refinements` you get a few handy [extensions to Ruby core classes](http://www.rubydoc.info/gems/aixm/AIXM/Refinements.html). -* `Hash#lookup(key, default)`<br>Similar to `fetch` but falls back to values -* `String#indent(number)`<br>Indent every line of a string with *number* spaces -* `String#uptrans`<br>upcase and transliterate to match the reduced character set for names -* `String#to_dd`<br>Convert DMS angle to DD or `nil` if the format is not recognized -* `Float#to_dms(padding)`<br>Convert DD angle to DMS with the degrees zero padded to *padding* length -* `Float#trim`<br>Convert whole numbers to Integer and leave all other untouched -* `Float#to_km(from: unit)`<br>Convert a distance from *unit* (:km, :m, :nm or :ft) to km - -See the [source code](https://github.com/svoop/aixm/blob/master/lib/aixm/refinements.rb) for more explicit descriptions and examples. - -## Extensions - -### OFM - -This extension adds proprietary tags and attributes (most of which are prefixed with `xt_`) aiming to improve importing the resulting AIXM into the OFM originative suite: - -* `<AIXM-Snapshot version="4.5 + OFM extensions of version 0.1" (...) />`<br>root node with extended version string -* `<Ase xt_classLayersAvail="(true|false)">`<br>true when multiple class layers and therefore an Adg-node is present -* `<xt_selAvail>(true|false)</xt_selAvail>`<br>enables conditional airspaces feature -* `<AseUid newEntity="(true|false)">`<br>tell the importer whether adding a new or updating an existing entity - ## References +### AIXM * [AIXM](http://aixm.aero) -* [AIXM on Wikipedia](https://en.wikipedia.org/wiki/AIXM) +* [AICM 4.5 Documentation](https://openflightmaps.github.io/ofmx/aixm/4.5/manual/aicm/) * [AIXM 4.5 Specification](http://aixm.aero/document/aixm-45-specification) -* [AICM 4.5 Entity-Relationship](https://www.ead.eurocontrol.int/SystemHelp/mergedProjects/SDO/aixm/) + +### OFMX +* [OFMX](https://github.com/openflightmaps/ofmx) +* [OFMX Documentation](https://github.com/openflightmaps/ofmx/wiki) * [Open Flightmaps](https://openflightmaps.org) ## Tests Some tests are very time consuming and therefore skipped by default. To run the full test suite, set the environment variable: