[9fans] marsv man page

[9fans] marsv man page

[okamoto]

[-- Attachment #1: Type: text/plain, Size: 156 bytes --]

I included the man page of marsv(1pub).
If you have any suggestions to make it more readable English,
please let me know PERSONALLY.

Thanks,

Kenji

[-- Attachment #2: Type: text/plain, Size: 3931 bytes --]

.TH MARSV 1
.SH NAME
marsv \- viewes PDS images and measures altitude of Mars surface using
MOLA grid data, and outputts its result to postscript formatted file
.SH SYNOPSIS
.B marsv
.SH DESCRIPTION
.I Marsv
is a GUI program to measure Mars altitude, latitude and longitude at the place
pointed by mouse on a Qube image or MOLA grid data, and to draw its contour
map laying over the image using MOLA grid data, and to output postscript file
for printing.
.PP
Marsv is aimed to make acme like user interface for Mars image
manipulation additionally with 3 button menu bar, where button 1 (left button)
shows the category name of the item, button 2 (middle button) does the indicated
job by the menu name, and button 3 (right button) lists the items of that category
and let choose one.
.PP
In Altitude menu of ISISmenu category of QUBELoad menu or MOLALoad menu,
button 1 shows the values of altitude, longitude and latitude pointed by the mouse.
When the mouse in this mode is dragged, those values will be shown continuously,
which makes you to understand the real shape of the object you are now watching.
In Contour menu of ISISmenu category of QUBELoad menu, dragging button 3 can
make correction of the minor discrepancy between that indicated by MOLA grid data
and by Qube image data.  After this recalibration, remapping of the countour will
be necessary to get a correct one.   The values of longitude and latitude
showed in Altitude menu of ISISmenu category are also recalculated by the above
procedure.  In short, you have to confirm the accuracy of those data shown by mouse
by showing contour maps, and if necessary, that recalibration should be done.
Those two values will not usually match each other from our experiences.
.PP
Mrasv designed as an single threaded concurrent program using thread(2) and
control(2) libraries of Plan 9.   Marsv assumes there is a MOLA grid data (such as
ieg0031t.img for 0.031 degree grid) under $home/data/mars/mola/ directory.
Additionally, marsv can read many other PDS formatted images of other planet,
and make a bit of annotations using Pen menu by changing colors from Palette
menu.
.SH EXTENSION
Four general purpose user interfaces with its own window are implemented as shown
in struct Form, struct Filebrowse, struct Select and struct Viewer.   Those structures are
constructed using two new basic structures, controlling those shape, position or
behaviours called struct Win and struct WinComm.
.PP
Struct Canvas is prepared to provide layer structures to marsv image by using memdraw
and layer functions in draw(2) libraries of Plan 9, which is a mechanism to use multiple
memory layers to draw for altitude, latitude and longitude data at the moving mouse
point.   Struct Layer and CanvasBase are used as their base structures.   The other
many structures from control(2) library are also used through newly defined structure
of Wincontrol.
.PP
We added struct Textbutton3 for our usage of 3 button menu bar to
control(2) library.  You may want to copy textbutton3.c file to /sys/src/libcontrol,
and do mk the control library with some change to /sys/include/control.h and
/sys/src/libcontrol/control.c and mkfile to make those usable..
.PP
If you want to extend functionarities to marsv, please refer to files such as imager.c
or marsv.c.
.SH BUGS
Some images with larger width may fail to be shown, because of the limit
of 9p protocol.  16 bit color is not supported to save the created image.  You will
lose true color from saving in 16 bit true color mode of Plan 9.
To input file name etc. onto the entry box, you have to hit Enter key at the end
to ensure the input, which is not a bug though.   There may be many other bugs.
.SH AUTHORS
Marsv is written by Yoshitatsu Suzuki and Kenji Okamoto of Osaka Prefecture
University.   We are financially supported by the citizens of Osaka Prefecure Japan.

Re: [9fans] marsv man page

[okamoto]

[-- Attachment #1: Type: text/plain, Size: 90 bytes --]

Ouch!
I enclosed older version of man page.
New man page I mentioned is here.

Kenji

[-- Attachment #2: Type: text/plain, Size: 7421 bytes --]

.TH MARSV 1
.SH NAME
marsv \- View PDS images and measure the elevation of Mars surface using
MOLA grid data; Output the result to a postscript formatted file
.SH SYNOPSIS
.B marsv
.SH DESCRIPTION
.I Marsv
is a GUI program for measuring Mars elevation, latitude and longitude at the location
pointed at by the mouse cursor, on a Qube image or MOLA grid data.    The program
draws a contour lines map overlaid on the image using MOLA grid data, and generates
a postscript output file.
.PP
Marsv is intended to be an acme like user interface for manipulating Mars images
with additional menubar property for 3 button mouse.   The Left button shows
the category name of the item, the Middle button executes the indicated job
by the menu name, and the Right button lists the items for that category so that
the user can choose and execute one.
.PP
In Elevation menu of ISISmenu category of QUBELoad menu or MOLALoad menu,
the Left button shows the values of elevation, longitude and latitude of the location
that the mouse points to.   When the mouse in this mode is dragged, those values
will be shown continuously, which makes you to understand the real shape of the
object you are now watching.   When you want to erase the data of the last point
from the screen, press the Middle button.
.PP
In Contour menu of ISISmenu category of QUBELoad menu, dragging the Right
button can make correction for the minor discrepancy between the location
indicated by MOLA grid data and by Qube image data.  Usually small parallel
shift will only be required to match those two data sets.   That is to match a
point indicated by the contour map in the MOLA grid data to some point which
is easily recongnized as the same one from an outstanding geographic feature.
After this recalibration, remaking of the contour lines map will be necessary to
get a correct one.   The values of longitude and latitude shown in Elevation
menu of ISISmenu category are also recalculated by the above procedure.
In short, you have to confirm the accuracy of those data by showing the contour
lines map before you try to ecamine the elevation of individual location.
Those two values will not usually match each other from our experience.
.PP
Marsv assumes there is a MOLA grid data (such as ieg0031t.img for 0.031 degree
grid) in the $home/data/mars/mola/ directory.   Additionally, marsv can read many
other PDS formatted images of other planet (and such as gif images of course), and
make simple annotations using Pen menu by changing colors from Palette menu.
.SH IMPLEMENTATION
Marsv designed as a single threaded concurrent program, ie. only a process can
include many threads, using thread(2) and control(2) libraries of Plan 9.   All the
controles to a window should be done by sending a control message to an appropriate
channel, which may not be necessarily attached to a visible window.   Five general
purpose user interfaces with its own windows are implemented as shown in struct
mItems, struct Form, struct Filebrowse, struct Select and struct Viewer.   Those
structures are constructed using two new basic structures, named struct Win and
struct WinComm, which control their shape, position and behaviour.   All those
structures have ctl, data, winctl and event channels to send or receive the control
messages or data, the last of which is just a handle to a real channel.    The winctl
channel controls the action of the window itself, such as resize, move and mount etc..
Those channels will be created by the function of mkwincomm() in wincomm.c.
.PP
Struct Canvas is prepared to provide layer structures to marsv image by using
memdraw and layer functions in memdraw(2) libraries of Plan 9, which is a
mechanism to make multiple layers in the user's memory space.   Each layer may
be for drawing the elevation, latitude and longitude data at the moving mouse point,
or for drawing image itself.   Struct Layer and CanvasBase are used as their base
structures.   The other many structures from control(2) library are also
used through newly defined structure of Wincontrol.  Struct Canvas related thread
has no winctl channel, then, has no distinct visible window, where channels are
created individually, and mkwincomm() is not applied.   The struct Viewer is used
to copy the layered image in user's memory space to visible image in kernal memory
space.   The layered memory image will be overlaid at this time if it is necessary.
.PP
We added struct Textbutton3 for our usage of 3 button menu bar to
control(2) library.  The method to install it is described in README file.
.PP
If you want to extend functionarities to marsv, please refer to files such as imager.c
or marsv.c.
.SH FILES
.nf
.B README	this file
.br
.B canvas.h	defines Canvas and CanvasBase structures,
.br
.B					and others for canvasthread
.br
.B mola.h		definitions for MOLA image
.br
.B win.h		basic definitions for win.c
.br
.B wincomm.h	basic definitions for wincomm.c
.br
.B page.h		stollen from page program included in
.br
.B					Plan 9 distribution
.br
.B qube.h		definitions for QUBE image
.br
.B browse.c	file browser for marsv
.br
.B canvas.c	canvasthread to make layer structure in
.br
.B 				marsv, and load images onto user
.br
.B					memory space using
.br
.B				 	memdraw(2) functions
.br
.B canvassub.c	subroutines for layer and canvas
.br
.B contour.c	make contour lines map using MOLA grid
.br
.B					data
.br
.B form.c		formthread to make basic window with
.br
.B					minimal user interface
.br
.B gfx.c		image file converter stollen from page
.br
.B					program of Plan 9 distribution
.br
.B imager.c	make window for Qube image or
.br
.B					other formatted images
.br
.B marsv.c	threadmain of marsv
.br
.B mitems.c	make menubar content and choose topmenu
.br
.B					etc.
.br
.B molaload.c	select the concerned area from MOLA
.br
.B						grid data
.br
.B palette.c	make color palette for drawing lines,
.br
.B					contour lines map etc.
.br
.B readmola.c	read selected MOLA data, and enhance
.br
.B						the image to fit better
.br
.B						to visualize
.br
.B readqube.c	ditto, but for Qube formatted image
.br
.B					by ISIS program from USGS
.br
.B save.c		save produced image to a file
.br
.B					with several format including
.br
.B					postscript
.br
.B select.c		select the file from shown directory
.br
.B					tree
.br
.B viewer.c	make view window with scrollbars
.br
.B win.c		basic functions to define the shape
.br
.B					of windows
.br
.B wincomm.c	basic function to define the behaviour
.br
.B						of each window
.br
.B pics/pds2pic.c	convert various PDS image to
.br
.B							Plan 9 image(6) format
.br
.B pics/pic2ps.c	convert Plan 9 image(6) to postscript
.br
.B							format


.SH BUGS
Some images with larger width may fail to be shown, because of the limit
of 9p protocol.  16 bit color is not supported to save the created image.  You will
lose true color from saving in 16 bit true color mode of Plan 9.
To input file name etc. onto the entry box, you have to hit Enter key at the end
to ensure the input, which is not a bug though.   There may be many other bugs.
.SH AUTHORS
Marsv was written by Yoshitatsu Suzuki and Kenji Okamoto of Osaka Prefecture
University.   We are financially supported by the citizens of Osaka Prefecure Japan.

Re: [9fans] marsv man page

[okamoto]

[-- Attachment #1: Type: text/plain, Size: 299 bytes --]

I used my last Saturday and Sunday to improve my documents
for Marsv.   Skip, you are very much appreciated!

I included two files, (1)man page for Marsv and (2)README.
It may be waste of space, however, I started it before, and then
I have to close it by myself...  Sorry, everyone.

Kenji

[-- Attachment #2: Type: text/plain, Size: 4950 bytes --]

.TH MARSV 1
.SH NAME
marsv \- View PDS images and measure the elevation of Mars surface using
MOLA grid data; Output the result to a postscript formatted file
.SH SYNOPSIS
.B marsv
.SH DESCRIPTION
.I Marsv
is a GUI program for measuring Mars elevation, latitude and longitude at the location
pointed at by the mouse cursor, on a Qube image or MOLA grid data.    The program
draws a contour map overlaid on the image using MOLA grid data, and generates a
postscript output file.
.PP
Marsv is intended to be an acme like user interface for manipulating Mars images
with additional menu barproperty for 3 button mouse.   The Left button shows
the category name of the item, the Middle button executes the indicated job
by the menu name, and the Right button lists the items for that category so that
the user can choose and execute one.
.PP
In Altitude menu of ISISmenu category of QUBELoad menu or MOLALoad menu,
the Left button shows the user the values of elevation, longitude and latitude of the
location that the mouse points to.
When the mouse in this mode is dragged, those values will be shown continuously,
which makes you to understand the real shape of the object you are now watching.
When you want to erase these data from the screen, press the Middle button.
.PP
In Contour menu of ISISmenu category of QUBELoad menu, dragging button 3 can
make correction for the minor discrepancy between that indicated by MOLA grid data
and by Qube image data.  After this recalibration, remapping of the countour will
be necessary to get a correct one.   The values of longitude and latitude
shown in Altitude menu of ISISmenu category are also recalculated by the above
procedure.  In short, you have to confirm the accuracy of those data shown by the mouse
over the contour maps, and if necessary, that recalibration should be done.
Those two values will not usually match each other from our experiences.
.PP
Marsv assumes there is a MOLA grid data (such as ieg0031t.img for 0.031 degree
grid) in the $home/data/mars/mola/ directory.   Additionally, marsv can read many
other PDS formatted images of other planet (and such as gif images of course), and
make simple annotations using Pen menu by changing colors from Palette menu.
.SH IMPLEMENTATION
Marsv designed as a single threaded concurrent program, ie. only a process can
include many threads, using thread(2) and control(2) libraries of Plan 9.   All the
controles to a window should be done by sending a control message to an appropriate
channel, which may not be necessarily attached to a visible window.   Four general
purpose user interfaces with its own windows are implemented as shown in struct
Form, struct Filebrowse, struct Select and struct Viewer.   Those structures are
constructed using two new basic structures, named struct Win and struct WinComm,
which control their shape, position and behaviour.   All those strructures have ctl,
data, winctl and event channels to send or receive the control messages or data,
the last of which is just a handle to a real channel.    Those channels will be created
by the function of mkwincomm() in wincomm.c.
.PP
Struct Canvas is prepared to provide layer structures to marsv image by using
memdraw and layer functions in memdraw(2) libraries of Plan 9, which is a
mechanism to make multiple layers in the user's memory space.   Each layer may
be for drawing the altitude, latitude and longitude data at the moving mouse point,
or for drawing image data themselves.   Struct Layer and CanvasBase are used as
their base structures.   The other many structures from control(2) library are also
used through newly defined structure of Wincontrol.  Struct Canvas related thread
has no winctl channel, then, has no distinct visible window, where channels are
created individually, and mkwincomm() is not applied.   The struct Viewer is used
to copy the layered image to visible image.
.PP
We added struct Textbutton3 for our usage of 3 button menu bar to
control(2) library.  You may want to copy textbutton3.c.lib file to /sys/src/libcontrol/txtbutton3.c,
and do mk the control library with some change to /sys/include/control.h and
/sys/src/libcontrol/control.c and mkfile to make those usable.
.PP
If you want to extend functionarities to marsv, please refer to files such as imager.c
or marsv.c.
.SH BUGS
Some images with larger width may fail to be shown, because of the limit
of 9p protocol.  16 bit color is not supported to save the created image.  You will
lose true color from saving in 16 bit true color mode of Plan 9.
To input file name etc. onto the entry box, you have to hit Enter key at the end
to ensure the input, which is not a bug though.   There may be many other bugs.
.SH AUTHORS
Marsv was written by Yoshitatsu Suzuki and Kenji Okamoto of Osaka Prefecture
University.   We are financially supported by the citizens of Osaka Prefecure Japan.

[-- Attachment #3: Type: text/plain, Size: 4861 bytes --]

Marsv is a Plan 9 GUI program for measuring elevations of Mars surface.
We employed acme style GUI interface for this purpose, where we aimed
to design it extendable for other image processing purpose.

We adopted 3 button mouse interface for menu bar, ie.
(1) left button: show the category name of the menu item
(2) center button: execute the job as acme does
(3) right button: show the content of the menu item, and choose one.

To wrtite this program, we referenced very often the sources of acme(1)
and control(2) library by Rob Pike.   We are very much grateful to his and
other developper's works for Plan 9 operating system.   Some of files,
gfx.c and page.h are whole copy of page(1) program of standard
distribution of Plan 9.  So, the license term of Plan 9 will also be applied
to gfx.c file.  In regard to the license terms for other files, we believe
that this software is for scientific use, and then, all the users of this
software will recognize and respect the importance of originality.

For full use of this program, you may need additional decompressing
program of, for an example, MOC PDS CDROM data.  We haven't
included those programs, because we don't know whether we can
do it.  If you want to try this, and you have license of those PDS images,
please contact Kenji Okamoto (okamoto@granite.cias.osakafu-u.ac.jp).
To compile those programs on Plan 9 is not difficult, and we believe
anyone who wants to run Plan 9 will have such ability.  So, please
don't bother us too much.   However, some friends of mine (Kenji)
in geology field are welcome anytime, of course.  I will help you
with pleasure.   We will not respond to any requests from anonymous
user.

Without those programs you can use only a very limitted functions
of marsv, where all the image format which page can recognize
except of postscript will be read into and then manupurated by marsv
program.   However, if you are not concerned with  Planetary Geology,
you may not want to run this anyway. :-)

This program was first coded by Yoshitatsu Suzuki for a part of his
master thesis of Osaka Prefecture University (planv was that name).
Yoshitatsu has left our Univ. for Tokyo, then, if you have questions,
please contact Kenji.   He will come back 9fans soon when he will
be ready.

Lastly, Please remember this is a product of Osaka Prefecture
University.   We are funded by the Univ., and which is been running
by taxes paid by the citizenes of Osaka Prefecture, Japan.

INSTALL

Copy textbutton3.c.lib to /sys/src/libcontrol/textbutton3.c, and
add a line to mkfile as 'textbutton3.$O\ to the last of OFILES list.
Similarly, add a line as '[Ctltextbutton3] =	"textbutton3",' just
before of the textbutton entry of ctltypenames array.   You may
also add a line into enum of types as Ctltextbutton3, just after
the item of Ctltextbutton, and then, recompile the libcontrol.
After above, you can just 'mk install' under the marsv source
directory.   You can copy marsv.1 to /sys/man/1pub/marsv,
which is a man page of marsv.

FILES

README		this file
canvas.h		defines Canvas and CanvasBase structures, and others for
			canvasthread
mola.h		definitions for MOLA image
win.h		basic definitions for win.c
wincomm.h	basic definitions for wincomm.c

page.h		stollen from page program included in Plan 9 distribution
qube.h		definitions for QUBE image
browse.c		file browser for marsv
canvas.c		canvasthread to make layer structure in marsv, and load
			images onto user memory space using memdraw(2)
			functions.
canvassub.c	subroutines for layer and canvas.
contour.c		make contour map using MOLA grid data
form.c		formthread to make basic window with minimal user
			interface
gfx.c			image file converter stollen from page program of
			Plan 9 distribution
imager.c		make window for Qube image or other formatted
			images
marsv.c		threadmain of marsv
mitems.c		make menubar content and choose topmenu etc.
molaload.c	select the concerned area from MOLA grid data
palette.c		make color palette for drawing lines, contour
			lines map etc.
readmola.c	read selected MOLA data, and enhance the image
			to fit better to visualize
readqube.c	ditto, but for Qube formatted image by ISIS program
			from USGS
save.c		save produced image to a file with several format
			including postscript
select.c		select the file from shown directory tree
viewer.c		make view window with scrollbars
win.c		basic functions to define the shape of windows
wincomm.c	basic function to define the behaviour of each window

pics/pds2pic.c	convert various PDS image to Plan 9 image(6) format
pics/pic2ps.c	convert Plan 9 image(6) to postscript format

			March 20, 2002
			February 14, 2003
							Osaka Prefecture University
							Kenji Okamoto
							okamoto@granite.cias.osakafu-u.ac.jp

[9fans] marsv man page

[okamoto]

Include /sys/man/1pub/marsv

Included is the man page of marsv(1pub)!

Kenji