-
Notifications
You must be signed in to change notification settings - Fork 15
/
zipfile-readme.txt
75 lines (49 loc) · 15.6 KB
/
zipfile-readme.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
This README file provides supplementary information about the data files and programs. A full version of the programs is provided in three languages: Java, Python 3, and Visual Basic. The programs and data files can be copied to your machine wherever is convenient, although the name of the directory "Ast Progs and Data" cannot be changed and the directory structure underneath it must be preserved. None of the programs make any changes to the Windows registry (for Windows-based platforms) and they require no special steps to install them. Simply copy the directory "Ast Progs and Data" to your local disk wherever you like (but do NOT change its name or change the directory structure underneath it), and copy the source code directories (e.g., Java, Python) to your system so that they are at the same level in the directory tree as "Ast Progs and Data". The programs and data can be removed from your system by merely deleting the "Ast Progs and Data" directory and the source code directories from wherever you installed them.
Unless you wish to modify the source code, you do not have to copy any source code directories to your system. The downloaded zip files contain all three versions (Java, Python 3, Visual Basic) of the software, with the executables and data being in the zip file with "data" in the name and source code being in the zip file with "src" in the name. You may leave all three versions installed on your machine, or delete the ones that you do not want from underneath both "Ast Progs and Data" (for the executables) and the relevant source code directory. For example, if you do not want the Visual Basic version of the software, delete the subdirectory "Ast Progs and Data\bin-VBasic" and the source code directory "Visual Basic".
***********************Special Note**************************
Some versions of the Norton anti-virus products have a feature that flags infrequently used programs with a “WS.reputation.1” warning, particularly if the program was downloaded from the Internet. This warning is often erroneous and typically means that it is a program that Norton has not previously analyzed to determine if it is safe. Norton anti-virus may flag the Visual Basic executables provided with this book (but not the Java jar files or the Python scripts) with this error, even if they are recompiled and rebuilt on your own computer. If you get this error, the best way to deal with it is to configure the Norton anti-virus program to ignore the directory(ies) (i.e., Ast Progs and Data\bin-VBasic for the executables and Ast Progs and Data\Visual Basic for the source code) in which you have installed the BASIC programs and/or BASIC source code. Refer to Norton documentation for how to exclude directories from a virus scan.
***********************Special Note**************************
The following sections provide additional details about the major directories.
1. "Ast Progs and Data" directory
This directory contains the following subdirectories:
(a) "Ast Data Files" contains various data files that the programs need. See the next section below for more information about the data files.
(b) "bin-Java" contains the executable Java jar files. The Java programs will run on any platform (Windows, Linux, iOS, etc.) that supports Java.
(c) "bin-Python" contains the Python 3 scripts. They will run on any platform that supports Python 3.
(d) "bin-VBasic" contains the executable programs for Visual Basic (See the Special Note above if you use Norton anti-virus products). The Visual Basic programs are pre-compiled as executables for Microsoft Windows. If you are using an Apple computer, you will need to download a free copy of Visual Studio from Microsoft and compile the programs for your platform. After doing so, copy the executables to the "bin-VBasic" subdirectory.
2. Additional information about the data files under "Ast Progs and Data"
2a. Subdirectory "Ast Data Files"
This subdirectory contains data files that are used by the book's programs. The data files are 'XML-Like' in that they use tags to identify data fields as values just as XML does. However, they are not true XML files and there is no guarantee that an XML parser can parse them. These data files can be modified, but be sure to make a backup of the file you wish to modify before you change it. The data tags in the field are generally always required, so follow the format of these files very carefully. Also, avoid using blank lines in the files. Files with blank lines should work, but extensive testing has not been done to ensure that blank lines are acceptable in every case.
2b. Data file "ConstellationData.dat" ***DO NOT MODIFY THIS FILE!***
This is a text file containing a list of each of the 88 modern constellations, the coordinates for the center of the constellation for the standard epoch J2000, the name of the brightest star in the constellation and that star's coordinates, and what the constellation's name means. The format of the data file is 'pseudo-XML' and should be easily readable. Following the BasicData section of the file is a list of constellation boundaries, referenced to epoch 1875.0. These boundaries are used in an algorithm developed by Rapport and Roman that will take an equatorial coordinate as input and return what constellation the coordinate falls within. For more details, see the code in ASTUtils (source code file ASTConstellations) for the function findConstellationFromCoord.
Note that the programs that reference constellations data should read this data file automatically. If for some reason they do not, this file is provided in the "Ast Progs and Data" subdirectory so that you can manually load the constellations data for any programs that need it.
2c. Data file "DefaultObsLoc.dat"
This text file contains the default observer location (latitude, longitude) and default time zone. This file is optional and if not provided, the default observer location will be lat=0, lon=0, and time zone based on longitude.
2d. Data file "J2000.dat"
This file contains the orbital elements for the Sun, Moon, and planets referenced to the standard epoch 2000.0. You may create your own orbital elements data files referenced to other epochs (e.g., 1980.0, 2015.0) and may add your own objects (e.g., Ceres). By default, the programs for the Sun, Moon, and Planets chapters load the J2000.dat file when the programs initialize. Once these programs are running, they provide a menu entry to allow you to load a different orbital elements data file.
2e. Data files "TLE-TABLE9.dat" and "TLEs.dat"
These files contain sample TLEs for experimenting with satellite orbits.
2f. Data file "Launch-Sites.dat"
This data file contains the name and latitude for several satellite launch sites.
2g. Subdirectory "Star Catalogs"
This subdirectory contains star data obtained from various public domain data sources. The star catalog data files are 'XML-like' text files whose contents should be self-explanatory. You may create your own star data files, but be sure to follow the format exactly as in the sample data files and with the file sections organized in exactly the same order as the sample data files. If these files are large (50,000 or more entries), they may take a few seconds to load or display. Also note that the objects in the disk file for a catalog must be sorted in ascending order by constellation and then in ascending order by object name within a constellation. The data files "Stars.dat" and "MoreStars.dat" are small files containing only a few stars and can be used for testing purposes.
3. Sample Programs
The sample programs have been optimized for 1920x1200 resolution. However, they have been tested for resolutions as low as 1280x800 and should work at lower resolutions.
4. "Java" directory
This directory contains the source code for each of the book's programs, organized in subdirectories by chapter. The jars subdirectory contains each of the compiled programs with the name "RunChapX.jar" where 'X' is the chapter to which the program pertains. For example, RunChap3.jar is the sample program from Chapter 3. The "jar" subdirectory also has a shared library, ASTUtils.jar, that contains the various routines that are used in the programs. The source code for the shared library is under "Java\ASTUtils."
These programs were developed in the Eclipse Oxygen development environment and compiled with a Java 1.8 compiler. Refer to the Eclipse user documentation for information about importing the source code into your environment. Note that you will most likely have to set the Java Build Path properties after you import the programs into your Eclipse environment to find the ASTUtils.jar library. All user interface components were developed with Swing widgets and were created with Eclipse's WindowBuilder tool. The main GUI for each chapter is in the ChapGUI.java source code file. The code for each chapter is placed in the package jll.celcalc.chapX where the 'X' is the chapter to which the code applies. The ASTUtils components are in the package jll.celcalc.ASTUtils.
The Java software can be compiled and exported as jar files through native Eclipse capabilities. Alternatively, you can use ant instead. The subdirectory "AntBuild" has the file "ant-build-master.xml" that recursively invokes an "ant-build.xml" file for the ASTUtils library and each chapter's program. The subdirectory "AntBuild" does not have any source code; its only purpose is to have a place to put the master ant build file. Besides compiling the code and packaging the results as a jar file, the ant build process also automatically creates Javadoc documentation. The documentation is located in a "doc" subdirectory underneath each chapter and the ASTUtils directory.
The batch file CleanupJava.BAT deletes all of the build artifacts (but not the resulting executables or Javadoc documentation) and must be executed from the Java directory. In addition to deleting the build artifacts, it copies all executables (and the shared ASTUtils file) to "Ast Progs and Data/bin-Java". You may need to edit this .BAT file, depending upon how you set up your development environment for modifying the source code files.
5. "Python" directory
This directory contains the source code for each of the book's programs, organized in subdirectories by chapter. Underneath each chapter subdirectory is a script named "RunChapX.py" where 'X' is the chapter to which the program pertains. For example, RunChap3.py is the sample program from Chapter 3. The ASTUtils subdirectory is a shared library package that contains the various routines that are used in the programs. The source code for the shared library is under "Python\ASTUtils."
These programs were developed in the Eclipse Oxygen development environment with the PyDev plugin and Python 3.6.3. The programs require that tkinter (the Python 3 version) already be installed. You may use whatever Python development environment you wish if you want to modify the programs. You may execute the Python scripts by double clicking on RunChapX.py, by executing the command 'python RunChapX.py' from a command line window, or by starting a Python environment from the desired "chapter" subdirectory, then executing
import RunChapX as rc
rc.runChap()
where X is the chapter of interest. If you do not want an empty command window to be displayed while the programs are running, rename the RunChapX.py scripts to be RunChapX.pyw or ensure that files with the extension .py are associated with pythonw instead of python. These programs will **NOT** run under Python 2 and will **NOT** work with Tkinter (the Python 2 version of tkinter).
The design philosophy for the Python programs was to use only the native capabilities found in a base Python 3 installation consisting of the base Python language plus tkinter. This decision was made so that no additional Python libraries or packages must be located, downloaded from the Internet, and installed. A consequence of this decision is that advanced math capabilities (such as provided by the numpy package) and graphics (such as provided by mathplotlib or PyQtGraph) are not available unless implemented in the book's utilities in modules such as ASTMath and ASTCharts. Of most importance, native tkinter does not support clipping, which impacts the quality of the star charts produced in the programs for Chapters 5 and 8. See the comments at the top of ASTUtils.ASTCharts for more details. Such limitations are not present in the Java and Visual Basic version of the programs.
When installing the Python programs, you do not have to set the PYTHONPATH environment variable to include the ASTUtils library in the search path, nor do you have to install any of the scripts (including ASTUtils) in your Python's site-packages directory. Each RunChapX.py script dynamically determines where the ASTUtils are located. For that to work, the ASTUtils directory must be at the same level in the directory path as the "chapter" directories. All user interface components were developed as native tkinter widgets. The main GUI for each chapter is in the ChapGUI.py source code file.
The batch file CleanupPython.BAT deletes all of the build artifacts (but not the python scripts) and must be executed from the Python directory. In addition to deleting the build artifacts, it copies all executables (and the shared ASTUtils lilbrary) to "Ast Progs and Data/bin-Python". You may need to edit this .BAT file, depending upon how you set up your development environment for modifying the source code files.
6. "Visual Basic" directory
This directory contains the source code for each of the book's programs, organized in subdirectories by chapter. The bin subdirectory contains each of the compiled programs with the name "RunChapX.exe" where 'X' is the chapter to which the program pertains. For example, RunChap3.exe is the sample program for chapter 3. The "bin" subdirectory also has a shared library, ASTUtils.dll, that contains various routines that are used in several of the programs. The source code for the shared library is under "Visual Basic\ASTUtils." The programs created by compiling the Visual Basic source code will only run on Microsoft Windows platforms. You may, however, use Visual Studio for Macs to recompile the source code for MAC platforms.
The programs were compiled with Microsoft Visual Studio 2017 Community (a free product from Microsoft), but they should be compilable under earlier versions of Microsoft's Visual Studio development environment (at least as old as version 2010). You should be able to copy the entire subdirectory "Visual Basic" to wherever is convenient and recompile the sample programs. Relative pathnames are used so that as long as the subdirectory structure underneath "Visual Basic" is preserved, where the root "Visual Basic" subdirectory is located is irrelevant for compilation purposes. See the Special Note above if you use Norton anti-virus products.
The Visual Basic project files can be found directly under the source code directory for a particular chapter (e.g., Chap1) and are named "ChapX.vbproj" where 'X' is the chapter the file pertains to. Following Microsoft's convention, source code files have a .VB extension. The subdirectory "ASTBookVBSolution" contains a solution file (with extension .sln) that allows all of the programs and ASTUtils.dll to be built from scratch. It also contains the icon used for each of the programs and the picture for the 'About' box.
The batch file CleanupVB.BAT deletes all of the build artifacts (but not the resulting executables) and must be executed from the Visual Basic directory. In addition to deleting the build artifacts, it copies all executables (and the shared dll file) to "Ast Progs and Data/bin-VBasic". You may need to edit this .BAT file, depending upon how you set up your development environment for modifying the source code files.